Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
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
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ bomly scan --json
# SARIF for security tabs and code-scanning integrations
bomly scan --enrich --audit --fail-on high --format sarif

# Write SBOMs while still showing the normal report
# Write SBOM artifacts (add --format text to also print the report)
bomly scan -o spdx=sbom.spdx.json -o cyclonedx=sbom.cdx.json

# Emit one SBOM to stdout
Expand Down
2 changes: 1 addition & 1 deletion docs/AUDITORS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ network.
| [`license`](auditors/license.md) | Package licenses vs. allow/deny SPDX policy | `--allow-license`, `--deny-license`, `--license-exempt-package` |
| [`package`](auditors/package.md) | Denied packages, typosquatted names, and source changes | `--deny-package`, `--deny-group`, `--protected-package`, `--typosquat-threshold`, `--typosquat-mode`, `--fail-on source-change` |

Select a subset with the `--auditors` selector (e.g. `--auditors license`). See the [per-auditor reference](auditors/) for options, examples, and limitations. Auditors are also a plugin extension point — for a worked example of an external auditor, see the [Meme Dependency Auditor](https://github.com/bomly-dev/bomly-plugin-meme-auditor).
Select a subset with the `--auditors` [selector](COMMANDS.md#selector-grammar) (e.g. `--auditors license`). See the [per-auditor reference](auditors/) for options, examples, and limitations. Auditors are also a plugin extension point — for a worked example of an external auditor, see the [Meme Dependency Auditor](https://github.com/bomly-dev/bomly-plugin-meme-auditor).

## When auditors run

Expand Down
15 changes: 14 additions & 1 deletion docs/COMMANDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,21 @@ Everything Bomly does runs through one of these commands. The three graph comman
| `bomly mcp` | Serve Bomly's tools to MCP-aware AI agents | [MCP Server](MCP.md) |
| `bomly version` | Print version information | — |

## Shared option surface

The three graph commands share one option surface: the same target flags (`--path`, `--recursive`, `--url`/`--ref`, `--image`, `--sbom`), the same pipeline gates (`--enrich`, `--audit`, `--analyze`), the same component selectors (`--detectors`, `--matchers`, `--auditors`, `--analyzers`), and the same output flags (`--format`, `-o`, `--json`). Learn them once on the [scan](commands/scan.md) page; the [explain](commands/explain.md) and [diff](commands/diff.md) pages cover only what differs.

Selectors use one grammar everywhere: a bare list replaces the default set (`--matchers osv`), `+name` appends to the defaults, and `-name` removes from them (`--matchers -depsdev-license-matcher`). Output targets use `-o <format>` or `-o <format>=<path>`, repeatable for multiple artifacts in one run.
## Selector grammar

`--detectors`, `--matchers`, `--auditors`, `--analyzers`, and `--ecosystems` all accept the same selector list:

- A bare list **replaces** the default set: `--matchers osv` runs only OSV.
- `+name` **appends** to the defaults: `--matchers +clearlydefined-license-matcher` adds an installed plugin matcher.
- `-name` **removes** from the defaults: `--matchers -depsdev-license-matcher` keeps everything else.
- Entries are comma-separated and may mix forms: `--ecosystems +go,-npm`.

A name must belong to a registered component — a typo or a plugin that isn't installed fails with exit `4` and a message naming the unknown selector. Discover valid names with `bomly plugins list`.

Output targets use a separate spec: `-o <format>` or `-o <format>=<path>`, repeatable for multiple artifacts in one run — see [Output Formats](OUTPUT_FORMATS.md#additional-output--o).

For every flag with its config key, environment variable, and default, see the generated [Config Reference](CONFIG_REFERENCE.md) — or run `bomly <command> --help`.
2 changes: 1 addition & 1 deletion docs/DETECTORS.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ Bomly prefers native detectors because they preserve edges (needed by `bomly exp

## Selecting detectors

Use `--detectors` to restrict or extend the default set with the standard `+/-` selector grammar:
Use `--detectors` to restrict or extend the default set with the standard [selector grammar](COMMANDS.md#selector-grammar):

```bash
# Use only the native Go detector
Expand Down
59 changes: 56 additions & 3 deletions docs/GETTING_STARTED.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,18 @@ This runs the default pipeline:
2. Run the best detector chain for each subproject.
3. Render a human-readable report.

On a small npm project it looks like this:

```text
✓ 68 packages in 1 manifest (1 direct, 67 transitive · runtime 68, dev 0)

Top-level dependencies
NAME VERSION LICENSE SCOPE VULNS
express 4.19.2 MIT runtime -
```

The VULNS column stays empty until you enrich — that's the next section.

**Matchers are offline by default** — no `--enrich` means zero outbound enrichment calls. **Detectors** may still invoke their build tool (Go, Maven, Gradle, sbt) which can download packages from package registries. Lockfile-parser detectors (npm, pnpm, yarn, Composer, Bundler, NuGet, GitHub Actions) and SBOM ingest are fully offline. See [Detectors → Network behavior](DETECTORS.md#network-behavior) for the full breakdown.

Pass `--path` to scan a directory other than the current one:
Expand Down Expand Up @@ -68,6 +80,21 @@ See [Scan targets](SCAN_TARGETS.md) for the full target list.
bomly scan --enrich
```

The same project now shows which packages carry advisories and whether fixes exist:

```text
✓ 68 packages in 1 manifest (1 direct, 67 transitive · runtime 68, dev 0)

✓ Enriched via Grype, deps.dev License Matcher

✓ 7 fix suggestions for 7 of 7 vulnerable packages.
Run again with --format json to see remediation details.

Top-level dependencies
NAME VERSION LICENSE SCOPE VULNS
express 4.19.2 MIT runtime 1L
```

This calls the enabled built-in matchers, including OSV, KEV, deps.dev, and OpenSSF Scorecard when selected. Responses are cached under `~/.bomly/cache/`. See [Matchers](MATCHERS.md) for the per-source list and cache TTLs. ClearlyDefined license and endoflife.date lifecycle enrichment are available as external matcher plugins.

## Generate an SBOM
Expand All @@ -80,7 +107,7 @@ bomly scan \
-o cyclonedx=sbom.cdx.json
```

`-o` can be passed multiple times. At most one may omit `=<path>` (that one goes to stdout). See [SBOM formats](SBOM.md) for the format comparison.
`-o` can be passed multiple times. At most one may omit `=<path>` (that one goes to stdout). When every `-o` has a file path and no `--format` is set, a successful run writes the files and prints nothing — add `--format text` if you also want the terminal report. See [SBOM formats](SBOM.md) for the format comparison.

## Gate CI on a policy

Expand All @@ -90,6 +117,16 @@ Add `--audit --fail-on <severity>` to turn findings into a non-zero exit code:
bomly scan --enrich --audit --fail-on high
```

On a project with vulnerable packages, the report gains a Findings section and the process exits `2`:

```text
Findings
[HIGH] GHSA-37ch-88jc-xwx2 path-to-regexp@0.1.7
[HIGH] GHSA-9wv6-86v2-598j path-to-regexp@0.1.7
[HIGH] GHSA-qwcr-r2fm-qrc7 body-parser@1.20.2
[HIGH] GHSA-rhx6-c78j-4q9w path-to-regexp@0.1.7
```

Exit `0` means clean. Exit `2` means at least one finding matched the threshold. Exit `4` means an invalid flag value. See [Exit codes](EXIT_CODES.md).

Common combinations:
Expand All @@ -107,10 +144,26 @@ See [Auditors](AUDITORS.md) for the full grammar and [Reachability](REACHABILITY
## Explain why a package is in the graph

```bash
bomly explain lodash
bomly explain send
```

Bomly prints the shortest dependency path that introduced the package, plus alternative paths if there are multiple roots.
Bomly prints every dependency path that introduces the package — not just the shortest one — so you can see each route you'd have to break to remove it:

```text
ecosystem npm
manager npm
package send@0.18.0
scope runtime
direct no
licenses
MIT [declared]
introduced by:
demo@1.0.0
└─ express@4.19.2
├─ send@0.18.0 [analyzed] (transitive)
└─ serve-static@1.15.0
└─ send@0.18.0 [analyzed] (transitive)
```

## Diff two versions

Expand Down
52 changes: 52 additions & 0 deletions docs/INTEGRATIONS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Integrations

Tools and surfaces that Bomly plugs into. Entries are tagged **Official** (built and maintained by the Bomly project) or **Community** (maintained by their own authors — direct support questions to them). To suggest an addition, open a pull request that adds an entry in the same format.

## CI / CD

### Bomly Guard (Official)

The turnkey GitHub Action: runs `bomly diff` against a pull request's merge base and reports dependency changes, findings, and an updatable PR comment, with optional SARIF upload to code scanning.
→ [bomly-dev/bomly-guard](https://github.com/bomly-dev/bomly-guard) · [Guard guide](BOMLY_GUARD.md)

### Direct CLI recipes (Official)

Drop-in pipeline snippets for GitHub Actions, GitLab CI, Jenkins, Azure DevOps, and CircleCI, plus a pre-commit hook for local enforcement.
→ [CI Integration](CI_INTEGRATION.md)

## AI agents and editors

### MCP server (Official)

`bomly mcp serve` is built into the binary and works with any MCP client that supports stdio transport. Documented host setups: Claude Code, Cursor, VS Code, GitHub Copilot, and Codex.
→ [MCP Server](MCP.md)

### Agent guidance snippet (Official)

A ready-made instruction block for `CLAUDE.md` / `AGENTS.md` / `copilot-instructions.md` that has coding agents run a dependency diff before committing lockfile changes.
→ [MCP Server → Agent workflows](MCP.md)

## GitHub code scanning

SARIF 2.1.0 output uploads to the GitHub Security tab (and any other SARIF-aware tool) either via Guard's `upload-sarif` input or directly from the CLI.
→ [Output Formats → SARIF](OUTPUT_FORMATS.md#sarif--ci-security-tools)

## Package managers and distribution

Official install channels: Homebrew tap (`bomly-dev/tap`), WinGet (`Bomly.BomlyCLI`), Scoop, install scripts (`bomly.dev/install.sh`), Linux packages, `go install`, and prebuilt release archives with checksums and SLSA provenance.
→ [Installation](INSTALLATION.md)

## Plugins

External detectors, matchers, and auditors install as managed plugins (versioned, verified, disabled until enabled). Official plugin repositories:

- **ClearlyDefined license matcher (Official)** — license enrichment from clearlydefined.io. → [bomly-plugin-clearlydefined-matcher](https://github.com/bomly-dev/bomly-plugin-clearlydefined-matcher)
- **EOL lifecycle matcher (Official)** — end-of-life status from endoflife.date. → [bomly-plugin-eol-matcher](https://github.com/bomly-dev/bomly-plugin-eol-matcher)
- **Bun lockfile detector (Official, example)** — reference implementation for plugin authors. → [bomly-plugin-bun-lock-detector](https://github.com/bomly-dev/bomly-plugin-bun-lock-detector)
- **Meme auditor (Official, example)** — a deliberately silly auditor showing the minimal auditor contract. → [bomly-plugin-meme-auditor](https://github.com/bomly-dev/bomly-plugin-meme-auditor)

Write your own: [Plugins](PLUGINS.md) and the per-role implementation guides.

## Community

No community integrations are listed yet — if you've built one (a CI orb, an IDE extension, a dashboard that reads Bomly JSON), open a pull request adding it here with a one-line description and a link.
2 changes: 1 addition & 1 deletion docs/MATCHERS.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Pass `--enrich` to run all default network matchers:
bomly scan --enrich
```

Use `--matchers` to restrict or extend the set with the standard `+/-` selector grammar:
Use `--matchers` to restrict or extend the set with the standard [selector grammar](COMMANDS.md#selector-grammar):

```bash
# Only OSV
Expand Down
66 changes: 65 additions & 1 deletion docs/OUTPUT_FORMATS.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,25 @@ The default. Groups packages by ecosystem and edge depth, summarizes finding cou
bomly scan --enrich --audit
```

```text
✓ 68 packages in 1 manifest (1 direct, 67 transitive · runtime 68, dev 0)

✓ Enriched via Grype, deps.dev License Matcher

✓ 7 fix suggestions for 7 of 7 vulnerable packages.
Run again with --format json to see remediation details.

Top-level dependencies
NAME VERSION LICENSE SCOPE VULNS
express 4.19.2 MIT runtime 1L

Findings
[HIGH] GHSA-37ch-88jc-xwx2 path-to-regexp@0.1.7
[HIGH] GHSA-9wv6-86v2-598j path-to-regexp@0.1.7
[HIGH] GHSA-qwcr-r2fm-qrc7 body-parser@1.20.2
[HIGH] GHSA-rhx6-c78j-4q9w path-to-regexp@0.1.7
```

Markdown reports include the same remediation summary and the complete
suggestion table.

Expand Down Expand Up @@ -83,6 +102,21 @@ bomly explain lodash --json | jq '.paths[] | .nodes | map(.name) | join(" -> ")'
bomly diff --base main --head HEAD --enrich --audit --json | jq '.findings.introduced[]'
```

The first query against a project pinning `express@4.19.2` (first two of several matches shown):

```json
{
"name": "body-parser",
"version": "1.20.2",
"ecosystem": "npm"
}
{
"name": "path-to-regexp",
"version": "0.1.7",
"ecosystem": "npm"
}
```

JSON output includes Bomly-specific metadata that standard SBOM formats don't carry: reachability tier/status/confidence, audit reasons, and per-finding source.

`bomly explain` returns every deterministic root-to-target path, not only a
Expand Down Expand Up @@ -128,11 +162,41 @@ SARIF 2.1.0. Findings only. One result per (rule × package) pair. Includes:
bomly scan --enrich --audit --fail-on high --format sarif > bomly.sarif
```

<details>
<summary>Sample result object (one finding, properties trimmed)</summary>

```json
{
"ruleId": "GHSA-m6fv-jmcg-4jfg",
"level": "error",
"message": {
"text": "send vulnerable to template injection that can lead to XSS in pkg:npm/send@0.18.0"
},
"locations": [
{
"physicalLocation": {
"artifactLocation": { "uri": "package-lock.json" },
"region": { "startLine": 636 }
}
}
],
"properties": {
"package_ref": "pkg:npm/send@0.18.0",
"fixed_in": "0.19.0",
"fix_state": "fixed"
}
}
```

Locations point at the lockfile line that pins the vulnerable version, so code-scanning annotations land somewhere actionable.

</details>

GitHub Code Scanning, Azure DevOps, and most IDE extensions ingest SARIF directly. See [CI integration](CI_INTEGRATION.md) for upload recipes.

## Additional output: `-o`

`-o` uses the same format names as `--format`, plus an optional file path. Use `<format>=<path>` to write to a file, or just `<format>` to write that additional output to stdout.
`-o` uses the same format names as `--format`, plus an optional file path. Use `<format>=<path>` to write to a file, or just `<format>` to write that additional output to stdout. When every `-o` names a file and `--format` is not set, a successful run writes the files silently — pass `--format text` (or any primary format) if you also want stdout output.

```bash
bomly scan --json \
Expand Down
2 changes: 1 addition & 1 deletion docs/REACHABILITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -348,7 +348,7 @@ Reachability data appears in three places:

## Selecting analyzers

Use the `--analyzers` selector to restrict or extend the default set:
Use the `--analyzers` [selector](COMMANDS.md#selector-grammar) to restrict or extend the default set:

```sh
bomly scan --enrich --analyze --analyzers govulncheck
Expand Down
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ Specifications and matrices. The generated pages are regenerated from code by `m

Running Bomly in CI and keeping pipelines healthy.

- [Integrations](INTEGRATIONS.md) — CI actions, AI agents, code scanning, install channels, and plugins
- [CI Integration](CI_INTEGRATION.md) — GitHub Actions, GitLab, Jenkins, Azure, CircleCI
- [CI-Readiness Warnings](CI_READINESS.md) — package-manager, lockfile-format, and install-policy mismatches that fail CI on their own
- [Bomly Guard](BOMLY_GUARD.md) — the turnkey GitHub Action for PR dependency review
Expand Down
27 changes: 27 additions & 0 deletions docs/SCAN_TARGETS.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,23 @@ bomly scan --recursive --exclude dist,examples # repeatable / comma-separated

It works with `--path` and `--url` targets. `--image` and `--sbom` scans do not use directory discovery and reject `--recursive` with exit 4.

The report shows the discovered structure — every subproject with its manifest and package count, consolidated into one graph:

```text
✓ 78 packages in 2 manifests (2 direct, 76 transitive · runtime 78, dev 0)
├─ api (subproject, npm)
│ └─ demo — 68 packages [package-lock.json]
└─ web (subproject, npm)
└─ demo — 69 packages [package-lock.json]

Top-level dependencies
NAME VERSION LICENSE SCOPE VULNS
express 4.19.2 MIT runtime -
express 4.21.2 MIT runtime -
```

Both versions of a package appear when different subprojects pin different releases — each is a distinct package keyed by its own PURL.

### Depth — `--max-depth`

Depth is counted from the scan root: the root itself is depth 0 and a direct child is depth 1. Directories at depths beyond `--max-depth` are not visited. The default is `3`; `--max-depth 0` removes the limit. `--max-depth` requires `--recursive`.
Expand Down Expand Up @@ -175,6 +192,16 @@ SPDX 2.3 JSON and CycloneDX 1.6 JSON are auto-detected. Useful when:
- A vendor sent you an SBOM and you want to evaluate it against your policy.
- You're testing detector output without re-running the heavy detector.

Ingest looks like a normal scan, with one visible difference — SBOMs don't carry Bomly's runtime/development scope split, so dependencies keep the relationship the SBOM recorded (here, `required`) and count as `unscoped`:

```text
✓ 69 packages in 1 manifest (1 direct, 68 transitive · runtime 0, dev 0, unscoped 69)

Top-level dependencies
NAME VERSION LICENSE SCOPE VULNS
express 4.21.2 MIT required -
```

See [SBOM formats](SBOM.md) for the format comparison.

## Combinations
Expand Down
Loading
Loading