{"id":18694241,"url":"https://github.com/9elements/autorev","last_synced_at":"2025-06-13T02:05:35.715Z","repository":{"id":57572743,"uuid":"237474285","full_name":"9elements/autorev","owner":"9elements","description":"Framework for automatic firmware reverse-engineering written in golang","archived":false,"fork":false,"pushed_at":"2020-01-31T16:56:38.000Z","size":264,"stargazers_count":32,"open_issues_count":0,"forks_count":1,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-06-06T05:46:26.826Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/9elements.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}},"created_at":"2020-01-31T16:50:34.000Z","updated_at":"2025-05-19T18:12:30.000Z","dependencies_parsed_at":"2022-08-24T05:21:22.474Z","dependency_job_id":null,"html_url":"https://github.com/9elements/autorev","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/9elements/autorev","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9elements%2Fautorev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9elements%2Fautorev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9elements%2Fautorev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9elements%2Fautorev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/9elements","download_url":"https://codeload.github.com/9elements/autorev/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/9elements%2Fautorev/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259565566,"owners_count":22877347,"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-07T11:08:54.678Z","updated_at":"2025-06-13T02:05:35.697Z","avatar_url":"https://github.com/9elements.png","language":"Go","readme":"# AUTOREV\n\nA framework for automated firmware reverse engineering using blackbox testing.\nAfter bringing the DUT in a defined state (powered-on, powered-off, restart) a\nserial connection is used to trace MMIO between firmware and the hardware.\nThe AUTOREV framework will generate an AST and do additional tests to restore\nthe high level programm that runs on this specific hardware (CPU, DRAM, Chipset,\nPCI devices, SuperIO, USB, SATA, PCIe ...).\n\nThat means the firmware must be patched in order to:\n* contain a serial driver\n* contain libx86emu to trace MMIO\n* contain a shell to allow runtime configuration of BIOS options\n\nAn example can be found here: [coreboot patch 32020](https://review.coreboot.org/c/coreboot/+/32020)\n\n**Note:** This framework can only generate code for a limited scope. It will never create an identical programm (compared the the programm that is being traced) as that would require too many tests on different hardware setups.\n\n## Documentation\n\nExtensive documentation can be found in the [Documentation](Documentation/Readme.md) folder.\n## Usage\n\nThe program basically consists of three different steps. Generating, Tracing,\nAnalyzing. When we have a fresh installation, we need to go through all the\nfollowing steps:\n\n0. Adjust the config.yml\n\nThe config.yml contains all user-specific configuration data. The _start-_ and\n_stopsignal_ can be signals coming from the DUT indicate when to start or stop the\nrecording of the trace. This is to minimize the scope of the recorded trace.\n\n_serial_ defines which serial we use. It can either be a file used for exchanging\ndate like in the QEMU example, or a (virtual) serial port. Here you can also\ndefine the baudrate and timeouts.\n\n_dutcontrol_ is used to, Suprise, control the dut. There are four types of\nscripts used: initcmd, startcmd, stopcmd and restartcmd. You can link shell\nscripts here. Use the QEMU example for reference.\n\n_options_default_table_ defines which device or default config should be used\nfor generating and running testcases. This should match the default config you\nadd in Step 1.\n\n_variable_ options defines the bios configuration options we want to alter. The\ndefault configuration blob can contain much more configuration options, those\nare the only one we iterate over. The options need a name, a byte offset where\nthey are located *within* the default bios configuration file. AUTOREV will\npatch the binary configuration file during runtime. Therefore also the size\n(bitwidth) is needed. To generate tests accordingly, AUTOREV needs to know what\nis the possible min value the configuration can be, and what is the maximum\nvalue it can contain, namely _min_ and _max_ in the config.yml\n\nDatabsae configuration can be made within the _database_ section and should be\nself explanatory.\n\n1. Add a new default configuration\n\nThe client side will/has to accep a configuration. Within AUTOREV we patch the\n_binary_ configuration with the offsets and possible values defined in the\nconfig.yml file.\n\n2. Generate possible traces\n\nWithin the config.yml we do five a range of possible values a bios configuration\ncan accept. AUTOREV generates test cases out of these possible values.\n\n3. Run the testcases and record traces\n\nAUTOREV now runs the testcases one-by-one and records all IO traces. The IO\ntraces will be saved in the MySQL DB. For more information check [Database\nDocumentation](Documentation/database.md).\n\n4. Generate an Abstract Syntax Tree (AST)\n\nAfter recording the traces and dumping them into the database, we can generate\nan Abstract Syntrax Tree out of it. The AST is a abstract representation of the\ncode flow. Each node equals one instruction and can have multiple connections to\nother nodes (instructions) with various conditions. We can either represent the\nAST in a .dot file or generate code out of it.\n\n5. Replace BLOB with generated .c file\n\nIf AUTOREV was successful, you can replace the BLOB with the generated .c file.\nThere is no guarantee that this actually works. Also features like Polling,\nLoop-detection, functions, etc. are still missing.\n\nThe steps 1. to 4. will be explained in more detail below.\n\n### Prerequesitions\n\n* Mysql DB (mariadb, mysqldb, etc.)\n* QEMU (for testing)\n* golang\n\n### Installation\n\nTo install the package, fetch it via go with\n\u003e go get github.com/9elements/autorev\n\nThis will automatically clone the repository into your $GO/src directory. Go to $GO/src/github.com/9elements/autorev and write\n\u003ego build\nto build a executable binary file.\n\n### Set up database\n\nYou need to have mysql installed an running. First create database with\n\u003e CREATE DATABASE autorev\n\nNext you need to create the tables with\n\u003e mysql -uroot -p autorev \u003c autorev_withData.sql\n\nThis generates all required tables.\n\n### Add new Default Configuration to the Database\n\nIn order to generate test-cases, you need to execute\n\u003e ./autorev -newConfig -newConfigFile qemu_test/qemuTestDefaults.bin -newConfigName qemuConfig\n\nThe `-newConfig` flag indicates that we are generating a new default config.\nDefault configs are needed for generating new test sets. AUTOREV patches the\ndefault config with the current option to test. `-newConfigFile` takes the\ndefault configuration blob as input. `newConfigName` provides a default name for\nthe configuration e.g. the platform name.\n\n### Generate Testcases for all bios configuration options\n\nNow we need to generate various test cases for all possible bios configuration\noptions.\n\n\u003e ./autorev -newtrace\n\ngenerates test cases for all possible bios configuration options specified in\nthe config.yml file. If the e.g. BiosOption1 can be set to values between 0 and\n10, AUTOREV generates 11 different test caes for all possible values between 0\nand 10. Of course, if we use more options, these options will be concatenated\nwith each other - which increases the amount of test cases exponentially.\nAfterwards, AUTOREV outputs the amount of generated test cases.\n\n### Run all Testcases and Collect Data\n\nNow that we have all test cases in place, we need to run the complete set with\n\n\u003e ./autorev -collecttraces\n\nDepending on the amount of generated traces, this might take a while.\n\n### Generate AST and SVG Tree\n\nNoe we have run all traces with all possible bios configurations options we want\nto test. Next, we need to generate a Abstract Syntax Tree (AST) from the\ngenerated traces. If we run\n\n\u003e ./autorev -buildast -genDot sampleTree.dot -genCCode sampleC.c\n\nAUTOREV fetches the traces from the databsae, generates an AST from those, and\nconverts the AST into useable C code.\nWe save this AST in a .dot file which can be converted to a SVG file with\n\n\u003e dot -Tsvg sampleTree.dot -O\n\nThis will genrate a sampleTree.dot.svg file which can be viewed with e.g.\nImageViewer.\n\n## Principle\n![AUTOREV Principle](AUTOREV_schematic.svg)\n\nThe analysis of a binary file can basically be divided into two parts - the first part is the data gathering, the second part consists of the dynamical analysis. Even though within the dynamical analysis we _might_ need to generate more test data - the initial data collection can take quite some time, depending on the options which need to be tested, the runtime of the binary and the complexity.\n\n### Data Collection\n\nFor collecting data, we first need to set up the target accordingly. The target needs to be configured such that it outputs test data as described in protocol.md.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F9elements%2Fautorev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F9elements%2Fautorev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F9elements%2Fautorev/lists"}