{"id":21928616,"url":"https://github.com/nuvious/cheeseshredder","last_synced_at":"2026-04-27T12:39:22.484Z","repository":{"id":251253773,"uuid":"753242570","full_name":"nuvious/CheeseShredder","owner":"nuvious","description":"Disassembler for x86 for the JHU Reverse Engineering Course","archived":false,"fork":false,"pushed_at":"2024-02-20T07:03:58.000Z","size":2603,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-30T19:46:44.505Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Assembly","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/nuvious.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License.txt","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":"2024-02-05T18:35:30.000Z","updated_at":"2024-08-01T16:53:28.000Z","dependencies_parsed_at":"2024-08-01T20:11:57.561Z","dependency_job_id":"a324197f-c966-43ab-b6d8-3adde3aa2786","html_url":"https://github.com/nuvious/CheeseShredder","commit_stats":null,"previous_names":["nuvious/cheeseshredder"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/nuvious/CheeseShredder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuvious%2FCheeseShredder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuvious%2FCheeseShredder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuvious%2FCheeseShredder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuvious%2FCheeseShredder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nuvious","download_url":"https://codeload.github.com/nuvious/CheeseShredder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuvious%2FCheeseShredder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32337274,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-28T22:27:08.259Z","updated_at":"2026-04-27T12:39:22.451Z","avatar_url":"https://github.com/nuvious.png","language":"Assembly","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cheese Shredder\n\nA decompiler for x86 written in python.\n\n## Overview\n\nCheeseShredder is a linear-sweep disassembler with a modular design to allow support for other architectures in the\nfuture.\n\n### Requirements\n\n- Python 3.7+\n\n### Capabilities and Limitations\n\nThis disassembler is limited to 32 bit addressing modes and tested on the following subset of instructions for the\npurpose of meeting the requirements of the course assignment this project was started for:\n\n| | | |\n|-|-|-|\n|add|jmp|pop|\n|and|jz/jnz|push|\n|call|lea|repne cmpsd|\n|clflush|mov|retf|\n|cmp|movsd|retn|\n|dec|nop|sub|\n|idiv|not|test|\n|inc|or|xor|\n\nReferences used for this project was primarily the Intel® 64 and IA-32 Architectures Software Developer’s Manual [1]. A\ncsv of the instructions with metadata about them was also used and modified from Gregory Comer on their github\nproject GregoryComer/x86-csv [2]. Initially this was added as a submodule, but some formatting adjustments needed to\nbe made for instructions such as `PUSH 50+rd` where in the source csv the opcodes are denoted as \"50 +rd\" and to make\nimplementation easier such instructions were reduced to a single operand token of `50+rd`.\n\n## Quick-Start\n\nClone or decompress the release tar.gz/zip to a directory of your choosing. Then run `pip install .` in the target\ndirectory.\n\n### Linux\n\n```bash\nwget https://github.com/nuvious/CheeseShredder/archive/refs/tags/latest.tar.gz -O CheeseShredder-latest.tar.gz\ntar -xvf CheeseShredder-latest.tar.gz\ncd CheeseShredder-latest\npip3 install .\ncheeseshredder -i tests/positive/example1\n```\n\n### Windows\n\n```powershell\nInvoke-WebRequest https://github.com/nuvious/CheeseShredder/archive/refs/tags/latest.zip `\n    -OutFile CheeseShredder-latest.zip\nExpand-Archive CheeseShredder-latest.zip -DestinationPath .\ncd CheeseShredder-latest\npip install .\ncheeseshredder -i tests\\positive\\example1\n```\n\n### Example Output\n\n```bash\n(.venv) $\u003e xxd tests/positive/example1\n00000000: 31c0 01c8 01d0 5589 e552 51b8 4443 4241  1.....U..RQ.DCBA\n00000010: 8b95 0800 0000 8b8d 0c00 0000 01d1 89c8  ................\n00000020: 5a59 5dc2 0800                           ZY]...\n(.venv) $\u003e cheeseshredder -i tests/positive/example1\n00000000: 31C0 xor eax,eax\n00000002: 01C8 add eax,ecx\n00000004: 01D0 add eax,edx\n00000006: 55 push ebp\n00000007: 89E5 mov ebp,esp\n00000009: 52 push edx\n0000000A: 51 push ecx\n0000000B: B844434241 mov eax,0x41424344\n00000010: 8B9508000000 mov edx,[ebp+0x00000008]\n00000016: 8B8D0C000000 mov ecx,[ebp+0x0000000c]\n0000001C: 01D1 add ecx,edx\n0000001E: 89C8 mov eax,ecx\n00000020: 5A pop edx\n00000021: 59 pop ecx\n00000022: 5D pop ebp\n00000023: C20800 retn 0x0008\n```\n\n## Usage\n\nYou can use the `-h` flag to see all the command line option:\n\n```bash\n(.venv) $\u003e cheeseshredder -h\nusage: CheeseShredder [-h] -i INPUT [-d] [-p] [-l LOG_LEVEL] [-f] [--no-jump-label] [-o OUTPUT]\n\nA binary disassembler for x86 32 bit addressing mode binaries.\n\noptions:\n  -h, --help            show this help message and exit\n  -i INPUT, --input INPUT\n                        Input file to disassemble.\n  -d, --debug           Sets debug mode; throws exceptions on any parse error.\n  -p, --progress        Show progress bar (requires tqdm).\n  -l LOG_LEVEL, --log-level LOG_LEVEL\n                        Set log level.\n  -f, --label-functions\n                        Label function locations and calls with func_XXXXXXXX.\n  --no-jump-label       Do not label jumps with offset_XXXXXXh format and just output the immediate value.\n  -o OUTPUT, --output OUTPUT\n                        Output to a file. If not set output will print to stdout.\n\nFor questions/contributions email5287736+nuvious@users.noreply.github.com.\n```\n\n### Jump and Function Labels\n\nJump labels are on by default and will have the syntax `offset_XXXXXXXXh`. These can be disabled with the\n`--no-jump-label` flag. Example output below:\n\n```text\n000000AF: 31D2 xor edx,edx\noffset_000000b1h: \u003c----\n000000B1: 8B06 mov eax,[esi]\n...\n000000BF: 39D1 cmp ecx,edx\n000000C1: 75EE jnz offset_000000b1h \u003c----\n000000C3: 5A pop edx\n```\n\nFunction labels are off by default and can be turned on with the `-f/--label-functions` flag. Function labels will take\nthe format of `func_XXXXXXXX`. Example output below:\n\n```text\n0000009E: C3 retn\nfunc_0000009f: \u003c---\n0000009F: 55 push ebp\n...\n00000056: 51 push ecx\n00000057: E843000000 call func_0000009f \u003c---\n0000005C: B91C000000 mov ecx,0x0000001c\n```\n\n## Docker\n\nA Dockerfile definition has been provided and can be built locally or pulled from DockerHub. Simply mount you desired\nbinary to `/workspace` and use the same relative paths (unix style) to run the disassembler.\n\n```bash\ndocker run --rm -it -v $PWD:/workspace nuvious/cheeseshredder -i tests/positive/example1\n```\n\nTo build from the Dockerfile simply run `docker build` and use your desired local tag:\n\n```bash\ndocker build -t cheeseshredder .\ndocker run --rm -it -v $PWD:/workspace cheeseshredder -i tests/positive/example1\n```\n\n## Development and Testing\n\nFor development, a [tox](https://tox.wiki/en/4.13.0/) configuration has been made to test compatibility with all\nactively supported versions of python.\n\n### Using Docker/Conda/Tox (Recommended)\n\n```bash\ndocker run --rm -it \\\n    -v ${PWD}:/workspace conda/miniconda3:latest \\\n    /bin/bash -c \"pushd workspace; pip install tox-conda; tox\"\n```\n\n### Locally with pytest\n\n```bash\ngit clone https://github.com/nuvious/CheeseShredder.git\ncd CheeseShredder\n# Setup a virtual environment if desired\npip install -e .[test]\npytest\n```\n\n### Fuzzing\n\nA script is also provided to fuzz input to find edge cases. The script will generate a random binary via /dev/urandom\nand then run the disassembler on it.\n\n```bash\ncd tests\n/bin/bash fuzz_it.sh\n```\n\nIf a payload is found that causes an exception, then it will be copied with the output to fuzz/test_case_NN(.out). The\n`test_fuzz.py` will then pick it up and should result in a failed pytest run. This allows for test-driven development\nof edge cases and/or bugs in parsing.\n\n### Build Documentation\n\nThis project uses [sphinx](https://www.sphinx-doc.org/en/master/) to generate documentation. Docs can be built by\nrunning the `make` build targets:\n\n```bash\n# PDF \nmake latexpdf\n# Artifact will be located at docs/build/latex/cheeseshredder-anx86disassembler.pdf\n\n# HTML\nmake html\n# Artifacts will be located at docs/build/html\ntar -czvf cheeseshredder-docs-html.tar.gz -C docs/build html\n```\n\nThis can also generate a man-page that you can include in one of your `man --path` locations.\n\n```bash\n# MAN Page\nmake man\n# Artifact will be located at docs/build/man/cheeseshredder-anx86disassembler.1\ncp docs/build/man/cheeseshredder-anx86disassembler.1 /usr/share/man/man1/cheeseshredder.1\n```\n\n[comment]: # (There are two includes of this image because this markdown is included by the sphinx build so the path needs to be relative to the README.md and the docs/ build directory)\n\n![](_static/man-page.png)\n\n![](docs/source/_static/man-page.png)\n\n## References\n\n[1] Intel, “Intel® 64 and IA-32 Architectures Software Developer’s Manual,” 2023.\n    Available: https://cdrdv2.intel.com/v1/dl/getContent/671110. [Accessed: Jan. 30, 2024]\n\n[2] G. Comer, “GregoryComer/x86-csv,” GitHub, Oct. 23, 2023.\n    Available: https://github.com/GregoryComer/x86-csv. [Accessed: Feb. 19, 2024]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnuvious%2Fcheeseshredder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnuvious%2Fcheeseshredder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnuvious%2Fcheeseshredder/lists"}