CLI reference¶

Full options, analysis modes, CI/CD integration, and troubleshooting for BomLens.

Options reference¶

./scripts/scan-sbom.sh [options]

Windows: the commands here are for macOS/Linux. Pick one of the following. See Getting started for installation.

Replace ./scripts/scan-sbom.sh with scripts\scan-sbom.bat (needs Git Bash).

Under WSL2, run the commands as-is.

To work without a command line, double-click scripts\sbom-ui.bat, or download the desktop app.

Option	Default	Description
`--project <name>`	—	(required) Project name
`--version <version>`	—	(required) Project version
`--target <target>`	current directory	What to analyze: a directory (source tree, or an OS rootfs / staging build output), a Docker image, a binary file, or a `.zip`/`.tar.gz` archive. A Yocto build directory is recognized as such, and the image SBOM it published under `tmp/deploy/images/` is analyzed instead of the build tree being walked (see the supplier SBOM guide)
`--git <url>`	—	Shallow-clone a git/GitHub URL and analyze it as source (private repos: `GIT_TOKEN` env var)
`--branch <ref>`	default branch	Branch, tag, or commit of the `--git` target (alias `--ref`)
`--firmware`	false	Force firmware mode on the `--target` file (opt-in firmware image)
`--analyze <sbom>`	—	Validate and analyze a supplier SBOM (alias `--sbom`). CycloneDX/SPDX. Mutually exclusive with `--target`
`--model <owner/name>`	—	Generate an AI SBOM (CycloneDX 1.7 ML-BOM) for a HuggingFace model via the OWASP AIBOM Generator (opt-in `bomlens-aibom` image; fetches model-card metadata over the network). Mutually exclusive with `--target`/`--analyze`/`--git`/`--merge`
`--license <spdx-id>`	—	The outbound license the project is distributed under (e.g. `Apache-2.0`). Recorded on the SBOM's root component and used to flag dependencies whose terms clash with it. A source scan cannot infer this — cdxgen leaves the root license empty for maven and gradle — so without it no conflict verdict is produced. An existing root license (a supplier SBOM's own declaration) is never replaced
`--usage <scenario>`	—	Tailor the AI model risk assessment (`--model` only) to how the model will be used: `internal`, `product`, `redistribute` or `outputs-only`. Only the license conditions that bind that scenario decide the verdict, and the report states which scenario it was judged for. Unset judges against every condition
`--merge <a.json> <b.json> …`	—	Merge two or more CycloneDX SBOMs into one, dedupe by purl, and stamp the root component with `--project`/`--version`. Optional — for a server SBOM when an external system needs a single product BOM; otherwise keep the layers separate (see the server SBOM guide). Mutually exclusive with `--target`/`--analyze`/`--git`
`--merge-root <file>`	—	With `--merge`: keep this input's `specVersion` and root component (for example an ML-BOM's CycloneDX 1.7 root with its model card) instead of writing a fresh 1.6 root. Must be one of the `--merge` files; the preserved root is renamed to `--project`/`--version`
`--generate-only`	false	Save locally only, without uploading
`--upload-target <target>`	`dependency-track`	Upload destination: `dependency-track` (DT-compatible) or `trusca` (native ingest)
`--trusca <project_id>`	—	Upload to TRUSCA (= `--upload-target trusca` + project id). Needs `API_URL` and a Bearer `API_KEY`
`--notice`	(on by default)	Generate the open-source notice (NOTICE, txt+html)
`--security`	(on by default)	Generate the Trivy security report (json+md+html), including CVSS, EPSS, and CISA KEV priority signals
`--spdx`	false	Also export the SBOM as SPDX 2.3 JSON (`_bom.spdx.json`), converted from the final CycloneDX output
`--all`	—	`--notice --security --spdx`
`--no-report`	false	Skip the open-source risk report (see below)
`--lang <en\\|ko>`	`en`	Language for the human-facing conformance and AI-profile reports (`.md`/`.html`). The SBOM and the JSON reports stay English regardless
`--deep-license`	false	Precise license detection with scancode (opt-in image)
`--deep-cve`	false	Also match Maven components against the NVD by CPE via grype (opt-in `bomlens-deep-cve` image, pulled automatically). Recovers NVD-only CVEs that Trivy misses for older Java libraries; implies `--security`. Findings not verified against the live NVD version range are flagged version-unverified in the report — see the deep CVE matching guide
`--identify-vendored`	false	Identify open source copied (vendored) into C/C++ source that has no package manager. Matches file fingerprints against the OSSKB service (included in the published image; sends hashes, not source). See the identify bundled OSS guide
`--byte-stable`	false	Deterministic (reproducible) SBOM output
`--sign`	false	cosign signature (`COSIGN_KEY` required)
`--output-dir <dir>`	current directory	Base directory for outputs (alias `-o`). Each scan lands in a `{Project}_{Version}/` subfolder under it, keeping the bundle together and out of the source tree
`--timestamp`	false	Append `_YYYYMMDD-HHMMSS` to the run subfolder so repeat scans of the same project and version are kept side by side instead of overwritten. Folder name only; SBOM bytes are unchanged
`--ui`	—	Launch the local web UI
`--mount <dir>`	—	With `--ui`: expose an extra host directory to the web UI as a read-only target for the Directory path input (repeatable). Lets the UI scan an OS tree outside the launch folder — including the running host OS with `--mount /`. Results still save under the launch folder
`--help`	—	Print help

Environment variables adjust the behavior.

Variable	Default	Description
`SBOM_SCANNER_IMAGE`	`ghcr.io/sktelecom/bomlens:latest`	Override the scanner image
`SBOM_FIRMWARE_IMAGE`	`ghcr.io/sktelecom/bomlens-firmware:latest`	Image used for firmware analysis
`SBOM_AIBOM_IMAGE`	`ghcr.io/sktelecom/bomlens-aibom:latest`	Image used for AI model (ML-BOM) generation
`SBOM_DEEP_CVE_IMAGE`	`ghcr.io/sktelecom/bomlens-deep-cve:latest`	Image used for `--deep-cve` (grype maven CPE matching)
`SBOM_OUTPUT_FLAT`	—	Set to `1` to write artifacts flat in the output base, with no per-run subfolder (the pre-isolation layout, for CI that expects the old paths)
`SBOM_OUTPUT_DIR`	`~/sbom-output`	Output base for the desktop app and web UI (the CLI uses `--output-dir` instead). Each scan still lands in a `{Project}_{Version}/` subfolder under it
`SBOM_UI_MOUNT_DIR`	—	For the Windows launcher `sbom-ui.bat`, which takes no CLI arguments: one extra folder to expose to the web UI as a read-only Directory path target (the double-click counterpart of `--ui --mount`). Use a path without `& ^ \| < >` — the launcher rejects those rather than passing a mangled mount to Docker
`SBOM_LANG`	system locale	`en` or `ko`, for the Windows launchers and the desktop app. Anything that is not Korean gets English
`SBOM_PULL`	`missing`	Windows launcher download behavior. `missing` downloads only when the image is absent, `always` re-checks the registry every run (picks up a newer `:latest`), `never` never touches the network
`SBOM_IMAGE_TAR`	—	Path to an image tar from `docker save`. The Windows launcher loads it instead of pulling; a file named `bomlens-image.tar` next to the scripts is picked up automatically. Combined with `SBOM_PULL=never` this gives a fully offline install
`CVE_BIN_TOOL_MODE`	`auto`	Firmware CVE matching. `auto` uses the bundled CVE database if present, otherwise downloads from NVD when the network is reachable. `offline` matches only against the bundled database. `online` always updates from the network. `components-only` skips CVE matching and emits a component-only SBOM
`CVE_BIN_TOOL_HOME`	`/opt/cve-bin-tool-home`	Location of the bundled cve-bin-tool CVE database. cve-bin-tool reads `$CVE_BIN_TOOL_HOME/.cache/cve-bin-tool/cve.db` (it keys the cache off `HOME`)
`CVE_BIN_TOOL_DISABLE_SOURCES`	`GAD`	cve-bin-tool data sources to disable during a firmware scan. `GAD` (GitLab Advisory) is disabled by default because it crashes the bundled cve-bin-tool on fetch
`SCANOSS_API_URL`	OSSKB free API	Endpoint for `--identify-vendored`. Point at a SCANOSS commercial or self-hosted endpoint for air-gapped or high-volume use
`SCANOSS_API_KEY`	—	Credential for `SCANOSS_API_URL`, if the endpoint requires one
`SCANOSS_MIN_FILES`	`2`	Minimum number of files that must match a library before it is reported, to drop one-off downstream-fork noise. Set `1` to keep every single-file match
`GIT_TOKEN`	—	Token for cloning private git repositories
`HF_TOKEN`	—	HuggingFace read token for `--model` and for the dataset metadata lookups during AI SBOM analysis. Required for a private or gated repository, which is how you review a model before publishing it. `HUGGING_FACE_HUB_TOKEN` is accepted as an alias
`ENRICH_HF_SECURITY`	`true`	Read HuggingFace's own file-security scan results (ClamAV and picklescan, per file) for `--model` scans and record them in the ML-BOM. Metadata only, no file download. Set `false` to skip the lookup
`COSIGN_KEY`	—	Path to the signing key used by `--sign`
`FETCH_LICENSE`	`true`	Resolve dependency licenses during source scans. Set `false` to skip the lookup and run faster
`PROJECT_LICENSE`	—	Same as `--license`. The outbound license the project is distributed under, as an SPDX id. Drives the `bomlens:licenseConflict` verdicts and the risk report's conflict section
`SECURITY_ENRICH`	`true`	Enrich the security report with EPSS and CISA KEV signals. Set `false` on air-gapped networks to skip the external lookups
`SECURITY_NVD_VERIFY`	`false`	With `--deep-cve`: verify each grype `nvd:cpe` finding against the live NVD version range and drop out-of-range false positives (needs `NVD_API_KEY` and network access; adds minutes). Off by default — findings are kept and flagged version-unverified
`NVD_API_KEY`	—	NVD API key for `SECURITY_NVD_VERIFY`. Passed to the container by name only, never inlined into the command
`API_URL`	—	Upload server URL (a DT server, or the TRUSCA base)
`API_KEY`	—	Upload credential. Used as `X-Api-Key` for DT, as a Bearer token for TRUSCA
`UPLOAD_TARGET`	`dependency-track`	Upload destination: `dependency-track` or `trusca`
`TRUSCA_PROJECT_ID`	—	TRUSCA project id (UUID). Required when `trusca`
`TRUSCA_REF`	`main`	Ingest ref label
`TRUSCA_RELEASE`	`--version` value	Ingest release label

On Windows, environment variables set in a command prompt do not survive a double-click. The launchers therefore also read UI_PORT, SBOM_LANG, SBOM_PULL, SBOM_IMAGE_TAR, SBOM_SCANNER_IMAGE, SBOM_OUTPUT_DIR and SBOM_UI_MOUNT_DIR from a plain text file: copy scripts/bomlens.settings.example.txt to bomlens.settings.txt beside the scripts (or to %USERPROFILE%\.bomlens\settings.txt). A real environment variable always wins over the file.

Output flags are detailed in the reports guide; validating a received supplier SBOM is covered in the supplier SBOM validation.

Where outputs go¶

Each scan is isolated in its own {Project}_{Version}/ subfolder, so the files from one run stay together and the CLI never litters the source tree it scans. That subfolder is created under a base directory:

CLI (scan-sbom.sh): the base is the directory you ran the command in. Override it with --output-dir <dir> (alias -o).
Desktop app and web UI: the base is ~/sbom-output (C:\Users\<you>\sbom-output on Windows). Override it with the SBOM_OUTPUT_DIR environment variable.

For --git or archive ingestion the clone or extract happens in a temp directory that is cleaned up on exit, and only the output subfolder remains.

A re-scan of the same project and version overwrites its subfolder by default, keeping just the latest result. Add --timestamp to keep each run instead: it appends _YYYYMMDD-HHMMSS to the folder name, for example MyApp_1.0.0_20260626-143000/. The flag changes the folder name only, not the SBOM file names or bytes, so it works together with --byte-stable.

To restore the previous flat layout, where every file is written directly in the base with no per-run subfolder, set SBOM_OUTPUT_FLAT=1. This is meant for CI that expects the old paths.

Pin the scanner image version¶

Override the scanner image with SBOM_SCANNER_IMAGE.

SBOM_SCANNER_IMAGE="ghcr.io/sktelecom/bomlens:1.8.0" \
  ./scripts/scan-sbom.sh --project "MyApp" --version "1.0.0" --generate-only

Troubleshooting¶

Windows: no outputs appear¶

If the scan finishes but no output files show up, check that the folder you ran from is inside a Docker file-sharing path. Anything under your home directory (C:\Users\...) is shared by default in both Rancher Desktop and Docker Desktop. From an unshared location the container cannot write results to the host.

Docker permission error¶

Got permission denied while trying to connect to the Docker daemon

Add your user to the docker group.

sudo usermod -aG docker $USER
newgrp docker

Out of disk space¶

no space left on device

Prune the Docker cache.

docker system prune -f

Anything else¶

Check verbose logs with VERBOSE=true ./tests/test-scan.sh.
Update the Docker image: docker pull ghcr.io/sktelecom/bomlens:latest.
If it still fails, open a GitHub Issue with your environment info and logs.

For how to use each mode, see the input scenarios guide; for the kinds of outputs, see the artifacts reference; for language detection, see supported ecosystems.