MITHRIL(1)

📦 version 0.4.0, in nixpkgs unstable

💖 mithril(1) 💖

okay bestie, this is the manual page for mithril — she lives in your terminal and she's literally so good at firmware forensics. grab a boba, we're going in 🧚

✨ NAME ✨

mithril — analyze firmware contents for secrets, SBOM, CVEs, and licenses 💅

✨ SYNOPSIS ✨

mithril [options] <file|dir>
mithril --fetch-db|--update-db [--with-kernel-feed]

✨ DESCRIPTION ✨

so the way that mithril works is she reads the contents of firmware and IoT software — either a single file or an unpacked rootfs — and then reports four things as structured findings. not me being obsessed with structured output 😭

  • secrets: embedded credential and key material (API tokens, cloud keys, JWTs, private keys, /etc/shadow hashes), and each one comes with a deterministic offline confidence rating. no vibes-based guessing here, it's giving rigor ✨
  • SBOM: a software bill of materials built from package databases (dpkg/opkg/apk/rpm), language manifests, ELF version strings, versioned libc filenames, and the kernel banner. emitted as CycloneDX and SPDX 🎀
  • CVEs: the SBOM joined against a local offline vulnerability mirror (OSV plus NVD/CPE) and a curated, version- and kconfig-gated kernel-CVE checklist, annotated with CISA KEV and EPSS. yes queen, all of that 🔥
  • licenses: the open-source licenses present, for compliance and provenance 👑

mithril pairs with moria(1), which handles structural identification and unpacking. a typical pipeline runs moria -e to unpack an image, then mithril over the extracted tree. ship it 🫶

a scan makes no network calls. the secrets, SBOM, and license passes are fully offline. the CVE pass reads a local mirror that is refreshed out of band (see THE CVE MIRROR below), so it is air-gappable once the mirror is in place. output is human-readable by default; pass -j/--json for a single JSON object designed to be consumed by a tool or model 🤖

with no pass flag, every pass runs. naming one or more passes (--secrets, --sbom, --cve, --licenses, --boot, --keys) restricts the run to just those. main character energy: you pick who gets to show up 😌

🌸 ARGUMENTS 🌸

  • <file|dir> — a single file, or a directory (typically moria's .extracted/ output) to scan recursively 🦋

✨ OPTIONS ✨

💅 Passes

  • --secrets — scan file content for credential and key material 🔑
  • --sbom — inventory software components and their versions 📦
  • --cve — match the detected components against known vulnerabilities in the local mirror. needs the mirror (see --fetch-db) 💀
  • --licenses — identify open-source licenses 📜
  • --boot — boot-security intel: U-Boot environment, device tree, and FIT/AVB/UEFI verified-boot posture 🥾
  • --keys — public-key weakness. this one is so much: keys whose private half is public (hardcoded/default keys, the compromised eMudhra intermediate CAs), the ROCA fingerprint (CVE-2017-15361), undersized or broken RSA keys, RSA factoring recoveries (Fermat/batch-GCD/Wiener), and near-zero EC private scalars recovered by a bounded search (the Oct 2026 eMudhra P-384 compromise). literally the whole key drama 🗝️
  • -A, --all — run every pass. this is the default when no pass is named 👑

🎀 Output detail

  • -j, --json — emit a single JSON object instead of the human-readable view. JSON always carries the complete result set, so the detail options below only affect the human view. use this when a tool or model will parse the output 🤖
  • -v, --verbose — human view: show full values instead of tail-truncating long ones with "..." 👀
  • --license-paths — list the file locations of each license, not just a count (human output). implies --licenses 📍
  • --component-cves-full — human view: list every component CVE, not just the high-signal set (on CISA KEV, or CVSS 9.0 and above, or EPSS 0.10 and above). implies --cve 🚨
  • --kernel-cves-full — list every CVE for the detected kernel version, matched branch-aware, instead of the curated high-signal checklist. needs the kernel feed (see --with-kernel-feed). implies --cve 🐧
  • --full — maximum human detail in one switch: equivalent to --verbose, --license-paths, --component-cves-full, and --kernel-cves-full together. no effect on JSON, which is always complete. one button, everything, slay ✨
  • --dump-kconfig — print the recovered kernel .config to stdout, then exit 🖨️

🦋 CVE mirror

  • --fetch-db — download a prebuilt CVE mirror and verify it against a published SHA-256, then exit. needs curl. this is the networked first-run step; see THE CVE MIRROR below 🌐
  • --update-db — rebuild the local CVE mirror from the upstream feeds, then exit. slower than --fetch-db; needs curl and unzip 🐢
  • --with-kernel-feed — given with --fetch-db or --update-db, also fetch the optional full kernel.org (Linux CNA) CVE feed that backs --kernel-cves-full 🐧
  • --no-fetch — suppress the interactive offer to download the CVE mirror. when the --cve pass runs with no local mirror on an interactive terminal, mithril otherwise asks whether to fetch it. with --no-fetch (or the environment variable MITHRIL_NO_FETCH), it never asks: a missing mirror is reported as an error and the scan exits nonzero, as in a non-interactive run. use it in scripts and CI 🙈

🌈 Configuration

  • --rules FILE — add user-defined detection rules from a JSON file 📝
  • -C, --outdir DIR — also write the report to DIR, regardless of the stdout format: mithril-report.json (the complete JSON result set) and, when the SBOM pass runs, sbom.cdx.json and sbom.spdx.json (the CycloneDX and SPDX bills of materials). these standard-format SBOMs are produced only through -C. ⚠️ note that moria(1) also has a -C but means its extraction output directory; here it is the report output directory. don't mix them up bestie, iykyk 💀
  • --threads N — worker threads for tree scans. default: automatic ⚡

⭐ Information

  • -h, --help — print help and exit 🫶
  • --version — print version and exit 🏷️

💜 THE CVE MIRROR 💜

the --cve pass reads a local mirror under ~/.local/share/mithril (or $MITHRIL_DB) — a compact memory-mapped index built from OSV.dev, the NVD 2.0 API, the CISA KEV catalog, and FIRST's EPSS scores ✨

on a first run, populate it once with mithril --fetch-db before the first CVE scan. without it, --cve reports the missing database and exits nonzero 😭

only --fetch-db and --update-db ever touch the network; a normal scan does not. no cap, that's the whole point 🔒

🍓 EXIT STATUS 🍓

  • 0 — success 🎉
  • 1 — runtime error (for example, an unreadable target or a missing CVE mirror for --cve) 😬
  • 2 — usage error (unknown option, missing argument) 🙃

🧚 ENVIRONMENT 🧚

  • MITHRIL_DB — path to the local CVE mirror (overrides the default under ~/.local/share/mithril)
  • MITHRIL_DB_URL — base URL that --fetch-db downloads the prebuilt mirror from
  • NVD_API_KEY — optional NVD API key used by --update-db to raise the upstream rate limit. it works without one, just more slowly 🐌
  • XDG_DATA_HOME — if set, mithril locates the mirror under $XDG_DATA_HOME/mithril instead of ~/.local/share/mithril
  • NO_COLOR — disables bold section headers in --help output 🎨

🌸 FILES 🌸

  • ~/.local/share/mithril/ — default location of the local CVE mirror (OSV plus NVD/CPE index, KEV, EPSS, and the optional kernel feed) 📁

🔥 EXAMPLES 🔥

run every analysis on an unpacked tree:

mithril ./rootfs/

only the secrets pass:

mithril --secrets ./rootfs/

JSON output for a tool or model:

mithril -j ./rootfs/

first run: download the CVE mirror:

mithril --fetch-db

the full pipeline with moria:

moria -e firmware.bin && mithril firmware.bin.extracted/

👑 SEE ALSO 👑

moria(1), trufflehog(1)

full documentation: README.md and docs/ in the source tree (https://github.com/nmatt0/mithril) 📚

and that's the whole page, bestie 🫶 this is mithril version 0.4.0, dated 2026-10-22 — go forth, scan some firmware, and stay iconic 💅✨

📦 where this page comes from