diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3867c97c..0bfb850c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -115,3 +115,17 @@ 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 + with: + persist-credentials: false + - 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/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/README.md b/README.md index ed86d287..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 @@ -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 @@ -221,6 +222,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). 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/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b8288995..ca14066f 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 four support 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/FAQ.md b/docs/FAQ.md new file mode 100644 index 00000000..d179639b --- /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. 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/NETWORK.md b/docs/NETWORK.md new file mode 100644 index 00000000..c685d592 --- /dev/null +++ b/docs/NETWORK.md @@ -0,0 +1,44 @@ +# Network and Privacy + +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 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, 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 | +| 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. 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 + +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/REACHABILITY.md b/docs/REACHABILITY.md index 48ab652b..f7baaceb 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 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 f1a4ee85..897269dd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,56 +1,70 @@ # 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 site navigation groups defined in [`manifest.json`](manifest.json), so this index and the published docs site 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 +- [FAQ](FAQ.md) — quick answers on privacy, accounts, tool differences, and first-scan surprises -## 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 +- [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 - [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 +- [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 +- [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 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 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..8e96b773 --- /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 · `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 + +- [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 196b1cdb..33ce5dd0 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", @@ -69,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", @@ -103,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",