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.01) and previous versions. 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!)
-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
-p [PROFILE]      Emba starts with a pre-defined profile (stored in ./scan-profiles)

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