Skip to content

emba-install-use-guide.md

Latest commit

 

History

History
1701 lines (1218 loc) · 42.7 KB

emba-install-use-guide.md

File metadata and controls

1701 lines (1218 loc) · 42.7 KB
Raw

EMBA Newbie Installation and Usage Guide

Date: 2026-05-25

Project:

https://github.com/e-m-b-a/emba

Official installation wiki:

https://github.com/e-m-b-a/emba/wiki/Installation

Official usage wiki:

https://github.com/e-m-b-a/emba/wiki/Usage

How To Use This File

Read emba-quickstart.md first.
Use emba-analysis-walkthrough.md for real firmware-analysis commands after installation.
Use this file as the detailed reference when something is unclear.
Do not read this whole file linearly during a time-boxed assignment.

Compact Menu

Scope:

emba-quickstart.md is the setup checklist.
emba-analysis-walkthrough.md is the analysis checklist.
This file explains the why and gives fallback detail.

What EMBA Is

EMBA is a firmware security analyzer.

In plain English:

You give EMBA a firmware image.
EMBA extracts it, analyzes it, runs many checks, builds logs/reports, and gives you leads.

It can help find:

  • extracted filesystem contents
  • architecture information
  • interesting binaries
  • hardcoded credentials
  • outdated components
  • vulnerable software versions
  • suspicious scripts
  • weak configuration
  • SBOM information
  • possible attack surfaces
  • emulation opportunities

EMBA is not a magic vulnerability finder.

Its output is a starting point. A real finding still needs:

reachability -> root cause -> reproducer -> exploitability argument

Should You Use Kali, Ubuntu, Docker, or Something Else?

Short answer:

Best default: VMware Pro + current Kali VM + EMBA classic Docker mode
Good alternative: VMware Pro + Ubuntu 24.04.4 LTS VM + EMBA classic Docker mode
Avoid: native Windows, WSL as primary environment, ARM/Mac host as primary EMBA box

The official EMBA installation wiki strongly recommends running EMBA inside a virtual machine with a current Kali Linux. It also says Ubuntu Jammy 22.04 or Ubuntu 24.04 should work. EMBA is designed for x86-64, not ARM.

The official wiki recommends the default Docker/classic mode. In this mode, EMBA modules run inside Docker containers. This is safer and easier to maintain than running everything directly on the host.

Important correction:

sudo ./installer.sh -d does not require a prior full Kali upgrade.
The installer itself runs apt-get update and installs/prepares the host pieces it needs.

The installer still touches the host. It is not "Docker only." In default/docker mode it installs or prepares host-side pieces such as Docker, Docker Compose, Python venv support, basic helper packages, external/, the EMBA Python environment, Docker image pull/setup, and host-side data such as the NVD feed.

A Kali full-upgrade is optional OS hygiene for a fresh VM, not an EMBA requirement. If the VM is already clean and apt/Docker are healthy, do not keep changing the OS before EMBA.

Recommended Setup For You

Because you have VMware Pro:

Windows host
  -> VMware Pro
    -> Kali Linux VM or Ubuntu 24.04.4 VM
      -> Docker
      -> EMBA classic mode
      -> firmware samples in a dedicated folder

I would choose:

Kali VM if you want maximum compatibility with EMBA's tested workflow.
Ubuntu 24.04.4 VM if you want a cleaner general-purpose Linux workstation.

For an interview assignment, I would use Kali VM + EMBA classic Docker mode for the EMBA-specific box unless you already have a well-maintained Ubuntu VM.

For the broader firmware-research lab, I would split the roles:

Ubuntu 24.04.4 LTS VM = primary stable workstation for manual triage, Python tooling, reports, QEMU/GDB, and repeatable scripts
Kali VM = secondary tool-heavy VM for EMBA and Kali-packaged security tooling
Windows host = comfortable GUI workstation for IDA/Ghidra, browser, notes, and report writing

As of 2026-05-24, Ubuntu 26.04 LTS exists, but I would not choose it yet for this firmware lab. Use Ubuntu 24.04.4 LTS unless you specifically need a newer kernel or userspace feature. The reason is boring but important: firmware-analysis tools, install scripts, Docker images, EMBA dependencies, QEMU helpers, and older emulation frameworks are more likely to have been tested on Ubuntu 22.04/24.04 than on the newest LTS release.

Reconsider 26.04 after 26.04.1 or after your required tools explicitly document good 26.04 support.

VMware, VirtualBox, Hyper-V, or QEMU?

Because you have VMware Pro, use it.

Use VMware Workstation Pro rather than old Workstation Player if possible. Workstation Pro is the current practical choice for this lab because it gives better snapshot, clone, and VM-management workflow. Older Player installs can run a VM, but they are not the best fit for firmware research where rollback and repeatability matter.

Hypervisor Recommendation For This Task
VMware Workstation Pro Best default on a Windows host: snapshots, stable Linux desktop VMs, NAT/host-only networking, shared folders, and mature GUI workflow
Hyper-V Good Microsoft-native option, especially for Ubuntu, but less convenient for many security-lab workflows and USB/network experiments
VirtualBox Free and workable, but usually not worth choosing over VMware if you already have VMware Pro
QEMU/KVM Excellent on a Linux host; inside the VM, use QEMU for target firmware/binary emulation, not as your main Windows-host desktop hypervisor

Use this model:

Windows host
  -> VMware Pro
    -> Ubuntu/Kali lab VMs
      -> Docker for scanners
      -> QEMU user-mode/system-mode for target firmware

Do not spend time migrating to another hypervisor unless VMware gives you a specific blocker.

VMware Workstation Setup Best Practices

Use this baseline:

Primary VM: Ubuntu 24.04.4 LTS
Secondary VM: current Kali VMware image
Hypervisor: VMware Workstation Pro
Storage: fast SSD/NVMe
Network default: NAT
Host-only network: optional for local service testing
Shared folders: disabled or read-only
Snapshots: required

Before creating the VM:

  1. Enable Intel VT-x / VT-d or AMD-V / IOMMU in BIOS/UEFI.
  2. Keep enough resources for Windows:
    • do not give all CPU cores to the VM
    • leave at least 8 GB RAM for the host if possible
  3. Store the VM on an SSD/NVMe.
  4. Avoid putting the VM under synced cloud folders.
  5. Make a dedicated folder such as D:\VMs\iot-lab-ubuntu-24.04.4.

Recommended VM settings:

Use Custom / Advanced in the VMware wizard.

Typical is acceptable for casual use, but Custom is better here because you control firmware type, disk size/layout, network mode, and hardware before the OS is installed.

VMware wizard path for Ubuntu:

  1. File -> New Virtual Machine.
  2. Choose Custom (advanced).
  3. Use the newest hardware compatibility available.
  4. Choose I will install the operating system later if you want to avoid VMware Easy Install.
  5. Guest OS: Linux -> Ubuntu 64-bit.
  6. Name:
iot-lab-ubuntu-24.04.4
  1. Firmware: UEFI, Secure Boot off.
  2. CPU: 1 processor, 8 cores.
  3. RAM: 16 GB minimum, 24 GB preferred.
  4. Network: NAT.
  5. Disk: new virtual disk, 120 GB thin-provisioned, single file.
  6. Customize Hardware:
    • attach Ubuntu ISO
    • shared folders disabled
    • printer removed
    • USB only if needed
    • clipboard/drag-drop disabled for unknown firmware work
  7. Install Ubuntu.
  8. Update the OS.
  9. Install VMware tools:
sudo apt update
sudo apt full-upgrade -y
sudo apt install -y open-vm-tools open-vm-tools-desktop
sudo reboot
  1. Snapshot:
ubuntu-24.04.4-clean-updated

For Kali, prefer the official Kali VMware image:

  1. Download and extract the Kali VMware image.
  2. Open the .vmx in VMware Workstation Pro.
  3. Set CPU/RAM/network/shared-folder policy before installing EMBA.
  4. Update Kali.
  5. Snapshot before EMBA.
Firmware: UEFI
Secure Boot: off unless specifically needed
CPU: 8 vCPU minimum, 12 if available
RAM: 16 GB minimum, 24 GB preferred
Disk: 120 GB thin-provisioned minimum
Network adapter 1: NAT
Network adapter 2: Host-only, disabled until needed
USB: disabled unless needed
Printers: disabled
Shared folders: disabled initially
Clipboard/drag-drop: disabled while running unknown services
3D acceleration: optional; disable if the Linux desktop becomes unstable

Install guest tools inside Ubuntu/Kali:

sudo apt update
sudo apt install -y open-vm-tools open-vm-tools-desktop
sudo reboot

Snapshot names:

ubuntu-24.04.4-clean-updated
ubuntu-24.04.4-tools-installed
before-emba-install
before-firmware-run
before-emulation
before-final-reproducer-rerun

Snapshot rules:

  • snapshot before large installs
  • snapshot before EMBA
  • snapshot before running unknown services
  • snapshot before changing networking
  • do not keep a long chain forever; clone important states if needed

Network rules:

NAT = package installs and normal work
host-only = local service testing from Windows
bridged = avoid unless there is a specific reason

Hyper-V / WHP / Docker WSL2 note:

If VMware warns that Hyper-V, Device Guard, Credential Guard, VBS, or Windows Hypervisor Platform is enabled, this is usually informational.
Normal VMware VMs should still work.
Do not disable Hyper-V just because of the warning.

The key distinction for this lab:

Inside The VMware Linux VM Needs Nested Virtualization? Practical Result
Docker / EMBA Docker classic mode Usually no Should work normally
QEMU user-mode, such as qemu-mipsel-static or qemu-arm-static No Should work normally
QEMU system-mode with TCG software emulation No Should work, but slower
QEMU/KVM acceleration inside the VM Yes May be blocked when host Hyper-V/WHP is enabled
Running a VM inside the VM Yes This is true nested virtualization

So:

QEMU inside VMware is not automatically a nested virtualization problem.
Only QEMU/KVM acceleration needs nested virtualization.
Most firmware workflows use qemu-user-static or TCG and do not require /dev/kvm.

Check inside the VM:

ls -l /dev/kvm
qemu-system-x86_64 -accel help

If /dev/kvm is missing, you can still use QEMU TCG:

qemu-system-mips -accel tcg ...
qemu-system-arm -accel tcg ...

Leave Docker Desktop's WSL2 backend enabled on Windows unless you specifically need nested virtualization inside VMware. Disabling Hyper-V can break WSL2, Windows Sandbox, and Docker Desktop's WSL2 backend.

Shared-folder rules:

Default: disabled
If needed: read-only
Never: mount your whole Windows profile into a firmware-analysis VM

Keep the canonical firmware workspace inside the VM:

~/iot-fw-lab/firmware/
~/iot-fw-lab/runs/
~/iot-fw-lab/reports/

Copy only selected binaries, logs, screenshots, and final reports back to Windows.

VMware Ubuntu or WSL2 Ubuntu?

Use VMware Ubuntu as the primary lab.

Environment Recommendation
Ubuntu 24.04.4 LTS on VMware Best default for this task: snapshots, isolation, Docker scanners, QEMU/GDB, service testing, controlled networking, and reproducible evidence
Ubuntu on WSL2 Useful convenience shell for quick grep/Python/static triage, but not the main firmware lab

WSL2 is strong for development convenience, but firmware work benefits from a full disposable VM boundary. You will extract untrusted files, run unknown services, create device/config stubs, test network daemons, use QEMU, and sometimes need to roll back after breaking the environment. VMware snapshots are a major advantage.

Use this split:

VMware Ubuntu = real analysis lab
Kali VM = EMBA/security-tool-heavy lab
WSL2 = quick helper shell only
Windows = GUI RE, notes, browser, final report

Where Should IDA Pro and Ghidra Run?

For GUI reverse engineering, comfort matters.

Tool Best Default
IDA Pro Windows host, if your license/platform allows it
Ghidra GUI Windows host or Ubuntu VM; choose where the UI feels smoother
Ghidra headless / PyGhidra Ubuntu/Kali VM
GDB, gdb-multiarch, strace, QEMU, curl, service harnesses Ubuntu/Kali VM

Practical workflow:

Extract, run, emulate, and test firmware inside the Linux VM.
Open important binaries in IDA/Ghidra from the Windows host when GUI work is easier.
Keep scripts, QEMU, GDB, EMBA, and evidence collection inside the VM.

If shared folders become unreliable or slow, keep the canonical firmware workspace inside the VM and copy only selected binaries/logs to the host.

Hardware / VM Requirements

Official wiki guidance:

  • x86-64 architecture.
  • Kali Linux or Ubuntu 22.04/24.04.
  • 16 GB RAM or more.
  • 8 CPU cores minimum recommended.
  • Around 12 cores is smoother.
  • Rule of thumb: if you increase cores, increase RAM too. 12 cores means at least 24 GB RAM.
  • 30-100 GB free disk, more is better.
  • Docker image is large: prepared Docker image is around 14 GB, compressed download around 6 GB.

Practical disk guidance:

80 GB VM disk: too tight for comfortable EMBA work.
120 GB VM disk: workable minimum.
200 GB VM disk: better if you will keep logs, Docker images, and multiple firmware samples.

If your Kali VMware image was created with an 80 GB disk, expand the VMware virtual disk before serious EMBA use if you can. After expansion, check inside Linux with:

lsblk
df -h

Do not start a large EMBA install/scan if / has less than about 50 GB free.

If VMware shows a larger disk but Kali still shows an 80 GB root filesystem, grow the partition and filesystem.

Example:

sda      200G disk
sda1    80.1G part mounted on /

For the common Kali ext4 single-partition layout:

findmnt -no SOURCE,FSTYPE,SIZE,USED,AVAIL /
lsblk -f
sudo apt update
sudo apt install -y cloud-guest-utils e2fsprogs
sudo growpart /dev/sda 1
sudo resize2fs /dev/sda1
df -h /
lsblk

Expected result: /dev/sda1 and / grow close to the full VMware disk size.

If growpart fails, reboot and retry. If it still fails, use parted only after confirming there is no partition after sda1:

sudo parted /dev/sda print
sudo parted /dev/sda resizepart 1 100%
sudo resize2fs /dev/sda1
df -h /

If / is XFS, use xfs_growfs / instead of resize2fs.

Recommended VMware Pro VM:

OS: Kali current release or Ubuntu 24.04.4 LTS
CPU: 8 cores minimum, 12 if available
RAM: 16 GB minimum, 24 GB preferred
Disk: 120 GB thin-provisioned
Network: NAT
Snapshot 1: clean OS
Snapshot 2: after Docker + EMBA install
Snapshot 3: before analyzing unknown firmware

If your machine cannot spare 16 GB RAM:

  • EMBA may still run on smaller firmware.
  • Some modules may crash or trigger OOM.
  • Use fewer modules or avoid heavy emulation scans.
  • Watch dmesg for out-of-memory messages.

Before sudo ./installer.sh -d, on VMware/Kali:

xset s off
xset -dpms

Also disable screen lock and power management in the Kali XFCE settings:

Settings -> Screensaver -> disable
Settings -> Power Manager -> Display -> Never
Settings -> Power Manager -> System -> Never

This avoids a real failure mode where VMware guest throttling or screen lock interrupts long Docker/containerd writes. Symptoms can include a silent hang or containerd messages such as:

context canceled
write timeout
total=8821973491

Do not use ctr image pull as a workaround for Docker image pulls. ctr defaults to a different containerd namespace while Docker uses moby, so the image can be downloaded but invisible to Docker.

If Docker pulls are extremely slow or curl cannot resolve Docker/registry hosts, check DNS before blaming EMBA.

Known VMware NAT DNS failure pattern:

eth0 has an IP such as 192.168.206.x
gateway 192.168.206.2 is reachable
public IPs such as 1.1.1.1 are reachable
hostnames do not resolve

Temporary fix:

sudo cp -a /etc/resolv.conf /etc/resolv.conf.bak.$(date +%s)
sudo rm -f /etc/resolv.conf
printf 'nameserver 1.1.1.1\nnameserver 8.8.8.8\noptions timeout:2 attempts:2\n' | sudo tee /etc/resolv.conf
getent hosts registry-1.docker.io
curl -I https://registry-1.docker.io/v2/

HTTP/2 401 from the Docker registry is a good sign: the registry is reachable.

Full troubleshooting is in emba-quickstart.md, section "Slow Docker Pull Troubleshooting".

If the host has only 4 logical cores:

Use 2 vCPU for the VM.
Do not run Ubuntu VM and Kali VM at the same time.
Prefer Ubuntu minimal/static triage first.
Use Kali/EMBA only when needed.
Run EMBA quick-scan before any broad default scan.
Avoid full-system emulation unless the finding depends on it.
Run IDA/Ghidra GUI on Windows host if the VM feels slow.

Expected tradeoff:

  • Basic extraction, grep, qemu-user-static, GDB, curl, and script review are still realistic.
  • EMBA may work on smaller firmware, but broad scans can be slow or unstable.
  • FACT, Firmadyne/FirmAE, heavy QEMU system emulation, and fuzzing are poor fits for this hardware.
  • For an interview assignment, prioritize a web/script/config vulnerability path over full firmware boot emulation.

Safety Model

This matters.

Firmware may contain malicious scripts, weird init logic, vulnerable services, or code that behaves badly under emulation.

The official wiki warns not to use developer mode (-D) for normal use because it can execute malicious code and harm the host.

Use:

classic Docker mode

Avoid unless you know exactly why:

developer mode (-D)

Installation Path Overview

You have three practical paths:

Path Use When Recommendation
Kali VM + classic Docker install You want best EMBA compatibility Best default
Ubuntu 24.04.4 LTS VM + classic Docker install You want a cleaner Linux workstation Good
Docker-only manual run You are developing/debugging EMBA Not needed for a newbie

For normal use, do not overthink it:

clone EMBA
run installer with -d
run quick scan first
run broader default scan if time allows
read reports
validate manually

Official Fast Path

If you already have a fresh Kali VM with enough CPU, RAM, disk, and internet bandwidth, this is the shortest useful path:

git clone https://github.com/e-m-b-a/emba.git
cd emba
sudo ./installer.sh -d
sudo ./emba -l ~/log -f ~/firmware -p ./scan-profiles/quick-scan.emba

What to expect:

  • sudo ./installer.sh -d installs prerequisites and prepares EMBA's Docker-based environment.
  • The first install can take a long time because it downloads tools, Docker images, and vulnerability data.
  • The quick scan profile is a good first pass when you need useful leads quickly.
  • After quick scan, move to the broader default-scan.emba only if time and resources allow.
  • Before updating an old EMBA install, use the update section near the end of this guide.

Step 1: Create The VM

In VMware Pro:

  1. Create new VM.
  2. Install Kali or Ubuntu 24.04.4 LTS.
  3. Give it at least:
    • 8 CPU cores
    • 16 GB RAM
    • 100-120 GB disk
  4. Use NAT networking.
  5. Update the OS.

Kali:

This is optional OS hygiene, not an EMBA installer requirement:

sudo apt update
sudo apt full-upgrade -y
sudo reboot

After reboot, cleanup is optional. With a large VM disk, prefer only:

sudo apt clean
df -h /

Run autoremove only if disk pressure matters, and inspect it first:

sudo apt autoremove --dry-run

If it proposes removing Java, Ghidra-related dependencies, Docker pieces, desktop components, or anything you recognize as useful, skip it. With a 200 GB VM disk, there is no need to risk changing the tool environment just to reclaim a little space.

Ubuntu:

sudo apt update
sudo apt upgrade -y
sudo reboot

Take a VMware snapshot:

snapshot-0-clean-updated-os

Step 2: Install Basic Host Packages

EMBA's installer handles most dependencies, but these basics help:

sudo apt update
sudo apt install -y git curl wget ca-certificates gnupg lsb-release docker.io docker-compose-v2

Enable Docker:

sudo systemctl enable docker
sudo systemctl start docker
sudo docker run hello-world

Optional: add your user to Docker group:

sudo usermod -aG docker "$USER"
newgrp docker

EMBA often runs with sudo, so Docker group membership is convenient but not essential.

Step 3: Clone EMBA

Choose a workspace:

mkdir -p ~/tools ~/firmware ~/emba_logs
cd ~/tools
git clone https://github.com/e-m-b-a/emba.git
cd emba

Check what you cloned:

ls
git log -1 --oneline

Step 4: Install EMBA Classic Docker Mode

Run:

sudo ./installer.sh -d

What this does:

  • installs host dependencies needed by EMBA
  • sets up Docker-based classic mode
  • downloads/builds the EMBA Docker environment
  • prepares a large toolchain used by EMBA modules

Important:

  • This can take time.
  • The Docker image is large.
  • Disk usage can grow quickly.
  • Use a VM snapshot before and after.

Take a snapshot after install:

snapshot-1-emba-installed

Step 5: Confirm EMBA Runs

From the EMBA directory:

sudo ./emba -h
sudo ./emba -V

Dependency check:

sudo ./emba -d 1

If you only want container dependency check:

sudo ./emba -d 2

If these fail:

  • check Docker is running
  • check free disk space
  • check internet access
  • check VM RAM
  • re-read the first error, not the last error

Step 6: Prepare A Firmware Folder

Do not analyze firmware from random places.

Create a clean workspace:

mkdir -p ~/firmware/assignment1
mkdir -p ~/emba_logs/assignment1
cp /path/to/firmware.bin ~/firmware/assignment1/
sha256sum ~/firmware/assignment1/firmware.bin | tee ~/firmware/assignment1/sha256.txt
file ~/firmware/assignment1/firmware.bin | tee ~/firmware/assignment1/file.txt

Record:

  • source of firmware
  • assignment scope
  • firmware hash
  • file name
  • date

Step 7: First Static Scan

For a first fast pass, use EMBA's quick scan profile:

cd ~/tools/emba
sudo ./emba -l ~/emba_logs/assignment1/quick_scan \
  -f ~/firmware/assignment1/firmware.bin \
  -p ./scan-profiles/quick-scan.emba

Use this when:

  • you are doing an interview assignment
  • you want the first useful output quickly
  • you are still deciding where to focus
  • you do not want to wait for a broad/deep scan before starting manual work

Then run the broader default scan profile:

cd ~/tools/emba
sudo ./emba -l ~/emba_logs/assignment1/default_scan \
  -f ~/firmware/assignment1/firmware.bin \
  -p ./scan-profiles/default-scan.emba

This is the standard first run.

Expected:

  • logs under ~/emba_logs/assignment1/default_scan
  • console output
  • extraction results
  • component/vulnerability leads
  • possible web report, depending on options/profile

Do not enable emulation on the first run unless you know why.

Practical interview workflow:

start quick-scan
  -> inspect extracted filesystem manually while it runs
  -> choose candidate surfaces
  -> start default-scan only if time/resources allow

Step 8: First SBOM Scan

If you care about components and version risk:

cd ~/tools/emba
sudo ./emba -l ~/emba_logs/assignment1/sbom \
  -f ~/firmware/assignment1/firmware.bin \
  -p ./scan-profiles/default-sbom.emba

Use this to find:

  • components
  • versions
  • package metadata
  • likely vulnerable libraries

But remember:

old component != confirmed exploitable vulnerability

You still need reachability.

Step 9: Optional Web Report

If you want a web report, use -W.

Example:

cd ~/tools/emba
sudo ./emba -l ~/emba_logs/assignment1/web_report \
  -f ~/firmware/assignment1/firmware.bin \
  -p ./scan-profiles/default-scan.emba \
  -W

After the scan, inspect the log directory for generated report files.

Use the report for navigation, not as final truth.

Step 10: Searching Logs

EMBA logs are already text files. After any scan, search the log directory directly:

rg -n "password|credential|CVE|critical|command|injection|private key" ~/emba_logs/assignment1/default_scan

If you want formatted/color log output, use -z:

sudo ./emba -l ~/emba_logs/assignment1/formatted_scan \
  -f ~/firmware/assignment1/firmware.bin \
  -p ./scan-profiles/default-scan.emba \
  -z

Step 11: User-Mode Emulation Scan

EMBA has options for QEMU user-mode emulation. The usage wiki warns that these emulation options can be risky and should be treated carefully.

Do this only after:

  • the static scan finished
  • you identified interesting binaries
  • you took a VM snapshot

Option:

sudo ./emba -l ~/emba_logs/assignment1/usermode \
  -f ~/firmware/assignment1/firmware.bin \
  -p ./scan-profiles/default-scan.emba \
  -E

What -E means:

  • enables automated QEMU user emulation tests

Risk:

  • emulated firmware code may execute
  • the official usage help warns these options could harm your host

Because you are in a VM and Docker mode, risk is reduced, but not gone.

Step 12: System Emulation Scan

System emulation is more ambitious.

Option:

sudo ./emba -l ~/emba_logs/assignment1/system_emulation \
  -f ~/firmware/assignment1/firmware.bin \
  -p ./scan-profiles/default-scan.emba \
  -Q

What -Q means:

  • enables automated QEMU system emulation tests

Use only if:

  • you have time
  • static analysis suggests a reachable service
  • you took a snapshot
  • you can tolerate failure

Do not make full-system emulation the first thing you try in a 48-hour assignment.

Step 13: Firmware Diffing

If you have two firmware versions:

sudo ./emba -l ~/emba_logs/assignment1/diff \
  -f ~/firmware/assignment1/new.bin \
  -o ~/firmware/assignment1/old.bin

Use for:

  • patch diffing
  • finding fixed bugs
  • identifying changed components

For an interview assignment, firmware diffing can be high-value if both versions are provided.

Step 14: How To Read EMBA Output

Do not read every line.

Use this order:

  1. Was the firmware extracted?
  2. What architecture was detected?
  3. What filesystem was found?
  4. What services/web files/scripts were found?
  5. Were hardcoded secrets found?
  6. Were known-vulnerable components found?
  7. Were suspicious shell scripts found?
  8. Were interesting binaries found?
  9. Did emulation succeed or fail?
  10. Which finding is most reachable?

Create your own file:

03_emba_triage.md

Template:

# EMBA Triage Notes

## Firmware
- Hash:
- Architecture:
- Filesystem:
- Extraction status:

## High-Value Surfaces
- Web:
- Network daemons:
- Update logic:
- Credentials:
- Interesting binaries:

## EMBA Leads
| Lead | Evidence path | Reachability | Next manual check |
| --- | --- | --- | --- |

## Selected Candidate
- Why this one:
- What must be verified:

What EMBA Findings Are Good For

Good:

  • finding likely attack surfaces
  • finding strings/secrets
  • finding old components
  • finding risky scripts
  • finding web roots
  • finding extraction paths
  • building SBOM-style inventory
  • generating a broad first pass quickly

Not enough by itself:

  • CVE lists
  • "potentially vulnerable" messages
  • old package versions
  • hardcoded string with no service path
  • unsafe C function with no attacker-controlled path

Reviewer-safe wording:

EMBA identified <lead>. I manually verified reachability through <file/route/service> and confirmed root cause in <file/function>.

Weak wording:

EMBA found many critical vulnerabilities.

EMBA In A 48-Hour Interview Assignment

Recommended flow:

Hours 0-2

  • run file, sha256sum, binwalk
  • start EMBA quick-scan.emba

Hours 2-5

  • while EMBA runs, manually inspect extracted files if available
  • build attack surface table
  • start broader default-scan.emba only if quick scan finished and resources allow

Hours 5-8

  • read EMBA top leads
  • choose one reachable finding candidate

Hours 8-16

  • manually verify selected candidate
  • use Ghidra/shell/curl/QEMU as needed

Hours 16-30

  • build reproducer
  • document root cause
  • write exploitability argument

Hours 30-48

  • final report
  • include EMBA as one tool in the methodology
  • do not submit EMBA output as the report

Kali vs Ubuntu

Kali

Use Kali if:

  • you want maximum alignment with EMBA's tested setup
  • you want many security tools preinstalled
  • you are okay with a security-distro workflow

Pros:

  • most compatible with EMBA's own testing
  • good security tooling
  • convenient for firmware/security work

Cons:

  • can be noisy
  • not always ideal as a clean dev workstation

Ubuntu 24.04.4 LTS

Use Ubuntu if:

  • you want a clean general-purpose Linux VM
  • you prefer stable workstation behavior
  • you are comfortable installing tools yourself

Pros:

  • clean
  • predictable
  • good for development
  • supported by EMBA docs for Jammy/24.04-era environments

Cons:

  • may require more manual package fixes than Kali

Recommendation

For a short assignment:

Kali + Docker/classic EMBA

For a long-term personal lab:

Ubuntu 24.04.4 LTS + Docker/classic EMBA + separate Kali/AttifyOS VM as backup

Docker: What It Means Here

You do not need to be a Docker expert.

In EMBA classic mode:

  • EMBA uses Docker to isolate its modules and dependencies.
  • The host still needs Docker and some dependencies.
  • You launch EMBA normally with sudo ./emba ....
  • EMBA starts the container automatically.

The official usage wiki says the explicit Docker shell mode is mostly for development. For normal use, classic mode already uses Docker.

Do not confuse:

classic mode using Docker = recommended
developer mode (-D) = avoid unless developing EMBA

Common Errors

Docker Not Running

Symptom:

Cannot connect to Docker daemon

Fix:

sudo systemctl start docker
sudo systemctl enable docker
sudo docker run hello-world

Out Of Disk

Symptom:

No space left on device

Check:

df -h
docker system df

Cleanup:

sudo docker system prune

Be careful: this removes unused Docker data.

Out Of Memory

Symptom:

  • EMBA crashes
  • desktop freezes
  • kernel OOM messages

Check:

dmesg | rg -i "oom|killed process"
free -h

Fix:

  • increase VM RAM
  • reduce cores
  • avoid heavy emulation
  • run smaller scan/profile

Old Docker Compose

EMBA warns that older distributions may ship old Docker Compose versions.

Fix:

  • use current Kali or Ubuntu 24.04.4 LTS
  • install docker-compose-v2
  • avoid old Ubuntu releases

Permission Problems

Run EMBA as the docs show:

sudo ./emba ...

Also avoid paths with spaces.

Use:

~/firmware/assignment1/firmware.bin
~/emba_logs/assignment1/

Not:

~/Downloads/My Firmware Stuff/fw.bin

Good Beginner Commands

Help:

sudo ./emba -h

Version:

sudo ./emba -V

Dependency check:

sudo ./emba -d 1

Default static scan:

sudo ./emba -l ~/emba_logs/fw1/default \
  -f ~/firmware/fw1/firmware.bin \
  -p ./scan-profiles/default-scan.emba

SBOM scan:

sudo ./emba -l ~/emba_logs/fw1/sbom \
  -f ~/firmware/fw1/firmware.bin \
  -p ./scan-profiles/default-sbom.emba

Web report:

sudo ./emba -l ~/emba_logs/fw1/web \
  -f ~/firmware/fw1/firmware.bin \
  -p ./scan-profiles/default-scan.emba \
  -W

Formatted log:

sudo ./emba -l ~/emba_logs/fw1/formatted \
  -f ~/firmware/fw1/firmware.bin \
  -p ./scan-profiles/default-scan.emba \
  -z

User-mode emulation, only after snapshot:

sudo ./emba -l ~/emba_logs/fw1/usermode \
  -f ~/firmware/fw1/firmware.bin \
  -p ./scan-profiles/default-scan.emba \
  -E

System emulation, only if needed:

sudo ./emba -l ~/emba_logs/fw1/system \
  -f ~/firmware/fw1/firmware.bin \
  -p ./scan-profiles/default-scan.emba \
  -Q

How To Use EMBA With The IoT Firmware Guide

Use EMBA in this role:

lead generator + extraction helper + SBOM/report helper

Do not use EMBA as:

final vulnerability judge

Protect Host And Network For EMBA Emulation

The EMBA warning about -E means firmware emulation may execute unknown firmware code or start unknown services. Do not expose that to your LAN.

VMware network profiles:

Phase VMware Network Why
Install/update/Docker pull NAT Internet access without exposing VM as a LAN host
Static scan NAT is fine No firmware services should be intentionally exposed
User-mode emulation -E / service testing Host-only preferred; disconnect NAT if internet is not needed Host can reach VM, LAN cannot
Unknown service testing Host-only, shared folders off/read-only Limits blast radius
Bridged Avoid VM appears directly on your LAN

Recommended before -E:

Power off VM.
Disconnect NAT or switch to Host-only.
Ensure Bridged is not enabled.
In Edit -> Virtual Network Editor, use VMnet1 / Host-only and do not bridge it to a physical adapter.
Do not configure VMware NAT port forwarding for emulated firmware services.
Disable shared folders or make them read-only.
Disable clipboard/drag-drop.
Snapshot.
Boot and run the emulation test.

Inside Kali:

ip -br addr
ip route

For the safest emulation profile, ip route should not show a normal NAT default route unless the test needs internet access. Avoid binding unknown services to 0.0.0.0 while NAT/bridged networking is connected.

Optional firewall:

sudo apt install -y ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw enable
sudo ufw status verbose

Only add inbound firewall allows for something you need, such as SSH from the VMware host-only subnet. Do not broadly allow your whole LAN.

For a time-boxed assignment, do not start with -E. Run static/quick scan first, pick a candidate, then use emulation only if it helps prove reachability or reproduce behavior.

Workflow:

1. Run Binwalk/manual extraction.
2. Run EMBA default scan.
3. Build attack surface table.
4. Use EMBA output to choose candidates.
5. Manually verify one candidate.
6. Write root cause and exploitability.

What To Put In Your Final Report

Good:

I used EMBA vX as an automated firmware triage tool. EMBA identified several leads, including <lead>. I manually verified <specific finding> by tracing <route/file/function> and reproducing <request/crash/output>.

Include:

  • EMBA version
  • command used
  • scan profile
  • firmware hash
  • log path
  • selected finding
  • what was manually verified
  • what was not verified

Do not include:

  • giant raw EMBA logs
  • every CVE candidate
  • unverified "critical" claims
  • screenshots without explanation

Minimal Report Snippet

## Automated Triage With EMBA

Command:

```bash
sudo ./emba -l ~/emba_logs/fw1/default \
  -f ~/firmware/fw1/firmware.bin \
  -p ./scan-profiles/default-scan.emba
```

Relevant EMBA leads:

| Lead | EMBA evidence | Manual verification |
| --- | --- | --- |
| Web root found | extracted `/www` | confirmed routes in `/etc/init.d/rcS` |
| Hardcoded credential candidate | string in `/etc/passwd` | checked service exposure |
| Suspicious shell command | `/www/cgi-bin/ping.cgi` | reproduced command injection with safe `sleep` payload |

Conclusion:

EMBA accelerated discovery, but the confirmed finding is based on manual review and reproduction.

Updating EMBA

From the EMBA directory:

git pull
sudo ./emba -U

The official update wiki breaks update work into a few pieces.

Update the EMBA repository:

cd ~/tools/emba
git pull

Update the EMBA Docker base image:

docker pull embeddedanalyzer/emba

Update the NVD CVE JSON data feed used by EMBA:

cd ~/tools/emba/external/nvd-json-data-feeds
sudo git pull

If you want future NVD feed updates without sudo, fix ownership:

sudo chown "$USER":"$USER" ~/tools/emba/external/nvd-json-data-feeds -R
cd ~/tools/emba/external/nvd-json-data-feeds
git pull

Update cve-bin-tool data if you use that path:

pip3 install --user cve-bin-tool
cve-bin-tool --update now -n json-mirror
cve-bin-tool --export ./config/cve-database.db

The update wiki notes that the dependency checker only checks for an available cve-database.db; you still need to keep track of freshness yourself.

Before updating:

  • snapshot the VM
  • record current version
  • avoid updating in the middle of an active assignment unless necessary

For a time-boxed interview assignment:

If EMBA already works, do not update mid-assignment.
If EMBA is stale/broken before starting, update before analyzing firmware.

Fresh Pull But Docker Image Updates Available

If the dependency check says:

Docker image version - Updates available

right after you pulled the image, do not assume the 8 GB download was wasted.

EMBA checks this by comparing your local embeddedanalyzer/emba:latest digest against EMBA's online-check metadata. The relevant upstream logic reads EMBA_CONTAINER_HASH.txt from the online-check repo and compares it with:

docker inspect --format='{{.RepoDigests}}' embeddedanalyzer/emba:latest

That means the warning is a digest mismatch, not a clock/time check.

Use this sequence:

cd ~/tools/emba
sudo ./emba -V
sudo ./emba -d 1
docker image inspect embeddedanalyzer/emba:latest --format '{{json .RepoDigests}}'
grep -n "image:" docker-compose.yml
docker images | grep embeddedanalyzer

Then update the supported way:

cd ~/tools/emba
sudo ./emba -U
sudo ./emba -d 1

If the image warning remains, try one explicit pull:

docker pull embeddedanalyzer/emba:latest
cd ~/tools/emba
sudo ./emba -d 1

Interpretation:

Result Meaning Action
Docker image version - ok Local digest matches online-check metadata. Proceed.
Docker image version - Updates available, but the Docker-compose EMBA image version line is ok Digest mismatch only; Docker image required by compose exists. Usually proceed, record warning.
Docker-compose EMBA image version - Updates available appears in EMBA output Compose expects an image tag/version you do not have locally. Pull/tag the expected image before scanning.
Docker cannot start or container dependency check fails Real setup problem. Fix Docker/image before scanning.

Docker-compose EMBA image version is the label of a status line printed by sudo ./emba -d 1. Do not type it as a shell command.

During an interview assignment, do not remove the existing image unless you are willing to re-download it. A working older image is better than losing the only runnable EMBA image while fighting Docker Hub or VM networking.

EMBA Book

The EMBA book/wiki is worth reading after the first successful scan.

Start here:

For an interview assignment, do not read the whole book first. Use it as a reference when you hit a specific question:

extraction problem -> chapter 1
static module meaning -> chapter 2
user-mode emulation -> chapter 3
system emulation -> chapter 4
SBOM/CVE output -> chapter 5
report output -> chapter 6

Cleanup

EMBA logs can be large.

Check disk:

du -sh ~/emba_logs/*
df -h
docker system df

Archive useful logs:

tar -czf assignment1_emba_logs.tar.gz ~/emba_logs/assignment1

Remove unneeded logs:

rm -rf ~/emba_logs/old_run

Do not delete logs before final report is done.

Final Recommendation

For a newbie with VMware Pro:

Use Ubuntu 24.04.4 LTS VM as the primary firmware research workstation.
Use Kali VM as the EMBA/security-tool-heavy VM.
Use VMware Pro snapshots.
Use EMBA classic Docker mode on Kali unless your Ubuntu VM is already well maintained.
Avoid developer mode.
Start with quick-scan.emba, then default-scan.emba if time/resources allow.
Use SBOM scan if component/version analysis matters.
Try emulation only after snapshot and only when it supports a concrete finding.
Run GUI IDA/Ghidra on the Windows host if that is more comfortable.
Run QEMU/GDB/strace/EMBA inside the Linux VM.
Manually verify everything important.

EC2 For EMBA

AWS free-tier micro/small instances are not a good replacement for your local machine for EMBA.

Reason:

EMBA wants 16 GB RAM or more, 8 cores recommended, large Docker images, and lots of disk.
Free-tier micro instances are for light Linux learning, not firmware analysis.

If you rent a short-lived EC2 instance for EMBA, use:

OS: Ubuntu 24.04 LTS x86_64
Minimum: 4 vCPU / 16 GB RAM
Better: 8 vCPU / 32 GB RAM
Disk: 200-500 GB gp3 EBS
Security group: SSH only from your IP
Lifecycle: stop/terminate when finished

Reasonable instance families to evaluate:

m7i-flex.xlarge or m7i.xlarge: 4 vCPU / 16 GB
m7i-flex.2xlarge or m7i.2xlarge: 8 vCPU / 32 GB
c7i-flex.2xlarge: 8 vCPU / 16 GB if CPU matters more than RAM

Before uploading firmware to cloud, confirm the assignment allows it.

Sources