Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
144 lines (92 loc) · 4.35 KB

GETTING_STARTED.md

File metadata and controls

144 lines (92 loc) · 4.35 KB

Getting Started

This page walks you from installation to your first useful scan in five minutes.

Install

If you have Go on PATH:

go install github.com/bomly-dev/bomly-cli/cmd/bomly@latest

Otherwise download a prebuilt archive from GitHub Releases and put bomly on your PATH. Verify:

bomly version

For the full install matrix — bomly vs bomly-lite, checksum verification, PowerShell instructions, uninstall — see Installation.

Scan a project

From inside any source tree:

bomly scan

This runs the default pipeline:

  1. Discover subprojects (every recognized lockfile or manifest).
  2. Run the best detector chain for each subproject.
  3. Render a human-readable report.

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 for the full breakdown.

Pass --path to scan a directory other than the current one:

bomly scan --path ./services/api

Need structured output for automation? --json is the shortcut for --format json:

bomly scan --json

Pass --container to scan a container image:

bomly scan --container ghcr.io/example/app:latest

Pass --url (with optional --ref) to scan a Git repository without cloning by hand:

bomly scan --url https://github.com/example/repo --ref v1.2.0

See Scan targets for the full target list.

Add vulnerability and license data

bomly scan is offline by default. Pass --enrich when you want vulnerability, license, and lifecycle data from public sources:

bomly scan --enrich

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 for the per-source list and cache TTLs. ClearlyDefined license and endoflife.date lifecycle enrichment are available as external matcher plugins.

Generate an SBOM

Use -o to write SPDX 2.3 or CycloneDX 1.6:

bomly scan \
  -o spdx=sbom.spdx.json \
  -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 for the format comparison.

Gate CI on a policy

Add --audit --fail-on <severity> to turn findings into a non-zero exit code:

bomly scan --enrich --audit --fail-on high

Exit 0 means clean. Exit 2 means at least one finding matched the threshold. Exit 4 means an invalid flag value. See Exit codes.

Common combinations:

# Fail on high or critical findings
bomly scan --enrich --audit --fail-on high

# Fail only when a high-or-above finding is actually reachable
bomly scan --enrich --audit --analyze --fail-on high --fail-on reachable

See Auditors for the full grammar and Reachability for what "reachable" means per ecosystem. Reachability is an experimental feature; review its limitations before gating CI on it.

Explain why a package is in the graph

bomly explain lodash

Bomly prints the shortest dependency path that introduced the package, plus alternative paths if there are multiple roots.

Diff two versions

Compare two Git refs:

bomly diff --base main --head HEAD

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.

Inspect the interactive view

bomly scan --interactive

Opens a terminal UI with tabs for packages, vulnerabilities, licenses, findings, and source. See TUI for keybindings.

What to read next