Reference
Config reference
All config keys, environment variables, and defaults.
Last updated July 30, 2026View source (v0.21.1)
Bomly resolves configuration in the following order, with later sources overriding earlier ones:
~/.bomly/config.yaml--config <path>orBOMLY_CONFIGBOMLY_*environment variables- CLI flags
Repository config files are never loaded automatically. Select a trusted project file explicitly, for example --config .bomly/config.yaml or BOMLY_CONFIG=.bomly/config.yaml. When both are set, --config wins.
Bomly rejects configuration files larger than 4 MiB before parsing them.
YAML files use the nested keys documented below. Unknown keys and the former flat keys are rejected so configuration mistakes fail fast.
General
| YAML Key | Environment Variable | Type | Default | Description |
|---|---|---|---|---|
target.path | BOMLY_PATH | string | - | Filesystem path to scan |
target.image | BOMLY_IMAGE | string | - | Container image to scan (e.g. alpine:latest) |
target.url | BOMLY_URL | string | - | Remote Git URL to clone and scan |
target.ref | BOMLY_REF | string | - | Git ref to checkout when scanning a URL |
target.sbom | BOMLY_SBOM | bool | - | Treat the selected filesystem target as an SBOM file |
target.recursive | BOMLY_RECURSIVE | bool | - | Recursively discover nested manifests under the scan root |
target.max_depth | BOMLY_MAX_DEPTH | int | 3 | Maximum directory depth for recursive discovery, counted from the scan root (0 = unlimited) |
target.exclude | BOMLY_EXCLUDE | []string | - | Glob pattern(s) relative to the scan root excluded from recursive discovery, in addition to built-in ignore rules; requires recursive |
pipeline.enrich | BOMLY_ENRICH | bool | - | Enrich packages with external license and vulnerability data |
pipeline.audit | BOMLY_AUDIT | bool | - | Evaluate policy and create findings from package vulnerability data |
pipeline.analyze | BOMLY_ANALYZE | bool | - | Run code analysis to confirm whether vulnerabilities are reachable from application code |
policy.fail_on | BOMLY_FAIL_ON | []string | - | Constraint(s) for which findings should fail. Repeatable. Vulnerability constraints are AND-ed. Values: any |
policy.allow_vulnerability_ids | BOMLY_ALLOW_VULNERABILITY_IDS | []string | - | Vulnerability IDs to ignore during policy evaluation |
policy.allow_licenses | BOMLY_ALLOW_LICENSES | []string | - | Allowed SPDX license identifiers or expressions |
policy.deny_licenses | BOMLY_DENY_LICENSES | []string | - | Denied SPDX license identifiers or expressions |
policy.license_exempt_packages | BOMLY_LICENSE_EXEMPT_PACKAGES | []string | - | Package URLs exempt from license policy checks |
policy.deny_packages | BOMLY_DENY_PACKAGES | []string | - | Package URLs to deny |
policy.deny_groups | BOMLY_DENY_GROUPS | []string | - | Package URL namespaces to deny |
policy.protected_packages | BOMLY_PROTECTED_PACKAGES | []string | - | Canonical package names to protect from typosquatting |
policy.typosquat_threshold | BOMLY_TYPOSQUAT_THRESHOLD | string | 0.90 | Similarity threshold for typosquatting detection |
policy.typosquat_mode | BOMLY_TYPOSQUAT_MODE | string | warn | Typosquatting policy mode: warn or fail |
policy.warn_only | BOMLY_WARN_ONLY | bool | - | Downgrade failing findings to warnings |
policy.baseline | BOMLY_BASELINE | string | auto | Finding baseline selection: auto, none, or a file path |
components.analyzers | BOMLY_ANALYZERS | string | - | Reachability analyzer selectors; supports +name and -name modifiers |
output.format | BOMLY_FORMAT | string | - | Primary output format: text, json, markdown, sarif, spdx, or cyclonedx. SBOM formats are scan-only |
output.outputs | BOMLY_OUTPUT | []string | - | Additional output target(s) as |
output.interactive | BOMLY_INTERACTIVE | bool | - | Enable interactive TUI mode |
components.ecosystems | BOMLY_ECOSYSTEMS | string | - | Ecosystem selectors; supports +name and -name modifiers |
components.detectors | BOMLY_DETECTORS | string | - | Detector selectors; supports +name and -name modifiers |
components.auditors | BOMLY_AUDITORS | string | - | Auditor selectors; supports +name and -name modifiers |
components.matchers | BOMLY_MATCHERS | string | - | Matcher selectors; supports +name and -name modifiers |
pipeline.install_first | BOMLY_INSTALL_FIRST | bool | - | Run detector-specific dependency installation before resolving graphs |
pipeline.install_args | BOMLY_INSTALL_ARGS | []string | - | Additional detector-specific install arguments |
logging.quiet | BOMLY_QUIET | bool | - | Suppress all non-error output |
logging.verbosity | BOMLY_VERBOSE | int | - | Verbosity level (0=normal, 1=verbose, 2+=debug) |
network.proxy.url | BOMLY_HTTP_PROXY | string | - | Outbound HTTP proxy URL; when set, it replaces standard HTTP_PROXY/HTTPS_PROXY URLs |
network.proxy.no_proxy | BOMLY_HTTP_NO_PROXY | string | - | Hosts, domains, or CIDRs added to the standard NO_PROXY/no_proxy bypass list |
network.proxy.type | BOMLY_HTTP_PROXY_TYPE | string | http | Outbound proxy type when using host/port proxy settings: http, https, or socks5 |
network.proxy.host | BOMLY_HTTP_PROXY_HOST | string | - | Outbound proxy hostname or IP address used when http_proxy is not set |
network.proxy.port | BOMLY_HTTP_PROXY_PORT | int | - | Outbound proxy port used with http_proxy_host |
network.proxy.username | BOMLY_HTTP_PROXY_USERNAME | string | - | Username for proxy authentication when using host/port proxy settings |
network.proxy.password | BOMLY_HTTP_PROXY_PASSWORD | string | - | Password for proxy authentication when using host/port proxy settings |
network.ca_cert_file | BOMLY_HTTP_CA_CERT_FILE | string | - | PEM certificate chain file to trust for outbound HTTPS connections, including TLS-intercepting proxies |
plugins | - | map[string]map[string]any | - | Per-plugin configuration keyed by managed plugin ID |
OSV matcher settings
| YAML Key | Environment Variable | Type | Default | Description |
|---|---|---|---|---|
matchers.osv.api_base | BOMLY_OSV_API_BASE | string | https://api.osv.dev | Base URL for the OSV vulnerability API |
matchers.osv.cache_dir | BOMLY_OSV_CACHE_DIR | string | - | Directory for the OSV response cache |
matchers.osv.cache_ttl | BOMLY_OSV_CACHE_TTL | string | 24h | TTL for cached OSV responses (e.g. 24h) |
KEV enrichment settings
| YAML Key | Environment Variable | Type | Default | Description |
|---|---|---|---|---|
matchers.osv.kev.cache_dir | BOMLY_KEV_CACHE_DIR | string | - | Directory for the CISA KEV cache |
matchers.osv.kev.cache_ttl | BOMLY_KEV_CACHE_TTL | string | 24h | TTL for cached KEV data (e.g. 24h) |
Scorecard matcher settings
| YAML Key | Environment Variable | Type | Default | Description |
|---|---|---|---|---|
matchers.scorecard.api_base | BOMLY_SCORECARD_API_BASE | string | https://api.scorecard.dev | Base URL for the OpenSSF Scorecard public API |
matchers.scorecard.cache_dir | BOMLY_SCORECARD_CACHE_DIR | string | - | Directory for the Scorecard response cache |
matchers.scorecard.cache_ttl | BOMLY_SCORECARD_CACHE_TTL | string | 24h | TTL for cached Scorecard responses (e.g. 24h) |
Flat YAML Migration
Flat YAML keys are no longer accepted. Move each existing key to its nested replacement:
| Former Flat Key | Replacement |
|---|---|
allow_licenses | policy.allow_licenses |
allow_vulnerability_ids | policy.allow_vulnerability_ids |
analyze | pipeline.analyze |
analyzers | components.analyzers |
audit | pipeline.audit |
auditors | components.auditors |
baseline | policy.baseline |
config | --config |
container | target.container |
deny_groups | policy.deny_groups |
deny_licenses | policy.deny_licenses |
deny_packages | policy.deny_packages |
detectors | components.detectors |
ecosystems | components.ecosystems |
enrich | pipeline.enrich |
exclude | target.exclude |
fail_on | policy.fail_on |
format | output.format |
http_ca_cert_file | network.ca_cert_file |
http_no_proxy | network.proxy.no_proxy |
http_proxy | network.proxy.url |
http_proxy_host | network.proxy.host |
http_proxy_password | network.proxy.password |
http_proxy_port | network.proxy.port |
http_proxy_type | network.proxy.type |
http_proxy_username | network.proxy.username |
image | target.image |
install_args | pipeline.install_args |
install_first | pipeline.install_first |
interactive | output.interactive |
kev_cache_dir | matchers.osv.kev.cache_dir |
kev_cache_ttl | matchers.osv.kev.cache_ttl |
license_exempt_packages | policy.license_exempt_packages |
matchers | components.matchers |
max_depth | target.max_depth |
osv_api_base | matchers.osv.api_base |
osv_cache_dir | matchers.osv.cache_dir |
osv_cache_ttl | matchers.osv.cache_ttl |
outputs | output.outputs |
path | target.path |
protected_packages | policy.protected_packages |
quiet | logging.quiet |
recursive | target.recursive |
ref | target.ref |
sbom | target.sbom |
scorecard_api_base | matchers.scorecard.api_base |
scorecard_cache_dir | matchers.scorecard.cache_dir |
scorecard_cache_ttl | matchers.scorecard.cache_ttl |
typosquat_mode | policy.typosquat_mode |
typosquat_threshold | policy.typosquat_threshold |
url | target.url |
verbose | logging.verbosity |
verbosity | logging.verbosity |
warn_only | policy.warn_only |
Example Configuration
# ~/.bomly/config.yaml, or a trusted file selected with --config
# target:
# Filesystem path to scan
# path: ""
# Container image to scan (e.g. alpine:latest)
# image: ""
# Remote Git URL to clone and scan
# url: ""
# Git ref to checkout when scanning a URL
# ref: ""
# Treat the selected filesystem target as an SBOM file
# sbom: false
# Recursively discover nested manifests under the scan root
# recursive: false
# Maximum directory depth for recursive discovery, counted from the scan root (0 = unlimited)
# max_depth: 3
# Glob pattern(s) relative to the scan root excluded from recursive discovery, in addition to built-in ignore rules; requires recursive
# exclude: []
# pipeline:
# Enrich packages with external license and vulnerability data
# enrich: false
# Evaluate policy and create findings from package vulnerability data
# audit: false
# Run code analysis to confirm whether vulnerabilities are reachable from application code
# analyze: false
# Run detector-specific dependency installation before resolving graphs
# install_first: false
# Additional detector-specific install arguments
# install_args: []
# components:
# Ecosystem selectors; supports +name and -name modifiers
# ecosystems: ""
# Detector selectors; supports +name and -name modifiers
# detectors: ""
# Auditor selectors; supports +name and -name modifiers
# auditors: ""
# Matcher selectors; supports +name and -name modifiers
# matchers: ""
# Reachability analyzer selectors; supports +name and -name modifiers
# analyzers: ""
# policy:
# Constraint(s) for which findings should fail. Repeatable. Vulnerability constraints are AND-ed. Values: any|low|medium|high|critical|reachable|exploitable; diff-only package changes: source-change
# fail_on: []
# Vulnerability IDs to ignore during policy evaluation
# allow_vulnerability_ids: []
# Allowed SPDX license identifiers or expressions
# allow_licenses: []
# Denied SPDX license identifiers or expressions
# deny_licenses: []
# Package URLs exempt from license policy checks
# license_exempt_packages: []
# Package URLs to deny
# deny_packages: []
# Package URL namespaces to deny
# deny_groups: []
# Canonical package names to protect from typosquatting
# protected_packages: []
# Similarity threshold for typosquatting detection
# typosquat_threshold: 0.90
# Typosquatting policy mode: warn or fail
# typosquat_mode: warn
# Downgrade failing findings to warnings
# warn_only: false
# Finding baseline selection: auto, none, or a file path
# baseline: auto
# output:
# Primary output format: text, json, markdown, sarif, spdx, or cyclonedx. SBOM formats are scan-only
# format: ""
# Additional output target(s) as <format> or <format>=<path>. Repeatable; supports text, json, markdown, sarif, spdx, and cyclonedx
# outputs: []
# Enable interactive TUI mode
# interactive: false
# logging:
# Suppress all non-error output
# quiet: false
# Verbosity level (0=normal, 1=verbose, 2+=debug)
# verbosity: 0
# network:
# proxy:
# Outbound HTTP proxy URL; when set, it replaces standard HTTP_PROXY/HTTPS_PROXY URLs
# url: ""
# Hosts, domains, or CIDRs added to the standard NO_PROXY/no_proxy bypass list
# no_proxy: ""
# Outbound proxy type when using host/port proxy settings: http, https, or socks5
# type: http
# Outbound proxy hostname or IP address used when http_proxy is not set
# host: ""
# Outbound proxy port used with http_proxy_host
# port: 0
# Username for proxy authentication when using host/port proxy settings
# username: ""
# Password for proxy authentication when using host/port proxy settings
# password: ""
# PEM certificate chain file to trust for outbound HTTPS connections, including TLS-intercepting proxies
# ca_cert_file: ""
# matchers:
# osv:
# Base URL for the OSV vulnerability API
# api_base: https://api.osv.dev
# Directory for the OSV response cache
# cache_dir: ""
# TTL for cached OSV responses (e.g. 24h)
# cache_ttl: 24h
# kev:
# Directory for the CISA KEV cache
# cache_dir: ""
# TTL for cached KEV data (e.g. 24h)
# cache_ttl: 24h
# scorecard:
# Base URL for the OpenSSF Scorecard public API
# api_base: https://api.scorecard.dev
# Directory for the Scorecard response cache
# cache_dir: ""
# TTL for cached Scorecard responses (e.g. 24h)
# cache_ttl: 24h
# Per-plugin configuration keyed by managed plugin ID
# plugins: {}