Generate notice, security & risk reports¶
Beyond SBOM generation, BomLens produces an open-source notice (NOTICE) and a security vulnerability report in one run. This page covers how to generate those outputs. For how to read and interpret them, see Reports explained.
Quickstart (5 minutes)¶
If this is your first time, this is all you need. With the Docker engine running, move to the project folder you want to scan and run one of the two (replace SBOM with the real path to scan-sbom.sh):
Windows users: the commands below assume macOS/Linux. Pick one of the following. For installation, see Getting started.
- Replace
./scripts/scan-sbom.shwithscripts\scan-sbom.bat(Git Bash required).- Under WSL2, run the commands as-is.
- To work without the command line, double-click
scripts\sbom-ui.bat.
SBOM=/path/to/sbom-tools/scripts/scan-sbom.sh
# (A) CLI — SBOM + notice + security report in one run
cd /path/to/your-project
$SBOM --project MyApp --version 1.0.0 --all --generate-only
# (B) Browser UI — if the CLI feels like too much
$SBOM --ui # opens http://localhost:8080 automatically (on a port conflict: UI_PORT=9090 $SBOM --ui)
When it finishes, open MyApp_1.0.0_NOTICE.html (notice) and MyApp_1.0.0_security.html (security) created in the same folder in a browser to check the results right away. See below for the detailed options.
Prerequisites¶
- Docker engine 20.10+ (free: WSL2 + docker-ce, or Rancher Desktop / Docker Desktop, which is paid for organizational use)
- Pull the scanner image:
- Run every example from the root of the project to scan.
Output flags are best used together with
--generate-only(save locally). Omit it to also auto-upload to a Dependency-Track server or TRUSCA (formerly TrustedOSS Portal); pick the target withUPLOAD_TARGET.
Generate everything at once (--all)¶
--all is shorthand for --notice --security. It produces the SBOM, the notice, and the security report in a single scan.
Generated files:
MyApp_1.0.0_bom.json # SBOM (CycloneDX 1.6)
MyApp_1.0.0_NOTICE.txt # notice (text)
MyApp_1.0.0_NOTICE.html # notice (HTML)
MyApp_1.0.0_security.json # security report (raw Trivy)
MyApp_1.0.0_security.md # security report (summary)
MyApp_1.0.0_security.html # security report (visual)
MyApp_1.0.0_risk-report.md # open-source risk report (summary)
MyApp_1.0.0_risk-report.html # open-source risk report (visual)
The open-source risk report (
_risk-report) is generated by default in every analysis mode (license + vulnerability tally, with response deadlines). To skip it, use--no-report. For handling each of the five input forms, see the Scenarios guide.
For the full list of artifact kinds, see the artifacts reference; to generate them from a browser, see the web UI.
Open-source notice (--notice)¶
Gathers the components[].licenses information from the SBOM and generates a notice that groups components by license.
_NOTICE.txt— standard text, good to ship with the distribution._NOTICE.html— a browser-friendly format. All package metadata is HTML-escaped and safe.- Components with no license information are classified as
NOASSERTION.
For license normalization and full-text bundling behavior, see Reports explained.
Example (text):
Security vulnerability report (--security)¶
Scans the generated SBOM with Trivy and reports known vulnerabilities (CVEs). (NVD + OSV + GHSA DB)
_security.json— raw Trivy JSON. For CI or machine processing._security.md— a per-severity tally table and CVE list. Good to attach to a PR or issue._security.html— a visual report with severity badges and tables.
The report does not fail the scan even when vulnerabilities exist (report-only). If you need a gate, post-process _security.json.
For severity, CVSS, EPSS, and KEV priority signals and follow-up interpretation, see Reports explained.
Deep license detection (--deep-license)¶
The basic notice covers the licenses of dependencies (3rd-party). --deep-license uses scancode-toolkit to also detect license headers in the project's own source code (1st-party).
scancode is heavy and slow (minutes to tens of minutes for a large repo). It is not in the base image; to use it, build the image as follows:
Additional output: MyApp_1.0.0_scancode.json
Deterministic output (--byte-stable)¶
Produces a byte-identical SBOM for the same input. It removes meaningless diffs in CI (timestamps, random IDs, ordering differences) and ensures reproducibility.
What it does: fixes metadata.timestamp to 1970-01-01T00:00:00Z, removes the random serialNumber, sorts components by purl, and sorts keys.
SBOM signing (--sign)¶
Creates a detached signature on the SBOM with cosign to establish supply-chain trust. It is offline key-based signing (--tlog-upload=false), so no network or OIDC is needed.
# 1) Generate a key (first time only). For a passwordless key, use COSIGN_PASSWORD=""
docker run --rm -v "$PWD":/keys -w /keys -e COSIGN_PASSWORD="" \
--entrypoint cosign ghcr.io/sktelecom/sbom-scanner:latest generate-key-pair
# 2) Scan while signing (COSIGN_KEY=private key path, COSIGN_PASSWORD=key password)
COSIGN_KEY="$PWD/cosign.key" COSIGN_PASSWORD="" \
./scripts/scan-sbom.sh --project MyApp --version 1.0.0 --sign --generate-only
# 3) Verify
docker run --rm -v "$PWD":/w -w /w --entrypoint cosign \
ghcr.io/sktelecom/sbom-scanner:latest \
verify-blob --key cosign.pub --signature MyApp_1.0.0_bom.json.sig \
--insecure-ignore-tlog MyApp_1.0.0_bom.json
The private key is mounted read-only into the container. Additional output: MyApp_1.0.0_bom.json.sig
Troubleshooting¶
| Symptom | Cause / fix |
|---|---|
trivy not installed ... skipping |
old image. Pull the latest image with docker pull. |
--deep-license requested but scancode not in image |
build the image with --build-arg SBOM_DEEP_LICENSE=true. |
Docker is not running in the UI |
start the Docker engine (Rancher Desktop/Docker Desktop, etc.) and run it again. |
Many NOASSERTION in the notice |
the dependencies have no license metadata. Supplement with --deep-license or check manually. |
Port conflict (--ui) |
specify a different port with UI_PORT. |
For the detailed design background, see the direction study (Korean).