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 ideal combination of options for you so you don't have to.

Test kernel config

• 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 and search for a kernel config inside the firmware
• 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 (2022.02). 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.

Limitations:

• CVE-Search needs the database exposed by the host

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