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 cdb68967..b764ab37 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 @@ -214,6 +214,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](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 @@ -224,6 +225,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/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 af964ced..fa2a4dc2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,57 +1,71 @@ # 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 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). -## 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](https://bomly.dev/faq) — quick answers on privacy, accounts, tool differences, and first-scan surprises (source: [`faq.json`](faq.json)) -## 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 - [Reproducible Evidence](EVIDENCE.md) — public inputs, commands, results, and limitations behind important behavior claims +## 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..1a95fe66 --- /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 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 + +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/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 19a13410..5939c0b1 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -76,6 +76,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", @@ -110,6 +116,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", diff --git a/internal/support/faq_test.go b/internal/support/faq_test.go new file mode 100644 index 00000000..d2fd2e4a --- /dev/null +++ b/internal/support/faq_test.go @@ -0,0 +1,108 @@ +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, "//"): + // 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) + } + 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) + } + } + } + } + } +}