Usage

Classic

Before running EMBA make sure that you have installed all dependencies.

Static firmware testing

• Execute EMBA with set parameters, e.g.

  sudo ./emba -l ./log -f ./firmware

• Path for logs and firmware path are necessary for testing a firmware image.
• You can specify multiple arguments.
• We are recommending to use the -p parameter and select one of the provided scan profiles:

  sudo ./emba -l ./log -f ./firmware -p ./scan-profiles/default-scan.emba

  Instead of looking for the right parameters for an optimized EMBA run, we've selected an mostly ideal combination of options for your quick start ... so you don't have to.

Test kernel config (under maintenance)

• Test only a kernel configuration with the kernel checker of checksec:

  sudo ./emba -l ./logs/kernel_conf -k ./kernel.config

• If you add -f ./firmware, it will ignore -k
• You can specify some arguments.

Good to know:

• sudo is necessary for some modules to run properly, e.g. S115_usermode_emulator.sh
• Currently only tested on Kali Linux (2023.04). We try to always update EMBA to the newest Kali Linux version and won't check if it stays compatible with older versions.
• EMBA needs quite a lot of free disk space for logging
• EMBA currently supports the following architectures: MIPS, ARM, PPC, x86 and x64
• As EMBA supports a lot of parameters we have introduced scan profiles. You can start EMBA for example with the following command line:

  sudo ./emba -l ~/emba_log -f ~/firmware -p ./scan-profiles/default-scan.emba

  This template sets multiple useful options for running EMBA

Docker

There is a simple docker-compose setup added, which allows you to run EMBA in a docker container. If you are using EMBA in the classic mode, you already are using our docker-compose setup. This chapter is now just for developing purposes.

Run interactive docker container:

EMBA="." FIRMWARE=/absolute/path/to/firmware LOG=/home/n/firmware_log/ docker-compose run emba

This will drop you a shell in the folder where EMBA has been added. The firmware is located at /firmware and the log directory at /log.

./emba -l /log -f /firmware -i

EMBA will do the work for you fully automatically: If you don't use the developer mode -D then it will start the EMBA docker container automatically.

sudo ./emba -l ./log -f /firmware

• You can specify some arguments.

Arguments

Print the possible command line options with

./emba -h

USAGE

Test firmware
-a [MIPS]         Architecture of the linux firmware [MIPS, ARM, x86, x64, PPC]
-A [MIPS]         Force Architecture of the linux firmware [MIPS, ARM, x86, x64, PPC] (disable architecture check)
-l [./path]       Log path
-f [./path]       Firmware path
-e [./path]       Exclude paths from testing (multiple usage possible)
-m [MODULE_NO.]   Test only with set modules [e.g. -m p05 -m s10 ... or -m p to run all p modules]
                  (multiple usage possible, case insensitive, final modules aren't selectable, if firmware isn't a binary, the p modules won't run)
-c                Enable cwe-checker
-g                Create grep-able log file in [log_path]/fw_grep.log
                  Schematic: MESSAGE_TYPE;MODULE_NUMBER;SUB_MODULE_NUMBER;MESSAGE
-E                Enables automated qemu emulation tests (WARNING this module could harm your host!)
-p [PROFILE]      EMBA starts with a pre-defined profile (stored in ./scan-profiles)
-Q                Enables automated qemu system emulation tests (WARNING this module could harm your host!)
-P                Overwrite auto MAX_MODS (maximum modules in parallel) configuration
-T                Overwrite auto MAX_MOD_THREADS (maximum threads per module) configuration

Developer options
-D                Developer mode - EMBA runs on the host without container protection
-S                STRICT mode - developer option to improve code quality (not enabled by default)
-i                Ignores log path check
-y                Overwrite log directory automaticially, even if it is not empty

Web reporter
-W                Activates web report creation in log path (overwrites -z)

System check
-d [1/2]          Only checks dependencies (1 - on host and in container, 2 - only container)
-F                Checks dependencies but ignore errors
-U                Check and apply available updates and exit
-V                Show EMBA version

Special tests
-k [./config]     Kernel config path
-C [container id] Extract and analyze a local docker container via container id
-x                Enable deep extraction - try to extract every file two times with binwalk (WARNING: Uses a lot of disk space)
-t                Activate multi threading (destroys regular console output)
-r                Remove temporary firmware directory after testing
-b                Just print a random banner and exit
-o [./path]       2nd Firmware path to diff against the main firmware file - diff mode only (no other firmware analysis)

Modify output
-s                Prints only relative paths
-z                Adds ANSI color codes to log
-B                Enables status bar (Warning: unstable on some firmware images)

Firmware details
-X [version]      Firmware version (versions aka 1.2.3-a:b only)
-Y [vendor]       Firmware vendor (alphanummerical values only)
-Z [device]       Device (alphanummerical values only)
-N [notes]        Testing notes (alphanummerical values only)

Help
-h                Prints this help message

Live systems (NOT officially supported)

For testing a live system with EMBA, run it as if you were testing static firmware, but with / as firmware path:

./emba -l ./log -f /

• Path for logs and firmware path are necessary for EMBA.
• It improves output and performance, if you exclude docker with the -e switch:

  ./emba -l ./log -f / -e /var/lib/docker