{"id":13515524,"url":"https://github.com/googleprojectzero/domato","last_synced_at":"2025-05-14T08:05:57.376Z","repository":{"id":37396880,"uuid":"104365791","full_name":"googleprojectzero/domato","owner":"googleprojectzero","description":"DOM fuzzer","archived":false,"fork":false,"pushed_at":"2024-11-26T08:55:07.000Z","size":480,"stargazers_count":1720,"open_issues_count":3,"forks_count":281,"subscribers_count":67,"default_branch":"master","last_synced_at":"2025-04-11T21:46:08.220Z","etag":null,"topics":["dom","fuzzing","security"],"latest_commit_sha":null,"homepage":"https://googleprojectzero.blogspot.ch/2017/09/the-great-dom-fuzz-off-of-2017.html","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/googleprojectzero.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-21T15:28:59.000Z","updated_at":"2025-04-11T08:58:45.000Z","dependencies_parsed_at":"2024-07-28T09:49:12.773Z","dependency_job_id":"0f9d59ec-e380-453b-a8e5-da3617809dbe","html_url":"https://github.com/googleprojectzero/domato","commit_stats":{"total_commits":94,"total_committers":29,"mean_commits":"3.2413793103448274","dds":0.851063829787234,"last_synced_commit":"fadff396cc45d521cc594d3e2396e27e887b1963"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleprojectzero%2Fdomato","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleprojectzero%2Fdomato/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleprojectzero%2Fdomato/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googleprojectzero%2Fdomato/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/googleprojectzero","download_url":"https://codeload.github.com/googleprojectzero/domato/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254101615,"owners_count":22014909,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dom","fuzzing","security"],"created_at":"2024-08-01T05:01:12.448Z","updated_at":"2025-05-14T08:05:52.366Z","avatar_url":"https://github.com/googleprojectzero.png","language":"Python","readme":"# Domato 🍅\n#### A DOM fuzzer\n\nWritten and maintained by Ivan Fratric, \u003cifratric@google.com\u003e\n\nCopyright 2017 Google Inc. All Rights Reserved.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n#### Usage\n\nTo see the usage information run the following command:\n\n`python3 generator.py --help`\n\nTo generate a single .html sample run:\n\n`python generator.py --file \u003coutput file\u003e`\n\nTo generate a single .html sample run using a template you wrote:\n\n`python generator.py --file \u003coutput file\u003e --template \u003cyour custom template file\u003e`\n\nTo generate multiple samples with a single call run:\n\n`python generator.py --output_dir \u003coutput directory\u003e --no_of_files \u003cnumber of output files\u003e`\n\nThe generated samples will be placed in the specified directory and will be named as fuzz-\u0026lt;number\u0026gt;.html, e.g. fuzz-00001.html, fuzz-00002.html etc. Generating multiple samples is faster because the input grammar files need to be loaded and parsed only once.\n\n#### Code organization\n\ngenerator.py contains the main script. It uses grammar.py as a library and contains additional helper code for DOM fuzzing.\n\ngrammar.py contains the generation engine that is mostly application-agnostic and can thus be used in other (i.e. non-DOM) generation-based fuzzers. As it can be used as a library, its usage is described in a separate section below.\n\n.txt files contain grammar definitions. There are 3 main files, html.txt, css.txt and js.txt which contain HTML, CSS and JavaScript grammars, respectively. These root grammar files may include content from other files.\n\n#### Using the generation engine and writing grammars\n\nTo use the generation engine with a custom grammar, you can use the following python code:\n\n```\nfrom grammar import Grammar\n\nmy_grammar = Grammar()\nmy_grammar.parse_from_file('input_file.txt')\nresult_string = my_grammar.generate_symbol('symbol_name')\n\n```\n\nThe following sections describe the syntax of the grammar files.\n\n##### Basic syntax\n\nDomato is based on an engine that, given a context-free grammar in a simple format specified below, generates samples from that grammar.\n\nA grammar is described as a set of rules in the following basic format:\n\n`\u003csymbol\u003e = a mix of constants and \u003cother_symbol\u003es`\n\nEach grammar rule contains a left side and the right side separated by the equal character. The left side contains a symbol, while the right side contains the details on how that symbol may be expanded. When expanding a symbol, all symbols on the right-hand side are expanded recursively while everything that is not a symbol is simply copied to the output. Note that a single rule can't span over multiple lines of the input file.\n\nConsider the following simplified example of a part of the CSS grammar:\n\n```\n\u003ccssrule\u003e = \u003cselector\u003e { \u003cdeclaration\u003e }\n\u003cselector\u003e = a\n\u003cselector\u003e = b\n\u003cdeclaration\u003e = width:100%\n```\n\nIf we instruct the grammar engine to parse that grammar and generate 'cssrule', we may end up with either:\n\n`a { width:100% }`\n\nor\n\n`b { width:100% }`\n\nNote there are two rules for the 'selector' symbol. In such cases, when the generator is asked to generate a 'selector', it will select the rule to use at random. It is also possible to specify the probability of the rule using the 'p' attribute, for example:\n\n```\n\u003cselector p=0.9\u003e = a\n\u003cselector p=0.1\u003e = b\n```\n\nIn this case, the string 'a' would be output more often than 'b'.\n\nThere are other attributes that can be applied to symbols in addition to the probability. Those are listed in a separate section.\n\nConsider another example for generating html samples:\n\n```\n\u003chtml\u003e = \u003clt\u003ehtml\u003cgt\u003e\u003chead\u003e\u003cbody\u003e\u003clt\u003e/html\u003cgt\u003e\n\u003chead\u003e = \u003clt\u003ehead\u003cgt\u003e...\u003clt\u003e/head\u003cgt\u003e\n\u003cbody\u003e = \u003clt\u003ebody\u003cgt\u003e...\u003clt\u003e/body\u003cgt\u003e\n```\n\nNote that since the '\u003c' and '\u003e' have a special meaning in the grammar syntax, so here we are using `\u003clt\u003e` and `\u003cgt\u003e` instead. These symbols are built in and don't need to be defined by the user. A list of all built-in symbols is provided in a separate section.\n\n##### Generating programming language code\n\nTo generate programming language code, a similar syntax can be used, but there are a couple of differences. Each line of the programming language grammar is going to correspond to the line of the output. Because of that, the grammar syntax is going to be more free-form to allow expressing constructs in various programming languages. Secondly, when a line is generated, in addition to outputting the line, one or more variables may be created and those variables may be reused when generating other lines. Again, let's take a look of the simplified example:\n\n```\n!varformat fuzzvar%05d\n!lineguard try { \u003cline\u003e } catch(e) {}\n\n!begin lines\n\u003cnew element\u003e = document.getElementById(\"\u003cstring min=97 max=122\u003e\");\n\u003celement\u003e.doSomething();\n!end lines\n```\n\nIf we instruct the engine to generate 5 lines, we may end up with something like:\n\n```\ntry { var00001 = document.getElementById(\"hw\"); } catch(e) {}\ntry { var00001.doSomething(); } catch(e) {}\ntry { var00002 = document.getElementById(\"feezcqbndf\"); } catch(e) {}\ntry { var00002.doSomething(); } catch(e) {}\ntry { var00001.doSomething(); } catch(e) {}\n```\n\nNote that\n\n- programming language lines are enclosed in '!begin lines' and '!end lines' statement. This gives the grammar parser the necessary information that the lines in-between are programming language lines and are thus parsed differently.\n- We used `\u003cnew element\u003e` instead of `\u003celement\u003e`. This instructs the generator to create a new variable of type 'element' instead of generating the 'element' symbol.\n- `\u003cstring\u003e` is one of the built-in symbols so no need to define it.\n- [optional] You can use !varformat statement to define the format of variables you want to use.\n- [optional] You can use !lineguard statement to define additional code that gets inserted around every line in order to catch exceptions or perform other tasks. This is so you wouldn't need to write it for every line separately.\n- In addition to '!begin lines' and '!end lines' you can also use '!begin helperlines' and '!end helperlines' to define lines of code that will only ever be used if required when generating other lines (for example, helper lines might generate variables needed by the 'main' code, but you don't ever want those helper lines to end up in the output when they are not needed).\n\n##### Comments\n\nEverything after the first '#' character on the line is considered a comment, so for example:\n\n```\n#This is a comment\n```\n\n\n##### Preventing infinite recursions\n\nThe grammar syntax has a way of telling the fuzzer which rules are nonrecursive and can be safe to use even if the maximum level of recursion has been reached. This is done with the ‘nonrecursive’ attributes. An example is given below.\n\n```\n!max_recursion 10\n\u003ctest root=true\u003e = \u003cfoobar\u003e\n\u003cfoobar\u003e = foo\u003cfoobar\u003e\n\u003cfoobar nonrecursive\u003e = bar\n```\n\nFirstly, an optional ‘!max_recursion’ statement defines the maximum recursion depth level (50 by default). Notice that the second production rule for ‘foobar’ is marked as non-recursive. If ever the maximum recursion level is reached the generator will force using the non-recursive rule for ‘foobar’ symbol, thus preventing infinite recursion.\n\n##### Including and importing other grammar files\n\nIn Domato, including and importing grammars are two different context.\n\nIncluding is simpler. You can use:\n\n```\n!include other.txt\n```\n\nto include rules from other.txt into the currently parsed grammar.\n\nImporting works a bit differently:\n\n```\n!import other.txt\n```\n\ntells the parser to create a new Grammar() object that can then be referenced from the current grammar by using the special `\u003cimport\u003e` symbol, for example like this:\n\n```\n\u003ccssrule\u003e = \u003cimport from=css.txt symbol=rule\u003e\n```\n\nYou can think about importing and including in terms of namespaces: !include will put the included grammar into the single namespace, while !import will create a new namespace which can then be accessed using the `\u003cimport\u003e` symbol and the namespace specified via the 'from' attribute.\n\n##### Including Python code\n\nSometimes you might want to call custom Python code in your grammar. For example, let’s say you want to use the engine to generate a http response and you want the body length to match the 'Size' header. Since this is something not possible with normal grammar rules, you can include custom Python code to accomplish it like this:\n\n```\n!begin function savesize\n  context['size'] = ret_val\n!end function\n\n!begin function createbody\n  n = int(context['size'])\n  ret_val = 'a' * n\n!end function\n\n\u003cfoo root\u003e = \u003cheader\u003e\u003ccr\u003e\u003clf\u003e\u003cbody\u003e\n\u003cheader\u003e = Size: \u003cint min=1 max=20 beforeoutput=savesize\u003e\n\u003cbody\u003e = \u003ccall function=createbody\u003e\n```\n\nThe python functions are defined between ‘!begin function \u003cfunction_name\u003e’ and ‘!end function’ commands. The functions can be called in two ways: using ‘beforeoutput’ attribute and using `\u003ccall\u003e` symbol.\n\nBy specifying the ‘beforeoutput’ attribute in some symbol, the corresponding function will be called when this symbol is expanded, just before the result of the expansion is output to the sample. The expansion result will be passed to the function in the ret_val variable. The function is then free to modify ret_val, store it for later use or perform any other operations.\n\nWhen using a special `\u003ccall\u003e` symbol, the function (specified in a ‘function’ attribute) will be called when the symbol is encountered during language generation. Any value stored by the function in ret_val will be considered the result of the expansion (ret_val gets included in the sample).\n\nYour python code has access to the following variables:\n\n- `context` - a dictionary that is passed through the whole sample generation. You can use it to store values (such as storing the size in an example above) and retrieve them in the rules that fire subsequently.\n- `attributes` - a dictionary corresponding to the symbol currently being processed. You can use it to pass parameters to your functions. For example if you used something like `\u003ccall function=func foo=bar\u003e` to call your function attributes\\[‘foo’\\] will be set to ‘bar’.\n- `ret_val` - The value that will be output as a result of the function call. It is initialized to an empty value when using `\u003ccall\u003e` symbol to call a function, otherwise it will be initialized to the value generated by the symbol.\n\n##### Built-in symbols\n\nThe following symbols have a special meaning and should not be redefined by users:\n\n- `\u003clt\u003e` - ‘\u003c’ character\n- `\u003cgt\u003e` - ‘\u003e’ character\n- `\u003chash\u003e` - ‘#’ character\n- `\u003ccr\u003e` - CR character\n- `\u003clf\u003e` - LF character\n- `\u003cspace\u003e` - space character\n- `\u003ctab\u003e` - tab character\n- `\u003cex\u003e` - ‘!’ character\n- `\u003cchar\u003e` - can be used to generate an arbitrary ascii character using ‘code’ attribute. For example `\u003cchar code=97\u003e` corresponds to ‘a’. Generates random character if not specified. Supports ‘min’ and ‘max’ attribute.\n- `\u003chex\u003e` - generates a random hex digit.\n- `\u003cint\u003e`, `\u003cint 8\u003e`, `\u003cuint8\u003e`, `\u003cint16\u003e`, `\u003cuint16\u003e`, `\u003cint32\u003e`, `\u003cuint32\u003e`, `\u003cint64\u003e`, `\u003cuint64\u003e` - can be used to generate random integers. Supports ‘min’ and ‘max’ attribute that can be used to limit the range of integers that will be generated. Supports the ‘b’ and ‘be’ attribute which makes the output binary in little/big endian format instead of text output.\n- `\u003cfloat\u003e`, `\u003cdouble\u003e` - generates a random floating-point number. Supports ‘min’ and ‘max’ attribute (0 and 1 if not specified). Supports ‘b’ attribute which makes the output binary.\n- `\u003cstring\u003e` - generates a random string. Supports ‘min’ and ‘max’ attributes which control the minimum and maximum charcode generated as well as ‘minlength’ and ‘maxlength’ attributes that control the length of the string.\n- `\u003chtmlsafestring\u003e` - same as `\u003cstring\u003e` except HTML metacharacters will be escaped, making it safe to embed the string as part of HTML text or attribute values.\n- `\u003clines\u003e` - outputs the given number (via ‘count’ attribute) lines of code. See the section on generating programming language code for example.\n- `\u003cimport\u003e` - imports a symbol from another grammar, see the section on including external grammars for details.\n- `\u003ccall\u003e` - calls a user-defined function corresponding to the function attribute. See the section on including Python code in the grammar for more info.\n\n##### Symbol attributes\n\nThe following attributes are supported:\n\n- root - marks a symbol as the root symbol of the grammar. The only supported value is ‘true’. When GenerateSymbol() is called, if no argument is specified, the root symbol will be generated.\n- nonrecursive - gives the generator a hint that this rule doesn’t contain recursion loops and is used to prevent infinite recursions. The only supported value is ‘true’.\n- new - used when generating programming languages to denote that a new variable is created here rather than expanding the symbol as usual. The only supported value is ‘true’.\n- from, symbol - used when importing symbols from other grammars, see ‘Including external grammars’ section.\n- count - used in lines symbol to specify the number of lines to be created.\n- id - used to mark that several symbols should share the same value. For example in the rule `‘doSomething(\u003cint id=1\u003e, \u003cint id=1\u003e)’` both ints would end up having the same value. Only the first instance is actually expanded, the second is just copied from the first.\n- min, max - used in generation of numeric types to specify the minimum and maximum value. Also used to limit the set of characters generated in strings.\n- b, be - used in numeric types to specify binary little-endian (‘b’) or big-endian (‘be’) output.\n- code - used in char symbol to specify the exact character to output by its code.\n- minlength, maxlength - used when generating strings to specify the minimum and maximum length.\n- up - used in hex symbol to specify uppercase output (lowercase is the default).\n- function - used in the `\u003ccall\u003e` symbol, see ‘Including Python code’ section for more info.\n- beforeoutput - used to call user-specified functions, see ‘Including Python’.\n\n#### Bug Showcase\n\nSome of the bugs that have been found with Domato:\n\n - Apple Safari: CVE-2017-2369, CVE-2017-2373, CVE-2017-2362, CVE-2017-2454, CVE-2017-2455, CVE-2017-2459, CVE-2017-2460, CVE-2017-2466, CVE-2017-2471, CVE-2017-2476, CVE-2017-7039, CVE-2017-7040, CVE-2017-7041, CVE-2017-7042, CVE-2017-7043, CVE-2017-7046, CVE-2017-7048, CVE-2017-7049, CVE-2017-13796, CVE-2017-13792, CVE-2017-13797, CVE-2017-13795, CVE-2017-13785, CVE-2017-13784, CVE-2017-13783, CVE-2017-13802, CVE-2017-13794, CVE-2017-13798, CVE-2017-13791, CVE-2018-4089, CVE-2018-4200, CVE-2018-4197, CVE-2018-4318, CVE-2018-4317, CVE-2018-4314, CVE-2018-4306, CVE-2018-4312, CVE-2018-4315, CVE-2018-4323, CVE-2018-4328\n - Google Chrome: Issues 666246 and 671328\n - Microsoft Internet Explorer 11: CVE-2017-0037, CVE-2017-0059, CVE-2017-0202, CVE-2017-8594, CVE-2018-0866\n - Microsoft Edge: CVE-2017-0037, CVE-2017-8496, CVE-2017-8652, CVE-2017-8644\n - Microsoft JScript: CVE-2017-11903, CVE-2017-11855, CVE-2017-11793, CVE-2017-11906, CVE-2017-11907, CVE-2018-0935, CVE-2018-8353, CVE-2018-8631\n - Microsoft VBScript: CVE-2018-8544, CVE-2018-8552, CVE-2018-8625\n - Mozilla Firefox: CVE-2017-5404, CVE-2017-5447, CVE-2017-5465\n\n#### Disclaimer\n\nThis is not an official Google product.\n\n","funding_links":[],"categories":["Fuzzing","\u003ca id=\"683b645c2162a1fce5f24ac2abfa1973\"\u003e\u003c/a\u003e漏洞\u0026\u0026漏洞管理\u0026\u0026漏洞发现/挖掘\u0026\u0026漏洞开发\u0026\u0026漏洞利用\u0026\u0026Fuzzing","Python","Python (1887)","Tools"],"sub_categories":["功能","API/协议","Web, JavaScript"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogleprojectzero%2Fdomato","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogleprojectzero%2Fdomato","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogleprojectzero%2Fdomato/lists"}