Command Line Interface Reference
This part of our documentation works as quick-reference to all the firmwire.py and firmwire_dev.py CLI arguments, and provides links about where they are covered. For more information about the single command line flags, you can also run FirmWire with the --help flag.
firmwire.py arguments
| Argument | Covered in | Description |
|---|---|---|
modem_file | Getting Started | The modem file FirmWire shall create an emulation environment for. Only mandatory argument(!) |
--consecutive-ports CONSECUTIVE_PORTS | Getting Started | Choose consecutive ports for the any listening sockets (e.g. QEMU's GDB & QMP), starting with the port provided. |
-h/--help | CLI reference | Show help for for different cli flags on commandline |
-w/--workspace WORKSPACE | Workspaces | Path to the workspace to use |
--snapshot-at SNAPSHOT_AT | Workspaces | Address and name for taking a snapshot. (Syntax: address,name) |
--restore-snapshot SNAPSHOT_NAME | Workspaces | Name of snapshot to be restored |
-t/--module INJECTED_TASK | Modkit | Module / Task to be injected to the baseband modem |
-S/--stop | Interactive exploration | Stop CPU after initializing the Machine. Useful for interactive exploration. |
-s/--gdb-server | Interactive exploration | Start GDB server on TCP port. Default is 1234. NOTE: this is a minimal GDB stub. |
--console | Interactive exploration | Spawn an ipython remote kernel that can be connected to from another terminal using jupyter console --existing |
--fuzz FUZZ | Fuzzing | Inject and invoke the passed AFL fuzz task module (headless). |
--fuzz-input FUZZ_INPUT | Fuzzing | Path the AFL test case (@@ should be sufficient) or just the path to a single test file. |
--fuzz-triage FUZZ_TRIAGE | Fuzzing | Invoke the fuzzer, but without an AFL front end. Enables debug hooks and saves code coverage. |
--fuzz-persistent FUZZ_PERSISTENT | Fuzzing | Enable persistent fuzzing with a loop count as the argument. |
--fuzz-crashlog-dir FUZZ_CRASHLOG_DIR | Fuzzing | Folder to which logs of all testcases (length testcase) for a crashing run in persistent mode |
--fuzz-crashlog-replay FUZZ_CRASHLOG_REPLAY | Fuzzing | Replay a persistent-mode crash trace written with fuzz-crashcase-dir. |
--fuzz-state-addr-file FUZZ_STATE_ADDR_FILE | Fuzzing | Textfile containing the hex-addresses of state-variables |
--full-coverage | Fuzzing | Enable full coverage collection (logs every executed basic block) |
--shannon-loader-nv_data NV_DATA | TBD | (Shannon only) Specify the NV_DATA to be used |
--mtk-loader-nv_data NV_DATA | TBD | (MediaTek only) Specify the NV_DATA to be used |
Developer options
Note: These arguments are mostly useful for development and debugging. As of now, they are part of firmwire.py, but will be moved to a custom firmwire_dev.py interface to clearly distinguish developer and user features in a future iteration of FirmWire.
| Argument | Covered in | Description |
|---|---|---|
--debug | TBD | Enable FirmWire debugging |
--debug-peripheral | TBD | Enable debugging for specified peripheralas |
--avatar-debug | TBD | Enable debug logging for Avatar2 |
--avatar-debug-memory | TBD | Enable Avatar2 remote memory debugging (useful when Peripherals crash) |
--unassigned-access-log | TBD | Print log messages when memory accesses to undefined memory occur |
--raw-asm-logging | TBD | Print assembly basic blocks as QEMU executes them. Useful for determining infinite loops. |
--trace-bb-translation | TBD | Print the address of each new Basic Block, useful to eval BBs reached during fuzzing. |