Breaking Bits
Search…
Interactive Firmware Emulator Usage

Running Firmware Emulator

The interactive firmware emulator is built using Riposte and provide a CLI to interact with a firmware while attempting to emulate it. This page breaks down each of the commands offered by the CLI.
1
$ python fw_emulator.py
2
______ _
3
| ___(_)
4
| |_ _ _ __ _ __ _____ ____ _ _ __ ___
5
| _| | | '__| '_ ` _ \ \ /\ / / _` | '__/ _ \
6
| | | | | | | | | | \ V V / (_| | | | __/
7
\_| |_|_| |_| |_| |_|\_/\_/ \__,_|_| \___|
8
9
10
_____ _ _
11
| ___| | | | |
12
| |__ _ __ ___ _ _| | __ _| |_ ___ _ __
13
| __| '_ ` _ \| | | | |/ _` | __/ _ \| '__|
14
| |__| | | | | | |_| | | (_| | || (_) | |
15
\____/_| |_| |_|\__,_|_|\__,_|\__\___/|_|
16
17
18
emu:~$
Copied!

add_file

The add_file command will copy a file from the host to the built image's file system.
Parameter
Description
local_file
Path to file on the host to copy
remote_file
Path in firmware to place file

Example

1
emu:~$ add_file README.md /README.md
2
[+] loop device at /dev/mapper/loop22p1
3
loop deleted : /dev/loop22
4
[+] Added file
Copied!

add_network

The add_network command will attempt to create a tap adapter at run time connecting the device ip address and host ip address under the name interface.
Parameter
Description
device_ip
Device IP address to use
host_ip
Host IP address to use
iface_dev
Name of adapter to use

Example

1
emu:~$ add_network 192.168.0.253 192.168.0.254 tap_8
2
DEBUG:root:Adding 192.168.0.253 192.168.0.254 tap_8
3
[+] Successfully added network information
Copied!

del_file

The del_file command will delete a file inside of the firmware image given the file path.
Parameter
Description
file_path
Path to file in firmware to delete

Example

1
emu:~$ del_file /README.md
2
DEBUG:root:Deleting file /README.md
3
[+] loop device at /dev/mapper/loop22p1
4
/tmp/tmp499bjsa4/file_system/README.md
5
loop deleted : /dev/loop22
6
[+] Removed file
Copied!

export

The export command will export the given emulator with dependencies into a provided folder with. This includes a runner.sh file which can run the emulator, the kernel that was to emulate it, and the emulator image.
Parameter
Description
location
Path to export folder

Example

1
emu:~$ export test_image/
2
# Outside the emulator
3
$ ls test_image/
4
image.raw runner.sh vmlinux.mips
Copied!

force_network

The force_network command will attempt to force the router image to network with the host during boot by adding an additional forcenetworking script to run at boot.
Parameter
Description
None
1
emu:~$ force_network
2
[+] loop device at /dev/mapper/loop25p1
3
loop deleted : /dev/loop25
4
[+] loop device at /dev/mapper/loop25p1
5
loop deleted : /dev/loop25
6
[+] Files changed, ready to setup network
Copied!

force_tty_login

The force_tty login command will attempt to force the router image to drop to /bin/sh instead a general login binary in the inittab.
Parameter
Description
None
1
emu:~$ force_tty_login
2
DEBUG:root:Replacing default ttyS0 program to /bin/sh
3
[+] loop device at /dev/mapper/loop28p1
4
loop deleted : /dev/loop28
5
[+] Successfully replaced tty login with /bin/sh
Copied!

info

The info command will list out some information about the currently loaded image being emulated.
Parameter
Description
None
1
emu:~$ info
2
[+] Image Arch : mips
3
[+] Image Endi : Iend_BE
4
[+] Image Path : /tmp/tmptw5a2mdy/image.raw
5
[+] Image IP ADDR : ['192.168.0.253']
6
[+] Image Kernel : /home/chris/projects/firmware_emulator/binaries/vmlinux.mips
Copied!

make_image

The make_image command will take a given firmware image, run an extractor on it, look for a root file system, identify the architecture of the firmware, and prepare initial emulator configurations.
Note, this command may ask for your sudo password to mount the image.
Parameter
Description
firmware_path
A path to the firmware to make an image out of.
1
emu:~$ make_image WNAP320.zip
2
INFO:root:Using firmadyne extractor
3
4
/home/chris/projects/firmware_emulator/WNAP320.zip
5
>> MD5: 51eddc7046d77a752ca4b39fbda50aff
6
>> Tag: WNAP320.zip_51eddc7046d77a752ca4b39fbda50aff
7
>> Temp: /tmp/tmpz7vwg79o
8
>> Status: Kernel: True, Rootfs: False, Do_Kernel: False, Do_Rootfs: True
9
>>>> Zip archive data, at least v2.0 to extract, compressed size: 1197, uncompressed size: 2667, name: ReleaseNotes_WNAP320_fw_2.0.3.HTML
10
>> Recursing into archive ...
11
...SNIP...
12
Allocating group tables: done
13
Writing inode tables: done
14
Writing superblocks and filesystem accounting information: done
15
16
Warning: Recreating device nodes!
17
Removing /etc/scripts/sys_resetbutton!
18
loop deleted : /dev/loop28
19
[+] Image created!
Copied!

mount

The mount command will mount the active image and provide a path to the temporary mount location. The file system can be unmount using the unmount command.
Changes made to the mounted file system will persist into the image.
Parameter
Description
None
1
emu:~$ mount
2
[+] loop device at /dev/mapper/loop28p1
3
[+] Successfully mounted at /tmp/tmpijag8vt0/file_system
Copied!

remove_root_password

The remove_root_password command will attempt to remove the root password hidden in the /etc/passwd or /etc/shadow file.
Parameter
Description
None
1
emu:~$ remove_root_passwd
2
DEBUG:root:Removing root passwd from shadow and passwd
3
[+] loop device at /dev/mapper/loop30p1
4
loop deleted : /dev/loop30
5
[+] Removed root passwd
Copied!

run

The run command will run the current emulator image and if any networking is configured, run the networking commands as well.
To exit the emulator Ctrl+a, x
Parameter
Description
None
1
emu:~$ run
2
DEBUG:root:Press Ctrl+a then x to exit
3
DEBUG:root:sudo QEMU_AUDIO_DRV=none qemu-system-mips -M malta -net nic,vlan=0 -net socket,vlan=0,listen=:2000 -net nic,vlan=1 -net socket,vlan=0,listen=:2001 -net nic,vlan=2 -net socket,vlan=0,listen=:2002 -net nic,vlan=3 -net socket,vlan=0,listen=:2003 -kernel /home/chris/projects/firmware_emulator/binaries/vmlinux.mips -drive if=ide,format=raw,file=/tmp/tmpxs8clt64/image.raw -append "firmadyne.syscall=0 root=/dev/sda1 console=ttyS0 nandsim.parts=64,64,64,64,64,64,64,64,64,64 rdinit=/firmadyne/preInit.sh rw debug ignore_loglevel print-fatal-signals=1" -m 1024 -nographic
4
Ctrl A + X to leave
5
...Emulator TTY here...
Copied!

setup_network

The setup_network command will run the firmware image and monitor for the router's attempt to network itself. On successful identification this information is captured and transferred to the image's networking config and will be used on future runs. It will run for 60 seconds.
Parameter
Description
None
1
emu:~$ setup_network
2
DEBUG:root:Getting network information
3
DEBUG:root:Getting serial from 60 second run
4
DEBUG:root:['qemu-system-mips', '-M', 'malta', '-net', 'nic,vlan=0', '-net', 'socket,vlan=0,listen=:2000', '-net', 'nic,vlan=1', '-net', 'socket,vlan=0,listen=:2001', '-net', 'nic,vlan=2', '-net', 'socket,vlan=0,listen=:2002', '-net', 'nic,vlan=3', '-net', 'socket,vlan=0,listen=:2003', '-kernel', '/home/chris/projects/firmware_emulator/binaries/vmlinux.mips', '-drive', 'if=ide,format=raw,file=/tmp/tmpxs8clt64/image.raw', '-append', 'firmadyne.syscall=1 root=/dev/sda1 console=ttyS0 nandsim.parts=64,64,64,64,64,64,64,64,64,64 rdinit=/firmadyne/preInit.sh rw debug ignore_loglevel print-fatal-signals=1', '-m', '1024', '-serial', 'file:/tmp/tmpxs8clt64/qemu.initial.serial.log', '-serial', 'unix:/tmp/tmpxs8clt64/serial.S1,server,nowait', '-monitor', 'unix:/tmp/tmpxs8clt64/monitor,server,nowait', '-display', 'none']
5
qemu-system-mips: -net nic,vlan=0: 'vlan' is deprecated. Please use 'netdev' instead.
6
qemu-system-mips: warning: vlan 3 is not connected to host network
7
qemu-system-mips: warning: vlan 2 is not connected to host network
8
qemu-system-mips: warning: vlan 1 is not connected to host network
9
DEBUG:root:done
10
[{'ip': '192.168.0.100', 'host_ip': '192.168.0.99', 'dev': 'eth0', 'vlan': None, 'mac': None, 'tap_dev': 'tap_0', 'host_net_dev': 'tap_0'}]
11
[+] Network is accessible!
Copied!

unmount

The unmount command will unmount the active image
Changes made to the mounted file system will persist into the image.
Parameter
Description
None
1
emu:~$ unmount
2
loop deleted : /dev/loop30
Copied!