# Interactive Firmware Emulator Usage ## Running Firmware Emulator The interactive firmware emulator is built using [Riposte](https://github.com/fwkz/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. ``` $ python fw_emulator.py ______ _ | ___(_) | |_ _ _ __ _ __ _____ ____ _ _ __ ___ | _| | | '__| '_ ` _ \ \ /\ / / _` | '__/ _ \ | | | | | | | | | | \ V V / (_| | | | __/ \_| |_|_| |_| |_| |_|\_/\_/ \__,_|_| \___| _____ _ _ | ___| | | | | | |__ _ __ ___ _ _| | __ _| |_ ___ _ __ | __| '_ ` _ \| | | | |/ _` | __/ _ \| '__| | |__| | | | | | |_| | | (_| | || (_) | | \____/_| |_| |_|\__,_|_|\__,_|\__\___/|_| emu:~$ ``` ### 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 ``` emu:~$ add_file README.md /README.md [+] loop device at /dev/mapper/loop22p1 loop deleted : /dev/loop22 [+] Added file ``` ### 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 ``` emu:~$ add_network 192.168.0.253 192.168.0.254 tap_8 DEBUG:root:Adding 192.168.0.253 192.168.0.254 tap_8 [+] Successfully added network information ``` ### 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 ``` emu:~$ del_file /README.md DEBUG:root:Deleting file /README.md [+] loop device at /dev/mapper/loop22p1 /tmp/tmp499bjsa4/file_system/README.md loop deleted : /dev/loop22 [+] Removed file ``` ### 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 ``` emu:~$ export test_image/ # Outside the emulator $ ls test_image/ image.raw runner.sh vmlinux.mips ``` ### 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 | | ``` emu:~$ force_network [+] loop device at /dev/mapper/loop25p1 loop deleted : /dev/loop25 [+] loop device at /dev/mapper/loop25p1 loop deleted : /dev/loop25 [+] Files changed, ready to setup network ``` ### 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 | | ``` emu:~$ force_tty_login DEBUG:root:Replacing default ttyS0 program to /bin/sh [+] loop device at /dev/mapper/loop28p1 loop deleted : /dev/loop28 [+] Successfully replaced tty login with /bin/sh ``` ### info The info command will list out some information about the currently loaded image being emulated. | Parameter | Description | | --------- | ----------- | | None | | ``` emu:~$ info [+] Image Arch : mips [+] Image Endi : Iend_BE [+] Image Path : /tmp/tmptw5a2mdy/image.raw [+] Image IP ADDR : ['192.168.0.253'] [+] Image Kernel : /home/chris/projects/firmware_emulator/binaries/vmlinux.mips ``` ### 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. | ``` emu:~$ make_image WNAP320.zip INFO:root:Using firmadyne extractor /home/chris/projects/firmware_emulator/WNAP320.zip >> MD5: 51eddc7046d77a752ca4b39fbda50aff >> Tag: WNAP320.zip_51eddc7046d77a752ca4b39fbda50aff >> Temp: /tmp/tmpz7vwg79o >> Status: Kernel: True, Rootfs: False, Do_Kernel: False, Do_Rootfs: True >>>> Zip archive data, at least v2.0 to extract, compressed size: 1197, uncompressed size: 2667, name: ReleaseNotes_WNAP320_fw_2.0.3.HTML >> Recursing into archive ... ...SNIP... Allocating group tables: done Writing inode tables: done Writing superblocks and filesystem accounting information: done Warning: Recreating device nodes! Removing /etc/scripts/sys_resetbutton! loop deleted : /dev/loop28 [+] Image created! ``` ### 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 | | ``` emu:~$ mount [+] loop device at /dev/mapper/loop28p1 [+] Successfully mounted at /tmp/tmpijag8vt0/file_system ``` ### 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 | | ``` emu:~$ remove_root_passwd DEBUG:root:Removing root passwd from shadow and passwd [+] loop device at /dev/mapper/loop30p1 loop deleted : /dev/loop30 [+] Removed root passwd ``` ### 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 | | ``` emu:~$ run DEBUG:root:Press Ctrl+a then x to exit 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 Ctrl A + X to leave ...Emulator TTY here... ``` ### 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 | | ``` emu:~$ setup_network DEBUG:root:Getting network information DEBUG:root:Getting serial from 60 second run 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'] qemu-system-mips: -net nic,vlan=0: 'vlan' is deprecated. Please use 'netdev' instead. qemu-system-mips: warning: vlan 3 is not connected to host network qemu-system-mips: warning: vlan 2 is not connected to host network qemu-system-mips: warning: vlan 1 is not connected to host network DEBUG:root:done [{'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'}] [+] Network is accessible! ``` ### unmount The unmount command will unmount the active image Changes made to the mounted file system will persist into the image. | Parameter | Description | | --------- | ----------- | | None | | ``` emu:~$ unmount loop deleted : /dev/loop30 ``` ### --- # 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://breaking-bits.gitbook.io/breaking-bits/interactive-firmware-emulator-usage.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.