Skip to content
Back to search

blint

SkillWorks with Claude CodeGitHub

blint is a Binary Linter that checks the security properties and capabilities of your executables. It can also generate a Software Bill-of-Materials (SBOM) for supported binaries.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/owasp-dep-scan/blint with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/owasp-dep-scan/blint'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/appthreat--blint/badge.svg)](/listings/appthreat--blint)

HTML

<a href="/listings/appthreat--blint"><img src="/api/listings/appthreat--blint/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

`blint` requires Python >= 3.10.

pip install blint

For **disassembly support**, which enables instruction-level analysis of functions, install the `extended` version. This includes the [nyxstone](https://github.com/emproof-com/nyxstone) disassembler.

pip install blint[extended]

Via Homebrew

On macOS and Linux, Homebrew installs the standalone `blint` binary from the [OWASP dep-scan tap](https://github.com/owasp-dep-scan/homebrew-tap), so no Python installation is needed. `brew trust` accepts the tap, which Homebrew requires before loading formulae from a third-party tap when `HOMEBREW_REQUIRE_TAP_TRUST` is set:

brew tap owasp-dep-scan/tap
brew trust --tap owasp-dep-scan/tap
brew install blint

Via Container Image

You can also run blint using the official container image available on GitHub Container Registry. This is a convenient way to run blint without installing Python or any dependencies on your host machine.

docker run --rm -it -v $(pwd):/app -w /app ghcr.io/owasp-dep-scan/blint:latest -i /path/to/your/binary

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 95 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # SKILL.md
  2. This file defines practical skills an AI agent should apply when working on `blint`.
  3. ## Skill: Navigate blint architecture quickly
  4. - Start at `blint/cli.py` to identify mode (`default`, `sbom`, `callgraph-match`, `canonicalize`, `capabilities`, `diff`, `db`, `cache`).
  5. - Follow orchestration in `blint/lib/runners.py`.
  6. - Review coordination lives in `blint/lib/review_runner.py`.
  7. - For extraction logic, use the per-format readers `blint/lib/binary_{elf,pe,macho,wasm}.py` (shared helpers in `binary_common.py`, entry point and callgraph in `binary.py`) and `blint/lib/android.py`.
  8. - For rule behavior, use `blint/lib/analysis.py`, `blint/lib/review_utils.py`, `blint/lib/function_reviews.py`, and `blint/data/annotations/*.yml`.
  9. - For SBOM behavior, use `blint/lib/sbom.py` and `blint/cyclonedx/spec.py`.
  10. ## Skill: Implement rule-driven behavior safely
  11. - Understand rule types:
  12. - `rules.yml` -> hardening checks (`run_checks`).
  13. - annotations -> reviews (`METHOD_REVIEWS`, `SYMBOL_REVIEWS`, etc.).
  14. - `FUNCTION_REVIEWS` -> disassembly-derived behavior checks implemented in `blint/lib/function_reviews.py`.
  15. - Keep rule IDs stable and unique.
  16. - Match field paths used in `function_metric` with actual metadata shape.
  17. - Respect evidence limits (`EVIDENCE_LIMIT`) to avoid noisy output.
  18. ## Skill: Work with binary metadata extraction
  19. - Preserve format-specific fields while maintaining normalized top-level fields.
  20. - Do not break keys used downstream by checks/reviews/SBOM mappers.
  21. - Keep defensive parsing style: suppress parser exceptions where already expected.
  22. - Validate changes against representative fixtures in `tests/data/*.json` and `tests/data/*.wasm`.
  23. ## Skill: Extend disassembly analytics
  24. - `--disassemble` is optional; do not force it into default flows.
  25. - Avoid architecture-specific regressions:
  26. - x86/x64 (and 32-bit i386)
  27. - AArch64/ARM64
  28. - 32-bit ARM (armeabi-v7a, both ARM and Thumb instruction states)
  29. - MIPS/microMIPS/MIPS16 fallback paths
  30. - Keep heuristics lightweight and deterministic.
  31. - Ensure new indicators are configurable/constants-based when possible.
  32. ## Skill: Maintain SBOM correctness
  33. - Preserve CycloneDX output validity (spec 1.7 model in this repo; `1.6` remains selectable with `--sbom-spec-version`).
  34. - Ensure each component has a stable `bom_ref`.
  35. - Avoid dependency self-loops.
  36. - Keep deep-mode details in properties, not default minimal output.
  37. - Respect `--stdout` and output path behavior.
  38. - Remember that `blint sbom --use-blintdb --deep` auto-enables disassembly. Test that path explicitly when changing SBOM or DB matching logic.
  39. ## Skill: Use blintdb integration properly
  40. - Database usage is optional and should not block core execution.
  41. - Keep behavior safe when DB is missing or download fails.
  42. - Prefer the local query contract in `blint/db.py` over importing runtime helpers from `blint-db`.
  43. - Use project-level evidence from symbols, binary-name hints, and disassembly hashes together.
  44. - Keep symbol-only matching conservative. Strong exact matches are better than noisy broad guesses.
  45. - Filter tiny or generic hash evidence when it creates cross-project collisions.
  46. - Avoid introducing non-read-only DB access in analysis paths.
  47. ## Skill: Testing and validation expectations
  48. - Core tests:
  49. - `tests/test_analysis.py`
  50. - `tests/test_binary.py`
  51. - `tests/test_android.py`
  52. - `tests/test_disassembler.py`
  53. - Add fixture-based tests for parser/rule changes.
  54. - Prefer narrow tests for one behavior change at a time.
  55. - For `blint/db.py` or `blint/lib/sbom.py` changes, run both fixture tests and one small real corpus build from the linked `blint-db` repo.
  56. - Validate both modes for real corpus checks:
  57. - symbol-only: `blint sbom --use-blintdb`
  58. - disassembly-assisted: `blint sbom --use-blintdb --deep`
  59. - For exact binaries that were used to build the corpus, expect near-exact component identification and inspect `internal:blintdb_*` properties when debugging drift.
  60. - Prefer the scripted validation flow in `tests/scripts/validate_blintdb_small_corpus.py` over one-off shell snippets. The selector manifest is versioned in `tests/data/blintdb-small-corpus.json`.
  61. ## Skill: Documentation updates with code changes
  62. - Update `docs/RULES.md` when rule schema/usage changes.
  63. - Update `docs/METADATA.md` when metadata keys/meaning change.
  64. - Update `docs/DISASSEMBLE.md` when disassembly fields/heuristics change.
  65. - Keep README examples aligned with actual CLI flags.
  66. - Update `AGENTS.md` and `SKILL.md` when the maintenance workflow changes in a meaningful way.
  67. ## Skill: High-confidence change checklist
  68. - Confirm changed fields are consumed correctly by:
  69. - checks
  70. - reviews
  71. - report exporters
  72. - SBOM generation
  73. - Run tests after editing Python logic.
  74. - Ensure no accidental behavior change in non-targeted binary formats.
  75. - For WASM parsing changes, verify both normalized fields (`imports`, `dynamic_entries`, `functions`) and raw passthrough fields (`wasm_report`, `wasm_analysis`).
  76. - WASM has three size controls that change what downstream code sees: `--no-wasm-strings` (removes the string-derived findings with their evidence), `--no-wasm-call-graph` (zeroes `wasm_call_graph_summary` and suppresses wasm callgraph exports), and `BLINT_MAX_WASM_INSTRUCTIONS` (bounds instruction streams in the report). Exercise a component fixture as well as a core module when touching any of them, since component reports nest functions under `core_modules` and `nested_components`.
README.md · README · 629 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # blint
  2. <img src="./blint.png" width="200" height="auto" />
  3. [![AI-DECLARATION: pair](https://img.shields.io/badge/䷼%20AI--DECLARATION-pair-ffedd5?labelColor=ffedd5)](./AI-DECLARATION.md)
  4. `blint` is a Binary Linter that checks the security properties and capabilities of your executables. It is powered by [lief](https://github.com/lief-project/LIEF) and can generate a Software Bill-of-Materials (SBOM) for supported binaries.
  5. ## What is blint?
  6. blint is a tool for reverse engineers, security analysts, and developers to quickly assess the security posture and composition of a binary file. In an age of statically-linked Golang, Rust, and .NET applications, understanding what's inside a binary is more important than ever. blint automates this initial triage process.
  7. The default scan flows like this:
  8. ```mermaid
  9. flowchart TD
  10. A["Inputs: binaries, directories, container images, app and package archives"] --> B["Discover analysis units (one per binary, bundle member, or container member)"]
  11. B --> P["Parse each unit (ELF, PE, Mach-O, WASM readers plus the Android, installer, and bundle unpackers)"]
  12. P --> M["*-metadata.json and analysis-coverage.json"]
  13. P --> C["Security checks (rules.yml)"]
  14. P --> R["Capability reviews (annotation rules)"]
  15. D["--disassemble, opt-in: nyxstone plus abstract interpretation"] --> C
  16. D --> R
  17. D --> G["Callgraph exports (.mmd, .graphml, .gexf)"]
  18. C --> O["findings.json, reviews.json, blint-output.html"]
  19. R --> O
  20. P -.->|"blint sbom"| S["CycloneDX 1.7 SBOM (1.6 selectable), optional blintdb and deep matching"]
  21. ```
  22. **Supported Binary Formats:**
  23. - ELF (for GNU and musl libc)
  24. - PE (Windows executables and DLLs), including .NET assemblies: metadata tables, strong-name facts, and publish shape (ReadyToRun, NativeAOT, single-file bundles)
  25. - Mach-O (macOS and iOS, x64 and arm64), including Objective-C and Swift metadata
  26. - iOS/macOS apps (`.ipa`, and on macOS also `.app`, `.framework`, and `.dSYM` bundles): the main executable, embedded frameworks, dylibs, and app extensions are all analyzed, and embedded provisioning profiles are decoded for the entitlements they grant
  27. - Windows packages and documents: `.msi`/`.msp` databases, `.cab` archives, driver package `.inf` files, `.msix`/`.appx` packages and bundles, ClickOnce deployments, `.nupkg` archives, and Office documents (including VBA macro analysis)
  28. - Android (APK, APKM, AAB, including DEX files in deep mode)
  29. - WASM (WebAssembly modules)
  30. - Disassembler: AArch64, x86/x86-64, i386, ARM and Thumb (armeabi-v7a), Mips, MicroMips (native), and Dalvik (DEX).
  31. ## Key Features & Use Cases
  32. - **Comprehensive Security Audits:** Automatically checks for common security mitigations like PIE, ASLR, NX, Stack Canaries, and RELRO. Ideal for ensuring your CI/CD pipeline produces hardened binaries.
  33. - **Software Bill-of-Materials (SBOM) Generation:** Creates [CycloneDX](https://cyclonedx.org/specification/overview/) SBOMs for binaries built with Go, Rust, .NET, and Android toolchains, providing a clear inventory of third-party components for vulnerability management.
  34. - **Deep Binary Inspection:** Disassembles, extracts, and analyzes a wealth of information including symbols, functions, dependencies, and build toolchains. This raw data is saved as a detailed JSON file.
  35. - For a complete guide to all attributes in this file, see the [Technical Metadata Documentation](./docs/METADATA.md).
  36. - For the custom CycloneDX properties blint adds to the BOM, see the [Custom Properties Documentation](./docs/CUSTOM_PROPERTIES.md).
  37. - Navigate to the [disassembly guide](./docs/DISASSEMBLE.md).
  38. - For callgraph internals and analyst-facing interpretation, see the [callgraph guide](./docs/CALLGRAPH.md).
  39. - **Android Deep Analysis:** In deep mode blint parses the dex classes, detects bundled service and tracker SDKs, and runs a Dalvik behavioural review that decodes the bytecode and flags risky behaviours such as dynamic code loading, reflection, native command execution, weak cryptography, and cleartext networking. The findings are attached to the BOM as custom properties. When disassembly is enabled, blint also writes a Dalvik callgraph sidecar next to the BOM. Native code (`lib/<abi>/*.so` of an APK/AAB or a standalone `.so`) gets its own analysis path: per-ABI bionic ELF facts and loader/hardening checks, framework identification in the SBOM, and a dex↔native JNI join that binds declared natives to their implementations (see the [Android native guide](./docs/ANDROID.md)).
  40. - **iOS/macOS App Analysis:** Point blint at an `.ipa` and it unpacks the app bundle, reads the `Info.plist` context (bundle id, version, minimum OS, FairPlay encryption status), and analyzes the main executable along with every embedded framework, dylib, and app extension. For Mach-O binaries, blint recovers Objective-C metadata (classes, superclasses, methods, protocols, and referenced selectors) and demangles Swift symbols, then surfaces iOS privacy capabilities such as location, camera, microphone, contacts, photos, telephony, motion, biometrics, and device fingerprinting. It also reports privacy and fingerprinting behaviours: passive device fingerprinting, installed-app probing, local-network scanning, cross-app tracking, and the app's `PrivacyInfo.xcprivacy` posture including undeclared "required reason" API usage.
  41. - **Capability Analysis:** Identifies potentially sensitive capabilities by reviewing imported functions and symbols, such as network access, filesystem operations, or cryptographic API usage.
  42. - Includes cluster-style behavioral reviews for low-level networking patterns (for example eBPF sock_ops usage, TUN interception stacks, raw packet injection primitives, and local DoH redirection indicators).
  43. - **Windows Depth:** Windows inputs get a structured Authenticode walk (signers, timestamps, chains, signing class), kernel-driver posture (frameworks, IOCTL surfaces, HVCI compatibility, known vulnerable driver matching against a shipped loldrivers.io and Microsoft blocklist snapshot), installer and container unpacking (MSI, CAB, MSIX, 7z SFX, ClickOnce), Plug and Play driver package review (what a pluggable device makes Windows install and run as SYSTEM), and a .NET metadata reader that recovers assembly references, P/Invoke surfaces, and publish shape without executing anything.
  44. - **Binary Diffing:** `blint diff` compares two versions of one binary (or two `*-metadata.json` exports) and reports metadata deltas, hardening regressions with per-property polarity, finding deltas paired across rebuilds, and, with `--disassemble`, a function-level delta keyed on content hashes.
  45. - **Performance:** `--jobs N` analyzes binaries in parallel worker processes with byte-identical output, and `--cache` turns on a content-addressed parse cache so unchanged binaries are parsed once. `blint capabilities` prints the full catalog of checks and reviews the engine will run, in text or JSON.
  46. - **CI/CD Integration:** Can be added to build pipelines to enforce security policies, such as requiring code signing on all release artifacts.
  47. - **Fuzzing Target Identification:** Suggests interesting functions to target for fuzzing based on common patterns in function names (e.g., `parse`, `decode`, `copy`).
  48. - **Extensible with Custom Rules:** Define your own capabilities and checks using simple [YAML rule files](./docs/RULES.md).
  49. ## Installation
  50. `blint` requires Python >= 3.10.
  51. ```shell
  52. pip install blint
  53. ```
  54. For **disassembly support**, which enables instruction-level analysis of functions, install the `extended` version. This includes the [nyxstone](https://github.com/emproof-com/nyxstone) disassembler.
  55. ```shell
  56. pip install blint[extended]
  57. ```
  58. ### Via Homebrew
  59. On macOS and Linux, Homebrew installs the standalone `blint` binary from the [OWASP dep-scan tap](https://github.com/owasp-dep-scan/homebrew-tap), so no Python installation is needed. `brew trust` accepts the tap, which Homebrew requires before loading formulae from a third-party tap when `HOMEBREW_REQUIRE_TAP_TRUST` is set:
  60. ```shell
  61. brew tap owasp-dep-scan/tap
  62. brew trust --tap owasp-dep-scan/tap
  63. brew install blint
  64. ```
  65. ### Via Container Image
  66. You can also run blint using the official container image available on GitHub Container Registry. This is a convenient way to run blint without installing Python or any dependencies on your host machine.
  67. ```
  68. docker run --rm -it -v $(pwd):/app -w /app ghcr.io/owasp-dep-scan/blint:latest -i /path/to/your/binary
  69. ```
  70. ## Quick Start
  71. Analyze a binary and save the reports to the `/tmp/blint` directory:
  72. ```shell
  73. blint -i /bin/netstat -o /tmp/blint
  74. ```
  75. ```shell
  76. docker run --rm -it -v /tmp:/tmp -v /bin:/app/bin -w /app ghcr.io/owasp-dep-scan/blint:latest -i /app/bin/netstat -o /tmp/blint
  77. ```
  78. Analyze a Go or Rust binary and get suggestions for fuzzing targets:
  79. ```shell
  80. blint -i /path/to/my-binary --suggest-fuzzable
  81. ```
  82. Analyze an iOS/macOS app (`.ipa`). blint unpacks the bundle and writes a separate
  83. `*-metadata.json` for the main executable and each embedded framework, dylib, and
  84. app extension. Add `--disassemble` for instruction-level analysis (Objective-C and
  85. Swift call sites are resolved to imported APIs):
  86. ```shell
  87. blint -i /path/to/app.ipa -o /tmp/blint --disassemble
  88. ```
  89. Generate a CycloneDX SBOM for an Android application:
  90. ```shell
  91. blint sbom -i /path/to/app.apk -o sbom.cdx.json
  92. ```
  93. ```shell
  94. docker run --rm -it -v /path/to:/app -w /app ghcr.io/owasp-dep-scan/blint:latest sbom -i /app/app.apk -o sbom.cdx.json
  95. ```
  96. For Android deep analysis, enable deep mode so the dex classes are parsed. This is what makes service and tracker detection and the Dalvik behavioural review possible. Deep mode also enables disassembly, which writes the Dalvik callgraph sidecar next to the BOM. Both `.apk` single files and `.apkm` split bundles are supported.
  97. ```shell
  98. blint sbom -i /path/to/app.apkm -o sbom.cdx.json --deep
  99. ```
  100. Attribute Mach-O imports against an Xcode SDK's `.tbd` stubs, so each imported symbol is confirmed against, and attributed to, the system library that actually exports it (see [`.tbd` SDK index](./docs/METADATA.md#the-tbd-sdk-index---sdk-path) in the metadata guide):
  101. ```shell
  102. blint -i /path/to/macho-binary -o /tmp/blint --sdk-path "$(xcrun --show-sdk-path)"
  103. ```
  104. The same flag exists on `blint sbom`, where it attributes and confirms the Mach-O dependency edges in the BOM.
  105. ## Understanding the Output
  106. blint produces several JSON artifacts in the specified reports directory.
  107. | Filename | Purpose | Details |
  108. | --------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  109. | `exename-metadata.json` | **Raw, detailed metadata** extracted from the binary. This is the source for all other reports. | Contains everything: headers, symbols, functions, dependencies, signature info, and more. See the **[Technical Metadata Documentation](./docs/METADATA.md)** for a full breakdown. |
  110. | `exename-wasm-report.json` | **Raw WASM parser report** for WebAssembly inputs. | Generated for `.wasm` files and contains the full `wasm_tools` parser output, including section/function/instruction detail, extracted strings with secret/IoC screening, the labeled call graph, toolchain fingerprint, and the `component` interface inventory for Component Model binaries. |
  111. | `findings.json` | A summary of the **security properties audit**. Designed for CI/CD integration. | Lists security mitigations like PIE, NX, and Stack Canaries and whether they are present. For WASM inputs, the `wasm_tools` analysis findings (`WASM-*`) are passed through as findings. |
  112. | `analysis-coverage.json` | A run-level account of **what was actually analyzed**. | Counts units attempted, succeeded, failed, and skipped (per role), and records every failure and skip with a reason, so a clean result can never be mistaken for a blind one. |
  113. | `reviews.json` | A summary of the **capability review**. | Lists detected capabilities (e.g., "networking", "file-read", "crypto") based on the symbols and functions found. |
  114. | `fuzzables.json` | A list of **suggested functions to fuzz**, generated when using the `--suggest-fuzzable` flag. | Identifies functions with names that suggest data parsing or manipulation, which are often good candidates for fuzzing. |
  115. | `exename-callgraph.mmd` | Mermaid callgraph export generated with `--export-callgraph-mermaid`. | Includes internal and unresolved edges; also embedded into `blint-output.html`. |
  116. | `exename-callgraph.graphml` | GraphML callgraph export generated with `--export-callgraph-graphml`. | Useful for Gephi, Cytoscape, and NetworkX workflows. |
  117. | `exename-callgraph.gexf` | GEXF callgraph export generated with `--export-callgraph-gexf`. | Useful for Gephi-centric large graph exploration. |
  118. | `sbom-*.cdx.json` | The **Software Bill-of-Materials (SBOM)**, generated by the `sbom` sub-command. | A CycloneDX-formatted JSON file detailing the binary's components and dependencies. |
  119. ## Advanced Usage: SBOM Generation with blintdb
  120. For C and C++ binaries, identifying components from symbols alone can be imprecise. `blint` can use **blintdb**, a pre-compiled database built from real project outputs, to improve component identification with:
  121. - project-level symbol matching
  122. - binary-name hints
  123. - optional disassembly hash matching when deep mode is enabled
  124. - similarity-hash matching (function fuzzy hashes, and the binary import-set digest) when the database carries those columns, so a compiler-drifted recompile degrades to fuzzy matching instead of missing
  125. - vendored-source banner detection: version strings a statically-linked vendored copy leaves in the binary, which attribute members of a static archive to the project they were compiled from
  126. Databases with schema version 2 and version 3 are both supported; the similarity-hash columns are detected per database, so a v2 database (or one whose hash columns are unpopulated) keeps working with exact matching only. Matched components record this as an `internal:blintdb_fuzzy_layer` property (`active`, or a named `unavailable_*`/`inactive_*` state such as `unavailable_hash_columns_absent` or `inactive_no_disassembly`) so "the fuzzy layer found nothing" is never confused with "the fuzzy layer could not run".
  127. The workflow is a two-step process:
  128. 1. **Download the blintdb database:**
  129. ```shell
  130. blint db --download
  131. ```
  132. This downloads the database to the directory specified by the `BLINTDB_HOME` environment variable. The layers are large (tens of GB), so the download streams to a `.part` file, resumes with HTTP range requests when the connection drops, and is verified against the image digest before it replaces `blint.db`. An interrupted run leaves the `.part` file behind and the next `blint db --download` resumes from it, including a refresh interrupted while an older `blint.db` is still in place. A response that does not continue the `.part` exactly restarts the layer, rate limiting (HTTP 429) is retried after the delay the registry asks for, and the finished file's size and digest are checked on the file itself. Only one download runs at a time per `BLINTDB_HOME`: a second one fails at once rather than writing the same file. The command exits non-zero when it cannot produce a verified database (unless `--no-error` is given), and a truncated or empty `blint.db` left by an older blint is detected and downloaded again rather than used.
  133. 2. **Generate the SBOM with blintdb enabled:**
  134. ```shell
  135. blint sbom -i /path/to/binary -o sbom.cdx.json --use-blintdb
  136. ```
  137. 3. **For higher-confidence native matching, enable deep mode:**
  138. ```shell
  139. blint sbom -i /path/to/binary -o sbom.cdx.json --use-blintdb --deep
  140. ```
  141. When `--use-blintdb` and `--deep` are set together, `blint` enables disassembly automatically and searches the database with function hashes before falling back to symbol evidence.
  142. The generated SBOM keeps the inferred package purl and also records `internal:blintdb_*` evidence properties on matched components so you can review why a component was selected.
  143. For repeatable end-to-end validation of local `blint-db` changes, use the integration script in `tests/scripts/validate_blintdb_small_corpus.py`. It builds and validates a versioned 15-case corpus split across Meson, vcpkg, and Homebrew, using the manifest stored in `tests/data/blintdb-small-corpus.json`.
  144. The generated `summary.json` includes per-ecosystem provenance copied from the linked `blint-db` run metadata under `ecosystems.<name>.provenance`. That block mirrors `projects.selected_count`, `attempted_count`, `success_count`, `failure_count`, `status_counts`, and `build_failures`. Each `projects.build_failures[]` entry is a flattened per-project failure record with stable keys such as `selector`, `project_name`, `ecosystem`, `build_system`, `status`, `stage`, and `message`, plus optional details like `returncode` or `exception_type` when they are available.
  145. ## WebAssembly Component Model SBOM
  146. `blint sbom` skips `.wasm` inputs by default. Pass `--wasm-sbom` to include Component Model binaries: their imported WIT interface packages (for example `wasi:cli` at `0.2.0`) are emitted as required library components, and the wasm binary itself becomes the application parent.
  147. The purls are built from exact import evidence only (`pkg:generic/wasi/cli@0.2.0?type=wasm` maps the WIT namespace/package identity; the `type=wasm` qualifier follows the format proposed in the wasm-tools dependency research notes). Exported interfaces are recorded as a property on the parent rather than as dependencies, because they are capabilities the binary provides. Core modules are skipped: their imports carry no package identity, so no versionless or fuzzy guesses are emitted.
  148. ```shell
  149. blint sbom -i /path/to/component.wasm -o sbom.cdx.json --wasm-sbom
  150. ```
  151. ## Environment Variables
  152. - `BLINTDB_HOME`, `BLINTDB_IMAGE_URL`, `BLINTDB_REFRESH`: Control blintdb download location, source image, and refresh behavior.
  153. - `BLINT_GLIBC_BASELINE`: Oldest glibc your deployment target ships (for example `2.28` for RHEL 8), used by the `CHECK_ABI_FLOOR` security check. A binary whose GLIBC symbol-version floor exceeds a baseline set here is a `medium` finding; without it the check compares against its built-in default (`2.28` in `rules.yml`) and reports at `info`, saying the default was used. musl and bionic binaries never fire the check. The `--glibc-baseline` CLI option is the same setting and wins when both are given. A value that is not a dotted version is ignored with a warning.
  154. - `BLINT_CACHE_DIR`: Where the content-addressed parse cache (enabled with `--cache`) stores its database. Defaults to the per-user cache directory.
  155. - `BLINT_CACHE_MAX_BYTES`: Size bound for the parse cache. Default is 1 GiB; `0` disables eviction.
  156. - `BLINT_MAX_HEX_BYTES`: Maximum number of raw bytes converted to hex when metadata contains undecodable byte sequences. Default is `4096`.
  157. - `0` disables truncation.
  158. - When truncation happens, blint appends `...<truncated:N_bytes>` to preserve context without producing huge JSON fields.
  159. - `BLINT_MAX_WASM_INSTRUCTIONS`: Total instruction-stream budget for each `*-wasm-report.json`. Instruction streams are the only unbounded part of the wasm parser output and dominate the report size for large modules. Default is `50000`; `0` disables the cap.
  160. - The budget is divided max-min fair across every function in the report, so short functions keep their whole body and the remainder goes to the long ones, rather than the first functions in section order consuming everything.
  161. - Trimmed functions keep their truthful `instruction_count` and gain an `instructions_truncated` count, and the report gains a top-level `blint_truncation` block recording the budget, the instructions dropped, and how many functions were affected.
  162. - `BLINT_RESOLVE_LINK_CLOSURE`: Set to `1` to resolve each ELF binary's dynamic dependency closure the way the loader would, reporting libraries that cannot be found, imported symbols nothing in the closure defines, and search paths that let an untrusted directory answer first. Off by default, because resolution reads the filesystem the scan runs on and is only meaningful when that filesystem is the binary's intended runtime. Results land in the `link_closure` metadata block.
  163. - `BLINT_LINK_ROOT`: Filesystem root to resolve against. Point this at an unpacked container image or sysroot rather than at the scanning host. Default is `/`.
  164. - `BLINT_LINK_SEARCH_PATH`: Extra directories treated as if they were in `LD_LIBRARY_PATH`, separated by the platform path separator.
  165. ## Command-Line Reference
  166. Every block below is the output of `<command> --help` on this version
  167. (default paths shown as `<user data dir>` are platform dependent).
  168. <details>
  169. <summary><strong>Main Command Help</strong></summary>
  170. ```shell
  171. usage: blint [-h] [-i SRC_DIR_IMAGE [SRC_DIR_IMAGE ...]] [-o REPORTS_DIR]
  172. [--no-error] [--no-banner] [--no-reviews] [--no-wasm-strings]
  173. [--no-wasm-call-graph] [--suggest-fuzzable] [--use-blintdb]
  174. [--disassemble] [--export-callgraph-mermaid]
  175. [--export-callgraph-graphml] [--export-callgraph-gexf]
  176. [--callgraph-min-confidence {low,medium,high}]
  177. [--custom-rules-dir CUSTOM_RULES_DIR] [--catalog-dir CATALOG_DIR]
  178. [--sdk-path SDK_PATH] [--cache] [--jobs JOBS]
  179. [--glibc-baseline VERSION] [-q]
  180. {sbom,callgraph-match,canonicalize,capabilities,diff,db,cache} ...
  181. Binary linter and SBOM generator.
  182. options:
  183. -h, --help show this help message and exit
  184. -i, --src SRC_DIR_IMAGE [SRC_DIR_IMAGE ...]
  185. Source directories, binary files or an exported
  186. container image filesystem (a directory). Defaults to
  187. current directory.
  188. -o, --reports REPORTS_DIR
  189. Reports directory. Defaults to reports.
  190. --no-error Continue on error to prevent build from breaking.
  191. --no-banner Do not display banner.
  192. --no-reviews Do not perform method reviews.
  193. --no-wasm-strings Do not extract strings from wasm files. Shrinks the
  194. wasm report and disables the string-based wasm
  195. findings (e.g. WASM-STR-007).
  196. --no-wasm-call-graph Do not build the wasm_tools call graph for wasm files.
  197. Shrinks the wasm report and disables wasm callgraph
  198. exports.
  199. --suggest-fuzzable Suggest functions and symbols for fuzzing based on a
  200. dictionary.
  201. --use-blintdb Use blintdb v4 for symbol resolution where supported.
  202. Defaults to true if the file exists at
  203. /Users/appthreat/Library/Application
  204. Support/blintdb/blint.db. Use environment variables:
  205. BLINTDB_IMAGE_URL, BLINTDB_HOME, and BLINTDB_REFRESH
  206. for customization.
  207. --disassemble Disassemble functions and store the instructions in
  208. the metadata. Requires blint extended group to be
  209. installed.
  210. --export-callgraph-mermaid
  211. Export callgraph as Mermaid (.mmd) files and embed
  212. diagrams into blint-output.html. Effective when
  213. --disassemble is enabled.
  214. --export-callgraph-graphml
  215. Export callgraph as GraphML for external graph
  216. analysis tools. Effective when --disassemble is
  217. enabled.
  218. --export-callgraph-gexf
  219. Export callgraph as GEXF for Gephi and other graph
  220. tooling. Effective when --disassemble is enabled.
  221. --callgraph-min-confidence {low,medium,high}
  222. Filter exported callgraph edges/external links by
  223. confidence. Defaults to low (no filtering).
  224. --custom-rules-dir CUSTOM_RULES_DIR
  225. Path to a directory containing custom YAML rule files
  226. (.yml or .yaml). These will be loaded in addition to
  227. default rules.
  228. --catalog-dir CATALOG_DIR
  229. Path to a directory of .cat catalog files (a copied
  230. CatRoot tree) used to resolve catalog-signed PEs that
  231. carry no embedded signature. Off by default: without
  232. it code_signature.scope stays 'none' with
  233. catalog_lookup 'not_performed' and no unsigned claim
  234. is made.
  235. --sdk-path SDK_PATH Path to an Apple SDK root whose .tbd stubs are used to
  236. attribute and confirm Mach-O imports (for example the
  237. path printed by `xcrun --show-sdk-path`). Off by
  238. default; the path must contain .tbd files or the run
  239. aborts.
  240. --cache Use the content-addressed parse metadata cache: reuse
  241. the parse result for a binary already analyzed with
  242. the same bytes, blint version and options. Off by
  243. default; see `blint cache stats`.
  244. --jobs JOBS Analyze up to N binaries in parallel worker processes.
  245. Accepts a positive integer, 0 or 'auto' for the CPU
  246. count. Defaults to 1 (sequential, unchanged behavior).
  247. --glibc-baseline VERSION
  248. Oldest glibc your deployment target ships (for example
  249. 2.28 for RHEL 8). CHECK_ABI_FLOOR compares each
  250. binary's GLIBC symbol-version floor against it; a
  251. floor above a baseline set here is a medium finding,
  252. above the built-in default it is info. Equivalent to
  253. the BLINT_GLIBC_BASELINE environment variable; the
  254. option wins when both are given.
  255. -q, --quiet Disable logging and progress bars.
  256. sub-commands:
  257. Additional sub-commands
  258. {sbom,callgraph-match,canonicalize,capabilities,diff,db,cache}
  259. sbom Command to generate SBOM for supported binaries.
  260. callgraph-match Match a source callgraph against a binary callgraph.
  261. canonicalize Show the canonical form of one or more function names.
  262. capabilities Emit the catalog of checks and reviews blint analyzes
  263. with.
  264. diff Compare two versions of a binary (binaries or
  265. *-metadata.json files).
  266. db Command to manage the pre-compiled database.
  267. cache Manage the content-addressed parse metadata cache.
  268. ```
  269. </details>
  270. <details>
  271. <summary><strong>SBOM Sub-command Help</strong></summary>
  272. ```shell
  273. usage: blint sbom [-h] [--no-error] [-i SRC_DIR_IMAGE [SRC_DIR_IMAGE ...]]
  274. [-o SBOM_OUTPUT] [--deep] [--stdout] [-q]
  275. [--exports-prefix EXPORTS_PREFIX [EXPORTS_PREFIX ...]]
  276. [--bom-src SRC_DIR_BOMS [SRC_DIR_BOMS ...]] [--use-blintdb]
  277. [--wasm-sbom] [--jobs JOBS] [--sdk-path SDK_PATH]
  278. options:
  279. -h, --help show this help message and exit
  280. --no-error Continue on error to prevent build from breaking.
  281. -i, --src SRC_DIR_IMAGE [SRC_DIR_IMAGE ...]
  282. Source directories, binary files or an exported
  283. container image filesystem (a directory). Defaults to
  284. current directory.
  285. -o, --output-file SBOM_OUTPUT
  286. SBOM output file. Defaults to sbom-binary-
  287. postbuild.cdx.json in current directory.
  288. --deep Enable deep mode to collect more used symbols and
  289. modules aggressively. Slow operation. Enables
  290. disassembly automatically (function-hash lookup with
  291. --use-blintdb, dex callgraph export for android apps).
  292. --stdout Print the SBOM to stdout instead of a file.
  293. -q, --quiet Disable logging and progress bars.
  294. --exports-prefix EXPORTS_PREFIX [EXPORTS_PREFIX ...]
  295. prefixes for the exports to be included in the SBOM.
  296. --bom-src SRC_DIR_BOMS [SRC_DIR_BOMS ...]
  297. Directories containing pre-build and build BOMs. Use
  298. to improve the precision.
  299. --use-blintdb Use blintdb v4 for symbol and disassembly-hash
  300. resolution. Defaults to true if the file exists at
  301. <user data dir>/blintdb/blint.db. Use environment variables:
  302. BLINTDB_IMAGE_URL, BLINTDB_HOME, and BLINTDB_REFRESH
  303. for customization.
  304. --wasm-sbom Emit SBOM components from WebAssembly Component Model
  305. binaries using their imported WIT interface packages
  306. (e.g. wasi:cli@0.2.0) as exact evidence. Core modules
  307. without component-model evidence are skipped.
  308. --jobs JOBS Parse up to N binaries in parallel worker processes.
  309. Accepts a positive integer, 0 or 'auto' for the CPU
  310. count. Defaults to 1 (sequential, unchanged behavior).
  311. --sdk-path SDK_PATH Path to an Apple SDK root whose .tbd stubs are used to
  312. attribute and confirm Mach-O dependency edges. Off by
  313. default; the path must contain .tbd files or the run
  314. aborts.
  315. ```
  316. An input that does not exist is reported and skipped, and the inputs that do exist are still scanned and written; the run then exits 1 unless `--no-error` is given. A symlink whose target is missing is skipped with a warning. blint reads files and directories: to scan a container image, export its filesystem first (`docker export $(docker create <image>) | tar -x -C rootfs`).
  317. </details>
  318. <details>
  319. <summary><strong>Callgraph-Match Sub-command Help</strong></summary>
  320. Matches a callgraph recovered from a compiled binary against one produced from
  321. source code, so binary functions can be identified even when the binary is
  322. stripped. Give it a source side (<code>--source</code> JSON or <code>--source-dir</code>,
  323. analyzed for you when it is a Rust crate) and a binary side (<code>--binary</code>, or
  324. <code>--binary-metadata</code> from a previous blint run). The primary quality knob is
  325. <code>--profile</code>; the <code>--min-votes</code>/<code>--margin</code>/<code>--khop</code>/<code>--fp-*</code>
  326. flags are expert overrides of that preset. The full guide covers layers, defaults, and
  327. honest accuracy results: [Callgraph matching](./docs/CALLGRAPH_MATCH.md).
  328. ```shell
  329. usage: blint callgraph-match [-h] [--source SOURCE_CALLGRAPH]
  330. [--source-dir SOURCE_DIR] [-l MATCH_LANGUAGE]
  331. [--rusi-cmd MATCH_RUSI_CMD]
  332. [--profile {precision,balanced,recall}]
  333. [--binary MATCH_BINARY]
  334. [--binary-metadata MATCH_BINARY_METADATA]
  335. [-o MATCH_OUTPUT]
  336. [--min-confidence {low,medium,high}]
  337. [--algorithm {anchors,layered}]
  338. [--no-propagation] [--with-fingerprint]
  339. [--min-votes MATCH_MIN_VOTES]
  340. [--margin MATCH_MARGIN]
  341. [--max-iterations MATCH_MAX_ITERATIONS]
  342. [--khop MATCH_KHOP]
  343. [--fp-min-shared MATCH_FP_MIN_SHARED]
  344. [--fp-min-score MATCH_FP_MIN_SCORE]
  345. [--fp-margin MATCH_FP_MARGIN] [-q]
  346. options:
  347. -h, --help show this help message and exit
  348. --source SOURCE_CALLGRAPH
  349. Path to a source-analysis callgraph JSON file.
  350. Alternatively use --source-dir to analyze a source
  351. tree directly.
  352. --source-dir SOURCE_DIR
  353. Path to a source tree to analyze (instead of
  354. --source). For Rust this runs rusi for you; set
  355. --rusi-cmd or the RUSI_CMD environment variable.
  356. -l, --language MATCH_LANGUAGE
  357. Source language for --source-dir analysis. Defaults to
  358. rust. rusi is invoked only when the language is rust.
  359. --rusi-cmd MATCH_RUSI_CMD
  360. Base command used to invoke rusi when --source-dir is
  361. a Rust project, for example 'cargo run -p rusi-cli --'
  362. or a path to a rusi binary. Falls back to the RUSI_CMD
  363. environment variable.
  364. --profile {precision,balanced,recall}
  365. Confidence preset that sets the matching knobs.
  366. precision favors high-confidence matches, recall
  367. enables structural fingerprinting, balanced is the
  368. default. Individual --min-votes/--margin/--khop/--fp-*
  369. flags override the preset.
  370. --binary MATCH_BINARY
  371. Path to a binary to parse with disassembly. Used when
  372. --binary-metadata is not supplied.
  373. --binary-metadata MATCH_BINARY_METADATA
  374. Path to a pre-generated blint *-metadata.json file.
  375. -o, --output MATCH_OUTPUT
  376. Write the full JSON match report to this path.
  377. --min-confidence {low,medium,high}
  378. Minimum confidence for matches listed in the report.
  379. Defaults to low.
  380. --algorithm {anchors,layered}
  381. Matching algorithm to use. Defaults to layered.
  382. --no-propagation Disable structural propagation and report only name-
  383. based anchors.
  384. --with-fingerprint Enable experimental Layer 2 structural fingerprint
  385. matching. Best suited to densely resolved callgraphs;
  386. may reduce precision on sparse ones.
  387. --min-votes MATCH_MIN_VOTES
  388. Layer 1: minimum agreeing matched neighbors to accept
  389. a propagated match. Overrides the --profile preset.
  390. --margin MATCH_MARGIN
  391. Layer 1: minimum vote lead over the runner-up.
  392. Overrides the preset.
  393. --max-iterations MATCH_MAX_ITERATIONS
  394. Maximum propagation/fingerprint rounds. Overrides the
  395. preset.
  396. --khop MATCH_KHOP Layer 2: hop radius for fingerprint context. Overrides
  397. the preset.
  398. --fp-min-shared MATCH_FP_MIN_SHARED
  399. Layer 2: minimum shared anchored neighbor names.
  400. Overrides the preset.
  401. --fp-min-score MATCH_FP_MIN_SCORE
  402. Layer 2: minimum combined Jaccard score to accept.
  403. Overrides the preset.
  404. --fp-margin MATCH_FP_MARGIN
  405. Layer 2: minimum Jaccard lead over the runner-up.
  406. Overrides the preset.
  407. -q, --quiet Disable logging and progress bars.
  408. ```
  409. </details>
  410. <details>
  411. <summary><strong>Canonicalize Sub-command Help</strong></summary>
  412. ```shell
  413. usage: blint canonicalize [-h] [--json] names [names ...]
  414. positional arguments:
  415. names Function names or raw mangled symbols to canonicalize.
  416. options:
  417. -h, --help show this help message and exit
  418. --json Emit the result as JSON instead of a table.
  419. ```
  420. </details>
  421. <details>
  422. <summary><strong>Capabilities Sub-command Help</strong></summary>
  423. ```shell
  424. usage: blint capabilities [-h] [--json]
  425. options:
  426. -h, --help show this help message and exit
  427. --json Emit the catalog as JSON (machine readable; for agents and
  428. tooling).
  429. ```
  430. </details>
  431. <details>
  432. <summary><strong>Diff Sub-command Help</strong></summary>
  433. Compare two versions of one binary. Inputs may be binaries or exported
  434. <code>*-metadata.json</code> files. The report covers metadata deltas
  435. (imports, exports, dependencies, entitlements, sections, identity),
  436. hardening regressions with an explicit per-property polarity, finding and
  437. capability-review deltas paired across rebuilds, and, with
  438. <code>--disassemble</code>, a function-level delta keyed on content hashes,
  439. so a recompile is not reported as rewritten code.
  440. ```shell
  441. usage: blint diff [-h] [--json] [--disassemble] [--no-reviews] [-q]
  442. old_input new_input
  443. positional arguments:
  444. old_input Old version: a binary or a blint *-metadata.json export.
  445. new_input New version: a binary or a blint *-metadata.json export.
  446. options:
  447. -h, --help show this help message and exit
  448. --json Emit the diff report as JSON (machine readable; for agents
  449. and tooling).
  450. --disassemble Disassemble binary inputs so the function-level delta
  451. (added/removed/changed by content hash) can be computed.
  452. Metadata-JSON inputs carry disassembly only if they were
  453. generated with --disassemble.
  454. --no-reviews Skip the capability-review delta.
  455. -q, --quiet Disable logging and progress bars.
  456. ```
  457. </details>
  458. <details>
  459. <summary><strong>DB Sub-command Help</strong></summary>
  460. ```shell
  461. usage: blint db [-h] [--no-error] [--download]
  462. [--image-url {ghcr.io/appthreat/blintdb-vcpkg:v4,ghcr.io/appthreat/blintdb-vcpkg-arm64:v4,ghcr.io/appthreat/blintdb-vcpkg-darwin-arm64:v4,ghcr.io/appthreat/blintdb-vcpkg-musl:v4,ghcr.io/appthreat/blintdb-meson:v4,ghcr.io/appthreat/blintdb-meson-arm64:v4,ghcr.io/appthreat/blintdb-meson-darwin-arm64:v4,ghcr.io/appthreat/blintdb-meson-musl:v4}]
  463. options:
  464. -h, --help show this help message and exit
  465. --no-error Continue on error to prevent build from breaking.
  466. --download Download the pre-compiled database to the
  467. <user data dir>/blintdb
  468. directory. Use the environment variable `BLINTDB_HOME`
  469. to override.
  470. --image-url {ghcr.io/appthreat/blintdb-vcpkg:v4,ghcr.io/appthreat/blintdb-vcpkg-arm64:v4,ghcr.io/appthreat/blintdb-vcpkg-darwin-arm64:v4,ghcr.io/appthreat/blintdb-vcpkg-musl:v4,ghcr.io/appthreat/blintdb-meson:v4,ghcr.io/appthreat/blintdb-meson-arm64:v4,ghcr.io/appthreat/blintdb-meson-darwin-arm64:v4,ghcr.io/appthreat/blintdb-meson-musl:v4}
  471. Blintdb image url. Defaults to
  472. ghcr.io/appthreat/blintdb-vcpkg-darwin-arm64:v4. The
  473. environment variable `BLINTDB_IMAGE_URL` is an
  474. alternative way to set this value.
  475. ```
  476. The default `--image-url` is platform dependent (the dump above was captured on macOS arm64, hence the `darwin-arm64` image); pick the image matching your platform and architecture from the listed choices.
  477. </details>
  478. <details>
  479. <summary><strong>Cache Sub-command Help</strong></summary>
  480. ```shell
  481. usage: blint cache [-h] {clear,stats} ...
  482. options:
  483. -h, --help show this help message and exit
  484. cache-actions:
  485. Cache management actions
  486. {clear,stats}
  487. clear Delete all cached parse metadata.
  488. stats Show cache location, entry count and actual size on disk.
  489. ```
  490. </details>
  491. ## Python API
  492. Analyze a single binary in process, with the same engine the CLI uses:
  493. ```python
  494. from blint import analyze, NotABinaryError
  495. result = analyze("/path/to/binary", disassemble=True)
  496. result.metadata # parsed metadata (same content as *-metadata.json)
  497. result.findings # security-check findings, each with a stable finding_id
  498. result.reviews # capability reviews
  499. result.fuzzables # fuzzable targets (suggest_fuzzable=True)
  500. result.coverage # run-level analysis_coverage block (units, failures, skips)
  501. ```
  502. `analyze()` writes no report files. A missing path raises `FileNotFoundError`, a file blint cannot parse raises `NotABinaryError`, and a failed analysis raises `AnalysisFailedError` with the structured failure record attached, so a clean result can never be mistaken for a blind one. Calls are serialized by an internal lock (the engine's rule state is module-global); sequential calls with different options each see their own rules.
  503. Every finding carries a `finding_id`: a content hash over `(rule id, binary sha256, evidence locator)`, deliberately not over titles, descriptions, paths or the blint version, so findings can be tracked, suppressed and diffed across runs on the same bytes.
  504. ## References
  505. - [Lessons from building blint v4](./docs/LESSONS.md)
  506. - [lief examples](https://github.com/lief-project/LIEF/tree/master/examples)
  507. - [checksec.py](https://github.com/slimm609/checksec.py)
  508. ## Sponsorship
  509. If you love `blint`, please consider [donating to our project](https://owasp.org/donate?reponame=www-project-dep-scan&title=OWASP+dep-scan). In addition, `blint` is made possible by the incredible work of the LIEF project. Please consider sponsoring them as well.
  510. - [LIEF Project](https://github.com/sponsors/lief-project/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.