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
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
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
- [Tutorial](docs/TUTORIAL.md) - from first scan to a CI gate on a real project
- [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
Expand Down
2 changes: 1 addition & 1 deletion docs/AUDITORS.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ See [EXIT_CODES.md](EXIT_CODES.md) for the full table.
- **Resolved** — present in base, absent in head
- **Persisted** — present in both

Combine with `--fail-on` to fail PRs that introduce new high-severity findings without complaining about pre-existing ones:
The diff audit only inspects packages the change touched, so findings on unchanged packages never appear — that is how pre-existing debt stays out of PR reviews. Both remaining buckets gate: `--fail-on` fails on introduced findings and on persisted ones, because a persisted finding means the changed package still ships a known issue at its new version:
Comment thread
bomly-guy marked this conversation as resolved.
Resolved

```bash
bomly diff --base main --head HEAD --enrich --audit --fail-on high
Expand Down
2 changes: 1 addition & 1 deletion docs/BOMLY_GUARD.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Pin to a major tag (`@v1`) for automatic patch and minor updates, or to an exact
On a `pull_request` event the action:

1. Installs the Bomly CLI (`version` input, defaults to `latest`).
2. Resolves the base and head refs. Pull requests default to the PR merge base for the base and the PR head SHA for the head, so review focuses only on what the PR changes — pre-existing findings on the target branch are ignored.
2. Resolves the base and head refs. Pull requests default to the PR merge base for the base and the PR head SHA for the head, so review focuses only on what the PR changes. Packages the PR doesn't touch are never audited — which is how pre-existing target-branch findings stay out of the review; persisted findings on a package the PR did change still count when they match the configured policy (here, `fail-on: high`).
3. Runs `bomly diff --format json` with the enrich/audit/analyze and policy flags mapped from the action inputs.
4. Renders the Markdown summary and SARIF side outputs.
5. Writes the job summary, optionally posts (or updates) a PR comment, and optionally uploads SARIF.
Expand Down
4 changes: 2 additions & 2 deletions docs/CI_INTEGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ jobs:
--json > bomly-diff.json
```

This fails only when the PR introduces a new high finding, ignoring pre-existing ones.
The diff audits only the packages the PR touched, so findings on untouched packages never fail the job. Within that scope, introduced and persisted high findings both gate — persisted means a changed package still ships a known issue at its new version.

### Cache matcher data

Expand Down Expand Up @@ -254,7 +254,7 @@ Tune `--fail-on` to taste. `pre-push` keeps commits fast and only runs on push.
- Pin the Bomly version in CI. Use a tagged release URL or package-manager version, not `latest`.
- Cache `~/.bomly/cache` across runs. Matcher TTLs make this safe.
- Always upload the SBOM even when the scan fails. The SBOM is a release artifact in its own right.
- Use `bomly diff` on PRs to avoid penalizing PRs for pre-existing findings.
- Use `bomly diff` on PRs so pre-existing findings on untouched packages don't penalize the job — only the packages the PR changes are audited.
- Pre-warm enrichment on `main` with a scheduled nightly run so PR jobs start with a warm cache.

## See also
Expand Down
2 changes: 1 addition & 1 deletion docs/GETTING_STARTED.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,7 @@ Or two SBOM files:
bomly diff --sbom --base ./old.spdx.json --head ./new.spdx.json --json
```

Add `--audit --fail-on high` to fail PRs that introduce new high-severity findings without complaining about pre-existing ones.
Add `--enrich --audit --fail-on high` to gate PRs (auditing requires enrichment). The diff audits only the packages the change touched — untouched debt elsewhere never blocks a PR — and within that scope it fails when the change introduces a matching finding or keeps one alive at the changed package's new version (see [diff](commands/diff.md)).

## Use Bomly with an AI agent

Expand Down
55 changes: 38 additions & 17 deletions docs/INSTALLATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,12 +94,12 @@ irm https://bomly.dev/install.ps1 | iex
Pin a version or install the lite binary:

```bash
curl -fsSL https://bomly.dev/install.sh | BOMLY_VERSION=v0.14.2 sh
curl -fsSL https://bomly.dev/install.sh | BOMLY_VERSION=v0.20.2 sh
curl -fsSL https://bomly.dev/install.sh | BOMLY_BINARY=bomly-lite sh
```

```powershell
$env:BOMLY_VERSION = "v0.14.2"; irm https://bomly.dev/install.ps1 | iex
$env:BOMLY_VERSION = "v0.20.2"; irm https://bomly.dev/install.ps1 | iex
$env:BOMLY_BINARY = "bomly-lite"; irm https://bomly.dev/install.ps1 | iex
```

Expand Down Expand Up @@ -143,19 +143,19 @@ Archive naming:
Manual Linux / macOS install:

```bash
curl -L -O https://github.com/bomly-dev/bomly-cli/releases/download/v0.14.2/bomly_v0.14.2_linux_amd64.tar.gz
curl -L -O https://github.com/bomly-dev/bomly-cli/releases/download/v0.14.2/SHA256SUMS
curl -L -O https://github.com/bomly-dev/bomly-cli/releases/download/v0.20.2/bomly_0.20.2_linux_amd64.tar.gz
curl -L -O https://github.com/bomly-dev/bomly-cli/releases/download/v0.20.2/SHA256SUMS
sha256sum --check SHA256SUMS --ignore-missing
tar -xzf bomly_v0.14.2_linux_amd64.tar.gz
tar -xzf bomly_0.20.2_linux_amd64.tar.gz
sudo install -m 0755 bomly /usr/local/bin/
```

Manual Windows install:

```powershell
$archive = "bomly_v0.14.2_windows_amd64.zip"
Invoke-WebRequest -Uri "https://github.com/bomly-dev/bomly-cli/releases/download/v0.14.2/$archive" -OutFile $archive
Invoke-WebRequest -Uri "https://github.com/bomly-dev/bomly-cli/releases/download/v0.14.2/SHA256SUMS" -OutFile SHA256SUMS
$archive = "bomly_0.20.2_windows_amd64.zip"
Invoke-WebRequest -Uri "https://github.com/bomly-dev/bomly-cli/releases/download/v0.20.2/$archive" -OutFile $archive
Invoke-WebRequest -Uri "https://github.com/bomly-dev/bomly-cli/releases/download/v0.20.2/SHA256SUMS" -OutFile SHA256SUMS
Get-FileHash .\$archive -Algorithm SHA256
Expand-Archive -Path $archive -DestinationPath .
# Move bomly.exe somewhere on your PATH.
Expand Down Expand Up @@ -191,19 +191,34 @@ curl -sSfL https://get.anchore.io/grype | sh -s -- -b /usr/local/bin

## Verify release checksums

Releases include `SHA256SUMS` alongside every archive and package.
Releases include `SHA256SUMS` alongside every archive and package. The commands below use `v0.20.2` and one archive per platform — substitute the release and artifact you are verifying, and download both the archive and the checksum file first.

Linux and macOS:
Linux (GNU coreutils):

```bash
curl -L -O https://github.com/bomly-dev/bomly-cli/releases/download/v0.14.2/SHA256SUMS
curl -L -O https://github.com/bomly-dev/bomly-cli/releases/download/v0.20.2/bomly_0.20.2_linux_amd64.tar.gz
curl -L -O https://github.com/bomly-dev/bomly-cli/releases/download/v0.20.2/SHA256SUMS
sha256sum --check SHA256SUMS --ignore-missing
```

macOS (the system `shasum`; select the artifact's line first):

```bash
curl -L -O https://github.com/bomly-dev/bomly-cli/releases/download/v0.20.2/bomly_0.20.2_darwin_arm64.tar.gz
curl -L -O https://github.com/bomly-dev/bomly-cli/releases/download/v0.20.2/SHA256SUMS
grep " bomly_0.20.2_darwin_arm64.tar.gz$" SHA256SUMS | shasum -a 256 -c
```

Either way, each verified archive prints one `OK` line and the command exits `0`:

```text
bomly_0.20.2_darwin_arm64.tar.gz: OK
```

PowerShell:

```powershell
Get-FileHash .\bomly_v0.14.2_windows_amd64.zip -Algorithm SHA256
Get-FileHash .\bomly_0.20.2_windows_amd64.zip -Algorithm SHA256
# Compare the printed hash against the matching line in SHA256SUMS.
```

Expand All @@ -212,25 +227,31 @@ Get-FileHash .\bomly_v0.14.2_windows_amd64.zip -Algorithm SHA256
`SHA256SUMS` is itself signed keylessly with [cosign](https://docs.sigstore.dev/cosign/signing/overview/), tying the release to the exact GitHub Actions workflow run that built it:

```bash
curl -L -O https://github.com/bomly-dev/bomly-cli/releases/download/v0.14.2/SHA256SUMS.sigstore.json
curl -L -O https://github.com/bomly-dev/bomly-cli/releases/download/v0.20.2/SHA256SUMS.sigstore.json
cosign verify-blob \
--bundle SHA256SUMS.sigstore.json \
--certificate-identity-regexp "^https://github.com/bomly-dev/bomly-cli/.github/workflows/release.yml@.*$" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
SHA256SUMS
```

A valid signature prints exactly:

```text
Verified OK
```

### Verify SLSA provenance

Each release also publishes a single `multiple.intoto.jsonl` SLSA Build Level 3 provenance file covering every release artifact, attesting which source commit and workflow produced them:

```bash
curl -L -O https://github.com/bomly-dev/bomly-cli/releases/download/v0.14.2/bomly_v0.14.2_linux_amd64.tar.gz
curl -L -O https://github.com/bomly-dev/bomly-cli/releases/download/v0.14.2/multiple.intoto.jsonl
slsa-verifier verify-artifact bomly_v0.14.2_linux_amd64.tar.gz \
curl -L -O https://github.com/bomly-dev/bomly-cli/releases/download/v0.20.2/bomly_0.20.2_linux_amd64.tar.gz
curl -L -O https://github.com/bomly-dev/bomly-cli/releases/download/v0.20.2/multiple.intoto.jsonl
slsa-verifier verify-artifact bomly_0.20.2_linux_amd64.tar.gz \
--provenance-path multiple.intoto.jsonl \
--source-uri github.com/bomly-dev/bomly-cli \
--source-tag v0.14.2
--source-tag v0.20.2
```

`slsa-verifier` is available from the [slsa-framework/slsa-verifier releases](https://github.com/slsa-framework/slsa-verifier/releases).
Expand Down
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ Start with [Getting Started](GETTING_STARTED.md) if you're new. Otherwise pick t
Install Bomly and run your first scan.

- [Getting Started](GETTING_STARTED.md) — first scan, enrich, audit, diff
- [Tutorial](TUTORIAL.md) — from first scan to a CI gate on a real project, with representative output from the workflow
- [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
Expand Down
219 changes: 219 additions & 0 deletions docs/TUTORIAL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,219 @@
# Tutorial: From First Scan to a CI Gate

A start-to-finish walkthrough on a real project: scan it, understand a finding, cut the list down to what matters, accept the existing debt, and wire the gate into CI. Every command below was run against the pinned repository shown, and the output you see is what it printed.

Where [Getting Started](GETTING_STARTED.md) introduces each feature on its own, this page chains them into the workflow you'd actually deploy.

## Prerequisites

- `bomly` on your `PATH` ([Installation](INSTALLATION.md)) — verify with `bomly version`
- `git`
- Network access for the enrichment steps (`--enrich` is the explicit opt-in — see [Network and Privacy](NETWORK.md))

We'll use a deliberately vulnerable demo project maintained by the Bomly org, pinned to a tag so the *dependency graph* you scan matches this page. The outputs below were captured with Bomly 0.20.2 on 2026-07-30; graph numbers are stable, but advisory counts and IDs come from live enrichment data and may drift as services add or withdraw records:

```bash
git clone --depth 1 --branch v1.0.0 https://github.com/bomly-dev/example-javascript-npm
cd example-javascript-npm
```

## Step 1 — Inventory the project

```bash
bomly scan
```

```text
✓ 136 packages in 1 manifest (14 direct, 122 transitive · runtime 43, dev 93)

Top-level dependencies
NAME VERSION LICENSE SCOPE VULNS
algo-httpserv 1.1.1 - runtime -
js-yaml 3.13.0 - runtime -
larvitbase 3.1.3 - runtime -
larvitfs 2.3.1 - runtime -
larvitreqparser 0.2.1 - runtime -
larvitrouter 3.0.2 - runtime -
larvitutils 2.3.0 - runtime -
lodash 4.17.15 - runtime -
marked 0.3.19 - runtime -
mocha 7.2.0 - development -
node-yaml-config 0.0.5 - runtime -
semver 5.7.1 - runtime -
to 0.2.9 - runtime -
url 0.11.0 - runtime -
```

Fourteen direct dependencies fan out into 136 packages — the other 122 are transitive, and they're where most surprises live. No network call happened yet: the license and vulnerability columns stay empty until you enrich.

## Step 2 — Ask why a package is there

Pick a package you never installed on purpose. `minimist` is a classic:

```bash
bomly explain minimist
```

```text
ecosystem npm
manager npm
package minimist@0.0.10
scope runtime
direct no
introduced by:
example-javascript-vulnerable-methods@0.0.1
└─ to@0.2.9
└─ optimist@0.6.1
└─ minimist@0.0.10 [analyzed] (transitive)
```

The chain reads bottom-up: removing `minimist@0.0.10` means dealing with `optimist`, which means dealing with the direct dependency `to`. That's the fact you need before filing any upgrade PR. ([explain reference](commands/explain.md))

## Step 3 — Enrich with vulnerability and license data

```bash
bomly scan --enrich
```

```text
✓ 136 packages in 1 manifest (14 direct, 122 transitive · runtime 43, dev 93)

✓ Enriched via Grype, deps.dev License Matcher

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

Top-level dependencies
NAME VERSION LICENSE SCOPE VULNS
algo-httpserv 1.1.1 MIT runtime 1H
js-yaml 3.13.0 MIT runtime 1H 1M
...
```

Twenty-three vulnerable packages, and a fix exists for all but one. Enrichment sends package coordinates — never your code — to the services listed in [Matchers](MATCHERS.md).

## Step 4 — Turn data into a gate

```bash
bomly scan --enrich --audit --fail-on high
echo $?
```

<details>
<summary>Findings (31 rows: 25 gating vulnerabilities + 6 license warnings — first ten shown)</summary>

```text
Findings
[CRITICAL] GHSA-cf4h-3jhx-xvhq underscore@1.9.2
[CRITICAL] GHSA-xvch-5gv4-984h minimist@0.0.10
[CRITICAL] GHSA-xvch-5gv4-984h minimist@1.2.5
[HIGH] GHSA-23c5-xmqv-rm74 minimatch@3.0.4
[HIGH] GHSA-35jh-r3h4-6jhm lodash@4.17.15
[HIGH] GHSA-3ppc-4f35-3m26 minimatch@3.0.4
[HIGH] GHSA-5v2h-r2cx-5xgj marked@0.3.19
[HIGH] GHSA-8j8c-7jfh-h6hx js-yaml@3.13.0
[HIGH] GHSA-cgjv-rghq-qhgp algo-httpserv@1.1.1
[HIGH] GHSA-p6mc-m468-83gw lodash@4.17.15
```

</details>

The exit code is `2`: at least one finding matched `--fail-on high`. The report lists 31 findings, of two kinds: 25 gating vulnerability findings, plus 6 license *warnings* (the `[WARNING] UNKNOWN-…` rows — packages whose license couldn't be determined) that inform but never gate. Twenty-five gating findings is too many to fix in one sitting, which is exactly the situation the next two steps are for. ([Auditors](AUDITORS.md), [Exit Codes](EXIT_CODES.md))

## Step 5 — Triage by reachability (experimental)

Which of those 25 gating findings live in code this app actually imports?

```bash
bomly scan --enrich --audit --analyze --fail-on high --fail-on reachable
```

The two `--fail-on` constraints AND together: a vulnerability finding now gates only when it is high-or-above **and** reachable. On this project that cuts the gating vulnerability findings from 25 to 10 (the report shows 16 rows — the 6 license warnings are unaffected by reachability). For example, `minimist@1.2.5` (pulled in by the dev-only `mocha` toolchain) drops out, while `minimist@0.0.10` on the runtime path stays.

Reachability is experimental, and at package precision "unreachable" means "no import path found", not "safe" — read [Reachability](REACHABILITY.md) before making this your only gate.

## Step 6 — Accept the existing debt

A gate you can't turn on because of old findings protects nothing. Baselines record today's findings so the gate fails only on *new* ones:

```bash
bomly baseline create --enrich
bomly scan --enrich --audit --fail-on high
echo $? # 0
```

The findings are still reported — their policy status becomes `suppressed` instead of gating. Commit `.bomly/baseline.json` so CI and teammates share the same accepted set, and use `bomly baseline update` / `prune` as debt gets paid down. ([Finding Baselines](BASELINES.md))

## Step 7 — Review changes, not snapshots

For pull requests, compare two states and audit only what changed. The demo repo has two tags to compare:

```bash
bomly diff --url https://github.com/bomly-dev/example-javascript-npm \
--base v0.9.0 --head v1.0.0 --enrich --audit --fail-on high
echo $? # 2
```

```text
Version changed (1)
~ lodash 4.17.14 → 4.17.15

3 finding(s) persisted.
persisted [HIGH] GHSA-35jh-r3h4-6jhm lodash@4.17.15
persisted [HIGH] GHSA-p6mc-m468-83gw lodash@4.17.15
persisted [HIGH] GHSA-r5fr-rjxr-66jc lodash@4.17.15

✓ 1 fix suggestion for 1 of 1 vulnerable package.
Run again with --format json to see remediation details.
```

(The `--fail-on high` threshold filters the rendered findings too — drop it to also see this bump's three medium-severity persisted advisories.)

Read this carefully, because it shows both halves of how diff gating works:

- The other 22 vulnerable packages from Step 3 are absent. Diff audits **only the packages the change touched** — untouched debt elsewhere in the repo never blocks a PR.
- The exit code is still `2`. The lodash bump *persisted* three high-severity findings: 4.17.15 still ships them, so the gate correctly refuses to call this upgrade done. The way out is the bump the fix suggestion points at — or an accepted baseline.
- The baseline from Step 6 didn't apply here because diff materializes each side from git: every side uses the baseline **committed at that ref**. Commit `.bomly/baseline.json` and PRs that leave accepted findings untouched pass.

([diff reference](commands/diff.md))

## Step 8 — Put it in CI

The turnkey form for GitHub pull requests is the Guard action — it runs the diff from Step 7 against the PR's merge base and posts the result as a check and an updatable comment:

```yaml
# .github/workflows/bomly.yml
on: pull_request
jobs:
bomly:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
with:
fetch-depth: 0
- uses: bomly-dev/bomly-guard@v1
with:
fail-on: high
```

Prefer the CLI directly (any CI system), with SARIF for the security tab:

```yaml
- name: Bomly gate
run: bomly diff --base origin/main --head HEAD --enrich --audit --fail-on high -o sarif=bomly.sarif
- name: Upload SARIF
if: success() || failure()
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: bomly.sarif
```

Recipes for GitLab, Jenkins, Azure DevOps, and CircleCI live in [CI Integration](CI_INTEGRATION.md); Guard's full input reference in [Bomly Guard](BOMLY_GUARD.md).

## What you built

An inventory you can query (`scan`, `explain`), an enrichment-backed policy gate with a reachability-aware triage path, a committed baseline that separates old debt from new risk, and a PR-level diff gate in CI. From here:

- [Use Cases](USE_CASES.md) — more goal-shaped recipes (licenses, typosquats, containers, SBOMs)
- [Output Formats](OUTPUT_FORMATS.md) — JSON, SARIF, and SBOM artifacts from the same runs
- [Interactive TUI](TUI.md) — explore the same graph with `bomly scan --interactive`
Loading
Loading