From 383dd943c17a9bde143e68914189f130db28c8c8 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Tue, 28 Jul 2026 18:23:02 -0700 Subject: [PATCH 01/14] docs: link release notes from the README documentation index The changelog lives in GitHub Releases (synced to the landing page per release), but nothing in the repo pointed at it. Co-Authored-By: Claude Fable 5 --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index ed86d287..da1de6a9 100644 --- a/README.md +++ b/README.md @@ -221,6 +221,7 @@ See [Plugins](docs/PLUGINS.md) for install, trust, and authoring guidance. - [MCP Server](docs/MCP.md) - connect Bomly to Claude Code, Cursor, VS Code, or another MCP client - [Reachability](docs/REACHABILITY.md) - experimental reachable-vulnerability triage - [Plugins](docs/PLUGINS.md) - managed external detectors, matchers, and auditors +- [Release Notes](https://github.com/bomly-dev/bomly-cli/releases) - what changed in each version - [All Documentation](docs/README.md) - full docs index Contributor setup lives in [CONTRIBUTING.md](CONTRIBUTING.md). Architecture details live in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). From 8118314972c26d8a983bf64f24fbe53ec8ea48c5 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Tue, 28 Jul 2026 18:23:58 -0700 Subject: [PATCH 02/14] docs: mirror site navigation in the docs index and codify style conventions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/README.md previously used its own Guides/Concepts/Reference/Project grouping while docs/manifest.json (which drives the site nav) uses start/concepts/reference/operations/experimental — GitHub readers and site readers saw different maps. The index now mirrors the manifest groups. CONTRIBUTING gains the docs rules that were previously tribal knowledge: manifest/slug discipline (with the redirect caveat), link-text and relative-link rules, copy-pasteability rules, and a single experimental banner template. REACHABILITY.md is updated to lead with that template's fixed sentence; the --analyze flag help already carries [Experimental]. Co-Authored-By: Claude Fable 5 --- CONTRIBUTING.md | 17 +++++++++++++++++ docs/REACHABILITY.md | 2 +- docs/README.md | 45 +++++++++++++++++++++++++++----------------- 3 files changed, 46 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3042d797..4ddd1e48 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -139,6 +139,23 @@ Run `make generate` after changing any of: For per-detector and per-matcher prose (Phase 2 hybrid generation), add a Markdown file under `internal/support/prose/{detectors,matchers}/.md` and re-run `make generate`. The generator embeds the prose between the structured fact table and the auto-generated banner. +### Docs navigation and slugs + +- Every top-level page in `docs/` needs an entry in `docs/manifest.json`, and the groups in `docs/README.md` mirror the manifest groups. `internal/support/manifest_test.go` enforces the 1:1 page/manifest sync; nested directories (`detectors/`, `matchers/`, `schemas/`, …) are auto-discovered by the site renderer and stay out of the manifest. +- A published slug is a URL. Do not rename or delete a manifest slug without coordinating a redirect in the landing-page repo first — the docs site has no automatic redirects, so a dropped slug is a permanently broken link. + +### Docs style + +- Link text names the destination ("see [Exit Codes](docs/EXIT_CODES.md)"), never "here" or "this page". +- Self-references are always relative links. Never hardcode absolute `https://bomly.dev/...` doc URLs in Markdown — they break silently when the site structure changes. +- Anything copy-pasteable uses straight quotes and one canonical spelling per command. If two pages show the same invocation, they show it identically. +- Prefer showing real expected output after a command. Wrap output longer than ~20 lines in `
Output…
`. +- Experimental features carry three markers that must agree: `experimental: true` on the manifest entry, an `[Experimental]` prefix in the flag help text, and a banner as the first block of the page: + + ```markdown + > ⚠️ **Experimental.** This feature may change without preserving backwards compatibility. + ``` + ## Release Bumps Bomly creates draft releases automatically after merges to `main`. The release workflow reads commit messages since the last `vX.Y.Z` tag and chooses the next version from the final merge history. diff --git a/docs/REACHABILITY.md b/docs/REACHABILITY.md index 48ab652b..1a403e25 100644 --- a/docs/REACHABILITY.md +++ b/docs/REACHABILITY.md @@ -1,6 +1,6 @@ # Reachability -> ⚠️ **Experimental.** Reachability is opt-in (`--analyze`) and under active development. The output shape is stable, but ecosystem coverage is expanding and Tier-3 analyzers (`jsreach`, `pyreach`, `jvmreach`) report at package precision today — sufficient for triage, not a fix substitute. Do not use `--fail-on reachable` as the sole gate for security-critical decisions without understanding the limitations below. +> ⚠️ **Experimental.** This feature may change without preserving backwards compatibility. Reachability is opt-in (`--analyze`) and under active development: the output shape is stable, but ecosystem coverage is expanding and Tier-3 analyzers (`jsreach`, `pyreach`, `jvmreach`) report at package precision today — sufficient for triage, not a fix substitute. Do not use `--fail-on reachable` as the sole gate for security-critical decisions without understanding the limitations below. `--analyze` runs code analysis on top of vulnerability matching to confirm whether a finding is actually reachable from your application code. Reachability annotations are written onto the matching `sdk.Vulnerability` records inside the PURL-keyed `sdk.PackageRegistry`. The output layer resolves them at projection time via `(Finding.PackageRef, Finding.VulnerabilityID)`, so reachability surfaces consistently in JSON, SARIF, and the text/TUI views without needing a separate field on `Finding`. See [Architecture → Domain model](ARCHITECTURE.md#domain-model) for the registry data model. diff --git a/docs/README.md b/docs/README.md index f1a4ee85..16f961d1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,56 +1,67 @@ # Bomly Documentation -Start with [Getting Started](GETTING_STARTED.md) if you're new. Otherwise pick the section that matches what you're doing. +Start with [Getting Started](GETTING_STARTED.md) if you're new. Otherwise pick the section that matches what you're doing. The sections below mirror the groups on the [documentation site](https://bomly.dev/docs), so this index and the site navigation always tell the same story. -## Guides +## Getting started -Task-oriented walkthroughs. +Install Bomly and run your first scan. -- [Installation](INSTALLATION.md) — install methods, `bomly` vs `bomly-lite`, checksum verification, uninstall - [Getting Started](GETTING_STARTED.md) — first scan, enrich, audit, diff +- [Installation](INSTALLATION.md) — install methods, `bomly` vs `bomly-lite`, checksum verification, uninstall - [Use Cases](USE_CASES.md) — recipes for PR gates, SBOMs, triage, license and offline scans - [Scan Targets](SCAN_TARGETS.md) — directories, Git repos, containers, SBOMs - [Output Formats](OUTPUT_FORMATS.md) — text, JSON, SARIF, SBOM - [SBOM Formats](SBOM.md) — SPDX vs. CycloneDX, write and ingest -- [CI Integration](CI_INTEGRATION.md) — GitHub Actions, GitLab, Jenkins, Azure, CircleCI -- [CI-Readiness Warnings](CI_READINESS.md) — package-manager, lockfile-format, and install-policy mismatches that fail CI on their own -- [Bomly Guard](BOMLY_GUARD.md) — the turnkey GitHub Action for PR dependency review -- [Finding Baselines](BASELINES.md) — keep accepted package findings visible without failing audits -- [Interactive TUI](TUI.md) — keybindings and tabs for `--interactive` -- [Troubleshooting](TROUBLESHOOTING.md) — common errors and fixes -## Concepts +## How it works -How Bomly thinks about your project. +What Bomly does, and why each piece exists. - [Architecture](ARCHITECTURE.md) — the scan pipeline, domain model, and network behavior - [Security and Trust Boundaries](SECURITY.md) — permissions, network behavior, plugins, input limits, and residual risks - [Detectors](DETECTORS.md) — turning project evidence into a dependency graph - [Matchers](MATCHERS.md) — enriching the graph with vulnerability, license, lifecycle data - [Auditors](AUDITORS.md) — evaluating the graph against policy -- [Reachability](REACHABILITY.md) — narrowing findings to code your app actually calls - [MCP Server](MCP.md) — connect Bomly to Claude Code, Cursor, VS Code, or another MCP client - [Plugins](PLUGINS.md) — install, trust, configure, and package external plugins - Plugin implementation guides: [detector](plugins/how-to-implement-detector.md), [matcher](plugins/how-to-implement-matcher.md), [auditor](plugins/how-to-implement-auditor.md) - Example plugin repos: [Bun detector](https://github.com/bomly-dev/bomly-plugin-bun-lock-detector), [ClearlyDefined matcher](https://github.com/bomly-dev/bomly-plugin-clearlydefined-matcher), [EOL lifecycle matcher](https://github.com/bomly-dev/bomly-plugin-eol-matcher), [Meme auditor](https://github.com/bomly-dev/bomly-plugin-meme-auditor) -- [Glossary](GLOSSARY.md) — every term, one sentence each ## Reference -Generated from code. Treat as authoritative. +Specifications and matrices. The generated pages are regenerated from code by `make generate` — treat those as authoritative. -- [Config Reference](CONFIG_REFERENCE.md) — every config key, env var, default, flag - [Support Matrix](SUPPORT_MATRIX.md) — every ecosystem and package manager +- [Config Reference](CONFIG_REFERENCE.md) — every config key, env var, default, flag - [Exit Codes](EXIT_CODES.md) — what each process exit value means +- [Interactive TUI](TUI.md) — keybindings and tabs for `--interactive` +- [JSON Schemas](SCHEMAS.md) — scan, explain, diff output shapes +- [Glossary](GLOSSARY.md) — every term, one sentence each - [Detector Ecosystem Guides](detectors/ecosystems/) — per-ecosystem detector chains - [Matcher Reference](matchers/) — per-matcher behavior, cache, output - [Auditor Reference](auditors/) — per-auditor options, examples, limitations -- [JSON Schemas](SCHEMAS.md) — scan, explain, diff output shapes + +## Operations + +Running Bomly in CI and keeping pipelines healthy. + +- [CI Integration](CI_INTEGRATION.md) — GitHub Actions, GitLab, Jenkins, Azure, CircleCI +- [CI-Readiness Warnings](CI_READINESS.md) — package-manager, lockfile-format, and install-policy mismatches that fail CI on their own +- [Bomly Guard](BOMLY_GUARD.md) — the turnkey GitHub Action for PR dependency review +- [Finding Baselines](BASELINES.md) — keep accepted package findings visible without failing audits +- [Troubleshooting](TROUBLESHOOTING.md) — common errors and fixes + +## Experimental + +Features that are still maturing. + +- [Reachability](REACHABILITY.md) — narrowing findings to code your app actually calls ## Project For contributors and release engineers. These live outside the published docs in [`dev-docs/`](../dev-docs/). +- [Release Notes](https://github.com/bomly-dev/bomly-cli/releases) — what changed in each version - [Architecture (deep dive)](../dev-docs/ARCHITECTURE.md) — full pipeline, package boundaries, decision log - [Domain Models](../dev-docs/MODELS.md) — SDK types behind detection, matching, and audit - [CI](../dev-docs/CI.md) — Bomly's own internal CI configuration From 5be5c4bf608610ebc498e1f2fdaec84221b34fc3 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Tue, 28 Jul 2026 18:24:46 -0700 Subject: [PATCH 03/14] docs: add a question-driven FAQ page Troubleshooting is organized by error and exit code; there was no page for the questions people ask before adopting the tool (privacy, accounts, telemetry, how it relates to image scanners, lockfile expectations, unreachable-is-not-safe). Registered in the manifest under Getting started and linked from both documentation indexes. Co-Authored-By: Claude Fable 5 --- README.md | 1 + docs/FAQ.md | 47 ++++++++++++++++++++++++++++++++++++++++++++++ docs/README.md | 1 + docs/manifest.json | 6 ++++++ 4 files changed, 55 insertions(+) create mode 100644 docs/FAQ.md diff --git a/README.md b/README.md index da1de6a9..2fb2dd97 100644 --- a/README.md +++ b/README.md @@ -211,6 +211,7 @@ See [Plugins](docs/PLUGINS.md) for install, trust, and authoring guidance. ## Documentation - [Getting Started](docs/GETTING_STARTED.md) - install Bomly and run your first scan +- [FAQ](docs/FAQ.md) - quick answers on privacy, accounts, and tool differences - [Installation](docs/INSTALLATION.md) - install methods, checksums, upgrades, uninstall - [Use Cases](docs/USE_CASES.md) - practical recipes for PR gates, SBOMs, triage, and offline scans - [Scan Targets](docs/SCAN_TARGETS.md) - directories, Git repos, containers, and SBOMs diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 00000000..cf8081fc --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,47 @@ +# FAQ + +Short answers to the questions people ask before and shortly after their first scan. For error messages and broken runs, see [Troubleshooting](TROUBLESHOOTING.md) instead — it is organized by symptom and exit code. + +## Does Bomly send my code anywhere? + +No. A plain `bomly scan` runs entirely against local files and makes no matcher network calls. When you opt in with `--enrich`, Bomly sends package identifiers — name, version, ecosystem, and for Scorecard the source repository URL — to the enrichment services you selected. It never uploads your source code, and the CISA KEV catalog is downloaded as a whole rather than queried per package. See [Matchers → Network endpoints](MATCHERS.md#network-endpoints) and [Architecture → Network behavior](ARCHITECTURE.md#network-behavior) for the complete model, including the separate boundaries for `--url`, build-tool detectors, and `--install-first`. + +## Do I need an account, API key, or login? + +No. Bomly has no account system, no license key, and no sign-up. Every feature in this documentation works with the binary alone. + +## Does Bomly collect telemetry? + +No. Bomly sends no usage data, crash reports, or version pings. The only network traffic is what you explicitly trigger (`--enrich`, `--url`, `--image`, `--install-first`, plugin installation). + +## How is Bomly different from image scanners like Trivy or Grype? + +Different focus. General-purpose scanners are built to cover many target and finding types — container images, IaC misconfigurations, secrets — with vulnerability detection per target. Bomly is built around one thing: the dependency graph. It keeps the full graph so it can answer *why* a package is present (`bomly explain`), *what changed* between two refs or SBOMs (`bomly diff`), and *whether a vulnerability is actually reachable* from your code (`--analyze`), alongside SBOM generation and policy auditing. For container images, Bomly embeds the same Syft technology those tools build on. The tools compose: many teams run an image scanner for images and Bomly for dependency intelligence and PR review. + +## Why does my scan show fewer dependencies than I expected? + +Bomly resolves the graph from evidence — lockfiles first, then package-manager output, then fallbacks. If a project has no lockfile, the responsible detector may fall back to a coarser source and report a `fallback` warning, which means transitive dependencies can be missing. Check the warnings in the report, commit a lockfile, or use `--install-first` to let the detector materialize one. See [Detectors](DETECTORS.md) and [CI-readiness warnings](CI_READINESS.md). + +## Does "unreachable" mean the vulnerability is safe to ignore? + +No. Reachability is a triage signal: "unreachable" at package precision means static analysis found no import path, and static analysis cannot see dynamic imports, plugin loaders, or runtime code generation. Use it to prioritize, not to dismiss. Read [Reachability](REACHABILITY.md) — especially ["Unreachable" is not "safe"](REACHABILITY.md#unreachable-is-not-safe) — before gating CI on `--fail-on reachable`. + +## Does `--audit` make network calls? + +No. `--audit` evaluates the vulnerability and license data already present on packages. Fetching that data is `--enrich`'s job; combine them (`--enrich --audit`) when you want to fetch and evaluate in one run. See [Auditors](AUDITORS.md). + +## Why did my scan exit non-zero? + +Bomly uses a small, stable set of exit codes: `2` means a finding matched your `--fail-on` policy, while `1`, `3`, `4`, and `5` distinguish execution errors, resolution failures, invalid input, and "nothing to evaluate". [Exit Codes](EXIT_CODES.md) has the full table and CI recipes for branching on them. + +## Should I install `bomly` or `bomly-lite`? + +`bomly` is the full binary with builtin Syft and Grype — no external tools needed. `bomly-lite` is a smaller download that shells out to `syft` and `grype` on your `PATH`. Both behave the same from the command line. If in doubt, install `bomly`. See [Installation](INSTALLATION.md#bomly-vs-bomly-lite). + +## Where are the release notes? + +On [GitHub Releases](https://github.com/bomly-dev/bomly-cli/releases). Draft releases are created automatically after merges to `main`, and the documentation site is versioned per release. + +## Where do I ask something this page doesn't answer? + +[Bomly Discussions](https://github.com/orgs/bomly-dev/discussions) for questions and ideas; this repository's issues for confirmed bugs and actionable work. diff --git a/docs/README.md b/docs/README.md index 16f961d1..9ece548e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,7 @@ Install Bomly and run your first scan. - [Scan Targets](SCAN_TARGETS.md) — directories, Git repos, containers, SBOMs - [Output Formats](OUTPUT_FORMATS.md) — text, JSON, SARIF, SBOM - [SBOM Formats](SBOM.md) — SPDX vs. CycloneDX, write and ingest +- [FAQ](FAQ.md) — quick answers on privacy, accounts, tool differences, and first-scan surprises ## How it works diff --git a/docs/manifest.json b/docs/manifest.json index 196b1cdb..d0ee6fe4 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -57,6 +57,12 @@ "description": "Text, JSON, SARIF, and SBOM artifacts — when to use each and how to combine them.", "group": "start" }, + { + "slug": "faq", + "title": "FAQ", + "description": "Quick answers on privacy, accounts, tool differences, and first-scan surprises.", + "group": "start" + }, { "slug": "sbom", "title": "SBOM formats", From 3702527113588ad1f7df82dcb1b5f2020a7816f8 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Tue, 28 Jul 2026 18:25:38 -0700 Subject: [PATCH 04/14] docs: add a network and privacy page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The opt-in network posture is the headline differentiator but its evidence was scattered across ARCHITECTURE, SECURITY, and MATCHERS. One page now enumerates every network trigger, what each contacts and transmits, what is never sent, and how to keep a run offline — making the README claim auditable instead of asserted. Co-Authored-By: Claude Fable 5 --- README.md | 2 +- docs/NETWORK.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ docs/README.md | 1 + docs/manifest.json | 6 ++++++ 4 files changed, 52 insertions(+), 1 deletion(-) create mode 100644 docs/NETWORK.md diff --git a/README.md b/README.md index 2fb2dd97..06cac03f 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Bomly is a free, open-source CLI for dependency intelligence. It scans source trees, SBOMs, Git refs, and container images; explains why dependencies are present; enriches packages with vulnerability and license data when you ask for it; evaluates policy; and writes automation-friendly output for CI. -Free and open source, no account, no login. One binary. No service to host. No telemetry. No outbound matcher calls unless you opt in with `--enrich`. +Free and open source, no account, no login. One binary. No service to host. No telemetry. No outbound matcher calls unless you opt in with `--enrich`. [Network and Privacy](docs/NETWORK.md) documents every network trigger so you can audit that claim instead of taking it on faith. ## Install Bomly diff --git a/docs/NETWORK.md b/docs/NETWORK.md new file mode 100644 index 00000000..87807395 --- /dev/null +++ b/docs/NETWORK.md @@ -0,0 +1,44 @@ +# Network and Privacy + +Bomly's rule is simple: **it touches the network only when a flag you passed requires it, and it never sends telemetry.** This page is the audit surface for that claim — every network trigger, what it contacts, what it transmits, and how to keep a run fully offline. + +A plain `bomly scan` of a local directory reads files and exits. No matcher calls, no version checks, no usage pings, no account. + +## What triggers network access + +| You pass | Bomly contacts | What is transmitted | +| --- | --- | --- | +| *(nothing)* | Nothing | — | +| `--enrich` | `api.osv.dev`, `api.cisa.gov`, `api.deps.dev`; `api.scorecard.dev` (Scorecard matcher); Grype database service (`grype.anchore.io/databases`, plus the archive URL it returns) on first use | Package identifiers: name, version, ecosystem/PURL. Scorecard queries use the package's source repository URL. The KEV catalog and Grype database are bulk downloads — no per-package data is sent. Never source code. | +| `--url` | The Git host you named | A `git clone` of that repository (10-minute deadline; checkout size, path, and symlink limits apply) | +| `--image` | The container registry for the reference | An image pull via the embedded Syft (or your external `syft` in the lite build) | +| `--install-first` | Your package manager's configured registries | Whatever `npm install`, `pip install`, etc. transmit — the package manager owns this traffic and its credentials | +| Build-tool-backed detectors | The build tool's configured registries | Some detectors run a build tool (Maven, Gradle, Go, …) when file evidence alone can't resolve the graph; that tool may download dependencies under its own configuration | +| `bomly plugins install` | The install source you named (e.g. GitHub) | A plugin package download, verified against size and archive-safety limits | +| Enabled external matcher plugins + `--enrich` | Their documented services (e.g. ClearlyDefined, endoflife.date) | Package identifiers, per the plugin's own documentation | + +Two flags never trigger network access on their own: `--audit` evaluates data already present on packages, and `--analyze` runs local code analysis. MCP requests follow exactly the same gates as the equivalent CLI flags. + +## What Bomly never sends + +- **Telemetry** — no usage data, crash reports, install IDs, or update checks. There is no endpoint for them. +- **Source code** — enrichment sends package coordinates, not file contents. +- **Credentials to built-in services** — built-in matcher requests are unauthenticated. Errors and logs never include configured endpoint or proxy credentials. + +## Keeping a run offline + +For an air-gapped or network-restricted pipeline: + +1. Don't pass `--enrich`, `--url`, `--image`, or `--install-first`; scan a local checkout. +2. Prefer projects with committed lockfiles, so lockfile detectors resolve the graph without a build tool. Pin `--detectors` in CI to make an unexpected fallback fail loudly instead of degrading silently — see [CI-readiness warnings](CI_READINESS.md). +3. Matcher responses are cached under `~/.bomly/cache/` with per-matcher TTLs, so a previously enriched environment keeps working through upstream outages — but an expired cache entry on an offline host is a miss, not stale data. See [Matchers → Cache](MATCHERS.md#cache). + +## Proxies, custom endpoints, and CAs + +Built-in HTTP clients honor configured proxies, no-proxy rules, and additional CA certificates, and support custom OSV/Scorecard endpoints — including private-network destinations — via trusted configuration (user config, `--config`, `BOMLY_CONFIG`, or environment variables; repository config is never loaded automatically). Redirects follow Go's standard rules, and Bomly deliberately does not block private addresses so self-hosted mirrors work. The trade-offs of that choice are documented in [Security → Network Trust](SECURITY.md#network-trust); the keys live in the [Config Reference](CONFIG_REFERENCE.md). + +## See also + +- [Architecture → Network behavior](ARCHITECTURE.md#network-behavior) — the same boundaries in pipeline context +- [Security and Trust Boundaries](SECURITY.md) — the full permission model and residual risks +- [Matchers](MATCHERS.md) — per-service endpoints, cache, and failure semantics diff --git a/docs/README.md b/docs/README.md index 9ece548e..71ff21e3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,6 +19,7 @@ Install Bomly and run your first scan. What Bomly does, and why each piece exists. - [Architecture](ARCHITECTURE.md) — the scan pipeline, domain model, and network behavior +- [Network and Privacy](NETWORK.md) — every network trigger, what it transmits, and how to stay offline - [Security and Trust Boundaries](SECURITY.md) — permissions, network behavior, plugins, input limits, and residual risks - [Detectors](DETECTORS.md) — turning project evidence into a dependency graph - [Matchers](MATCHERS.md) — enriching the graph with vulnerability, license, lifecycle data diff --git a/docs/manifest.json b/docs/manifest.json index d0ee6fe4..2694a890 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -75,6 +75,12 @@ "description": "How the scan pipeline is structured: targets, detectors, matchers, auditors.", "group": "concepts" }, + { + "slug": "network", + "title": "Network and privacy", + "description": "Every network trigger, what it contacts and transmits, and how to keep a run offline.", + "group": "concepts" + }, { "slug": "security", "title": "Security and trust boundaries", From 06a28d6757694adc57c0085728850b52f3786367 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Tue, 28 Jul 2026 18:28:17 -0700 Subject: [PATCH 05/14] docs: add per-command reference pages for scan, explain, and diff MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The three graph commands had no dedicated pages — their flags were spread across six feature pages — and the ARCHITECTURE command table was stale (it omitted baseline, plugins, and mcp). Each new page follows one anatomy: job, minimal invocation with real captured output, the flag groups that matter, exit codes, and cross-links instead of duplicated prose. A COMMANDS index carries the shared option surface and the selector grammar. Co-Authored-By: Claude Fable 5 --- docs/ARCHITECTURE.md | 23 ++++++----- docs/COMMANDS.md | 19 +++++++++ docs/README.md | 1 + docs/commands/diff.md | 68 +++++++++++++++++++++++++++++++ docs/commands/explain.md | 61 ++++++++++++++++++++++++++++ docs/commands/scan.md | 87 ++++++++++++++++++++++++++++++++++++++++ docs/manifest.json | 7 ++++ 7 files changed, 256 insertions(+), 10 deletions(-) create mode 100644 docs/COMMANDS.md create mode 100644 docs/commands/diff.md create mode 100644 docs/commands/explain.md create mode 100644 docs/commands/scan.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b8288995..2968128c 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -4,16 +4,19 @@ A tour of how Bomly turns a scan target into a report — the stages a scan runs ## Commands -Bomly is a CLI. Everything runs through one of four commands: - -| Command | Purpose | -|-----------------|--------------------------------------------------------| -| `bomly scan` | Resolve dependencies, render reports, and write SBOMs | -| `bomly explain` | Show why a dependency exists in a graph | -| `bomly diff` | Compare dependency state across Git refs or SBOM files | -| `bomly version` | Print version information | - -Each invocation works on exactly one target: a filesystem path, a container image, a remote Git repository, or an existing SBOM file. See [Scan targets](SCAN_TARGETS.md) for the details of each. +Bomly is a CLI. Three commands run the dependency pipeline described on this page, and three manage the machinery around it: + +| Command | Purpose | +|-----------------|----------------------------------------------------------------------| +| `bomly scan` | Resolve dependencies, render reports, and write SBOMs | +| `bomly explain` | Show why a dependency exists in a graph | +| `bomly diff` | Compare dependency state across Git refs, SBOM files, or image tags | +| `bomly baseline`| Create and inspect finding baselines | +| `bomly plugins` | List, install, enable, verify, and test external plugins | +| `bomly mcp` | Serve Bomly's tools to MCP-aware AI agents | +| `bomly version` | Print version information | + +Each pipeline invocation works on exactly one target: a filesystem path, a container image, a remote Git repository, or an existing SBOM file. See [Commands](COMMANDS.md) for the per-command reference and [Scan targets](SCAN_TARGETS.md) for the details of each target. ## The scan pipeline diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md new file mode 100644 index 00000000..777a40c0 --- /dev/null +++ b/docs/COMMANDS.md @@ -0,0 +1,19 @@ +# Commands + +Everything Bomly does runs through one of these commands. The three graph commands have dedicated reference pages; the others are documented on their feature pages. + +| Command | Purpose | Reference | +| --- | --- | --- | +| `bomly scan` | Resolve dependencies, render reports, and write SBOMs | [scan](commands/scan.md) | +| `bomly explain` | Show every path that pulls a package into the graph | [explain](commands/explain.md) | +| `bomly diff` | Compare dependency state across Git refs, SBOM files, or image tags | [diff](commands/diff.md) | +| `bomly baseline` | Create and inspect finding baselines | [Finding Baselines](BASELINES.md) | +| `bomly plugins` | List, install, enable, verify, and test external plugins | [Plugins](PLUGINS.md) | +| `bomly mcp` | Serve Bomly's tools to MCP-aware AI agents | [MCP Server](MCP.md) | +| `bomly version` | Print version information | — | + +The three graph commands share one option surface: the same target flags (`--path`, `--recursive`, `--url`/`--ref`, `--image`, `--sbom`), the same pipeline gates (`--enrich`, `--audit`, `--analyze`), the same component selectors (`--detectors`, `--matchers`, `--auditors`, `--analyzers`), and the same output flags (`--format`, `-o`, `--json`). Learn them once on the [scan](commands/scan.md) page; the [explain](commands/explain.md) and [diff](commands/diff.md) pages cover only what differs. + +Selectors use one grammar everywhere: a bare list replaces the default set (`--matchers osv`), `+name` appends to the defaults, and `-name` removes from them (`--matchers -depsdev-license-matcher`). Output targets use `-o ` or `-o =`, repeatable for multiple artifacts in one run. + +For every flag with its config key, environment variable, and default, see the generated [Config Reference](CONFIG_REFERENCE.md) — or run `bomly --help`. diff --git a/docs/README.md b/docs/README.md index 71ff21e3..ba9a31bd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -33,6 +33,7 @@ What Bomly does, and why each piece exists. Specifications and matrices. The generated pages are regenerated from code by `make generate` — treat those as authoritative. +- [Commands](COMMANDS.md) — per-command reference for [scan](commands/scan.md), [explain](commands/explain.md), and [diff](commands/diff.md) - [Support Matrix](SUPPORT_MATRIX.md) — every ecosystem and package manager - [Config Reference](CONFIG_REFERENCE.md) — every config key, env var, default, flag - [Exit Codes](EXIT_CODES.md) — what each process exit value means diff --git a/docs/commands/diff.md b/docs/commands/diff.md new file mode 100644 index 00000000..db806d71 --- /dev/null +++ b/docs/commands/diff.md @@ -0,0 +1,68 @@ +# bomly diff + +Compare dependency state between two points — two Git refs, two SBOM files, or two container image tags — and report what changed. `diff` runs the [scan](scan.md) pipeline against both states, so the same target flags and gates apply to each side. + +## Minimal invocation + +```bash +bomly diff --base main --head HEAD +``` + +Comparing two commits where `express` was upgraded: + +```text +Added (1) + + encodeurl@2.0.0 MIT runtime +Version changed (9) + ~ body-parser 1.20.2 → 1.20.3 + ~ cookie 0.6.0 → 0.7.1 + ~ express 4.19.2 → 4.21.2 + ~ finalhandler 1.2.0 → 1.3.1 + ~ merge-descriptors 1.0.1 → 1.0.3 + ~ path-to-regexp 0.1.7 → 0.1.12 + ~ qs 6.11.0 → 6.13.0 + ~ send 0.18.0 → 0.19.0 + ~ serve-static 1.15.0 → 1.16.2 +``` + +Beyond additions, removals, and version changes, `diff` also reports changes to a dependency's relationship (direct vs transitive), source, and registry-matching eligibility — the detail shifts that alter your exposure without a version number moving. + +## What to compare + +```bash +# Git refs of the current repository (or a remote one via --url) +bomly diff --base main --head HEAD +bomly diff --url https://github.com/owner/repo --base v1.2.0 --head v1.3.0 + +# Two SBOM files +bomly diff --sbom --base ./before.cdx.json --head ./after.cdx.json + +# Two tags or digests of a container image +bomly diff --image alpine --base 3.19 --head 3.20 +``` + +## Audit the delta + +Add `--enrich --audit` to classify findings between the two states into three buckets — **introduced** (present in head, absent in base), **resolved** (present in base, absent in head), and **persisted** (present in both): + +```bash +bomly diff --base main --head HEAD --enrich --audit --fail-on high +``` + +`--fail-on` gates on the *introduced* bucket, so this is the PR-gate form: fail the build when the change introduces a matching finding, without complaining about pre-existing ones. See [Auditors → Diff and auditing](../AUDITORS.md#diff-and-auditing). This is exactly what [Bomly Guard](../BOMLY_GUARD.md) runs on pull requests, with the result rendered as a PR comment. + +```bash +bomly diff --base main --head HEAD --json # structured delta for tooling +``` + +The JSON shape is documented in the [diff schema](../schemas/diff.md). + +## Exit codes + +Same table as every command ([Exit Codes](../EXIT_CODES.md)): `2` when an audited head-side finding matches `--fail-on`, `3`/`5` when either side fails to resolve or has nothing to evaluate. + +## See also + +- [scan](scan.md) — the shared target, gate, and output flags +- [Bomly Guard](../BOMLY_GUARD.md) — this command as a turnkey GitHub Action +- [Use Cases → Release diff](../USE_CASES.md) — reviewing dependency changes between releases diff --git a/docs/commands/explain.md b/docs/commands/explain.md new file mode 100644 index 00000000..f190f933 --- /dev/null +++ b/docs/commands/explain.md @@ -0,0 +1,61 @@ +# bomly explain + +Answer "why is this package here?" — trace every dependency path that pulls a package into the graph. `explain` runs the same detect and match stages as [scan](scan.md), then walks the graph from the project roots to the package you named. + +## Minimal invocation + +```bash +bomly explain send +``` + +On a project that depends on `express`: + +```text +ecosystem npm +manager npm +package send@0.18.0 +scope runtime +direct no +licenses + MIT [declared] +introduced by: + demo@1.0.0 + └─ express@4.19.2 + ├─ send@0.18.0 [analyzed] (transitive) + └─ serve-static@1.15.0 + └─ send@0.18.0 [analyzed] (transitive) +``` + +Every path is shown, not just the shortest one — here `send` enters both directly through `express` and again through `serve-static`, which matters when you're deciding what to bump. + +## Naming the package + +Pass a package name or a full PURL. A PURL disambiguates when the same name exists in more than one ecosystem: + +```bash +bomly explain lodash +bomly explain pkg:npm/react +bomly explain github.com/spf13/cobra --path ./backend +``` + +## Targets and gates + +`explain` accepts the same target flags as scan (`--path`, `--recursive`, `--url`/`--ref`, `--image`, `--sbom`) and the same pipeline gates. Add `--enrich` to include the package's vulnerabilities in the explanation, and `--audit`/`--analyze` when you want policy findings or reachability on it: + +```bash +bomly explain send --enrich # include known vulnerabilities +bomly explain send --enrich --analyze # and whether they're reachable +bomly explain send --json # structured paths for tooling +``` + +The JSON shape is documented in the [explain schema](../schemas/explain.md). + +## Exit codes + +Same table as every command — see [Exit Codes](../EXIT_CODES.md). Notably `5` when the target has no supported manifests, and `4` for a malformed PURL. + +## See also + +- [scan](scan.md) — the shared target, gate, and output flags +- [diff](diff.md) — when the question is "what changed" rather than "why is it here" +- [Interactive TUI](../TUI.md) — explore the same paths interactively with `bomly scan --interactive` diff --git a/docs/commands/scan.md b/docs/commands/scan.md new file mode 100644 index 00000000..90274217 --- /dev/null +++ b/docs/commands/scan.md @@ -0,0 +1,87 @@ +# bomly scan + +Resolve a target's dependencies into one consolidated graph, then optionally enrich, analyze, audit, and render it. `scan` is the pipeline every other graph command builds on — flags you learn here work the same way on [explain](explain.md) and [diff](diff.md). + +## Minimal invocation + +```bash +bomly scan +``` + +Scans the current directory. On a small npm project: + +```text +✓ 68 packages in 1 manifest (1 direct, 67 transitive · runtime 68, dev 0) + +Top-level dependencies + NAME VERSION LICENSE SCOPE VULNS + express 4.19.2 MIT runtime - +``` + +No network calls happen here — enrichment columns stay empty until you ask for them. + +## Choose a target + +One target per invocation: + +```bash +bomly scan --path ./services/api # a specific directory +bomly scan --recursive # discover nested subprojects (see --max-depth, --exclude) +bomly scan --url https://github.com/owner/repo --ref v1.2.3 # a remote Git ref +bomly scan --image ghcr.io/example/app:latest # a container image +bomly scan --sbom --path ./sbom.cdx.json # an existing SBOM +``` + +[Scan Targets](../SCAN_TARGETS.md) covers each target's semantics and limits. + +## Enrich, analyze, audit + +The pipeline gates are independent opt-ins that compose: + +```bash +# Fetch vulnerability, license, lifecycle, and scorecard data +bomly scan --enrich + +# Evaluate policy against enriched data; exit 2 when a finding matches +bomly scan --enrich --audit --fail-on high + +# Add reachability analysis and gate only on reachable findings +bomly scan --enrich --audit --analyze --fail-on low --fail-on reachable +``` + +- `--enrich` is the only flag that turns on matcher network calls ([Network and Privacy](../NETWORK.md)). +- `--audit` evaluates data already present; repeatable `--fail-on` constraints AND together (`any|low|medium|high|critical`, `reachable`, `exploitable`). Policy flags such as `--deny-license`, `--deny-package`, `--allow-vulnerability-id`, and `--baseline` are documented in [Auditors](../AUDITORS.md) and [Finding Baselines](../BASELINES.md). +- `--analyze` is experimental — read [Reachability](../REACHABILITY.md) before gating on it. +- `--warn-only` keeps findings visible but downgrades them so the exit code stays `0`. + +## Render output + +```bash +bomly scan --json # shortcut for --format json +bomly scan --enrich --audit --fail-on high --format sarif +bomly scan -o spdx=sbom.spdx.json -o cyclonedx=sbom.cdx.json # extra artifacts alongside the report +bomly scan --interactive # open the TUI instead of printing a report +``` + +`--format` accepts `text`, `json`, `markdown`, `sarif`, `spdx`, `cyclonedx`. See [Output Formats](../OUTPUT_FORMATS.md), [SBOM Formats](../SBOM.md), and [Interactive TUI](../TUI.md). + +## Narrow the run + +```bash +bomly scan --scope runtime # drop development dependencies +bomly scan --ecosystems npm,go # only these ecosystems (+/- grammar supported) +bomly scan --detectors npm-detector # pin the detector chain (recommended in CI) +bomly scan --install-first # let detectors install dependencies first (network, opt-in) +``` + +Pinning `--detectors` makes CI fail loudly instead of silently regenerating a fallback-shaped graph — see [Detectors](../DETECTORS.md) and [CI-readiness warnings](../CI_READINESS.md). + +## Exit codes + +`0` clean · `2` a finding matched `--fail-on` · `3` a required detector could not produce a graph · `4` invalid flag or target · `5` nothing to evaluate. Full table and CI recipes: [Exit Codes](../EXIT_CODES.md). + +## See also + +- [Getting Started](../GETTING_STARTED.md) — the five-minute walkthrough +- [Use Cases](../USE_CASES.md) — goal-shaped recipes built on `scan` +- [Config Reference](../CONFIG_REFERENCE.md) — every flag's config key, env var, and default diff --git a/docs/manifest.json b/docs/manifest.json index 2694a890..33ce5dd0 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -115,6 +115,13 @@ "group": "concepts", "hasChildren": true }, + { + "slug": "commands", + "title": "Commands", + "description": "Per-command reference for scan, explain, and diff, plus the shared option surface.", + "group": "reference", + "hasChildren": true + }, { "slug": "support-matrix", "title": "Support matrix", From 81a149c4e5bde740043de81dde1e31a4570e5cee Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Tue, 28 Jul 2026 18:29:36 -0700 Subject: [PATCH 06/14] ci: check relative links and anchors in Markdown docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a docs-links job to Build & Test running lychee in offline mode with fragment checking over docs/, README.md, and CONTRIBUTING.md, so restructures can't leave dead intra-repo links or anchors behind. The check immediately caught one: USE_CASES.md pointed at a Bomly Guard anchor that doesn't exist in CI_INTEGRATION.md — fixed here. Co-Authored-By: Claude Fable 5 --- .github/workflows/ci.yml | 12 ++++++++++++ dev-docs/CI.md | 4 ++-- docs/USE_CASES.md | 2 +- 3 files changed, 15 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3867c97c..0e7a9f85 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -115,3 +115,15 @@ jobs: set -euo pipefail make generate git diff --exit-code + + docs-links: + name: Docs link check + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - name: Check relative links and anchors in Markdown docs + uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2.9.0 + with: + args: --offline --include-fragments --no-progress 'docs/**/*.md' README.md CONTRIBUTING.md + fail: true diff --git a/dev-docs/CI.md b/dev-docs/CI.md index b658c0af..83ee0771 100644 --- a/dev-docs/CI.md +++ b/dev-docs/CI.md @@ -9,7 +9,7 @@ The workflow permission and credential inventory is maintained in | Workflow | Trigger | Purpose | |------------------------|------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| -| `Build & Test` | Pull requests, pushes to `main` | Fast validation split into parallel jobs: `lint`, `test`, `build`, `format`, `modules` (go.mod drift), and `generated-docs` (generated-doc drift) | +| `Build & Test` | Pull requests, pushes to `main` | Fast validation split into parallel jobs: `lint`, `test`, `build`, `format`, `modules` (go.mod drift), `generated-docs` (generated-doc drift), and `docs-links` (relative-link and anchor check over `docs/`, `README.md`, and `CONTRIBUTING.md` via lychee in offline mode) | | `CodeQL` | Pull requests, pushes to `main`, weekly | Static security/quality analysis for Go; results surface in the Security tab | | `Scorecard` | Pushes to `main`, weekly, manual dispatch | OpenSSF Scorecard supply-chain checks; publishes results and uploads SARIF | | `Fuzz` | Nightly schedule, manual dispatch | Native Go fuzzing over lockfile parsers, SBOM JSON, SDK transport JSON, and plugin path/archive sanitizers | @@ -24,7 +24,7 @@ The workflow permission and credential inventory is maintained in For protected branches, require at least: -- The `Build & Test` jobs (`Lint`, `Test`, `Build`, `Format`, `Module drift`, `Generated docs drift`) +- The `Build & Test` jobs (`Lint`, `Test`, `Build`, `Format`, `Module drift`, `Generated docs drift`, `Docs link check`) - `Dependency review` when dependency metadata changes - `Smoke` on merge queue entries diff --git a/docs/USE_CASES.md b/docs/USE_CASES.md index 8ab1dc61..ea8be634 100644 --- a/docs/USE_CASES.md +++ b/docs/USE_CASES.md @@ -12,7 +12,7 @@ bomly diff --base main --head HEAD --enrich --audit --fail-on high `diff` classifies findings as introduced / resolved / persisted and only `--fail-on` matches against the introduced set, so a clean PR passes even on a repo with known debt. Exit code `2` means a new high finding; see [Exit codes](EXIT_CODES.md). -→ Turnkey version for GitHub PRs: the [Bomly Guard action](https://github.com/bomly-dev/bomly-guard) ([setup](CI_INTEGRATION.md#turnkey-pr-reviews-with-the-bomly-guard-action)). +→ Turnkey version for GitHub PRs: the [Bomly Guard action](https://github.com/bomly-dev/bomly-guard) ([setup](CI_INTEGRATION.md#turnkey-pr-reviews-with-bomly-guard)). ## Generate and publish an SBOM From 287993e3c8ba2ae5bc9cfa70cf20418be9912ac2 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Tue, 28 Jul 2026 23:23:04 -0700 Subject: [PATCH 07/14] docs: address review feedback on wave-1 docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ci: set persist-credentials: false on the docs-links checkout (zizmor artipacked); the lychee step needs no credentials. - NETWORK/FAQ: tighten the offline promise — a default scan can invoke a build-tool-backed detector whose package manager downloads dependencies; the opening claim, the trigger table, and the offline recipe now say so and explain how to prevent it (lockfiles + pinned --detectors). - NETWORK: expand KEV and PURL on first use. - REACHABILITY: define package precision and Tier-3 in plain language in the experimental banner, linking the tier table. - ARCHITECTURE: correct the supporting-command count (four, not three). - scan command page: include exit code 1 in the summary line. - FAQ: built-in, not builtin. - docs index: drop the hardcoded bomly.dev URL per the new relative-link rule; point at manifest.json instead. Co-Authored-By: Claude Fable 5 --- .github/workflows/ci.yml | 2 ++ docs/ARCHITECTURE.md | 2 +- docs/FAQ.md | 4 ++-- docs/NETWORK.md | 10 +++++----- docs/REACHABILITY.md | 2 +- docs/README.md | 2 +- docs/commands/scan.md | 2 +- 7 files changed, 13 insertions(+), 11 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0e7a9f85..0bfb850c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -122,6 +122,8 @@ jobs: steps: - name: Check out repository uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Check relative links and anchors in Markdown docs uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2.9.0 with: diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2968128c..ca14066f 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -4,7 +4,7 @@ A tour of how Bomly turns a scan target into a report — the stages a scan runs ## Commands -Bomly is a CLI. Three commands run the dependency pipeline described on this page, and three manage the machinery around it: +Bomly is a CLI. Three commands run the dependency pipeline described on this page, and four support it: | Command | Purpose | |-----------------|----------------------------------------------------------------------| diff --git a/docs/FAQ.md b/docs/FAQ.md index cf8081fc..46726bf3 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -12,7 +12,7 @@ No. Bomly has no account system, no license key, and no sign-up. Every feature i ## Does Bomly collect telemetry? -No. Bomly sends no usage data, crash reports, or version pings. The only network traffic is what you explicitly trigger (`--enrich`, `--url`, `--image`, `--install-first`, plugin installation). +No. Bomly sends no usage data, crash reports, or version pings. Network traffic comes only from what you trigger (`--enrich`, `--url`, `--image`, `--install-first`, plugin installation) — plus whatever your own package manager downloads if a build-tool-backed detector has to run it to resolve the graph. [Network and Privacy](NETWORK.md) has the complete table. ## How is Bomly different from image scanners like Trivy or Grype? @@ -36,7 +36,7 @@ Bomly uses a small, stable set of exit codes: `2` means a finding matched your ` ## Should I install `bomly` or `bomly-lite`? -`bomly` is the full binary with builtin Syft and Grype — no external tools needed. `bomly-lite` is a smaller download that shells out to `syft` and `grype` on your `PATH`. Both behave the same from the command line. If in doubt, install `bomly`. See [Installation](INSTALLATION.md#bomly-vs-bomly-lite). +`bomly` is the full binary with built-in Syft and Grype — no external tools needed. `bomly-lite` is a smaller download that shells out to `syft` and `grype` on your `PATH`. Both behave the same from the command line. If in doubt, install `bomly`. See [Installation](INSTALLATION.md#bomly-vs-bomly-lite). ## Where are the release notes? diff --git a/docs/NETWORK.md b/docs/NETWORK.md index 87807395..c685d592 100644 --- a/docs/NETWORK.md +++ b/docs/NETWORK.md @@ -1,15 +1,15 @@ # Network and Privacy -Bomly's rule is simple: **it touches the network only when a flag you passed requires it, and it never sends telemetry.** This page is the audit surface for that claim — every network trigger, what it contacts, what it transmits, and how to keep a run fully offline. +Bomly's rule is simple: **matcher services, telemetry, and version checks are never contacted on their own — network-backed enrichment requires `--enrich`, and telemetry doesn't exist.** This page is the audit surface for that claim — every network trigger, what it contacts, what it transmits, and how to keep a run fully offline. -A plain `bomly scan` of a local directory reads files and exits. No matcher calls, no version checks, no usage pings, no account. +A plain `bomly scan` of a local directory with committed lockfiles reads files and exits. No matcher calls, no version checks, no usage pings, no account. The one nuance is dependency *resolution* itself: when a lockfile parser can't resolve a project, the detector chain may fall through to a build-tool-backed detector that runs your package manager (Maven, Gradle, Go, …), and that tool may download dependencies under its own configuration — see the table below and the offline recipe for how to prevent it. ## What triggers network access | You pass | Bomly contacts | What is transmitted | | --- | --- | --- | -| *(nothing)* | Nothing | — | -| `--enrich` | `api.osv.dev`, `api.cisa.gov`, `api.deps.dev`; `api.scorecard.dev` (Scorecard matcher); Grype database service (`grype.anchore.io/databases`, plus the archive URL it returns) on first use | Package identifiers: name, version, ecosystem/PURL. Scorecard queries use the package's source repository URL. The KEV catalog and Grype database are bulk downloads — no per-package data is sent. Never source code. | +| *(nothing)* | Nothing, when lockfile detectors resolve the graph. If the chain falls through to a build-tool-backed detector, that tool may contact its registries (see the build-tool row) | — | +| `--enrich` | `api.osv.dev`, `api.cisa.gov` (CISA Known Exploited Vulnerabilities — KEV — catalog), `api.deps.dev`; `api.scorecard.dev` (Scorecard matcher); Grype database service (`grype.anchore.io/databases`, plus the archive URL it returns) on first use | Package identifiers: name, version, and ecosystem — the package URL (PURL) coordinates. Scorecard queries use the package's source repository URL. The KEV catalog and Grype database are bulk downloads — no per-package data is sent. Never source code. | | `--url` | The Git host you named | A `git clone` of that repository (10-minute deadline; checkout size, path, and symlink limits apply) | | `--image` | The container registry for the reference | An image pull via the embedded Syft (or your external `syft` in the lite build) | | `--install-first` | Your package manager's configured registries | Whatever `npm install`, `pip install`, etc. transmit — the package manager owns this traffic and its credentials | @@ -30,7 +30,7 @@ Two flags never trigger network access on their own: `--audit` evaluates data al For an air-gapped or network-restricted pipeline: 1. Don't pass `--enrich`, `--url`, `--image`, or `--install-first`; scan a local checkout. -2. Prefer projects with committed lockfiles, so lockfile detectors resolve the graph without a build tool. Pin `--detectors` in CI to make an unexpected fallback fail loudly instead of degrading silently — see [CI-readiness warnings](CI_READINESS.md). +2. Commit lockfiles, so lockfile detectors resolve the graph without a build tool ever running. Pin `--detectors` to the lockfile detectors in CI so an unexpected fall-through to a build-tool-backed detector fails loudly instead of silently invoking the tool — see [CI-readiness warnings](CI_READINESS.md). If you do rely on a build-tool-backed detector, the tool's own offline configuration (Go module proxy settings, Maven offline mode, a local registry mirror) governs whether it downloads anything. 3. Matcher responses are cached under `~/.bomly/cache/` with per-matcher TTLs, so a previously enriched environment keeps working through upstream outages — but an expired cache entry on an offline host is a miss, not stale data. See [Matchers → Cache](MATCHERS.md#cache). ## Proxies, custom endpoints, and CAs diff --git a/docs/REACHABILITY.md b/docs/REACHABILITY.md index 1a403e25..f7baaceb 100644 --- a/docs/REACHABILITY.md +++ b/docs/REACHABILITY.md @@ -1,6 +1,6 @@ # Reachability -> ⚠️ **Experimental.** This feature may change without preserving backwards compatibility. Reachability is opt-in (`--analyze`) and under active development: the output shape is stable, but ecosystem coverage is expanding and Tier-3 analyzers (`jsreach`, `pyreach`, `jvmreach`) report at package precision today — sufficient for triage, not a fix substitute. Do not use `--fail-on reachable` as the sole gate for security-critical decisions without understanding the limitations below. +> ⚠️ **Experimental.** This feature may change without preserving backwards compatibility. Reachability is opt-in (`--analyze`) and under active development: the output shape is stable, but ecosystem coverage is expanding, and today the JavaScript, Python, and JVM analyzers (`jsreach`, `pyreach`, `jvmreach`) work at *package* precision — they confirm your code imports the vulnerable package, not that it calls the vulnerable function (the "Tier-3" level in [How it works](#how-it-works)). That is sufficient for triage, not a fix substitute. Do not use `--fail-on reachable` as the sole gate for security-critical decisions without understanding the limitations below. `--analyze` runs code analysis on top of vulnerability matching to confirm whether a finding is actually reachable from your application code. Reachability annotations are written onto the matching `sdk.Vulnerability` records inside the PURL-keyed `sdk.PackageRegistry`. The output layer resolves them at projection time via `(Finding.PackageRef, Finding.VulnerabilityID)`, so reachability surfaces consistently in JSON, SARIF, and the text/TUI views without needing a separate field on `Finding`. See [Architecture → Domain model](ARCHITECTURE.md#domain-model) for the registry data model. diff --git a/docs/README.md b/docs/README.md index ba9a31bd..897269dd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # Bomly Documentation -Start with [Getting Started](GETTING_STARTED.md) if you're new. Otherwise pick the section that matches what you're doing. The sections below mirror the groups on the [documentation site](https://bomly.dev/docs), so this index and the site navigation always tell the same story. +Start with [Getting Started](GETTING_STARTED.md) if you're new. Otherwise pick the section that matches what you're doing. The sections below mirror the site navigation groups defined in [`manifest.json`](manifest.json), so this index and the published docs site always tell the same story. ## Getting started diff --git a/docs/commands/scan.md b/docs/commands/scan.md index 90274217..8e96b773 100644 --- a/docs/commands/scan.md +++ b/docs/commands/scan.md @@ -78,7 +78,7 @@ Pinning `--detectors` makes CI fail loudly instead of silently regenerating a fa ## Exit codes -`0` clean · `2` a finding matched `--fail-on` · `3` a required detector could not produce a graph · `4` invalid flag or target · `5` nothing to evaluate. Full table and CI recipes: [Exit Codes](../EXIT_CODES.md). +`0` clean · `1` execution error · `2` a finding matched `--fail-on` · `3` a required detector could not produce a graph · `4` invalid flag or target · `5` nothing to evaluate. Full table and CI recipes: [Exit Codes](../EXIT_CODES.md). ## See also From 468270d43e87074156c54d3be6ae94564f5219f7 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Tue, 28 Jul 2026 23:42:10 -0700 Subject: [PATCH 08/14] docs: keep the FAQ scanner comparison generic Name no third-party scanners; describe the category and the embedded Syft/Grype technology instead. Co-Authored-By: Claude Fable 5 --- docs/FAQ.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index 46726bf3..d179639b 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -14,9 +14,9 @@ No. Bomly has no account system, no license key, and no sign-up. Every feature i No. Bomly sends no usage data, crash reports, or version pings. Network traffic comes only from what you trigger (`--enrich`, `--url`, `--image`, `--install-first`, plugin installation) — plus whatever your own package manager downloads if a build-tool-backed detector has to run it to resolve the graph. [Network and Privacy](NETWORK.md) has the complete table. -## How is Bomly different from image scanners like Trivy or Grype? +## How is Bomly different from general-purpose security scanners? -Different focus. General-purpose scanners are built to cover many target and finding types — container images, IaC misconfigurations, secrets — with vulnerability detection per target. Bomly is built around one thing: the dependency graph. It keeps the full graph so it can answer *why* a package is present (`bomly explain`), *what changed* between two refs or SBOMs (`bomly diff`), and *whether a vulnerability is actually reachable* from your code (`--analyze`), alongside SBOM generation and policy auditing. For container images, Bomly embeds the same Syft technology those tools build on. The tools compose: many teams run an image scanner for images and Bomly for dependency intelligence and PR review. +Different focus. General-purpose scanners are built to cover many target and finding types — container images, IaC misconfigurations, secrets — with vulnerability detection per target. Bomly is built around one thing: the dependency graph. It keeps the full graph so it can answer *why* a package is present (`bomly explain`), *what changed* between two refs or SBOMs (`bomly diff`), and *whether a vulnerability is actually reachable* from your code (`--analyze`), alongside SBOM generation and policy auditing. For container images, Bomly embeds Syft and Grype — proven scanning technology used widely across the ecosystem. The tools compose: many teams run an image scanner for images and Bomly for dependency intelligence and PR review. ## Why does my scan show fewer dependencies than I expected? From aff367eb119cf5a9519116144916ce493be30444 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Wed, 29 Jul 2026 02:47:34 -0700 Subject: [PATCH 09/14] docs: replace the FAQ page with faq.json as the site FAQ's source of truth MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The landing page already serves a richer, styled FAQ at /faq with FAQPage JSON-LD; shipping a second markdown FAQ under /docs would duplicate it and drift. Instead the FAQ data now lives here as docs/faq.json — the site's 25 questions plus 6 new ones (scanner comparison, lockfile fallback, audit vs enrich, unreachable semantics, exit codes, release notes) — so claims about CLI behavior are reviewed in the same PRs that change the behavior. A shape test guards the contract (ids, backtick pairing, link forms) the site's renderer and JSON-LD rely on. The landing page consumes this file in a companion PR; until that lands, /faq keeps rendering its inline copy. Co-Authored-By: Claude Fable 5 --- README.md | 2 +- docs/FAQ.md | 47 ---- docs/README.md | 2 +- docs/faq.json | 524 +++++++++++++++++++++++++++++++++++ docs/manifest.json | 6 - internal/support/faq_test.go | 104 +++++++ 6 files changed, 630 insertions(+), 55 deletions(-) delete mode 100644 docs/FAQ.md create mode 100644 docs/faq.json create mode 100644 internal/support/faq_test.go diff --git a/README.md b/README.md index 06cac03f..528509b1 100644 --- a/README.md +++ b/README.md @@ -211,7 +211,7 @@ See [Plugins](docs/PLUGINS.md) for install, trust, and authoring guidance. ## Documentation - [Getting Started](docs/GETTING_STARTED.md) - install Bomly and run your first scan -- [FAQ](docs/FAQ.md) - quick answers on privacy, accounts, and tool differences +- [FAQ](https://bomly.dev/faq) - quick answers on privacy, accounts, and tool differences - [Installation](docs/INSTALLATION.md) - install methods, checksums, upgrades, uninstall - [Use Cases](docs/USE_CASES.md) - practical recipes for PR gates, SBOMs, triage, and offline scans - [Scan Targets](docs/SCAN_TARGETS.md) - directories, Git repos, containers, and SBOMs diff --git a/docs/FAQ.md b/docs/FAQ.md deleted file mode 100644 index d179639b..00000000 --- a/docs/FAQ.md +++ /dev/null @@ -1,47 +0,0 @@ -# FAQ - -Short answers to the questions people ask before and shortly after their first scan. For error messages and broken runs, see [Troubleshooting](TROUBLESHOOTING.md) instead — it is organized by symptom and exit code. - -## Does Bomly send my code anywhere? - -No. A plain `bomly scan` runs entirely against local files and makes no matcher network calls. When you opt in with `--enrich`, Bomly sends package identifiers — name, version, ecosystem, and for Scorecard the source repository URL — to the enrichment services you selected. It never uploads your source code, and the CISA KEV catalog is downloaded as a whole rather than queried per package. See [Matchers → Network endpoints](MATCHERS.md#network-endpoints) and [Architecture → Network behavior](ARCHITECTURE.md#network-behavior) for the complete model, including the separate boundaries for `--url`, build-tool detectors, and `--install-first`. - -## Do I need an account, API key, or login? - -No. Bomly has no account system, no license key, and no sign-up. Every feature in this documentation works with the binary alone. - -## Does Bomly collect telemetry? - -No. Bomly sends no usage data, crash reports, or version pings. Network traffic comes only from what you trigger (`--enrich`, `--url`, `--image`, `--install-first`, plugin installation) — plus whatever your own package manager downloads if a build-tool-backed detector has to run it to resolve the graph. [Network and Privacy](NETWORK.md) has the complete table. - -## How is Bomly different from general-purpose security scanners? - -Different focus. General-purpose scanners are built to cover many target and finding types — container images, IaC misconfigurations, secrets — with vulnerability detection per target. Bomly is built around one thing: the dependency graph. It keeps the full graph so it can answer *why* a package is present (`bomly explain`), *what changed* between two refs or SBOMs (`bomly diff`), and *whether a vulnerability is actually reachable* from your code (`--analyze`), alongside SBOM generation and policy auditing. For container images, Bomly embeds Syft and Grype — proven scanning technology used widely across the ecosystem. The tools compose: many teams run an image scanner for images and Bomly for dependency intelligence and PR review. - -## Why does my scan show fewer dependencies than I expected? - -Bomly resolves the graph from evidence — lockfiles first, then package-manager output, then fallbacks. If a project has no lockfile, the responsible detector may fall back to a coarser source and report a `fallback` warning, which means transitive dependencies can be missing. Check the warnings in the report, commit a lockfile, or use `--install-first` to let the detector materialize one. See [Detectors](DETECTORS.md) and [CI-readiness warnings](CI_READINESS.md). - -## Does "unreachable" mean the vulnerability is safe to ignore? - -No. Reachability is a triage signal: "unreachable" at package precision means static analysis found no import path, and static analysis cannot see dynamic imports, plugin loaders, or runtime code generation. Use it to prioritize, not to dismiss. Read [Reachability](REACHABILITY.md) — especially ["Unreachable" is not "safe"](REACHABILITY.md#unreachable-is-not-safe) — before gating CI on `--fail-on reachable`. - -## Does `--audit` make network calls? - -No. `--audit` evaluates the vulnerability and license data already present on packages. Fetching that data is `--enrich`'s job; combine them (`--enrich --audit`) when you want to fetch and evaluate in one run. See [Auditors](AUDITORS.md). - -## Why did my scan exit non-zero? - -Bomly uses a small, stable set of exit codes: `2` means a finding matched your `--fail-on` policy, while `1`, `3`, `4`, and `5` distinguish execution errors, resolution failures, invalid input, and "nothing to evaluate". [Exit Codes](EXIT_CODES.md) has the full table and CI recipes for branching on them. - -## Should I install `bomly` or `bomly-lite`? - -`bomly` is the full binary with built-in Syft and Grype — no external tools needed. `bomly-lite` is a smaller download that shells out to `syft` and `grype` on your `PATH`. Both behave the same from the command line. If in doubt, install `bomly`. See [Installation](INSTALLATION.md#bomly-vs-bomly-lite). - -## Where are the release notes? - -On [GitHub Releases](https://github.com/bomly-dev/bomly-cli/releases). Draft releases are created automatically after merges to `main`, and the documentation site is versioned per release. - -## Where do I ask something this page doesn't answer? - -[Bomly Discussions](https://github.com/orgs/bomly-dev/discussions) for questions and ideas; this repository's issues for confirmed bugs and actionable work. diff --git a/docs/README.md b/docs/README.md index 897269dd..b9ae6a04 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,7 +12,7 @@ Install Bomly and run your first scan. - [Scan Targets](SCAN_TARGETS.md) — directories, Git repos, containers, SBOMs - [Output Formats](OUTPUT_FORMATS.md) — text, JSON, SARIF, SBOM - [SBOM Formats](SBOM.md) — SPDX vs. CycloneDX, write and ingest -- [FAQ](FAQ.md) — quick answers on privacy, accounts, tool differences, and first-scan surprises +- [FAQ](https://bomly.dev/faq) — quick answers on privacy, accounts, tool differences, and first-scan surprises (source: [`faq.json`](faq.json)) ## How it works diff --git a/docs/faq.json b/docs/faq.json new file mode 100644 index 00000000..3121d6a0 --- /dev/null +++ b/docs/faq.json @@ -0,0 +1,524 @@ +{ + "groups": [ + { + "id": "general", + "title": "General", + "icon": "message-circle-question", + "subgroups": [ + { + "faqs": [ + { + "id": "what-is-bomly", + "question": "What is Bomly?", + "answer": "Bomly is a free, open-source CLI for dependency intelligence. It scans source trees, SBOMs, Git refs, and container images, builds one dependency graph, and explains why each package is present. When you ask for it, Bomly enriches packages with vulnerability and license data, evaluates policy, and writes automation-friendly output for CI. It ships as one binary, with no service to host.", + "links": [ + { + "label": "Bomly CLI", + "href": "/cli" + }, + { + "label": "Getting started", + "href": "/docs/getting-started" + } + ] + }, + { + "id": "how-is-bomly-different", + "question": "How is Bomly different from general-purpose security scanners?", + "toc": "How is Bomly different?", + "answer": "Different focus. General-purpose scanners cover many target and finding types — container images, IaC misconfigurations, secrets — with vulnerability detection per target. Bomly is built around one thing: the dependency graph. It keeps the full graph so it can answer why a package is present (`bomly explain`), what changed between two refs or SBOMs (`bomly diff`), and whether a vulnerability is actually reachable from your code (`--analyze`), alongside SBOM generation and policy auditing. For container images, Bomly embeds Syft and Grype — proven scanning technology used widely across the ecosystem. The tools compose: many teams run an image scanner for images and Bomly for dependency intelligence and PR review.", + "links": [ + { + "label": "Architecture", + "href": "/docs/architecture" + }, + { + "label": "Bomly CLI", + "href": "/cli" + } + ] + }, + { + "id": "is-bomly-free", + "question": "Is Bomly really free?", + "answer": "Yes. The Bomly CLI and the Bomly Guard GitHub Action are open source under the Apache License 2.0. There is no account, no login, and no subscription required to run Bomly locally or in CI.", + "links": [ + { + "label": "License (Apache 2.0)", + "href": "https://github.com/bomly-dev/bomly-cli/blob/main/LICENSE", + "external": true + }, + { + "label": "Support the project", + "href": "/support" + } + ] + }, + { + "id": "what-data-leaves-my-machine", + "question": "What data leaves my machine when I run Bomly?", + "toc": "What data leaves my machine?", + "answer": "By default, nothing. Bomly has no telemetry, no usage tracking, and no crash reporting. Network enrichment is opt-in: when you pass `--enrich`, Bomly queries public data sources such as OSV, CISA KEV, and deps.dev for vulnerability and license data. One detail to know: detectors that use a build tool, such as Maven or Gradle, may resolve packages from the package registry, because that is how those build tools work.", + "links": [ + { + "label": "Privacy", + "href": "/privacy" + } + ] + }, + { + "id": "who-builds-bomly", + "question": "Who builds Bomly?", + "answer": "Bomly is built by Ahmed ElMallah, a senior software engineer at GitHub, as a personal open-source project. Development happens in the open at github.com/bomly-dev, and the roadmap is driven by real usage and reported issues. Bomly is a personal project — it is not affiliated with or endorsed by GitHub.", + "links": [ + { + "label": "elmallah.dev", + "href": "https://elmallah.dev", + "external": true + }, + { + "label": "github.com/bomly-dev", + "href": "https://github.com/bomly-dev", + "external": true + }, + { + "label": "Support the project", + "href": "/support" + } + ] + }, + { + "id": "how-do-i-get-help", + "question": "How do I get help or report a bug?", + "toc": "Help & bug reports", + "answer": "Open an issue on the bomly-cli repository for bugs, or start a GitHub Discussion for questions and feedback. Security reports go through the repository security policy so they can be handled privately. The support page lists all the ways to reach the project.", + "links": [ + { + "label": "Support", + "href": "/support" + }, + { + "label": "Troubleshooting", + "href": "/docs/troubleshooting" + } + ] + }, + { + "id": "where-are-the-release-notes", + "question": "Where are the release notes?", + "toc": "Release notes", + "answer": "On GitHub Releases. Draft releases are created automatically after merges to main, and the documentation site is updated per release.", + "links": [ + { + "label": "GitHub Releases", + "href": "https://github.com/bomly-dev/bomly-cli/releases", + "external": true + } + ] + } + ] + } + ] + }, + { + "id": "cli", + "title": "Bomly CLI", + "icon": "square-terminal", + "subgroups": [ + { + "label": "Getting started", + "faqs": [ + { + "id": "how-do-i-install-bomly", + "question": "How do I install Bomly?", + "toc": "Installing Bomly", + "answer": "The quickest ways are Homebrew (`brew install bomly-dev/tap/bomly`) and the install script (`curl -fsSL https://bomly.dev/install.sh | sh`). On Windows you can use WinGet (`winget install Bomly.BomlyCLI`) or Scoop, and every release also ships binaries and Linux packages on GitHub. The default `bomly` binary has Syft and Grype built in; a smaller `bomly-lite` binary uses the `syft` and `grype` already on your PATH.", + "links": [ + { + "label": "Installation", + "href": "/docs/installation" + } + ] + }, + { + "id": "which-ecosystems-are-supported", + "question": "Which ecosystems does Bomly support?", + "toc": "Supported ecosystems", + "answer": "Bomly has native detectors for Go, npm (including pnpm and Yarn), Maven and Gradle, Python (pip, pipenv, Poetry, uv), PHP Composer, Ruby Bundler, Rust Cargo, .NET NuGet, Swift (SwiftPM and CocoaPods), Dart pub, Scala sbt, Elixir Mix, C/C++ Conan, and GitHub Actions workflows, plus SPDX and CycloneDX SBOM ingest. Bundled Syft-based detectors cover the long tail, including container images and OS-level packages. The support matrix in the docs lists every detector and the files it reads.", + "links": [ + { + "label": "Support matrix", + "href": "/docs/support-matrix" + }, + { + "label": "Detectors", + "href": "/docs/detectors" + } + ] + } + ] + }, + { + "label": "Scanning & SBOMs", + "faqs": [ + { + "id": "can-bomly-read-or-generate-sboms", + "question": "Can Bomly read or generate SBOMs?", + "toc": "Reading & generating SBOMs", + "answer": "Both. `bomly scan --sbom --path ./sbom.cdx.json` reads an existing SPDX or CycloneDX SBOM and turns it into a dependency graph you can diff, explain, and audit. Bomly also writes SBOMs in SPDX 2.3 and CycloneDX 1.6, either to stdout or to files while still printing the normal report.", + "links": [ + { + "label": "SBOM guide", + "href": "/docs/sbom" + }, + { + "label": "Scan targets", + "href": "/docs/scan-targets" + } + ] + }, + { + "id": "does-bomly-scan-container-images", + "question": "Does Bomly scan container images?", + "toc": "Container images", + "answer": "Yes. `bomly scan --image ghcr.io/example/app:latest` reads the image layers and resolves the packages inside them into the same dependency graph. Container image support comes from the bundled Syft detectors, which also cover OS-level packages such as apk and dpkg databases.", + "links": [ + { + "label": "Scan targets", + "href": "/docs/scan-targets" + } + ] + }, + { + "id": "why-is-this-package-in-my-project", + "question": "How do I find out why a package is in my project?", + "toc": "Why is this package here?", + "answer": "Run `bomly explain `, for example `bomly explain lodash`. Bomly prints the dependency paths that bring the package in, so you can see which direct dependency is responsible, and it includes advisory and fix context when enrichment data is present. This works for transitive packages that never appear in your own manifests.", + "links": [ + { + "label": "Use cases", + "href": "/docs/use-cases" + }, + { + "label": "Getting started", + "href": "/docs/getting-started" + } + ] + }, + { + "id": "compare-branches-or-sboms", + "question": "How do I compare dependencies between two branches or two SBOMs?", + "toc": "Comparing branches & SBOMs", + "answer": "Use `bomly diff`. `bomly diff --base main --head HEAD` compares two Git refs, `bomly diff --sbom --base ./old.spdx.json --head ./new.spdx.json` compares two SBOM files, and `--image` compares two container tags or digests. Findings are grouped into introduced, resolved, and persisted, so you can see exactly what a change adds or fixes.", + "links": [ + { + "label": "Scan targets", + "href": "/docs/scan-targets" + }, + { + "label": "CI integration", + "href": "/docs/ci-integration" + } + ] + }, + { + "id": "fewer-dependencies-than-expected", + "question": "Why does my scan show fewer dependencies than I expected?", + "toc": "Fewer dependencies than expected", + "answer": "Bomly resolves the graph from evidence — lockfiles first, then package-manager output, then fallbacks. If a project has no lockfile, the responsible detector may fall back to a coarser source and report a fallback warning, which means transitive dependencies can be missing. Check the warnings in the report, commit a lockfile, or use `--install-first` to let the detector materialize one.", + "links": [ + { + "label": "Detectors", + "href": "/docs/detectors" + }, + { + "label": "CI-readiness warnings", + "href": "/docs/ci-readiness" + } + ] + } + ] + }, + { + "label": "CI & policy", + "faqs": [ + { + "id": "fail-ci-on-a-vulnerability", + "question": "How do I fail CI when a change introduces a high-severity vulnerability?", + "toc": "Failing CI on vulnerabilities", + "answer": "Run `bomly scan --enrich --audit --fail-on high` in your pipeline. Exit codes are stable for scripts: 0 for clean results and 2 for policy violations, so any CI system can gate on the result. Add `--format sarif` to send findings to GitHub code scanning or any other SARIF-aware tool. On GitHub pull requests, the Bomly Guard action packages this whole flow for you.", + "links": [ + { + "label": "CI integration", + "href": "/docs/ci-integration" + }, + { + "label": "Exit codes", + "href": "/docs/exit-codes" + }, + { + "label": "Bomly Guard", + "href": "/guard" + } + ] + }, + { + "id": "enforce-a-license-policy", + "question": "Can I enforce a license policy?", + "toc": "License policy", + "answer": "Yes. Use `--allow-license` to define an allowlist of SPDX license expressions, `--deny-license` to block specific ones, and `--license-exempt-package` for packages you have reviewed and accepted. Combined with `--fail-on`, license findings can fail the scan in CI. The same options are available as inputs on the Bomly Guard action.", + "links": [ + { + "label": "Auditors", + "href": "/docs/auditors" + }, + { + "label": "Config reference", + "href": "/docs/config-reference" + } + ] + }, + { + "id": "typosquat-detection", + "question": "Can Bomly warn me about typosquatted package names?", + "toc": "Typosquat detection", + "answer": "Yes. The package auditor compares new package names against a protected set: pass `--protected-package` for the names you care about, and tune `--typosquat-threshold` (default 0.90) and `--typosquat-mode` (`warn` or `fail`). The check is name-based and needs no network enrichment. Under `bomly diff`, the packages already in your base branch seed the protected set, so only newly introduced names are checked.", + "links": [ + { + "label": "Auditors", + "href": "/docs/auditors" + } + ] + }, + { + "id": "output-formats", + "question": "What output formats does Bomly produce?", + "toc": "Output formats", + "answer": "The default output is a human-readable text report. With `--format` you can switch to `json`, `markdown`, SARIF 2.1.0 (requires `--audit`), SPDX 2.3, or CycloneDX 1.6, and `-o format=path` writes several formats in one run while still printing the normal report.", + "links": [ + { + "label": "Output formats", + "href": "/docs/output-formats" + } + ] + }, + { + "id": "does-audit-make-network-calls", + "question": "Does auditing make network calls?", + "toc": "Audit & network", + "answer": "No. `--audit` evaluates the vulnerability and license data already present on packages. Fetching that data is `--enrich`'s job; combine them (`--enrich --audit`) when you want to fetch and evaluate in one run.", + "links": [ + { + "label": "Auditors", + "href": "/docs/auditors" + }, + { + "label": "Network and privacy", + "href": "/docs/network" + } + ] + }, + { + "id": "is-unreachable-safe-to-ignore", + "question": "Does \"unreachable\" mean a vulnerability is safe to ignore?", + "toc": "Is \"unreachable\" safe?", + "answer": "No. Reachability is a triage signal: \"unreachable\" at package precision means static analysis found no import path, and static analysis cannot see dynamic imports, plugin loaders, or runtime code generation. Use it to prioritize, not to dismiss — and read the reachability guide before gating CI on `--fail-on reachable`.", + "links": [ + { + "label": "Reachability", + "href": "/docs/reachability" + } + ] + }, + { + "id": "why-did-my-scan-exit-non-zero", + "question": "Why did my scan exit non-zero?", + "toc": "Non-zero exit codes", + "answer": "Bomly uses a small, stable set of exit codes: 0 is clean, 2 means a finding matched your `--fail-on` policy, and 1, 3, 4, and 5 distinguish execution errors, resolution failures, invalid input, and \"nothing to evaluate\". The exit-codes reference has the full table and CI recipes for branching on them.", + "links": [ + { + "label": "Exit codes", + "href": "/docs/exit-codes" + }, + { + "label": "Troubleshooting", + "href": "/docs/troubleshooting" + } + ] + } + ] + }, + { + "label": "Plugins", + "faqs": [ + { + "id": "extend-bomly-with-plugins", + "question": "Can I extend Bomly with plugins?", + "toc": "Extending with plugins", + "answer": "Yes. Managed plugins add new detectors, matchers, and auditors without changing the binary. Install one from a local archive, a URL with a checksum, or a GitHub release (`bomly plugins install github:owner/repo@tag`); installed plugins stay disabled until you run `bomly plugins enable`, which is the explicit trust decision. The docs include guides for writing your own plugin in Go.", + "links": [ + { + "label": "Plugins", + "href": "/docs/plugins" + } + ] + } + ] + } + ] + }, + { + "id": "guard", + "title": "Bomly Guard", + "icon": "shield-check", + "subgroups": [ + { + "faqs": [ + { + "id": "what-is-bomly-guard", + "question": "What is Bomly Guard?", + "answer": "Bomly Guard is the official GitHub Action for Bomly. It installs the Bomly CLI and runs `bomly diff` against the pull request's merge base, so every PR gets a dependency review with vulnerability, license, and policy findings. It is free and open source under Apache 2.0 — no server, no signup.", + "links": [ + { + "label": "Bomly Guard", + "href": "/guard" + }, + { + "label": "Guard docs", + "href": "/docs/bomly-guard" + } + ] + }, + { + "id": "add-guard-to-my-repository", + "question": "How do I add Guard to my repository?", + "toc": "Adding Guard to a repo", + "answer": "Add one step to a `pull_request` workflow: `uses: bomly-dev/bomly-guard@v1`, with the policy inputs you want, such as `fail-on: high`. Check out the repository with `fetch-depth: 0` so both refs can be resolved. Guard reports a normal GitHub check, so you can make it required through branch protection.", + "links": [ + { + "label": "Bomly Guard", + "href": "/guard" + }, + { + "label": "Guard docs", + "href": "/docs/bomly-guard" + } + ] + }, + { + "id": "guard-pull-request-results", + "question": "Does Guard post results to my pull request?", + "toc": "PR comments & results", + "answer": "Guard always writes a job summary with the results. Set `comment-summary-in-pr` to `always` or `on-failure` and it also posts a single PR comment — updated in place on new pushes — with an overview, the dependency changes, and the policy findings. With `upload-sarif` enabled, findings also go to GitHub code scanning as alerts.", + "links": [ + { + "label": "Guard docs", + "href": "/docs/bomly-guard" + } + ] + }, + { + "id": "reproduce-guard-locally", + "question": "Can I reproduce Guard's CI result locally?", + "toc": "Reproducing CI locally", + "answer": "Yes. Guard is a thin wrapper around the Bomly CLI, so the same command runs on your machine: `bomly diff --base main --head HEAD` with the same policy flags reproduces the review before you push. This also makes CI results easy to debug.", + "links": [ + { + "label": "CI integration", + "href": "/docs/ci-integration" + } + ] + } + ] + } + ] + }, + { + "id": "mcp", + "title": "MCP server", + "icon": "bot", + "subgroups": [ + { + "faqs": [ + { + "id": "set-up-the-mcp-server", + "question": "How do I set up the Bomly MCP server?", + "toc": "Setting up the server", + "answer": "Install the Bomly CLI and run `bomly mcp serve` — the MCP server is built into the same binary, so there is nothing else to install. Then register it in your agent's MCP configuration: Claude Code (`~/.claude.json`), Cursor (`.cursor/mcp.json`), VS Code and GitHub Copilot (`.vscode/mcp.json`), or Codex (`~/.codex/config.toml`). The MCP page walks through the whole setup.", + "links": [ + { + "label": "Bomly MCP", + "href": "/mcp" + }, + { + "label": "MCP docs", + "href": "/docs/mcp" + } + ] + }, + { + "id": "which-agents-work-with-mcp", + "question": "Which agents and editors work with the Bomly MCP server?", + "toc": "Supported agents & editors", + "answer": "Any MCP client that supports stdio transport can use it. Documented setups exist for Claude Code, Cursor, VS Code, GitHub Copilot, and Codex. The server runs as a local child process of your agent — there is no remote endpoint to configure.", + "links": [ + { + "label": "Bomly MCP", + "href": "/mcp" + }, + { + "label": "MCP docs", + "href": "/docs/mcp" + } + ] + }, + { + "id": "mcp-tools", + "question": "What tools does the MCP server expose?", + "toc": "Available tools", + "answer": "Four tools. `bomly_scan` scans a path, Git URL, container image, or SBOM and returns a compact summary grouped by remediation. `bomly_explain` shows dependency paths, advisories, and fix context for one package. `bomly_diff` reports the dependency changes between two refs, images, or SBOM files as introduced, resolved, and persisted. `bomly_plugins` lists the plugins in your installation. Responses are compact on purpose, sized for agent tool-result limits.", + "links": [ + { + "label": "MCP docs", + "href": "/docs/mcp" + } + ] + }, + { + "id": "mcp-network-and-accounts", + "question": "Does the MCP server need network access or an account?", + "toc": "Network access & accounts", + "answer": "No account and no API key. The server runs locally over stdio, and network enrichment is opt-in per tool call through the `enrich` argument — without it, the matchers make no vulnerability or license calls. As with the CLI, some build-tool detectors may still resolve packages from a registry while constructing the graph.", + "links": [ + { + "label": "MCP docs", + "href": "/docs/mcp" + }, + { + "label": "Privacy", + "href": "/privacy" + } + ] + }, + { + "id": "agent-checks-before-committing", + "question": "How do I make my agent check dependencies before committing?", + "toc": "Checks before committing", + "answer": "Add a short instruction to your repository's agent guidance file — `CLAUDE.md`, `AGENTS.md`, or `copilot-instructions.md` — telling the agent to run a dependency diff against the base branch before committing dependency or lockfile changes. The Bomly docs include a ready snippet for this. It is a workflow hint, not a security guarantee: the agent decides when to call the tools.", + "links": [ + { + "label": "Bomly MCP", + "href": "/mcp" + }, + { + "label": "MCP docs", + "href": "/docs/mcp" + } + ] + } + ] + } + ] + } + ] +} diff --git a/docs/manifest.json b/docs/manifest.json index 33ce5dd0..0e80464b 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -57,12 +57,6 @@ "description": "Text, JSON, SARIF, and SBOM artifacts — when to use each and how to combine them.", "group": "start" }, - { - "slug": "faq", - "title": "FAQ", - "description": "Quick answers on privacy, accounts, tool differences, and first-scan surprises.", - "group": "start" - }, { "slug": "sbom", "title": "SBOM formats", diff --git a/internal/support/faq_test.go b/internal/support/faq_test.go new file mode 100644 index 00000000..8a9412c6 --- /dev/null +++ b/internal/support/faq_test.go @@ -0,0 +1,104 @@ +package support + +import ( + "encoding/json" + "os" + "path/filepath" + "strings" + "testing" +) + +// docs/faq.json is the source of truth for the landing page's /faq route. The +// site renders it with its own styled component and reuses the answer strings +// (backticks stripped) for FAQPage JSON-LD, so the data must stay well-formed +// here — a malformed entry should fail this repo's CI, not the site build. +func TestDocsFAQIsWellFormed(t *testing.T) { + raw, err := os.ReadFile(filepath.Join("..", "..", "docs", "faq.json")) + if err != nil { + t.Fatalf("read faq.json: %v", err) + } + + var doc struct { + Groups []struct { + ID string `json:"id"` + Title string `json:"title"` + Icon string `json:"icon"` + Subgroups []struct { + Label string `json:"label"` + Faqs []struct { + ID string `json:"id"` + Question string `json:"question"` + Toc string `json:"toc"` + Answer string `json:"answer"` + Links []struct { + Label string `json:"label"` + Href string `json:"href"` + External bool `json:"external"` + } `json:"links"` + } `json:"faqs"` + } `json:"subgroups"` + } `json:"groups"` + } + if err := json.Unmarshal(raw, &doc); err != nil { + t.Fatalf("parse faq.json: %v", err) + } + if len(doc.Groups) == 0 { + t.Fatal("faq.json has no groups") + } + + groupIDs := map[string]bool{} + faqIDs := map[string]bool{} + for _, g := range doc.Groups { + if g.ID == "" || g.Title == "" || g.Icon == "" { + t.Errorf("group %q must have id, title, and icon", g.ID) + } + if groupIDs[g.ID] { + t.Errorf("duplicate group id %q", g.ID) + } + groupIDs[g.ID] = true + if len(g.Subgroups) == 0 { + t.Errorf("group %q has no subgroups", g.ID) + } + for _, sg := range g.Subgroups { + if len(sg.Faqs) == 0 { + t.Errorf("group %q has a subgroup with no faqs", g.ID) + } + for _, f := range sg.Faqs { + if f.ID == "" || f.Question == "" || f.Answer == "" { + t.Errorf("faq %q in group %q must have id, question, and answer", f.ID, g.ID) + } + if faqIDs[f.ID] { + t.Errorf("duplicate faq id %q", f.ID) + } + faqIDs[f.ID] = true + // Question text becomes the JSON-LD Question name verbatim; + // answers get backticks stripped, questions do not. + if strings.Contains(f.Question, "`") { + t.Errorf("faq %q question must not contain backticks", f.ID) + } + // Backtick code spans in answers must pair up for the site's + // inline-code renderer. + if strings.Count(f.Answer, "`")%2 != 0 { + t.Errorf("faq %q answer has an unbalanced backtick", f.ID) + } + for _, l := range f.Links { + if l.Label == "" || l.Href == "" { + t.Errorf("faq %q has a link missing label or href", f.ID) + } + switch { + case strings.HasPrefix(l.Href, "/"): + if l.External { + t.Errorf("faq %q link %q is site-relative but marked external", f.ID, l.Href) + } + case strings.HasPrefix(l.Href, "https://"): + if !l.External { + t.Errorf("faq %q link %q is absolute but not marked external", f.ID, l.Href) + } + default: + t.Errorf("faq %q link %q must start with / or https://", f.ID, l.Href) + } + } + } + } + } +} From ac20d9f1144b639c2b76a22212f5a473ac9005b6 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Wed, 29 Jul 2026 03:02:53 -0700 Subject: [PATCH 10/14] docs: address second-round review feedback - scan command page: scope the no-network sentence to matcher services and point at the full network model (build tools can run during resolution). - faq_test: reject protocol-relative hrefs, which resolve to an external origin but passed the site-relative branch. - docs index: stop promising a strict manifest mirror now that the index also links site pages outside the versioned docs (the FAQ). Co-Authored-By: Claude Fable 5 --- docs/README.md | 2 +- docs/commands/scan.md | 2 +- internal/support/faq_test.go | 4 ++++ 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index b9ae6a04..36b31c0e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # Bomly Documentation -Start with [Getting Started](GETTING_STARTED.md) if you're new. Otherwise pick the section that matches what you're doing. The sections below mirror the site navigation groups defined in [`manifest.json`](manifest.json), so this index and the published docs site always tell the same story. +Start with [Getting Started](GETTING_STARTED.md) if you're new. Otherwise pick the section that matches what you're doing. The sections below follow the site navigation groups defined in [`manifest.json`](manifest.json), plus links to a few site pages that live outside the versioned docs (such as the FAQ). ## Getting started diff --git a/docs/commands/scan.md b/docs/commands/scan.md index 8e96b773..1a95fe66 100644 --- a/docs/commands/scan.md +++ b/docs/commands/scan.md @@ -18,7 +18,7 @@ Top-level dependencies express 4.19.2 MIT runtime - ``` -No network calls happen here — enrichment columns stay empty until you ask for them. +No matcher service is contacted here — enrichment columns stay empty until you ask for them. (Resolution itself can still invoke your build tool when a lockfile parser can't resolve the project; [Network and Privacy](../NETWORK.md) has the full model.) ## Choose a target diff --git a/internal/support/faq_test.go b/internal/support/faq_test.go index 8a9412c6..d2fd2e4a 100644 --- a/internal/support/faq_test.go +++ b/internal/support/faq_test.go @@ -86,6 +86,10 @@ func TestDocsFAQIsWellFormed(t *testing.T) { t.Errorf("faq %q has a link missing label or href", f.ID) } switch { + case strings.HasPrefix(l.Href, "//"): + // Protocol-relative URLs resolve to an external origin + // but would pass the site-relative branch below. + t.Errorf("faq %q link %q must not be protocol-relative", f.ID, l.Href) case strings.HasPrefix(l.Href, "/"): if l.External { t.Errorf("faq %q link %q is site-relative but marked external", f.ID, l.Href) From 8547f904b628aeccba19b3856aedb2ef36ff0d9b Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Wed, 29 Jul 2026 03:49:42 -0700 Subject: [PATCH 11/14] docs: show real expected output across the guide pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every load-bearing command in Getting Started, Scan Targets, Use Cases, and Output Formats now shows the output it produces, captured from real runs on an express-pinning npm fixture (scan, enrich, audit with findings and exit 2, all-paths explain, recursive discovery tree, SBOM ingest scope difference, audited diff with introduced/persisted buckets, jq and SARIF samples). Long blocks are collapsed in details elements per the style rules. Two accuracy fixes surfaced by capturing for real: Getting Started claimed explain prints the shortest path (it prints every path), and the README claimed -o file outputs still show the terminal report (a run with only file-target -o specs and no --format is silent — now documented on the Getting Started and Output Formats -o sections). Co-Authored-By: Claude Fable 5 --- README.md | 2 +- docs/GETTING_STARTED.md | 59 ++++++++++++++++++++++++++++++++++-- docs/OUTPUT_FORMATS.md | 66 ++++++++++++++++++++++++++++++++++++++++- docs/SCAN_TARGETS.md | 27 +++++++++++++++++ docs/USE_CASES.md | 48 ++++++++++++++++++++++++++++-- 5 files changed, 195 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 528509b1..28be2b9c 100644 --- a/README.md +++ b/README.md @@ -145,7 +145,7 @@ bomly scan --json # SARIF for security tabs and code-scanning integrations bomly scan --enrich --audit --fail-on high --format sarif -# Write SBOMs while still showing the normal report +# Write SBOM artifacts (add --format text to also print the report) bomly scan -o spdx=sbom.spdx.json -o cyclonedx=sbom.cdx.json # Emit one SBOM to stdout diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 75eac6be..6ba4cf06 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -32,6 +32,18 @@ This runs the default pipeline: 2. Run the best detector chain for each subproject. 3. Render a human-readable report. +On a small npm project it looks like this: + +```text +✓ 68 packages in 1 manifest (1 direct, 67 transitive · runtime 68, dev 0) + +Top-level dependencies + NAME VERSION LICENSE SCOPE VULNS + express 4.19.2 MIT runtime - +``` + +The VULNS column stays empty until you enrich — that's the next section. + **Matchers are offline by default** — no `--enrich` means zero outbound enrichment calls. **Detectors** may still invoke their build tool (Go, Maven, Gradle, sbt) which can download packages from package registries. Lockfile-parser detectors (npm, pnpm, yarn, Composer, Bundler, NuGet, GitHub Actions) and SBOM ingest are fully offline. See [Detectors → Network behavior](DETECTORS.md#network-behavior) for the full breakdown. Pass `--path` to scan a directory other than the current one: @@ -68,6 +80,21 @@ See [Scan targets](SCAN_TARGETS.md) for the full target list. bomly scan --enrich ``` +The same project now shows which packages carry advisories and whether fixes exist: + +```text +✓ 68 packages in 1 manifest (1 direct, 67 transitive · runtime 68, dev 0) + +✓ Enriched via Grype, deps.dev License Matcher + +✓ 7 fix suggestions for 7 of 7 vulnerable packages. + Run again with --format json to see remediation details. + +Top-level dependencies + NAME VERSION LICENSE SCOPE VULNS + express 4.19.2 MIT runtime 1L +``` + This calls the enabled built-in matchers, including OSV, KEV, deps.dev, and OpenSSF Scorecard when selected. Responses are cached under `~/.bomly/cache/`. See [Matchers](MATCHERS.md) for the per-source list and cache TTLs. ClearlyDefined license and endoflife.date lifecycle enrichment are available as external matcher plugins. ## Generate an SBOM @@ -80,7 +107,7 @@ bomly scan \ -o cyclonedx=sbom.cdx.json ``` -`-o` can be passed multiple times. At most one may omit `=` (that one goes to stdout). See [SBOM formats](SBOM.md) for the format comparison. +`-o` can be passed multiple times. At most one may omit `=` (that one goes to stdout). When every `-o` has a file path and no `--format` is set, a successful run writes the files and prints nothing — add `--format text` if you also want the terminal report. See [SBOM formats](SBOM.md) for the format comparison. ## Gate CI on a policy @@ -90,6 +117,16 @@ Add `--audit --fail-on ` to turn findings into a non-zero exit code: bomly scan --enrich --audit --fail-on high ``` +On a project with vulnerable packages, the report gains a Findings section and the process exits `2`: + +```text +Findings + [HIGH] GHSA-37ch-88jc-xwx2 path-to-regexp@0.1.7 + [HIGH] GHSA-9wv6-86v2-598j path-to-regexp@0.1.7 + [HIGH] GHSA-qwcr-r2fm-qrc7 body-parser@1.20.2 + [HIGH] GHSA-rhx6-c78j-4q9w path-to-regexp@0.1.7 +``` + Exit `0` means clean. Exit `2` means at least one finding matched the threshold. Exit `4` means an invalid flag value. See [Exit codes](EXIT_CODES.md). Common combinations: @@ -107,10 +144,26 @@ See [Auditors](AUDITORS.md) for the full grammar and [Reachability](REACHABILITY ## Explain why a package is in the graph ```bash -bomly explain lodash +bomly explain send ``` -Bomly prints the shortest dependency path that introduced the package, plus alternative paths if there are multiple roots. +Bomly prints every dependency path that introduces the package — not just the shortest one — so you can see each route you'd have to break to remove it: + +```text +ecosystem npm +manager npm +package send@0.18.0 +scope runtime +direct no +licenses + MIT [declared] +introduced by: + demo@1.0.0 + └─ express@4.19.2 + ├─ send@0.18.0 [analyzed] (transitive) + └─ serve-static@1.15.0 + └─ send@0.18.0 [analyzed] (transitive) +``` ## Diff two versions diff --git a/docs/OUTPUT_FORMATS.md b/docs/OUTPUT_FORMATS.md index 83652ae1..9982a369 100644 --- a/docs/OUTPUT_FORMATS.md +++ b/docs/OUTPUT_FORMATS.md @@ -40,6 +40,25 @@ The default. Groups packages by ecosystem and edge depth, summarizes finding cou bomly scan --enrich --audit ``` +```text +✓ 68 packages in 1 manifest (1 direct, 67 transitive · runtime 68, dev 0) + +✓ Enriched via Grype, deps.dev License Matcher + +✓ 7 fix suggestions for 7 of 7 vulnerable packages. + Run again with --format json to see remediation details. + +Top-level dependencies + NAME VERSION LICENSE SCOPE VULNS + express 4.19.2 MIT runtime 1L + +Findings + [HIGH] GHSA-37ch-88jc-xwx2 path-to-regexp@0.1.7 + [HIGH] GHSA-9wv6-86v2-598j path-to-regexp@0.1.7 + [HIGH] GHSA-qwcr-r2fm-qrc7 body-parser@1.20.2 + [HIGH] GHSA-rhx6-c78j-4q9w path-to-regexp@0.1.7 +``` + Markdown reports include the same remediation summary and the complete suggestion table. @@ -83,6 +102,21 @@ bomly explain lodash --json | jq '.paths[] | .nodes | map(.name) | join(" -> ")' bomly diff --base main --head HEAD --enrich --audit --json | jq '.findings.introduced[]' ``` +The first query against a project pinning `express@4.19.2` (first two of several matches shown): + +```json +{ + "name": "body-parser", + "version": "1.20.2", + "ecosystem": "npm" +} +{ + "name": "path-to-regexp", + "version": "0.1.7", + "ecosystem": "npm" +} +``` + JSON output includes Bomly-specific metadata that standard SBOM formats don't carry: reachability tier/status/confidence, audit reasons, and per-finding source. `bomly explain` returns every deterministic root-to-target path, not only a @@ -122,11 +156,41 @@ SARIF 2.1.0. Findings only. One result per (rule × package) pair. Includes: bomly scan --enrich --audit --fail-on high --format sarif > bomly.sarif ``` +
+Sample result object (one finding, properties trimmed) + +```json +{ + "ruleId": "GHSA-m6fv-jmcg-4jfg", + "level": "error", + "message": { + "text": "send vulnerable to template injection that can lead to XSS in pkg:npm/send@0.18.0" + }, + "locations": [ + { + "physicalLocation": { + "artifactLocation": { "uri": "package-lock.json" }, + "region": { "startLine": 636 } + } + } + ], + "properties": { + "package_ref": "pkg:npm/send@0.18.0", + "fixed_in": "0.19.0", + "fix_state": "fixed" + } +} +``` + +Locations point at the lockfile line that pins the vulnerable version, so code-scanning annotations land somewhere actionable. + +
+ GitHub Code Scanning, Azure DevOps, and most IDE extensions ingest SARIF directly. See [CI integration](CI_INTEGRATION.md) for upload recipes. ## Additional output: `-o` -`-o` uses the same format names as `--format`, plus an optional file path. Use `=` to write to a file, or just `` to write that additional output to stdout. +`-o` uses the same format names as `--format`, plus an optional file path. Use `=` to write to a file, or just `` to write that additional output to stdout. When every `-o` names a file and `--format` is not set, a successful run writes the files silently — pass `--format text` (or any primary format) if you also want stdout output. ```bash bomly scan --json \ diff --git a/docs/SCAN_TARGETS.md b/docs/SCAN_TARGETS.md index 3600860b..f35b342d 100644 --- a/docs/SCAN_TARGETS.md +++ b/docs/SCAN_TARGETS.md @@ -39,6 +39,23 @@ bomly scan --recursive --exclude dist,examples # repeatable / comma-separated It works with `--path` and `--url` targets. `--image` and `--sbom` scans do not use directory discovery and reject `--recursive` with exit 4. +The report shows the discovered structure — every subproject with its manifest and package count, consolidated into one graph: + +```text +✓ 78 packages in 2 manifests (2 direct, 76 transitive · runtime 78, dev 0) + ├─ api (subproject, npm) + │ └─ demo — 68 packages [package-lock.json] + └─ web (subproject, npm) + └─ demo — 69 packages [package-lock.json] + +Top-level dependencies + NAME VERSION LICENSE SCOPE VULNS + express 4.19.2 MIT runtime - + express 4.21.2 MIT runtime - +``` + +Both versions of a package appear when different subprojects pin different releases — each is a distinct package keyed by its own PURL. + ### Depth — `--max-depth` Depth is counted from the scan root: the root itself is depth 0 and a direct child is depth 1. Directories at depths beyond `--max-depth` are not visited. The default is `3`; `--max-depth 0` removes the limit. `--max-depth` requires `--recursive`. @@ -175,6 +192,16 @@ SPDX 2.3 JSON and CycloneDX 1.6 JSON are auto-detected. Useful when: - A vendor sent you an SBOM and you want to evaluate it against your policy. - You're testing detector output without re-running the heavy detector. +Ingest looks like a normal scan, with one visible difference — SBOMs don't carry Bomly's runtime/development scope split, so dependencies keep the relationship the SBOM recorded (here, `required`) and count as `unscoped`: + +```text +✓ 69 packages in 1 manifest (1 direct, 68 transitive · runtime 0, dev 0, unscoped 69) + +Top-level dependencies + NAME VERSION LICENSE SCOPE VULNS + express 4.21.2 MIT required - +``` + See [SBOM formats](SBOM.md) for the format comparison. ## Combinations diff --git a/docs/USE_CASES.md b/docs/USE_CASES.md index ea8be634..1fe20f03 100644 --- a/docs/USE_CASES.md +++ b/docs/USE_CASES.md @@ -12,6 +12,37 @@ bomly diff --base main --head HEAD --enrich --audit --fail-on high `diff` classifies findings as introduced / resolved / persisted and only `--fail-on` matches against the introduced set, so a clean PR passes even on a repo with known debt. Exit code `2` means a new high finding; see [Exit codes](EXIT_CODES.md). +
+Sample output — an express upgrade that drags in one new advisory + +```text +Added (1) + + encodeurl@2.0.0 MIT runtime +Version changed (9) + ~ body-parser 1.20.2 → 1.20.3 + ~ cookie 0.6.0 → 0.7.1 + ~ express 4.19.2 → 4.21.2 + ~ finalhandler 1.2.0 → 1.3.1 + ~ merge-descriptors 1.0.1 → 1.0.3 + ~ path-to-regexp 0.1.7 → 0.1.12 + ~ qs 6.11.0 → 6.13.0 + ~ send 0.18.0 → 0.19.0 + ~ serve-static 1.15.0 → 1.16.2 + +1 new finding(s) introduced; 3 finding(s) persisted. + introduced [MEDIUM] GHSA-q8mj-m7cp-5q26 qs@6.13.0 + persisted [HIGH] GHSA-37ch-88jc-xwx2 path-to-regexp@0.1.12 + persisted [MEDIUM] GHSA-6rw7-vpxm-498p qs@6.13.0 + persisted [LOW] GHSA-w7fw-mjwx-w883 qs@6.13.0 + +✓ 2 fix suggestions for 2 of 2 vulnerable packages. + Run again with --format json to see remediation details. +``` + +With `--fail-on high`, this run passes: the only *introduced* finding is medium, and the persisted high is pre-existing debt. + +
+ → Turnkey version for GitHub PRs: the [Bomly Guard action](https://github.com/bomly-dev/bomly-guard) ([setup](CI_INTEGRATION.md#turnkey-pr-reviews-with-bomly-guard)). ## Generate and publish an SBOM @@ -125,10 +156,23 @@ You get added, removed, and updated dependencies, plus introduced/resolved findi **Goal:** find the path that pulled a transitive package into your build. ```bash -bomly explain lodash +bomly explain send +``` + +`explain` prints every dependency path that introduces the package: + +```text +package send@0.18.0 +direct no +introduced by: + demo@1.0.0 + └─ express@4.19.2 + ├─ send@0.18.0 [analyzed] (transitive) + └─ serve-static@1.15.0 + └─ send@0.18.0 [analyzed] (transitive) ``` -`explain` prints the dependency path(s) that introduced the package. Add `--audit` to see findings in that path's context. +Add `--audit` to see findings in that path's context. Full reference: [explain](commands/explain.md). ## Explore results interactively From 3212297556971d9f828a7c55b70062d08bccbb4b Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Wed, 29 Jul 2026 03:50:33 -0700 Subject: [PATCH 12/14] docs: add an integrations page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit One place that catalogs everything Bomly plugs into — Guard, CI recipes, MCP hosts, code scanning, install channels, and the official plugin repos — with an Official/Community tagging convention and an explicit invitation for community additions. Gives future integrators a stable place to land. Co-Authored-By: Claude Fable 5 --- docs/INTEGRATIONS.md | 52 ++++++++++++++++++++++++++++++++++++++++++++ docs/README.md | 1 + docs/manifest.json | 6 +++++ 3 files changed, 59 insertions(+) create mode 100644 docs/INTEGRATIONS.md diff --git a/docs/INTEGRATIONS.md b/docs/INTEGRATIONS.md new file mode 100644 index 00000000..ec687013 --- /dev/null +++ b/docs/INTEGRATIONS.md @@ -0,0 +1,52 @@ +# Integrations + +Tools and surfaces that Bomly plugs into. Entries are tagged **Official** (built and maintained by the Bomly project) or **Community** (maintained by their own authors — direct support questions to them). To suggest an addition, open a pull request that adds an entry in the same format. + +## CI / CD + +### Bomly Guard (Official) + +The turnkey GitHub Action: runs `bomly diff` against a pull request's merge base and reports dependency changes, findings, and an updatable PR comment, with optional SARIF upload to code scanning. +→ [bomly-dev/bomly-guard](https://github.com/bomly-dev/bomly-guard) · [Guard guide](BOMLY_GUARD.md) + +### Direct CLI recipes (Official) + +Drop-in pipeline snippets for GitHub Actions, GitLab CI, Jenkins, Azure DevOps, and CircleCI, plus a pre-commit hook for local enforcement. +→ [CI Integration](CI_INTEGRATION.md) + +## AI agents and editors + +### MCP server (Official) + +`bomly mcp serve` is built into the binary and works with any MCP client that supports stdio transport. Documented host setups: Claude Code, Cursor, VS Code, GitHub Copilot, and Codex. +→ [MCP Server](MCP.md) + +### Agent guidance snippet (Official) + +A ready-made instruction block for `CLAUDE.md` / `AGENTS.md` / `copilot-instructions.md` that has coding agents run a dependency diff before committing lockfile changes. +→ [MCP Server → Agent workflows](MCP.md) + +## GitHub code scanning + +SARIF 2.1.0 output uploads to the GitHub Security tab (and any other SARIF-aware tool) either via Guard's `upload-sarif` input or directly from the CLI. +→ [Output Formats → SARIF](OUTPUT_FORMATS.md#sarif--ci-security-tools) + +## Package managers and distribution + +Official install channels: Homebrew tap (`bomly-dev/tap`), WinGet (`Bomly.BomlyCLI`), Scoop, install scripts (`bomly.dev/install.sh`), Linux packages, `go install`, and prebuilt release archives with checksums and SLSA provenance. +→ [Installation](INSTALLATION.md) + +## Plugins + +External detectors, matchers, and auditors install as managed plugins (versioned, verified, disabled until enabled). Official plugin repositories: + +- **ClearlyDefined license matcher (Official)** — license enrichment from clearlydefined.io. → [bomly-plugin-clearlydefined-matcher](https://github.com/bomly-dev/bomly-plugin-clearlydefined-matcher) +- **EOL lifecycle matcher (Official)** — end-of-life status from endoflife.date. → [bomly-plugin-eol-matcher](https://github.com/bomly-dev/bomly-plugin-eol-matcher) +- **Bun lockfile detector (Official, example)** — reference implementation for plugin authors. → [bomly-plugin-bun-lock-detector](https://github.com/bomly-dev/bomly-plugin-bun-lock-detector) +- **Meme auditor (Official, example)** — a deliberately silly auditor showing the minimal auditor contract. → [bomly-plugin-meme-auditor](https://github.com/bomly-dev/bomly-plugin-meme-auditor) + +Write your own: [Plugins](PLUGINS.md) and the per-role implementation guides. + +## Community + +No community integrations are listed yet — if you've built one (a CI orb, an IDE extension, a dashboard that reads Bomly JSON), open a pull request adding it here with a one-line description and a link. diff --git a/docs/README.md b/docs/README.md index 36b31c0e..09cde48e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -48,6 +48,7 @@ Specifications and matrices. The generated pages are regenerated from code by `m Running Bomly in CI and keeping pipelines healthy. +- [Integrations](INTEGRATIONS.md) — CI actions, AI agents, code scanning, install channels, and plugins - [CI Integration](CI_INTEGRATION.md) — GitHub Actions, GitLab, Jenkins, Azure, CircleCI - [CI-Readiness Warnings](CI_READINESS.md) — package-manager, lockfile-format, and install-policy mismatches that fail CI on their own - [Bomly Guard](BOMLY_GUARD.md) — the turnkey GitHub Action for PR dependency review diff --git a/docs/manifest.json b/docs/manifest.json index 0e80464b..09eb9cb7 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -153,6 +153,12 @@ "description": "Every Bomly term, one sentence each.", "group": "reference" }, + { + "slug": "integrations", + "title": "Integrations", + "description": "CI actions, AI agents, code scanning, install channels, and plugins Bomly connects to.", + "group": "operations" + }, { "slug": "ci-integration", "title": "CI integration", From 6b00be1bf89c2dce9c07968d749b6263639c73be Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Wed, 29 Jul 2026 03:52:09 -0700 Subject: [PATCH 13/14] docs: give the selector grammar one home and link it from every selector flag COMMANDS.md gains a Selector grammar section (replace / +append / -remove, comma-mixing, unknown-name behavior verified against the binary), and the detectors, matchers, auditors, and reachability pages now link to it instead of re-describing the grammar inline. Co-Authored-By: Claude Fable 5 --- docs/AUDITORS.md | 2 +- docs/COMMANDS.md | 15 ++++++++++++++- docs/DETECTORS.md | 2 +- docs/MATCHERS.md | 2 +- docs/REACHABILITY.md | 2 +- 5 files changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/AUDITORS.md b/docs/AUDITORS.md index bd3dfe8c..9db465b5 100644 --- a/docs/AUDITORS.md +++ b/docs/AUDITORS.md @@ -18,7 +18,7 @@ bomly scan --enrich --audit --fail-on high | [`license`](auditors/license.md) | Package licenses vs. allow/deny SPDX policy | `--allow-license`, `--deny-license`, `--license-exempt-package` | | [`package`](auditors/package.md) | Denied packages and typosquatted names | `--deny-package`, `--deny-group`, `--protected-package`, `--typosquat-threshold`, `--typosquat-mode` | -Select a subset with the `--auditors` selector (e.g. `--auditors license`). See the [per-auditor reference](auditors/) for options, examples, and limitations. Auditors are also a plugin extension point — for a worked example of an external auditor, see the [Meme Dependency Auditor](https://github.com/bomly-dev/bomly-plugin-meme-auditor). +Select a subset with the `--auditors` [selector](COMMANDS.md#selector-grammar) (e.g. `--auditors license`). See the [per-auditor reference](auditors/) for options, examples, and limitations. Auditors are also a plugin extension point — for a worked example of an external auditor, see the [Meme Dependency Auditor](https://github.com/bomly-dev/bomly-plugin-meme-auditor). ## When auditors run diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 777a40c0..079d24e2 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -12,8 +12,21 @@ Everything Bomly does runs through one of these commands. The three graph comman | `bomly mcp` | Serve Bomly's tools to MCP-aware AI agents | [MCP Server](MCP.md) | | `bomly version` | Print version information | — | +## Shared option surface + The three graph commands share one option surface: the same target flags (`--path`, `--recursive`, `--url`/`--ref`, `--image`, `--sbom`), the same pipeline gates (`--enrich`, `--audit`, `--analyze`), the same component selectors (`--detectors`, `--matchers`, `--auditors`, `--analyzers`), and the same output flags (`--format`, `-o`, `--json`). Learn them once on the [scan](commands/scan.md) page; the [explain](commands/explain.md) and [diff](commands/diff.md) pages cover only what differs. -Selectors use one grammar everywhere: a bare list replaces the default set (`--matchers osv`), `+name` appends to the defaults, and `-name` removes from them (`--matchers -depsdev-license-matcher`). Output targets use `-o ` or `-o =`, repeatable for multiple artifacts in one run. +## Selector grammar + +`--detectors`, `--matchers`, `--auditors`, `--analyzers`, and `--ecosystems` all accept the same selector list: + +- A bare list **replaces** the default set: `--matchers osv` runs only OSV. +- `+name` **appends** to the defaults: `--matchers +clearlydefined-license-matcher` adds an installed plugin matcher. +- `-name` **removes** from the defaults: `--matchers -depsdev-license-matcher` keeps everything else. +- Entries are comma-separated and may mix forms: `--ecosystems +go,-npm`. + +A name must belong to a registered component — a typo or a plugin that isn't installed fails with exit `4` and a message naming the unknown selector. Discover valid names with `bomly plugins list`. + +Output targets use a separate spec: `-o ` or `-o =`, repeatable for multiple artifacts in one run — see [Output Formats](OUTPUT_FORMATS.md#additional-output--o). For every flag with its config key, environment variable, and default, see the generated [Config Reference](CONFIG_REFERENCE.md) — or run `bomly --help`. diff --git a/docs/DETECTORS.md b/docs/DETECTORS.md index 103cd252..a0d015af 100644 --- a/docs/DETECTORS.md +++ b/docs/DETECTORS.md @@ -40,7 +40,7 @@ Bomly prefers native detectors because they preserve edges (needed by `bomly exp ## Selecting detectors -Use `--detectors` to restrict or extend the default set with the standard `+/-` selector grammar: +Use `--detectors` to restrict or extend the default set with the standard [selector grammar](COMMANDS.md#selector-grammar): ```bash # Use only the native Go detector diff --git a/docs/MATCHERS.md b/docs/MATCHERS.md index 6a96cdac..e9ec620b 100644 --- a/docs/MATCHERS.md +++ b/docs/MATCHERS.md @@ -32,7 +32,7 @@ Pass `--enrich` to run all default network matchers: bomly scan --enrich ``` -Use `--matchers` to restrict or extend the set with the standard `+/-` selector grammar: +Use `--matchers` to restrict or extend the set with the standard [selector grammar](COMMANDS.md#selector-grammar): ```bash # Only OSV diff --git a/docs/REACHABILITY.md b/docs/REACHABILITY.md index f7baaceb..f9189a5b 100644 --- a/docs/REACHABILITY.md +++ b/docs/REACHABILITY.md @@ -348,7 +348,7 @@ Reachability data appears in three places: ## Selecting analyzers -Use the `--analyzers` selector to restrict or extend the default set: +Use the `--analyzers` [selector](COMMANDS.md#selector-grammar) to restrict or extend the default set: ```sh bomly scan --enrich --analyze --analyzers govulncheck From aad5e38b373de33d90c84307d86de2b673fa0a55 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Wed, 29 Jul 2026 20:33:45 -0700 Subject: [PATCH 14/14] docs: generate the selector-grammar links instead of hand-editing hybrid pages The DETECTORS/MATCHERS/AUDITORS selector-grammar cross-links were applied to the generated pages directly, which the generated-docs drift job rightly rejects. The sentences now live in internal/support/component_docs.go and make generate reproduces the pages byte-identically. Co-Authored-By: Claude Fable 5 --- internal/support/component_docs.go | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/internal/support/component_docs.go b/internal/support/component_docs.go index af38919c..bb7628c1 100644 --- a/internal/support/component_docs.go +++ b/internal/support/component_docs.go @@ -81,7 +81,7 @@ Bomly prefers native detectors because they preserve edges (needed by `+"`bomly ## Selecting detectors -Use `+"`--detectors`"+` to restrict or extend the default set with the standard `+"`+/-`"+` selector grammar: +Use `+"`--detectors`"+` to restrict or extend the default set with the standard [selector grammar](COMMANDS.md#selector-grammar): `+"```bash"+` # Use only the native Go detector @@ -266,7 +266,7 @@ Pass `+"`--enrich`"+` to run all default network matchers: bomly scan --enrich `+"```"+` -Use `+"`--matchers`"+` to restrict or extend the set with the standard `+"`+/-`"+` selector grammar: +Use `+"`--matchers`"+` to restrict or extend the set with the standard [selector grammar](COMMANDS.md#selector-grammar): `+"```bash"+` # Only OSV @@ -366,7 +366,7 @@ network. | [`+"`license`"+`](auditors/license.md) | Package licenses vs. allow/deny SPDX policy | `+"`--allow-license`"+`, `+"`--deny-license`"+`, `+"`--license-exempt-package`"+` | | [`+"`package`"+`](auditors/package.md) | Denied packages, typosquatted names, and source changes | `+"`--deny-package`"+`, `+"`--deny-group`"+`, `+"`--protected-package`"+`, `+"`--typosquat-threshold`"+`, `+"`--typosquat-mode`"+`, `+"`--fail-on source-change`"+` | -Select a subset with the `+"`--auditors`"+` selector (e.g. `+"`--auditors license`"+`). See the [per-auditor reference](auditors/) for options, examples, and limitations. Auditors are also a plugin extension point — for a worked example of an external auditor, see the [Meme Dependency Auditor](https://github.com/bomly-dev/bomly-plugin-meme-auditor). +Select a subset with the `+"`--auditors`"+` [selector](COMMANDS.md#selector-grammar) (e.g. `+"`--auditors license`"+`). See the [per-auditor reference](auditors/) for options, examples, and limitations. Auditors are also a plugin extension point — for a worked example of an external auditor, see the [Meme Dependency Auditor](https://github.com/bomly-dev/bomly-plugin-meme-auditor). ## When auditors run