embedded_linux_audit

embedded_linux_audit (ela) is a static C binary for security assessment of embedded Linux devices. It runs directly on the target — no runtime dependencies, no package manager, no installation required — and covers U-Boot analysis, Linux system introspection, EFI/BIOS option ROM inspection, TPM 2.0 interrogation, and remote exfiltration of collected data.

Command groups

uboot — Boot environment and image analysis

Subcommand	Description
uboot env	Scan MTD/UBI/block devices for U-Boot environment partitions; emit fw_env.config entries and raw variable dumps
uboot image	Detect uImage and FIT headers on flash/block devices; resolve load addresses and extract image bytes
uboot audit	Run compiled security rules against U-Boot environment data to check Secure Boot posture, environment write-protection, and command-line integrity

linux — Operating system introspection

Subcommand	Description
linux dmesg	Capture the kernel ring buffer; dmesg watch for continuous streaming
linux execute-command	Run an arbitrary shell command and collect output
linux list-files	Enumerate files under a path (optionally recursive)
linux list-symlinks	Enumerate symbolic links under a path (optionally recursive)
linux grep	Search file contents under a directory for a pattern
linux download-file	Fetch a file from an HTTP(S) URL to a local path
linux netstat	List listening and active TCP/UDP sockets with PID/program data
linux remote-copy	Upload a local file to a remote HTTP(S) endpoint
linux pcap	Capture packets from an interface as pcap data; stream to the agent API over WebSocket when --output-http is configured
linux coredump	Configure kernel coredump collection to /tmp; with --output-http, POST captured cores to the agent API
linux ssh client	Open an interactive SSH session (via libssh)
linux ssh copy	Transfer files over SFTP
linux ssh tunnel	Establish a reverse SSH tunnel
linux ssh socks	Set up a SOCKS proxy over SSH
linux process watch on <needle>	Start watching for processes whose command line matches <needle>; emits a record each time the matching PID set changes (restart detected)
linux process watch off <needle>	Stop watching a previously registered needle
linux process watch list	List all active needles and their current matching PIDs
linux gdbserver <PID> <PORT>	Attach to a running process and expose a GDB remote stub on the given TCP port; connect with target remote <agent-ip>:<PORT> in gdb-multiarch
linux modules	List, load, unload, and inspect kernel modules directly through /proc/modules, module files, and module syscalls

efi — EFI/UEFI inspection

Subcommand	Description
efi dump-vars	Enumerate all EFI runtime variables with attributes and decoded values
efi orom	List and extract EFI PCI option ROMs

bios — Legacy BIOS inspection

Subcommand	Description
bios orom	List and extract legacy PCI option ROMs

tpm2 — TPM 2.0 interrogation

Subcommand	Description
tpm2 getcap	Query TPM capabilities and properties
tpm2 pcrread	Read PCR values
tpm2 nvreadpublic	Read NV index metadata
tpm2 createprimary	Create a primary object and serialize the context

transfer — Remote terminal and data exfiltration

Subcommand	Description
transfer --remote <host:port>	Connect to a TCP listener, transfer the agent binary, and drop into an interactive session
transfer --remote ws[s]://...	Connect over WebSocket (plain or TLS) to the ELA terminal server and start an interactive session

Interactive shell

Running ela with no arguments starts a REPL that exposes all command groups above, supports tab completion (when built with readline), maintains command history, and provides a set built-in for configuring per-session environment variables (ELA_API_URL, ELA_OUTPUT_FORMAT, ELA_QUIET, etc.).

Global flags

Flag	Description
--output-format <txt|csv|json>	Output encoding (default: txt)
--output-tcp <ip:port>	Stream command output to a TCP listener
--output-http <url>	POST command output to an HTTP(S) endpoint; linux pcap uses the same base URL to open ws(s)://.../pcap/<mac>
--script <path|url>	Execute commands from a local or remote script file
--remote <target>	Connect to a reverse-shell/WebSocket terminal before starting
--api-key <key>	Bearer token for API server authentication
--insecure	Disable TLS certificate and hostname verification
--quiet	Suppress informational output

API keys are also read from the ELA_API_KEY environment variable or /tmp/ela.key.

Companion server components

Agent helper API (api/agent/)

A Node.js HTTP(S) server that acts as a collection point for agent data and a distribution server for binaries and test scripts.

• Accepts POST /:mac/upload/:type for command output, dmesg, coredumps, file contents, EFI variables, option ROM data, U-Boot images, and environment dumps
• Accepts ws(s)://host/pcap/<mac> for streaming linux pcap captures as binary pcap data
• Normalizes uploads into a PostgreSQL schema and stores raw payloads alongside relational records
• Optionally keeps runtime file artifacts under timestamped per-device directories in api/agent/data/
• Serves release binaries (with optional auto-download from GitHub), test scripts, and U-Boot environment files
• Optional bearer token authentication (--validate-key)
• Optional HTTPS with self-signed certificate (--https)

cd api/agent && npm install && npm start -- --host 0.0.0.0 --port 5000

To reuse the latest timestamped artifact directory instead of creating a new one on startup:

cd api/agent && npm start -- --reuse-last-data-dir

See docs/api/agent/helper-server.md for full options.

WebSocket terminal server (api/terminal/)

A Node.js WebSocket server with a terminal TUI for managing multiple simultaneous agent sessions. Each agent that connects via transfer --remote ws://... appears as a named session the operator can attach to, send commands to, and detach from without dropping the connection.

• Persists terminal connection events in PostgreSQL
• Stores operator-assigned device aliases in PostgreSQL and maps them to upload records by MAC address

cd api/terminal && npm install && npm start

See docs/api/terminal/index.md.

nginx reverse proxy (nginx/ela.conf)

An example nginx configuration that exposes the server components behind a single frontend — HTTP on port 80 and HTTPS on port 443 — routing /terminal/<mac> to the WebSocket terminal server, /gdb/ to the GDB bridge, /pcap/<mac> to the agent API WebSocket receiver, and everything else to the agent helper API.

See docs/api/nginx.md.

Docker Deployment

The repository now includes a containerized deployment path with PostgreSQL, the agent API, the terminal WebSocket API, and nginx fronting both services.

docker compose up --build

The default stack exposes:

• http://localhost/ → agent helper API
• http://localhost/terminal/<mac> → terminal WebSocket endpoint
• http://localhost/pcap/<mac> → pcap capture WebSocket endpoint

The agent API container runs database migrations automatically on startup. Compose defaults target the bundled PostgreSQL container (defined in docker-compose.override.yml) using the ela/ela credentials.

To use an existing PostgreSQL server instead of the bundled container, set ELA_DB_HOST (and the other ELA_DB_* variables) and start the base file only — ELA_DB_HOST=db.example.com docker compose -f docker-compose.yml up -d — or pass --db-host to nginx/install.sh. See docs/api/docker-operations.md.

For operational details, see docs/api/docker-operations.md.

Portable static release builds

GitHub Releases contain fully static binaries for the following architectures, compiled via Zig + musl cross-compilation:

x86_64 · x86 · arm32-le · arm32-be · aarch64-le · aarch64-be · mips-le · mips-be · mips64-le · mips64-be · powerpc-le · powerpc64-be · powerpc-be · riscv32 · riscv64

No target-side dependencies. Drop the binary on the device and run it.

See docs/agent/getting-started/build.md for the full build matrix and local build instructions.

Documentation

• Documentation index
• Manual assessment checklist

Licensing

• The embedded_linux_audit agent and associated build/test material: GPL-3.0-or-later (COPYING)
• The helper API under api/ and other non-agent files: MIT (LICENSE.api)
• Third-party code under third_party/: each component's own license

See LICENSE for the full breakdown.