Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
17 changes: 17 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}/<name>.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 `<details><summary>Output</summary>…</details>`.
- 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. <one sentence on what is stable and what is not>
```

## 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.
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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).
Expand Down
4 changes: 2 additions & 2 deletions dev-docs/CI.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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

Expand Down
23 changes: 13 additions & 10 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
19 changes: 19 additions & 0 deletions docs/COMMANDS.md
Original file line number Diff line number Diff line change
@@ -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 <format>` or `-o <format>=<path>`, 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 <command> --help`.
44 changes: 44 additions & 0 deletions docs/NETWORK.md
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion docs/REACHABILITY.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down
Loading
Loading