{"id":22103062,"url":"https://github.com/pr0v3rbs/FirmAE","last_synced_at":"2025-07-25T01:31:42.148Z","repository":{"id":37376311,"uuid":"297554727","full_name":"pr0v3rbs/FirmAE","owner":"pr0v3rbs","description":"Towards Large-Scale Emulation of IoT Firmware for Dynamic Analysis","archived":false,"fork":false,"pushed_at":"2023-10-22T12:45:52.000Z","size":1492,"stargazers_count":572,"open_issues_count":37,"forks_count":111,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-03-28T15:17:02.070Z","etag":null,"topics":["analysis","arbitration","emulation","firmware","fuzzing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pr0v3rbs.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}},"created_at":"2020-09-22T06:20:51.000Z","updated_at":"2024-03-27T20:54:04.000Z","dependencies_parsed_at":"2023-01-21T05:16:54.981Z","dependency_job_id":"1c4a5933-c946-40d9-b93f-94365856b7d1","html_url":"https://github.com/pr0v3rbs/FirmAE","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pr0v3rbs%2FFirmAE","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pr0v3rbs%2FFirmAE/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pr0v3rbs%2FFirmAE/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pr0v3rbs%2FFirmAE/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pr0v3rbs","download_url":"https://codeload.github.com/pr0v3rbs/FirmAE/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227497353,"owners_count":17781119,"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":["analysis","arbitration","emulation","firmware","fuzzing"],"created_at":"2024-12-01T06:01:46.503Z","updated_at":"2025-07-25T01:31:42.088Z","avatar_url":"https://github.com/pr0v3rbs.png","language":"Python","funding_links":[],"categories":["Python","Testing Tools","Firmware Security","Software Tools"],"sub_categories":["Firmware Analysis and Exploit Frameworks","Dynamic Analysis and Emulation","Emulation Tools"],"readme":"# FirmAE\n\nFirmAE is a fully-automated framework that performs emulation and vulnerability analysis. FirmAE significantly increases the emulation success rate (From [Firmadyne](https://github.com/firmadyne/firmadyne)'s 16.28% to 79.36%) with five arbitration techniques. We tested FirmAE on 1,124 wireless-router and IP-camera firmware images from top eight vendors.\n\nWe also developed a dynamic analysis tool for 0-day discovery, which infers web service information based on the filesystem and kernel logs of target firmware.\nBy running our tool on the succesfully emulation firmware images, we discovered 12 new 0-days which affect 23 devices.\n\n# Installation\n\nNote that we tested FirmAE on Ubuntu 20.04.\n\n1. Clone `FirmAE`\n```console\n$ git clone --recursive https://github.com/pr0v3rbs/FirmAE\n```\n\n2. Run `download.sh` script.\n```console\n$ ./download.sh\n```\n\n3. Run `install.sh` script.\n```console\n$ ./install.sh\n```\n\n# Usage\n\n1. Execute `init.sh` script.\n```console\n$ ./init.sh\n```\n\n2. Prepare a firmware.\n```console\n$ wget https://github.com/pr0v3rbs/FirmAE/releases/download/v1.0/DIR-868L_fw_revB_2-05b02_eu_multi_20161117.zip\n```\n\n3. Check emulation\n```console\n$ sudo ./run.sh -c \u003cbrand\u003e \u003cfirmware\u003e\n```\n\n4. Analyze the target firmware\n\n* Analysis mode uses the FirmAE analyzer\n\n```console\n$ sudo ./run.sh -a \u003cbrand\u003e \u003cfirmware\u003e\n```\n\n* Run mode helps to test web service or execute custom analyzer\n\n```console\n$ sudo ./run.sh -r \u003cbrand\u003e \u003cfirmware\u003e\n```\n\n## Debug\n\nAfter `run.sh -c` finished.\n\n### 1. User-level basic debugging utility.\n\nUseful when an emulated firmware is network reachable or not\n* It supports `socat` connection, `nc` reverse shell (31337) and `telnet` connection (31338)\n* And the setup will be done automatically\n\n```console\n$ sudo ./run.sh -d \u003cbrand\u003e \u003cfirmware\u003e\n```\n\n### 2. Kernel-level boot debugging.\n\n```console\n$ sudo ./run.sh -b \u003cbrand\u003e \u003cfirmware\u003e\n```\n\n## Turn on/off arbitration\n\nCheck the five arbitrations environment variable in the `firmae.config`\n```sh\n$ head firmae.config\n#!/bin/sh\n\nFIRMAE_BOOT=true\nFIRMAE_NETWORK=true\nFIRMAE_NVRAM=true\nFIRMAE_KERNEL=true\nFIRMAE_ETC=true\n\nif (${FIRMAE_ETC}); then\n  TIMEOUT=240\n```\n\n## Docker\n\nFirst, prepare a docker image.\n```console\n$ ./docker-init.sh\n```\n\n### Parallel mode\n\nThen, run one of the below commands. ```-ec``` checks only the emulation, and ```-ea``` checks the emulation and analyzes vulnerabilities.\n```console\n$ ./docker-helper.py -ec \u003cbrand\u003e \u003cfirmware\u003e\n$ ./docker-helper.py -ea \u003cbrand\u003e \u003cfirmware\u003e\n```\n\n### Debug mode\n\nAfter a firmware image successfully emulated.\n```console\n$ ./docker-helper.py -ed \u003cfirmware\u003e\n```\n\n# Evaluation\n\n## Emulation result\n\nGoogle spreadsheet -\n[view](https://docs.google.com/spreadsheets/d/1dbKxr_WOZ7UmneOogug1Zykj1erpfk-GzRNni8DjroI/edit?usp=sharing)\n\n## Dataset\n\nGoogle drive -\n[download](https://drive.google.com/file/d/1hdm75NVKBvs-eVH9rKb5xfgryNSnsg_8/view?usp=sharing)\n\n# CVEs\n\n- ASUS: [CVE-2019-20082](https://github.com/pr0v3rbs/CVE/tree/master/CVE-2019-20082)\n- Belkin: [Belkin01](https://github.com/pr0v3rbs/CVE/tree/master/Belkin01)\n- D-Link: [CVE-2018-20114](https://github.com/pr0v3rbs/CVE/tree/master/CVE-2018-20114),\n          [CVE-2018-19986](https://github.com/pr0v3rbs/CVE/tree/master/CVE-2018-19986%20-%2019990#cve-2018-19986---hnap1setroutersettings),\n          [CVE-2018-19987](https://github.com/pr0v3rbs/CVE/tree/master/CVE-2018-19986%20-%2019990#cve-2018-19987---hnap1setaccesspointmode),\n          [CVE-2018-19988](https://github.com/pr0v3rbs/CVE/tree/master/CVE-2018-19986%20-%2019990#cve-2018-19988---hnap1setclientinfodemo),\n          [CVE-2018-19989](https://github.com/pr0v3rbs/CVE/tree/master/CVE-2018-19986%20-%2019990#cve-2018-19989---hnap1setqossettings),\n          [CVE-2018-19990](https://github.com/pr0v3rbs/CVE/tree/master/CVE-2018-19986%20-%2019990#cve-2018-19990---hnap1setwifiverifyalpha),\n          [CVE-2019-6258](https://github.com/pr0v3rbs/CVE/tree/master/CVE-2019-6258),\n          [CVE-2019-20084](https://github.com/pr0v3rbs/CVE/tree/master/CVE-2019-20084)\n- TRENDNet: [CVE-2019-11399](https://github.com/pr0v3rbs/CVE/tree/master/CVE-2019-11399),\n            [CVE-2019-11400](https://github.com/pr0v3rbs/CVE/tree/master/CVE-2019-11400)\n\n# Authors\nThis research project has been conducted by [SysSec Lab](https://syssec.kr) at KAIST.\n* [Mingeun Kim](https://pr0v3rbs.blogspot.kr/)\n* [Dongkwan Kim](https://0xdkay.me/)\n* [Eunsoo Kim](https://hahah.kim)\n* [Suryeon Kim](#)\n* [Yeongjin Jang](https://www.unexploitable.systems/)\n* [Yongdae Kim](https://syssec.kaist.ac.kr/~yongdaek/)\n\n# Citation\nWe would appreciate if you consider citing [our paper](https://syssec.kaist.ac.kr/pub/2020/kim_acsac2020.pdf) when using FirmAE.\n```bibtex\n@inproceedings{kim:2020:firmae,\n  author = {Mingeun Kim and Dongkwan Kim and Eunsoo Kim and Suryeon Kim and Yeongjin Jang and Yongdae Kim},\n  title = {{FirmAE}: Towards Large-Scale Emulation of IoT Firmware for Dynamic Analysis},\n  booktitle = {Annual Computer Security Applications Conference (ACSAC)},\n  year = 2020,\n  month = dec,\n  address = {Online}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpr0v3rbs%2FFirmAE","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpr0v3rbs%2FFirmAE","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpr0v3rbs%2FFirmAE/lists"}