{"id":19681028,"url":"https://github.com/aflplusplus/unicornafl","last_synced_at":"2025-04-04T12:08:51.180Z","repository":{"id":38214620,"uuid":"433080123","full_name":"AFLplusplus/unicornafl","owner":"AFLplusplus","description":"AFL bindings for Unicorn-Engine","archived":false,"fork":false,"pushed_at":"2024-11-07T13:59:44.000Z","size":9810,"stargazers_count":69,"open_issues_count":2,"forks_count":32,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-11-24T17:47:44.289Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/AFLplusplus.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}},"created_at":"2021-11-29T14:43:39.000Z","updated_at":"2024-11-22T21:06:29.000Z","dependencies_parsed_at":"2023-11-14T01:02:12.053Z","dependency_job_id":"74b4088b-e0e8-468d-9ac8-bc7c66ae1ea8","html_url":"https://github.com/AFLplusplus/unicornafl","commit_stats":{"total_commits":94,"total_committers":15,"mean_commits":6.266666666666667,"dds":0.3936170212765957,"last_synced_commit":"1c58dc9774012bace730df5c1c273356762e848a"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AFLplusplus%2Funicornafl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AFLplusplus%2Funicornafl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AFLplusplus%2Funicornafl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AFLplusplus%2Funicornafl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AFLplusplus","download_url":"https://codeload.github.com/AFLplusplus/unicornafl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247174423,"owners_count":20896078,"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-11-11T18:06:45.221Z","updated_at":"2025-04-04T12:08:51.155Z","avatar_url":"https://github.com/AFLplusplus.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UnicornAFL\n\nThe project builds a bridge between AFL++ and unicorn engine.\nYou can fuzz unicorn targets using python, rust, and C.\n\nCheck out [the examples](https://github.com/AFLplusplus/AFLplusplus/tree/stable/unicorn_mode/samples) in AFLplusplus/unicorn_mode\n\n## Compile\n\nIf you have unicorn installed globally, you may just:\n\n```bash\nmkdir build\ncd build\ncmake .. -DCMAKE_BUILD_TYPE=Release\nmake\n```\n\nOr if you prefer a latest build, don't forget to update submodule before building.\n\n```bash\ngit submodule update --init --recursive\nmkdir build\ncd build\ncmake .. -DCMAKE_BUILD_TYPE=Release -DUCAFL_NO_LOG=on # disable logging for the maximum speed\nmake\n```\n\nOr if you would like python bindings.\n\n```bash\npython3 -m pip install unicornafl\n```\n\nOr build it by yourself.\n\n```bash\ngit submodule update --init --recursive\ncd bindings/python/\npython3 -m pip install -e .\n```\n\n## API\n\nThe only API currently unicornafl exposes is:\n\n```C\n//\n//  Start our fuzzer.\n//\n//  If no afl-fuzz instance is found, this function is almost identical to uc_emu_start()\n//  \n//  @uc: The uc_engine return-ed from uc_open().\n//  @input_file: This usually is the input file name provided by the command argument.\n//  @place_input_callback: This callback is triggered every time a new child is generated. It returns \n//                         true if the input is accepted, or the input would be skipped.\n//  @exits: All possible exits.\n//  @exit_count: The count of the @exits array.\n//  @validate_crash_callback: This callback is triggered every time to check if we are crashed.                     \n//  @always_validate: If this is set to False, validate_crash_callback will be only triggered if\n//                    uc_emu_start (which is called internally by uc_afl_fuzz) returns an error. Or\n//                    the validate_crash_callback will be triggered every time.\n//  @persistent_iters: Fuzz how many times before forking a new child.\n//  @data: The extra data user provides.\n//\n//  @uc_afl_ret: The error the fuzzer returns.\nUNICORNAFL_EXPORT\nuc_afl_ret uc_afl_fuzz(uc_engine* uc, char* input_file,\n                       uc_afl_cb_place_input_t place_input_callback,\n                       uint64_t* exits, size_t exit_count,\n                       uc_afl_cb_validate_crash_t validate_crash_callback,\n                       bool always_validate, uint32_t persistent_iters,\n                       void* data);\n```\n\n## Migration\n\nunicornafl 2.x remains the same API compatible to unicornafl 1.x so there is no extra work to migrate.\n\nHowever, a change in unicornafl 2.x is that the monkey patch is no longer needed for Python, which is a bit more elegant. For instance:\n\n```python\n# works with both unicornafl 1.x and unicornafl 2.x\nimport unicornafl\n\nunicornafl.monkeypatch()\n\nuc.afl_fuzz(...)\n```\n\nIn unicornafl 2.x, we recommend:\n\n```python\n# unicornafl 2.x only!\nimport unicornafl\n\nunicornafl.uc_afl_fuzz(uc, ...)\n```\n\n## Debugging\n\nUnicornAFL supports debugging in a similar way to AFL++.\nSetting the environment variable `AFL_DEBUG` will provide additional output relating to the forkserver and interaction between parent and child processes during execution.\nAs usual with AFL++, `AFL_DEBUG_CHILD` will enable the output of the fuzzed children.\nThis output can be further enriched via the `AFL_DEBUG_UNICORN` variable, which will detail information about child execution including block translations, hooks, and encountered errors. Note that this variable also requires `AFL_DEBUG_CHILD` to be set, as the output is provided from child context.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faflplusplus%2Funicornafl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faflplusplus%2Funicornafl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faflplusplus%2Funicornafl/lists"}