Startup-SBOM

What runs at boot, what it is made of, and how it can be attacked.

Read the documentation →

Startup-SBOM statically analyses a Linux root filesystem, container or image and answers three questions most SBOM tools can't:

1. Vulnerability → threat. Not "openssl has 14 CVEs", but "an unauthenticated remote attacker who can reach TCP/22 could exploit CVE-2024-6387 in openssh-server (sshd, ssh.service, enabled at boot, runs as root) to execute code as root — EPSS 0.94, known exploited. Fix: upgrade to 1:9.2p1-2+deb12u3." Every finding is placed in context: is it reachable at boot, through which service, linked by which binary, what triggers it (boot, socket, timer, cron, D-Bus, udev device event, setuid binary, kernel) and who can fire that trigger, as which user, network-exposed, mitigated by which systemd hardening, mapped to MITRE ATT&CK, with a CISA SSVC decision (Track / Track* / Attend / Act).
2. Chained attacks. A privilege-state attack graph (remote → local:<user> → root → container escape → persistence) built from vulnerabilities and misconfigurations (setuid/capability binaries, privileged containers, mounted Docker socket, kernel CVEs, writable units), pruned by hardening and ranked by likelihood × impact.
3. Supply-chain blast radius. A vendor → source package → binary package → file → service graph built from real code-loading edges (ELF DT_NEEDED, .note.dlopen, ld.so.preload, interpreters). It catches the xz → liblzma → libsystemd → sshd class of problem, which package dependencies alone miss. It also flags provenance risks: third-party repositories, unsigned or locally built packages, unmanaged binaries, modified files and EOL distributions.

It is read-only by design: nothing in the target is mounted, extracted or modified, symlinks can never escape the analysed root, and in the default static mode nothing in the target is executed. The opt-in chroot mode (--mode chroot) runs a few of the target's own tools to confirm the static results, only inside an unprivileged, read-only, network-less bubblewrap sandbox.

Install

uv tool install startup-sbom        # or: pipx install startup-sbom
uvx startup-sbom --help             # run without installing
docker run --rm ghcr.io/morpheuslord/startup-sbom --help

The core scanner has no heavy dependencies; optional features are extras:

uv tool install "startup-sbom[all]"

From source:

git clone https://github.com/morpheuslord/Startup-SBOM && cd Startup-SBOM
uv sync
uv run startup-sbom --help

Python ≥ 3.11 on Linux, macOS or Windows. Everything except host: mode and live container acquisition is pure Python and host-OS independent.

Usage

# A mounted disk or extracted rootfs
startup-sbom scan dir:/mnt/target_root -f html -f cyclonedx -o out/

# A running or stopped container (docker / podman / nerdctl)
startup-sbom scan docker:web -f json -f sarif

# Images without a container engine
startup-sbom scan docker-archive:./image.tar      # docker/podman save
startup-sbom scan oci-dir:./layout                 # OCI image layout
startup-sbom scan tar:./rootfs.tar.zst             # docker export / rootfs tarball

# The machine you are on (Linux)
sudo startup-sbom scan host: -f markdown

# CI gate: fail when anything warrants immediate action
startup-sbom scan oci-archive:img.tar -f sarif --fail-on act

# Confirm with the target's own tools in a sandbox (needs bubblewrap), keep a journal
startup-sbom scan dir:/mnt/target_root --mode chroot --journal scan.jsonl -f html

Other commands: startup-sbom tui (interactive UI), startup-sbom ai … (AI analysis and agent servers), startup-sbom intel … (CVE intelligence lookup), startup-sbom db update|status|clear (cache KEV/EPSS for offline use), startup-sbom schema (JSON Schema of the native report), startup-sbom version.

Exit codes: 0 success, 1 --fail-on threshold reached, 2 usage or target error, 3 internal error.

Outputs

VEX is conservative. A vulnerable package with no observed execution path is reported as under_investigation, not not_affected, because "not started at boot" is not the same as "unreachable". Opt in with --vex-unreachable-not-affected.

Beyond the scanner

Chroot mode. --mode chroot asks the target's own dynamic loader, systemctl and package manager to confirm what static analysis inferred: link closures, unit enablement and the package inventory. They run as nobody in a bubblewrap sandbox with no capabilities, no network, a read-only root, resource limits and timeouts. Directory targets (dir:, host:) on a Linux host with unprivileged user namespaces only; otherwise the scan stays static and says why.

Live progress. On a terminal, scan shows each stage as it runs with a one-line digest of what it found and a rolling pane of raw operations (HTTP requests, package databases read, ELF closures, sandboxed commands). --journal records the same as JSON lines; --ai-live adds a cheap model's running commentary, which is never written into the report.

Explainable results. Every risk score decomposes exactly into its factors (baseline + contributions = total), every SSVC decision carries its decision path and the flips that would change it, and the report proposes a minimal fix plan that breaks every attack chain. The console, HTML, Markdown and PDF outputs render these as charts and graphs.

Interactive TUI. startup-sbom tui walks through target selection, scan settings, a live scan (stage digests, raw operations, optional live analyst) and an eight-tab results browser with search, filters, explanations, intel articles and export.

Intel prefetch. --prefetch-intel gathers vendor advisories, exploit and PoC references and readable articles for the highest-risk findings, over an SSRF-hardened fetcher. Public exploitation evidence can raise a threat's priority, never lower it.

AI analysis. startup-sbom ai analyze report.json runs grounded agents over a report on your choice of LLM provider (Anthropic, OpenAI, Google, Groq, Mistral, OpenRouter, Ollama) with --provider, --model or --profile cheap|balanced|quality, optional DuckDuckGo search and a cost ceiling. Claims the report doesn't support are flagged. The same analysis is available over MCP (Model Context Protocol) and as A2A / ACP (Agent Communication Protocol) agent servers.

Integrations

GitHub Action

- uses: morpheuslord/Startup-SBOM@v2
  with:
    target: oci-archive:image.tar
    formats: sarif,cyclonedx
    fail-on: act

pre-commit

- repo: https://github.com/morpheuslord/Startup-SBOM
  rev: v2.0.2
  hooks:
    - id: startup-sbom
      args: [scan, "dir:rootfs", --offline, --fail-on, act]

Python

from startup_sbom import ScanOptions, scan

report = scan("docker-archive:image.tar", ScanOptions(offline=True))
for chain in report.attack_chains:
    print(chain.ssvc_decision, chain.narrative)

Coverage

When a distribution is not covered by a vulnerability source, the report says so explicitly under coverage limitations. It never returns a silent "0 vulnerabilities".

Security model

• Never mounts, chroots or uses sudo; never writes into the target.
• In the default static mode, never executes anything from the target. With --mode chroot/auto, the target's loader, systemctl and package manager run only inside a bubblewrap sandbox: a new user namespace as nobody, all capabilities dropped, no network, the target root read-only, a cleared environment, resource limits, timeouts and output caps.
• All target paths are resolved inside the analysed root, with a symlink budget. Non-regular files are refused and reads are size-capped.
• Archives are indexed in place, never extracted. Setuid bits and file capabilities are preserved for analysis.
• Network access is limited to an allow-list of HTTPS endpoints with TLS verification. --offline disables it entirely.
• Container environment variable values are never recorded.

See SECURITY.md for reporting vulnerabilities.

Upgrading from 1.x

python3 main.py … still works through a compatibility shim that maps the old flags. The old chroot mode has been removed: it bind-mounted the target over the host's /usr, /bin and /lib and ran target binaries as root. --analysis-mode chroot now maps to the sandboxed --mode chroot, which never mounts over the host or runs anything as root. It does not produce boot timings: capture systemd-analyze plot > boot.svg on the target and pass --boot-timing boot.svg. See the refactor plan for every change.

Citation

See CITATION.cff.

License

MIT. Bundled MITRE CWE/CAPEC/ATT&CK-derived data and CTID mappings are redistributed under their own terms; see NOTICE.md.