reference

Config reference

All config keys, environment variables, and defaults.

Bomly resolves configuration in the following order, with later sources overriding earlier ones:

  1. ~/.bomly/config.yaml
  2. <project>/.bomly/config.yaml
  3. BOMLY_* environment variables
  4. CLI flags

--config <path> adds an explicit config file to the load list before environment variables and flags are applied.

YAML files use the nested keys documented below. Unknown keys and the former flat keys are rejected so configuration mistakes fail fast.


General

YAML KeyEnvironment VariableTypeDefaultDescription
target.pathBOMLY_PATHstring-Filesystem path to scan
target.containerBOMLY_CONTAINERstring-Container image to scan (e.g. alpine:latest)
target.urlBOMLY_URLstring-Remote Git URL to clone and scan
target.refBOMLY_REFstring-Git ref to checkout when scanning a URL
target.sbomBOMLY_SBOMbool-Treat the selected filesystem target as an SBOM file
pipeline.enrichBOMLY_ENRICHbool-Enrich packages with external license and vulnerability data
pipeline.auditBOMLY_AUDITbool-Evaluate policy and create findings from package vulnerability data
pipeline.analyzeBOMLY_ANALYZEbool-Run code analysis to confirm whether vulnerabilities are reachable from application code
policy.fail_onBOMLY_FAIL_ON[]string-Constraint(s) for which findings should be created. Repeatable; AND-ed. Severity: any
policy.allow_vulnerability_idsBOMLY_ALLOW_VULNERABILITY_IDS[]string-Vulnerability IDs to ignore during policy evaluation
policy.allow_licensesBOMLY_ALLOW_LICENSES[]string-Allowed SPDX license identifiers or expressions
policy.deny_licensesBOMLY_DENY_LICENSES[]string-Denied SPDX license identifiers or expressions
policy.license_exempt_packagesBOMLY_LICENSE_EXEMPT_PACKAGES[]string-Package URLs exempt from license policy checks
policy.deny_packagesBOMLY_DENY_PACKAGES[]string-Package URLs to deny
policy.deny_groupsBOMLY_DENY_GROUPS[]string-Package URL namespaces to deny
policy.protected_packagesBOMLY_PROTECTED_PACKAGES[]string-Canonical package names to protect from typosquatting
policy.typosquat_thresholdBOMLY_TYPOSQUAT_THRESHOLDstring0.90Similarity threshold for typosquatting detection
policy.typosquat_modeBOMLY_TYPOSQUAT_MODEstringwarnTyposquatting policy mode: warn or fail
policy.warn_onlyBOMLY_WARN_ONLYbool-Downgrade failing findings to warnings
components.analyzersBOMLY_ANALYZERSstring-Reachability analyzer selectors; supports +name and -name modifiers
output.formatBOMLY_FORMATstring-Primary output format: text, json, markdown, sarif, spdx, or cyclonedx. SBOM formats are scan-only
output.outputsBOMLY_OUTPUT[]string-Additional output target(s) as <format> or <format>=<path>. Repeatable; supports text, json, markdown, sarif, spdx, and cyclonedx
output.interactiveBOMLY_INTERACTIVEbool-Enable interactive TUI mode
components.ecosystemsBOMLY_ECOSYSTEMSstring-Ecosystem selectors; supports +name and -name modifiers
components.detectorsBOMLY_DETECTORSstring-Detector selectors; supports +name and -name modifiers
components.auditorsBOMLY_AUDITORSstring-Auditor selectors; supports +name and -name modifiers
components.matchersBOMLY_MATCHERSstring-Matcher selectors; supports +name and -name modifiers
pipeline.install_firstBOMLY_INSTALL_FIRSTbool-Run detector-specific dependency installation before resolving graphs
pipeline.install_argsBOMLY_INSTALL_ARGS[]string-Additional detector-specific install arguments
logging.quietBOMLY_QUIETbool-Suppress all non-error output
logging.verbosityBOMLY_VERBOSEint-Verbosity level (0=normal, 1=verbose, 2+=debug)
network.proxy.urlBOMLY_HTTP_PROXYstring-Outbound HTTP proxy URL used by Bomly and managed plugins
network.proxy.no_proxyBOMLY_HTTP_NO_PROXYstring-Comma-separated hosts, domains, or CIDRs that should bypass the outbound HTTP proxy
network.proxy.typeBOMLY_HTTP_PROXY_TYPEstringhttpOutbound proxy type when using host/port proxy settings: http, https, or socks5
network.proxy.hostBOMLY_HTTP_PROXY_HOSTstring-Outbound proxy hostname or IP address used when http_proxy is not set
network.proxy.portBOMLY_HTTP_PROXY_PORTint-Outbound proxy port used with http_proxy_host
network.proxy.usernameBOMLY_HTTP_PROXY_USERNAMEstring-Username for proxy authentication when using host/port proxy settings
network.proxy.passwordBOMLY_HTTP_PROXY_PASSWORDstring-Password for proxy authentication when using host/port proxy settings
network.ca_cert_fileBOMLY_HTTP_CA_CERT_FILEstring-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 KeyEnvironment VariableTypeDefaultDescription
matchers.osv.api_baseBOMLY_OSV_API_BASEstringhttps://api.osv.devBase URL for the OSV vulnerability API
matchers.osv.cache_dirBOMLY_OSV_CACHE_DIRstring-Directory for the OSV response cache
matchers.osv.cache_ttlBOMLY_OSV_CACHE_TTLstring24hTTL for cached OSV responses (e.g. 24h)

KEV enrichment settings

YAML KeyEnvironment VariableTypeDefaultDescription
matchers.osv.kev.cache_dirBOMLY_KEV_CACHE_DIRstring-Directory for the CISA KEV cache
matchers.osv.kev.cache_ttlBOMLY_KEV_CACHE_TTLstring24hTTL for cached KEV data (e.g. 24h)

Scorecard matcher settings

YAML KeyEnvironment VariableTypeDefaultDescription
matchers.scorecard.api_baseBOMLY_SCORECARD_API_BASEstringhttps://api.scorecard.devBase URL for the OpenSSF Scorecard public API
matchers.scorecard.cache_dirBOMLY_SCORECARD_CACHE_DIRstring-Directory for the Scorecard response cache
matchers.scorecard.cache_ttlBOMLY_SCORECARD_CACHE_TTLstring24hTTL 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 KeyReplacement
allow_licensespolicy.allow_licenses
allow_vulnerability_idspolicy.allow_vulnerability_ids
analyzepipeline.analyze
analyzerscomponents.analyzers
auditpipeline.audit
auditorscomponents.auditors
config--config
containertarget.container
deny_groupspolicy.deny_groups
deny_licensespolicy.deny_licenses
deny_packagespolicy.deny_packages
detectorscomponents.detectors
ecosystemscomponents.ecosystems
enrichpipeline.enrich
fail_onpolicy.fail_on
formatoutput.format
http_ca_cert_filenetwork.ca_cert_file
http_no_proxynetwork.proxy.no_proxy
http_proxynetwork.proxy.url
http_proxy_hostnetwork.proxy.host
http_proxy_passwordnetwork.proxy.password
http_proxy_portnetwork.proxy.port
http_proxy_typenetwork.proxy.type
http_proxy_usernamenetwork.proxy.username
install_argspipeline.install_args
install_firstpipeline.install_first
interactiveoutput.interactive
kev_cache_dirmatchers.osv.kev.cache_dir
kev_cache_ttlmatchers.osv.kev.cache_ttl
license_exempt_packagespolicy.license_exempt_packages
matcherscomponents.matchers
osv_api_basematchers.osv.api_base
osv_cache_dirmatchers.osv.cache_dir
osv_cache_ttlmatchers.osv.cache_ttl
outputsoutput.outputs
pathtarget.path
protected_packagespolicy.protected_packages
quietlogging.quiet
reftarget.ref
sbomtarget.sbom
scorecard_api_basematchers.scorecard.api_base
scorecard_cache_dirmatchers.scorecard.cache_dir
scorecard_cache_ttlmatchers.scorecard.cache_ttl
typosquat_modepolicy.typosquat_mode
typosquat_thresholdpolicy.typosquat_threshold
urltarget.url
verboselogging.verbosity
verbositylogging.verbosity
warn_onlypolicy.warn_only

Example Configuration

# ~/.bomly/config.yaml or .bomly/config.yaml
# target:
#   Filesystem path to scan
#   path: ""
#   Container image to scan (e.g. alpine:latest)
#   container: ""
#   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
# 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 be created. Repeatable; AND-ed. Severity: any|low|medium|high|critical. Reachability: reachable. Exploitability: exploitable
#   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
# 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 used by Bomly and managed plugins
#     url: ""
#     Comma-separated hosts, domains, or CIDRs that should bypass the outbound HTTP proxy
#     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: {}