Skip to content

Firmware analysis guide

How to identify components and check the SBOM, licenses, and vulnerabilities in a network-device firmware binary (.bin, .img, squashfs, and so on). Use it when you only have the binary and no source, such as firmware received from a supplier.

How it works

Firmware is a single file that packs and seals an operating system and dozens of libraries. Feeding a firmware file straight into a normal scan detects almost nothing and yields an empty SBOM. Firmware analysis first unpacks the contents, then identifies components.

  1. Unpack the firmware (unblob, falling back to unsquashfs, 7z, then binwalk) to extract the rootfs.
  2. Use syft to identify components installed by a package manager (opkg, dpkg, apk, rpm). An image can carry more than one filesystem, and a tree sitting beside the rootfs rather than inside it is cataloged too. Three kinds are recognized, each by the record of what is installed in it rather than by its directory name: a container image store, identified by the image index Docker keeps (the usual layout on a switch OS, where most of what runs is in a container); a second filesystem carrying its own package database; and an interpreter's installed library set, such as a Python site-packages. Set FW_EXTRA_ROOTS=false to read only the rootfs. Components from a container store record the image they belong to in bomlens:container:image, and the images themselves appear as container components. A package installed by dpkg inside a container is identified by the distribution the container runs, read from the os-release in its own layers, so that the vulnerability step has something to match it against; those carry bomlens:purlSource. An SPDX export keeps this: the images and the distribution are packages there, and the membership is a CONTAINS relationship.
  3. Use cve-bin-tool to find the versions and vulnerabilities of stripped static binaries (busybox, openssl, dropbear, and so on).
  4. Merge the two results into one SBOM, then run the same post-processing as a normal scan (licenses, CVEs, signing).

Preparing the firmware image

Firmware analysis needs a separate image that bundles the unpacking and binary-identification tools (unblob, cve-bin-tool, and so on). These are GPL-family tools, so they are kept out of the lightweight base image and split into an opt-in firmware image.

docker pull ghcr.io/sktelecom/bomlens-firmware:latest

This image is the default, so adding --firmware pulls it without any extra setting. To use a different tag, set the environment variable SBOM_FIRMWARE_IMAGE.

In the web UI and the desktop app you do not have to run that command: the firmware input offers a Download now button with the download size, and shows how many layers are done while it runs. Without it the image is still pulled on the first firmware scan, so the only difference is whether the wait happens before the scan or inside it.

Running it

Firmware analysis needs the firmware image (above), whether you use the web UI or the CLI.

From the web UI

The web UI offers the firmware upload tile whenever the firmware image is reachable, then runs the firmware analysis in that image. Launch the UI and upload the file:

SBOM_FIRMWARE_IMAGE=ghcr.io/sktelecom/bomlens-firmware:latest ./scripts/scan-sbom.sh --ui
#   Windows: set SBOM_FIRMWARE_IMAGE before double-clicking sbom-ui.bat

Enter a project name and version, choose the firmware upload tile, upload the file, and run. While the CVE database downloads on a first online run, the UI shows a download progress bar.

From the CLI

Pass the firmware file you received to --target and add --firmware:

./scripts/scan-sbom.sh --project device-fw --version 1.0.0 \
  --target "./device.bin" --firmware \
  --all --generate-only
  • Recognized extensions (.bin, .img, .squashfs, .ubi, .ubifs, .trx, .chk, .fw, .rom) are auto-detected even without --firmware, but being explicit is recommended.
  • The outputs are the same three as a normal scan: the notice (_NOTICE), the SBOM (_bom.json), and the risk report (_risk-report).

CVE matching, online and offline

CVE matching for static binaries uses cve-bin-tool with its own vulnerability database. The firmware image ships in a hybrid arrangement, so the same image works both air-gapped and online.

  • When the image is built with the database bundled, firmware scans match CVEs offline at scan time. This is the fast, air-gap-friendly path.
  • When the bundled database is absent but the network is reachable, cve-bin-tool downloads the database from NVD at runtime. The first run is slow; the web UI shows a download progress bar while it runs.
  • When neither a bundled database nor a network is available, the scan degrades to component-only identification (no CVEs) and logs the reason rather than silently dropping the CVE stage.

CVE_BIN_TOOL_MODE selects the behavior: auto (default; bundled database first, otherwise download if online), offline, online, or components-only.

The database is aggregated from several sources (NVD, PURL2CPE, and others), not from NVD alone. cve-bin-tool prints the notice "This product uses the NVD API but is not endorsed or certified by the NVD."

OSV (Open Source Vulnerabilities) advisories are not bundled, to keep the redistributed image free of share-alike data. The web UI offers an opt-in toggle, "Include OSV advisories," that fetches OSV from osv.dev for that single scan, so the data is downloaded directly on your machine rather than shipped in the image.

License note

The firmware image contains GPL tools (cve-bin-tool, sasquatch, and some extractors that unblob depends on). The shell scripts only invoke them as separate processes, so copyleft does not propagate into our code, but redistributing GPL binaries in an image carries the obligation to include the license texts and offer the source. For the full inventory, see Bundled tool licenses. The GPL analysis tools live only in this firmware image. Every image including the base one is Debian-based, though, so all of them also carry GPL system packages; source directions for those are in the same document.

Limits

  • The open-source tool stack detects roughly 60–85% of components, and the result depends heavily on the firmware type, how aggressively it is stripped, and whether unpacking succeeds.
  • Without function-level binary fingerprinting, stripped or inlined components and binaries with version strings removed are missed.
  • Statically linked libraries, vendor-modified squashfs, encrypted or signed firmware, and renamed libraries go undetected or are misidentified.
  • The resulting SBOM is a best-effort estimate, so do not use it as the sole basis for legal license compliance.

Related: Getting started | Scenarios guide | CLI reference | Notice and security guide