{"id":13538665,"url":"https://github.com/christhecoolhut/firmware_slap","last_synced_at":"2025-04-05T12:06:07.175Z","repository":{"id":96692048,"uuid":"193618712","full_name":"ChrisTheCoolHut/Firmware_Slap","owner":"ChrisTheCoolHut","description":"Discovering vulnerabilities in firmware through concolic analysis and function clustering.","archived":false,"fork":false,"pushed_at":"2020-09-17T19:07:12.000Z","size":5085,"stargazers_count":478,"open_issues_count":9,"forks_count":79,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-29T11:08:28.302Z","etag":null,"topics":["angr","exploit","firmware","vulnerability-discovery"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChrisTheCoolHut.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}},"created_at":"2019-06-25T02:24:29.000Z","updated_at":"2025-03-18T15:17:51.000Z","dependencies_parsed_at":"2024-01-07T13:04:36.003Z","dependency_job_id":"19bbe8da-bdb7-466b-b5ad-a2444ee2460f","html_url":"https://github.com/ChrisTheCoolHut/Firmware_Slap","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/ChrisTheCoolHut%2FFirmware_Slap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisTheCoolHut%2FFirmware_Slap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisTheCoolHut%2FFirmware_Slap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisTheCoolHut%2FFirmware_Slap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChrisTheCoolHut","download_url":"https://codeload.github.com/ChrisTheCoolHut/Firmware_Slap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247332604,"owners_count":20921853,"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":["angr","exploit","firmware","vulnerability-discovery"],"created_at":"2024-08-01T09:01:14.651Z","updated_at":"2025-04-05T12:06:07.151Z","avatar_url":"https://github.com/ChrisTheCoolHut.png","language":"Python","funding_links":[],"categories":["\u003ca id=\"683b645c2162a1fce5f24ac2abfa1973\"\u003e\u003c/a\u003e漏洞\u0026\u0026漏洞管理\u0026\u0026漏洞发现/挖掘\u0026\u0026漏洞开发\u0026\u0026漏洞利用\u0026\u0026Fuzzing"],"sub_categories":["\u003ca id=\"9d1ce4a40c660c0ce15aec6daf7f56dd\"\u003e\u003c/a\u003e未分类-Vul"],"readme":"# Firmware Slap\n\nFirmware slap combines concolic analysis with function clustering for vulnerability discovery and function similarity in firmware. Firmware slap is built as a series of libraries and exports most information as either pickles or JSON for integration with other tools.\n\n![Firmware Slap](https://i.imgur.com/fxIIogI.gif)\n\nSlides from the talk can be found [here](https://media.defcon.org/DEF%20CON%2027/DEF%20CON%2027%20presentations/DEFCON-27-Christopher-Roberts-Firmware-Slap.pdf)\n\n## Setup\n\nFirmware slap should be run in a virtual environment. It has been tested on Python3.6\n```bash\nsudo apt install python3-virtualenv\nvirtualenv -p python3 fwslap\nsource fwslap/bin/activate\n```\n-- or --\n\n```bash\ncd ~\nmkdir .virtualenvs\npip install virtualenv\nwhich virtualenv #note path warnings\npip install virtualenvwrapper\necho \"export PATH=$PATH:~/.local/bin\" \u003e\u003e ~/.bashrc\necho \"export WORKON_HOME=~/.virtualenvs\" \u003e\u003e ~/.bashrc\necho \"source ~/.local/bin/virtualenvwrapper.sh\" \u003e\u003e ~/.bashrc\n\n#usually best here to open new terminal\n\nmkvirtualenv fwslap -p /usr/bin/python3\nworkon fwslap\n```\n\n\n```bash\npython setup.py install\n```\n\nYou will need rabbitmq, docker, and (radare2 or Ghidra)\n```bash\n# Ubuntu\nsudo apt install rabbitmq-server docker.io\n# OSX\nbrew install rabbitmq\n\n# Radare2\ngit clone https://github.com/radare/radare2.git\nsudo ./radare2/sys/install.sh\n# Ghidra\nwget https://ghidra-sre.org/ghidra_9.0.4_PUBLIC_20190516.zip\nunzip ghidra_9.0.4_PUBLIC_20190516.zip -d ghidra\necho \"export PATH=\\$PATH:$PWD/ghidra/ghidra_9.0.4/support\" \u003e\u003e ~/.bashrc\n```\n\nGhidra requires JDK 11.\n```bash\nsudo apt install default-jdk\njava --version\n```\n\nIf you want to use the Elastic search stuff run the `Elasticsearch_and_kibana.sh` script\n\n## Quickstart\n\nEnsure rabbitmq-server is running.\n\n```bash\n# In a Separate terminal, run this in the top level \"Firmware_Slap\" directory\ncelery -A firmware_slap.celery_tasks worker --loglevel=info\n# Basic buffer overflow\nDiscover_And_Dump.py examples/iwconfig -D iwconfig_results\nLoad_And_View_Results.py iwconfig_results.all.pickle\n\n# Click management on the left pane\n# Click Saved Objects\n# Click Import\n# Select 'elastic_export.json' under the elastic directory in firmware slap\n# Navigate to dashboards on left pane and select 'Overview Dashboard'\n\nLoad_And_View_Results.py iwconfig_results.all.pickle -s\n\n# Command injection\ntar -xvf examples/Almond_libs.tar.gz\nVuln_Discover_Celery.py examples/upload.cgi -L Almond_Root/lib/\n```\n\n## Usage\n\n```bash\n# Get the firmware used for examples\nwget https://firmware.securifi.com/AL3_64MB/AL3-R024-64MB\nbinwalk -Mre AL3-R024-64MB\n```\n\nStart a celery work from the project root directory:\n```bash\n# In a separate terminal\ncelery -A firmware_slap.celery_tasks worker --loglevel=info\n```\n\nIn a different terminal window, run a vulnerability discovery job.\n\n```bash\n$ Vuln_Discover_Celery.py Almond_Root/etc_ro/lighttpd/www/cgi-bin/upload_bootloader.cgi -L Almond_Root/lib/\n[+] Getting argument functions\n[+] Analyzing 1 functions\n  0%|                                                                                                                                                                                                                                   | 0/1 [00:01\u003c?, ?it/s]\n{   'Injected_Location': {   'base': '0x7ffefde8',\n........................ SNIP ......................\n    'type': 'Command Injection'}\nPython 3.5.2 (default, Nov 12 2018, 13:43:14) \nType 'copyright', 'credits' or 'license' for more information\nIPython 7.3.0 -- An enhanced Interactive Python. Type '?' for help.\n\nIn [1]: \n```\n\n## The returned vulnerability object\n\nThe above command will return an object in the `result` variable. This is a dictionary will all sorts of awesome information about the vulnerability. There are three major keys in the object: The function arguments, The memory, and the injected location.\n```\nIn [3]: result.keys()                                                                                 \nOut[3]: dict_keys(['args', 'file_name', 'type', 'mem', 'Injected_Location'])\n```\n### args\nThe args key will detail information about the recovered argument and what the argument values must be to recreate the vulnerability. In the below example, one argument is recovered, and to trigger the command injection that argument must be a char* that contains \"\\`reboot\\`\" to trigger a reboot.\n```\nIn [1]: result['args']                                                           \nOut[1]: \n[{'base': 'a1',\n  'type': 'int',\n  'value': \"0x0 -\u003e b'`reboot`\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x00'\"}]\n```\n\n### Memory\nThe memory component of the object keeps track of the required memory values set to trigger the vulnerability. It also offers stack addresses and .text addresses with the offending commands for setting the required memory constraints. The first memory event required is at `mtd_write_firmware+0x0` and the second is at `mtd_write_firmware+0x38`. Assembly is provided to help prettify future display work.\n```\nIn [2]: result['mem']                                                                   \nOut[2]: \n[{'BBL_ADDR': '0x401138',\n  'BBL_DESC': {'DESCRIPTION': 'mtd_write_firmware+0x0 in upload_bootloader.cgi (0x401138)',\n   'DISASSEMBLY': ['0x401138:\\tlui\\t$gp, 0x42',\n    '0x40113c:\\taddiu\\t$sp, $sp, -0x228',\n    '0x401140:\\taddiu\\t$gp, $gp, -0x5e90',\n    '0x401144:\\tlw\\t$t9, -0x7f84($gp)',\n    '0x401148:\\tsw\\t$a2, 0x10($sp)',\n    '0x40114c:\\tlui\\t$a2, 0x40',\n    '0x401150:\\tmove\\t$a3, $a1',\n    '0x401154:\\tsw\\t$ra, 0x224($sp)',\n    '0x401158:\\tsw\\t$gp, 0x18($sp)',\n    '0x40115c:\\tsw\\t$a0, 0x14($sp)',\n    '0x401160:\\taddiu\\t$a1, $zero, 0x200',\n    '0x401164:\\taddiu\\t$a0, $sp, 0x20',\n    '0x401168:\\tjalr\\t$t9',\n    '0x40116c:\\taddiu\\t$a2, $a2, 0x196c']},\n  'DATA': \"b'`reboot`\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x01\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00'\",\n  'DATA_ADDRS': ['0x0']},\n {'BBL_ADDR': '0x401170',\n  'BBL_DESC': {'DESCRIPTION': 'mtd_write_firmware+0x38 in upload_bootloader.cgi (0x401170)',\n   'DISASSEMBLY': ['0x401170:\\tlw\\t$gp, 0x18($sp)',\n    '0x401174:\\tnop\\t',\n    '0x401178:\\tlw\\t$t9, -0x7f68($gp)',\n    '0x40117c:\\tnop\\t',\n    '0x401180:\\tjalr\\t$t9',\n    '0x401184:\\taddiu\\t$a0, $sp, 0x20']},\n  'DATA': \"b'/bin/mtd_write -o 0 -l 0 write `reboot`'\",\n  'DATA_ADDRS': ['0x7ffefe07']}]\n```\n### Command Injection Specific\nSince command injections are the easiest to demo, I've created a convenience dictionary key to demonstrate the location of the command injection easily.\n```\nIn [4]: result['Injected_Location']                                                                      \nOut[4]: {'base': '0x7ffefde8', 'type': 'char *', 'value': '/bin/mtd_write -o 0 -l 0 write `reboot`'}\n```\n\n### Sample Vulnerability Cluster Script\nThe vulnerability cluster script will attempt to discover vulnerabilities using the method in the Sample Vulnerability Discovery script and then build k-means clusters of a set of given functions across an extracted firmware to find similar functions to vulnerable ones.\n```bash\n$ Vuln_Cluster_Celery.py -h\nusage: Vuln_Cluster_Celery.py [-h] [-L LD_PATH] [-F FUNCTION] [-V VULN_PICKLE]\n                              Directory\n\npositional arguments:\n  Directory\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -L LD_PATH, --LD_PATH LD_PATH\n                        Path to libraries to load\n  -F FUNCTION, --Function FUNCTION\n  -V VULN_PICKLE, --Vuln_Pickle VULN_PICKLE\n\n```\nThe below command takes -F as a known vulnerable function. -V as a dumped pickle from a previous run  to not need to discover new vulnerabilites and -L for the library path.\nA sample usage:\n\n```bash\n$ python Vuln_Cluster_Celery.py -F mtd_write_firmware -L Almond_Root/lib/ Almond_Root/etc_ro/lighttpd/www/cgi-bin/\n[+] Reading Files\n100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00\u003c00:00,  2.80it/s]\nGetting functions from executables\nStarting main\n... Snip ...\n\n```\n \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristhecoolhut%2Ffirmware_slap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchristhecoolhut%2Ffirmware_slap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristhecoolhut%2Ffirmware_slap/lists"}