# FirmAE - Emulate Firmware
**FirmAE** 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.
**Spreadcheet of verified firmware versions:** [**view**](https://docs.google.com/spreadsheets/d/1dbKxr_WOZ7UmneOogug1Zykj1erpfk-GzRNni8DjroI/edit?usp=sharing)
Below is a short guide on how to emulate the firmware of a TP-Link Wireless Router.
***
### 1. Clone repo, install dependencies and build image
```sh
void@dev:~$ git clone https://github.com/pr0v3rbs/FirmAE.git
void@dev:~/FirmAE$ ./download.sh
void@dev:~/FirmAE$ ./install.sh
void@dev:~/FirmAE$ reboot (to make sure $USER is member of docker group)
void@dev:~/FirmAE$ ./docker-init.sh
void@dev:~/FirmAE$ sudo apt install python3-coloredlogs -y
```
### 2. Setup a postgres container and import database schema
```sh
void@dev:~/FirmAE$ service postgresql stop
void@dev:~/FirmAE$ docker pull postgres
void@dev:~/FirmAE$ docker run -itd -e POSTGRES_USER=firmadyne -e POSTGRES_PASSWORD=firmadyne -e POSTGRES_DB=firmware -p 5432:5432 -v /data:/var/lib/postgresql/data --name postgresql postgres
void@dev:~/FirmAE$ PGPASSWORD=firmadyne psql -h localhost -p 5432 -U firmadyne -d firmware < ./database/schema
(optional - verify)
void@dev:~/FirmAE$ PGPASSWORD=firmadyne psql -h localhost -p 5432 -U firmadyne -d firmware
```
### 3. Emulate firmware
Check the emulation using the `-ec` flag, if successfull you can then build/debug it using `-ed` flag.
```sh
void@dev:~/FirmAE/firmwares$ cp /mnt/hgfs/vm-share/Archer_C5400_US__V1_170731.zip .
void@dev:~/FirmAE$ ./docker-helper.py -ec tplink ./firmwares/Archer_C5400_US__V1_170731.zip
2024-06-10 12:48:24 dev root[24739] INFO [*] docker0_Archer_C5400_US__V1_170731.zip emulation start!
2024-06-10 12:54:08 dev root[24739] INFO [+] docker0_Archer_C5400_US__V1_170731.zip emulation finished. (339.4081s)
void@dev:~/FirmAE$ ./docker-helper.py -ed firmwares/Archer_C5400_US__V1_170731.zip
2024-06-10 12:56:53 dev root[27825] INFO [*] docker0_Archer_C5400_US__V1_170731.zip start!
[*] /work/firmwares/Archer_C5400_US__V1_170731.zip emulation start!!!
[*] extract done!!!
[*] get architecture done!!!
[*] /work/firmwares/Archer_C5400_US__V1_170731.zip already succeed emulation!!!
[IID] 2
[MODE] debug
[+] Network reachable on 192.168.1.1!
[+] Web service on 192.168.1.1
[+] Run debug!
Creating TAP device tap2_0...
Set 'tap2_0' persistent and owned by uid 0
Bringing up TAP device...
Starting emulation of firmware... 192.168.1.1 true true 8.186311590 50.931019008
[*] firmware - Archer_C5400_US__V1_170731
[*] IP - 192.168.1.1
[*] connecting to netcat (192.168.1.1:31337)
[-] failed to connect netcat
------------------------------
| FirmAE Debugger |
------------------------------
1. connect to socat
2. connect to shell
3. tcpdump
4. run gdbserver
5. file transfer
6. exit
>
```
### 4. Create tunnel to emulated devices' web interface with socat
```sh
void@dev:~/FirmAE$ socat TCP-LISTEN:8080,reuseaddr,fork 'EXEC:docker exec -i docker0_Archer_C5400_US__V1_170731.zip "socat STDIO TCP-CONNECT:192.168.1.1:80"' &
[1] 68468
void@dev:~/FirmAE$ ss -plunta
Netid State Recv-Q Send-Q Local Address:Port Peer Address:Port Process
udp ESTAB 0 0 192.168.101.224%eth0:68 192.168.101.1:67
tcp LISTEN 0 4096 0.0.0.0:5432 0.0.0.0:*
tcp LISTEN 0 4096 127.0.0.1:42187 0.0.0.0:*
tcp LISTEN 0 4096 [::]:5432 [::]:*
tcp LISTEN 0 5 *:8080 *:* users:(("socat",pid=67161,fd=5))
void@dev:~/FirmAE$ curl http://localhost:8080
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://0xpthree.gitbook.io/notes/development/docker/firmae-emulate-firmware.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.