{"id":13540045,"url":"https://github.com/shellphish/driller","last_synced_at":"2025-10-16T21:49:54.359Z","repository":{"id":10558701,"uuid":"66166800","full_name":"shellphish/driller","owner":"shellphish","description":"Driller: augmenting AFL with symbolic execution!","archived":false,"fork":false,"pushed_at":"2025-03-24T19:44:29.000Z","size":312,"stargazers_count":926,"open_issues_count":36,"forks_count":162,"subscribers_count":54,"default_branch":"master","last_synced_at":"2025-04-11T10:01:03.016Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shellphish.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"zenodo":null}},"created_at":"2016-08-20T20:30:27.000Z","updated_at":"2025-04-08T17:12:42.000Z","dependencies_parsed_at":"2025-04-11T06:27:38.638Z","dependency_job_id":"dc09597c-a96c-41fa-b7df-21921450493f","html_url":"https://github.com/shellphish/driller","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellphish%2Fdriller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellphish%2Fdriller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellphish%2Fdriller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellphish%2Fdriller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shellphish","download_url":"https://codeload.github.com/shellphish/driller/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254227611,"owners_count":22035669,"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":[],"created_at":"2024-08-01T09:01:38.387Z","updated_at":"2025-10-16T21:49:49.311Z","avatar_url":"https://github.com/shellphish.png","language":"Python","funding_links":[],"categories":["\u003ca id=\"546f4fe70faa2236c0fbc2d486a83391\"\u003e\u003c/a\u003e社工(SET)\u0026\u0026钓鱼\u0026\u0026鱼叉攻击","Uncategorized","\u003ca id=\"3e622bff3199cf22fe89db026b765cd4\"\u003e\u003c/a\u003e工具","Tools","Python"],"sub_categories":["\u003ca id=\"290e9ae48108d21d6d8b9ea9e74d077d\"\u003e\u003c/a\u003e钓鱼\u0026\u0026Phish","Uncategorized","Binary"],"readme":"## Driller\n\nDriller is an implementation of the [driller paper](https://www.cs.ucsb.edu/~vigna/publications/2016_NDSS_Driller.pdf). This implementation was built on top of AFL with angr being used as a symbolic tracer. Driller selectively traces inputs generated by AFL when AFL stops reporting any paths as 'favorites'. Driller will take all untraced paths which exist in AFL's queue and look for basic block transitions AFL failed to find satisfying inputs for. Driller will then use angr to synthesize inputs for these basic block transitions and present it to AFL for syncing. From here, AFL can determine if any paths generated by Driller are interesting, it will then go ahead and mutate these as normal in an attempt to find more paths.\n\n### The \"Stuck\" heuristic\n\nDriller's symbolic execution component is invoked when AFL is 'stuck'. \nIn this implementation, AFL's progress is determined by its 'pending\\_favs' attribute which can found in the fuzzer\\_stats file. \nWhen this attribute reaches 0, Driller is invoked. Other heuristics could also be used, and it's infact likely that better heuristics exist.\n\n### Use in the Cyber Grand Challenge\n\nThis same implementation of Driller was used team Shellphish in DARPA's Cyber Grand Challenge (CGC) to aid in the discovery of exploitable bugs.\nTo see how Driller's invokation was scheduled for the CGC you can look at the Mechanical Phish's scheduler component 'meister'.\n\n### Current State and Caveats\n\nThe code currently supports three modes of operation:\n\n+ A script that facilitates AFL and driller on one machine (over many cores if needed): https://github.com/shellphish/fuzzer/blob/master/shellphuzz\n+ A monitor process watches over the fuzzer\\_stats file to determine when Driller should be invoked. When Driller looks like it could be useful, the monitor process schedules 'jobs' to work over all the inputs AFL has discovered / deemed interesting.\n+ Celery tasks are assigned over a fleet of machines, some number of these tasks are assigned to fuzzing, some are assigned to drilling. Fuzzer tasks monitors the stats file, and invokes driller tasks when Driller looks like it could be useful. Redis is used to sync testcases to the filesystem of the fuzzer.\n\nDriller was built and developed for DECREE binaries.\nWhile some support for other formats should work out-of-the-box, expect `TracerMisfollowError`s to occur when unsupported or incorrectly implemented simprocedures are hit.\n\n### Example\n\nHere is an example of using driller to find new testcases based off the trace of a single testcase.\n\n```python\nimport driller\n\nd = driller.Driller(\"./CADET_00001\",  # path to the target binary\n                    \"racecar\", # initial testcase\n                    \"\\xff\" * 65535, # AFL bitmap with no discovered transitions\n                   )\n\nnew_inputs = d.drill()\n```\n\n#### Dependencies\n\n+ Mechaphish Fuzzer component\n+ Mechaphish Tracer component\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshellphish%2Fdriller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshellphish%2Fdriller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshellphish%2Fdriller/lists"}