{"id":13836329,"url":"https://github.com/trailofbits/mishegos","last_synced_at":"2025-05-16T15:09:15.795Z","repository":{"id":35706782,"uuid":"187746996","full_name":"trailofbits/mishegos","owner":"trailofbits","description":"A differential fuzzer for x86 decoders","archived":false,"fork":false,"pushed_at":"2024-10-21T09:10:34.000Z","size":1146,"stargazers_count":251,"open_issues_count":24,"forks_count":30,"subscribers_count":34,"default_branch":"master","last_synced_at":"2025-05-12T05:54:16.685Z","etag":null,"topics":["fuzzing","hacktoberfest","x86"],"latest_commit_sha":null,"homepage":"https://blog.trailofbits.com/2019/10/31/destroying-x86_64-instruction-decoders-with-differential-fuzzing/","language":"C++","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/trailofbits.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":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-21T02:27:06.000Z","updated_at":"2025-05-07T22:26:06.000Z","dependencies_parsed_at":"2024-01-13T16:51:19.655Z","dependency_job_id":"5a9c7e0d-b3c9-43dd-a063-fdfac773002a","html_url":"https://github.com/trailofbits/mishegos","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/trailofbits%2Fmishegos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fmishegos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fmishegos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fmishegos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trailofbits","download_url":"https://codeload.github.com/trailofbits/mishegos/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254553958,"owners_count":22090417,"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":["fuzzing","hacktoberfest","x86"],"created_at":"2024-08-04T15:00:41.800Z","updated_at":"2025-05-16T15:09:10.779Z","avatar_url":"https://github.com/trailofbits.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"mishegos\n========\n\n[![CI](https://github.com/trailofbits/mishegos/actions/workflows/ci.yml/badge.svg)](https://github.com/trailofbits/mishegos/actions/workflows/ci.yml)\n\nA differential fuzzer for x86 decoders.\n\n![mishegos](https://user-images.githubusercontent.com/3059210/59005797-da89b400-87ec-11e9-8274-321edfa6df45.png)\n\nRead more about `mishegos` in its accompanying [blog post](https://blog.trailofbits.com/2019/10/31/destroying-x86_64-instruction-decoders-with-differential-fuzzing/)\nand academic publication ([paper](https://github.com/gangtan/LangSec-papers-and-slides/raw/main/langsec21/papers/Woodruff_LangSec21.pdf)\n| [recording](https://www.youtube.com/watch?v=a2q86KTZt0g)\n| [slides](https://github.com/trailofbits/publications/blob/master/presentations/Differential%20analysis%20of%20x86-64%20decoders/langsec-2021-slides.pdf)).\n\n```bibtex\n@InProceedings{woodruff21differential,\n  author       = \"William Woodruff and Niki Carroll and Sebastiaan Peters\",\n  title        = \"Differential analysis of x86-64 instruction decoders\",\n  booktitle    = \"Proceedings of the Seventh Language-Theoretic Security Workshop~({LangSec}) at the {IEEE} Symposium on Security and Privacy\",\n  year         = \"2021\",\n  month        = \"May\"\n}\n```\n\n## Usage\n\nStart with a clone, including submodules:\n\n```bash\ngit clone --recurse-submodules https://github.com/trailofbits/mishegos\n```\n\n### Building\n\n`mishegos` is most easily built within Docker:\n\n```bash\ndocker build -t mishegos .\n```\n\nAlternatively, you can try building it directly.\n\nMake sure you have `binutils-dev` (or however your system provides `libopcodes`) installed:\n\n```bash\nmake\n# or\nmake debug\n```\n\nBuild specific workers by passing a space-delimited list as the `WORKERS` varable:\n\n```bash\nWORKERS=\"bfd capstone\" make worker\n```\n\n### Running\n\nRun the fuzzer for a bit:\n\n```bash\n./src/mishegos/mishegos ./workers.spec \u003e /tmp/mishegos\n```\n\n`mishegos` checks for three environment variables:\n\n* `V=1` enables verbose output on `stderr`\n* `D=1` enables the \"dummy\" mutation mode for debugging purposes\n* `M=1` enables the \"manual\" mutation mode (i.e., read from `stdin`)\n* `MODE=mode` can be used to configure the mutation mode in the absence of `D` and `M`\n    * Valid mutation modes are `sliding` (default), `havoc`, and `structured`\n\nConvert mishegos's raw output into JSONL suitable for analysis:\n\n```bash\n./src/mish2jsonl/mish2jsonl /tmp/mishegos \u003e /tmp/mishegos.jsonl\n```\n\n`mish2jsonl` checks for `V=1` to enable verbose output on `stderr`.\n\nRun an analysis/filter pass group on the results:\n\n```bash\n./src/analysis/analysis -p same-size-different-decodings \u003c /tmp/mishegos.jsonl \u003e /tmp/mishegos.interesting\n```\n\nGenerate an ~ugly~ pretty visualization of the filtered results:\n\n```bash\n./src/mishmat/mishmat \u003c /tmp/mishegos.interesting \u003e /tmp/mishegos.html\nopen /tmp/mishegos.html\n```\n\nTip: The HTML file that `mishmat` generates could be hundreds of megabytes large, which will likely result in a bad browser viewing experience. Using the [`split`](https://man7.org/linux/man-pages/man1/split.1.html) tool, you can create multiple smaller HTML files with a specified number of entries per file (10,000 in the following example) and load each of them separately:\n\n```bash\nmkdir /tmp/mishegos-html\nsplit -d --lines=10000 - /tmp/mishegos-html/mishegos_ \\\n    --additional-suffix='.html' --filter='./src/mishmat/mishmat \u003e $FILE' \\\n    \u003c /tmp/mishegos.interesting\n```\n\n### Contributing\n\nWe welcome contributors to mishegos!\n\nA guide for adding new disassembler workers can be found [here](./docs/adding_a_worker.md).\n\n### Performance notes\n\nAll numbers below correspond to the following run:\n\n```bash\nV=1 timeout 60s ./src/mishegos/mishegos ./workers.spec \u003e /tmp/mishegos\n```\n\nOutside Docker:\n\n* On a Linux desktop (Ubuntu 20.04, Ryzen 5 3600, 32GB DDR4):\n    * Commit [`d80063a`](https://github.com/trailofbits/mishegos/commit/d80063a575c4b10d5f787ac88f45d44c8e7f9937)\n    * 8 workers (no `udis86`) + 1 `mishegos` fuzzer process\n    * 8.7M outputs/minute\n    * 9 cores pinned\n\n## TODO\n\n* Performance improvements\n    * Break cohort collection out into a separate process (requires re-addition of semaphores)\n    * Maybe use a better data structure for input/output/cohort slots\n* Add a scaling factor for workers, e.g. spawn `N` of each worker\n* Pre-analysis normalization (whitespace, immediate representation, prefixes)\n* Analysis strategies:\n    * Filter by length, decode status discrepancies\n    * Easy: lexical comparison\n    * Easy: reassembly + effects modeling (maybe with microx?)\n* Scoring ideas:\n    * Low value: Flag/prefix discrepancies\n    * Medium value: Decode success/failure/crash discrepancies\n    * High value: Decode discrepancies with differing control flow, operands, maybe some immediates\n* Visualization ideas:\n    * Basic but not really basic: some kind of mouse-over differential visualization\n\n## License\n\n`mishegos` is licensed and distributed under the [Apache v2.0](LICENSE) license. [Contact us](mailto:opensource@trailofbits.com) if you’re looking for an exception to the terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailofbits%2Fmishegos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrailofbits%2Fmishegos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailofbits%2Fmishegos/lists"}