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.sh -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.sh -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.sh -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.sh -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:

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.sh -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.sh -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.sh -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
-j                No check for cve-search

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

System check
-d                Only checks dependencies
-F                Checks dependencies but ignore errors
-U                Check and apply available updates and exit

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)
-o                Activate online checks (e.g. upload and test with VirusTotal)
-r                Remove temporary firmware directory after testing
-b                Just print a random banner and exit

Modify output
-s                Prints only relative paths
-z                Adds ANSI color codes to log
-M                MATRIX mode (Warning: CPU intense)

Firmware details
-X [version]      Firmware version (double quote your input)
-Y [vendor]       Firmware vendor (double quote your input)
-Z [device]       Device (double quote your input)
-N [notes]        Testing notes (double quote your input)

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.sh -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.sh -l ./log -f / -e /var/lib/docker