Documentation
¶
Overview ¶
Package config defines Bomly's resolved CLI configuration shape.
The Resolved struct is the canonical declaration of every runtime config value and environment override. The nested File structs declare YAML paths. Resolved tag conventions:
- `doc:"..."` — human-readable description (rendered in docs/CONFIG_REFERENCE.md)
- `env:"..."` — environment variable that sets the field
- `default:"..."` — default value when neither config nor flag is set
The configref / schemajson / schemadocs generators (under internal/support/cmd/) parse this file's source to produce the published reference docs. If you change the path of this file, update those generators.
CLI-level orchestration (flag binding, env merging, YAML loading, validation) remains in package cli — this package only owns the schema and the file shape consumed by it.
Index ¶
- Constants
- func ApplyDefaults(cfg *Resolved)
- func ApplyEnvOverrides(dst *Resolved)
- func ApplyFileConfig(dst *Resolved, src File)
- func LegacyMigrationPaths() map[string]string
- func ResolvedSource() []byte
- func SchemaKey(kind, name string) string
- func UserConfigPath() (string, error)
- func Validate(cfg Resolved) error
- func ValidatePluginConfigs(cfg Resolved, catalog PluginCatalog) []string
- func YAMLPathsByResolvedField() map[string]string
- type ComponentsFile
- type FailOnList
- type File
- type KEVFile
- type LoggingFile
- type MatchersFile
- type NetworkFile
- type OSVMatcherFile
- type OutputFile
- type PipelineFile
- type PluginCatalog
- type PluginConfigs
- type PluginsFile
- type PolicyFile
- type ProxyFile
- type Resolved
- type ScorecardMatcherFile
- type TargetFile
Constants ¶
const ( PluginKindDetector = "detector" PluginKindMatcher = "matcher" PluginKindAuditor = "auditor" PluginKindAnalyzer = "analyzer" )
Plugin component kind keys used by the kind-scoped plugins configuration.
Variables ¶
This section is empty.
Functions ¶
func ApplyDefaults ¶
func ApplyDefaults(cfg *Resolved)
ApplyDefaults fills in zero-value fields with their documented defaults, driven by the `default` struct tags on Resolved.
func ApplyEnvOverrides ¶
func ApplyEnvOverrides(dst *Resolved)
ApplyEnvOverrides reads the environment variables named in Resolved's env struct tags and overwrites the corresponding dst fields.
func ApplyFileConfig ¶
ApplyFileConfig merges explicitly set src leaves into dst.
func LegacyMigrationPaths ¶
LegacyMigrationPaths returns former flat YAML keys and their replacements.
func ResolvedSource ¶ added in v0.22.0
func ResolvedSource() []byte
ResolvedSource returns the embedded source of config.go, the file that declares the Resolved configuration schema.
func UserConfigPath ¶
UserConfigPath returns the path to the user-level config file (~/.bomly/config.yaml). Returns an empty string (no error) when the home directory cannot be determined.
func ValidatePluginConfigs ¶ added in v0.22.0
func ValidatePluginConfigs(cfg Resolved, catalog PluginCatalog) []string
ValidatePluginConfigs returns warning messages (never errors) for the resolved plugins configuration: deprecated legacy flat blocks, blocks that name no known component, and blocks with keys the component's advertised config schema rejects.
func YAMLPathsByResolvedField ¶
YAMLPathsByResolvedField returns nested YAML paths keyed by flat runtime field.
Types ¶
type ComponentsFile ¶
type ComponentsFile struct {
Ecosystems *string `yaml:"ecosystems,omitempty" resolved:"Ecosystems" legacy:"ecosystems"`
Detectors *string `yaml:"detectors,omitempty" resolved:"Detectors" legacy:"detectors"`
Auditors *string `yaml:"auditors,omitempty" resolved:"Auditors" legacy:"auditors"`
Matchers *string `yaml:"matchers,omitempty" resolved:"Matchers" legacy:"matchers"`
Analyzers *string `yaml:"analyzers,omitempty" resolved:"Analyzers" legacy:"analyzers"`
}
ComponentsFile configures component selection.
type FailOnList ¶
type FailOnList []string
FailOnList is the YAML shape for fail_on values. It accepts either a single scalar string ("policy.fail_on: low") for backward compatibility with the historical single-value form, or a sequence of strings ("policy.fail_on: [low, reachable]") for the repeatable form. Both shapes normalize to []string.
func (*FailOnList) UnmarshalYAML ¶
func (l *FailOnList) UnmarshalYAML(node *yaml.Node) error
UnmarshalYAML implements yaml.Unmarshaler so existing single-string configs continue to parse alongside the new sequence form.
type File ¶
type File struct {
Target TargetFile `yaml:"target,omitempty"`
Pipeline PipelineFile `yaml:"pipeline,omitempty"`
Components ComponentsFile `yaml:"components,omitempty"`
Policy PolicyFile `yaml:"policy,omitempty"`
Output OutputFile `yaml:"output,omitempty"`
Logging LoggingFile `yaml:"logging,omitempty"`
Network NetworkFile `yaml:"network,omitempty"`
Matchers MatchersFile `yaml:"matchers,omitempty"`
Plugins PluginsFile `yaml:"plugins,omitempty" resolved:"Plugins"`
}
File is the nested YAML-deserialized shape of a Bomly config file. Leaf fields use pointers so merging can distinguish "field absent" from "field explicitly set to its zero value". The resolved tags map YAML leaves back to the flat runtime configuration, while legacy tags drive migration errors and generated documentation for the former flat YAML keys.
type KEVFile ¶
type KEVFile struct {
CacheDir *string `yaml:"cache_dir,omitempty" resolved:"KEVCacheDir" legacy:"kev_cache_dir"`
CacheTTL *string `yaml:"cache_ttl,omitempty" resolved:"KEVCacheTTL" legacy:"kev_cache_ttl"`
}
KEVFile configures CISA Known Exploited Vulnerabilities enrichment.
type LoggingFile ¶
type LoggingFile struct {
Quiet *bool `yaml:"quiet,omitempty" resolved:"Quiet" legacy:"quiet"`
Verbosity *int `yaml:"verbosity,omitempty" resolved:"Verbosity" legacy:"verbosity"`
}
LoggingFile configures CLI logging.
type MatchersFile ¶
type MatchersFile struct {
OSV OSVMatcherFile `yaml:"osv,omitempty"`
Scorecard ScorecardMatcherFile `yaml:"scorecard,omitempty"`
}
MatchersFile configures built-in enrichment matchers.
type NetworkFile ¶
type NetworkFile struct {
Proxy ProxyFile `yaml:"proxy,omitempty"`
CACertFile *string `yaml:"ca_cert_file,omitempty" resolved:"HTTPCACertFile" legacy:"http_ca_cert_file"`
}
NetworkFile configures outbound network behavior.
type OSVMatcherFile ¶
type OSVMatcherFile struct {
APIBase *string `yaml:"api_base,omitempty" resolved:"OsvAPIBase" legacy:"osv_api_base"`
CacheDir *string `yaml:"cache_dir,omitempty" resolved:"OsvCacheDir" legacy:"osv_cache_dir"`
CacheTTL *string `yaml:"cache_ttl,omitempty" resolved:"OsvCacheTTL" legacy:"osv_cache_ttl"`
KEV KEVFile `yaml:"kev,omitempty"`
}
OSVMatcherFile configures OSV vulnerability enrichment.
type OutputFile ¶
type OutputFile struct {
Format *string `yaml:"format,omitempty" resolved:"Format" legacy:"format"`
Outputs *[]string `yaml:"outputs,omitempty" resolved:"Outputs" legacy:"outputs"`
Interactive *bool `yaml:"interactive,omitempty" resolved:"Interactive" legacy:"interactive"`
}
OutputFile configures report rendering.
type PipelineFile ¶
type PipelineFile struct {
Enrich *bool `yaml:"enrich,omitempty" resolved:"Enrich" legacy:"enrich"`
Audit *bool `yaml:"audit,omitempty" resolved:"Audit" legacy:"audit"`
Analyze *bool `yaml:"analyze,omitempty" resolved:"Analyze" legacy:"analyze"`
InstallFirst *bool `yaml:"install_first,omitempty" resolved:"InstallFirst" legacy:"install_first"`
InstallArgs *[]string `yaml:"install_args,omitempty" resolved:"InstallArgs" legacy:"install_args"`
}
PipelineFile configures optional pipeline behavior and dependency preparation.
type PluginCatalog ¶ added in v0.22.0
type PluginCatalog struct {
Components map[string][]string
Schemas map[string]json.RawMessage
}
PluginCatalog describes the known component universe used to validate `plugins:` configuration blocks. Components maps a component kind (PluginKindDetector, ...) to known component names, including aliases and installed plugin IDs. Schemas maps "<kind>/<name>" to the component's advertised JSON config schema.
type PluginConfigs ¶ added in v0.22.0
type PluginConfigs struct {
Detectors map[string]map[string]any
Matchers map[string]map[string]any
Auditors map[string]map[string]any
Analyzers map[string]map[string]any
Legacy map[string]map[string]any
}
PluginConfigs is the resolved, kind-scoped plugin configuration. Legacy holds deprecated flat `plugins.<id>` blocks, which apply to whichever component name matches, regardless of kind.
func (PluginConfigs) ForComponent ¶ added in v0.22.0
func (p PluginConfigs) ForComponent(kind, name string) map[string]any
ForComponent returns the configuration block for a (kind, name) pair. Kind-scoped blocks win; legacy flat blocks apply to any kind for compatibility. Returns nil when no block is configured.
func (PluginConfigs) ForPlugin ¶ added in v0.22.0
func (p PluginConfigs) ForPlugin(name string) map[string]any
ForPlugin returns the configuration block for a component name across all kinds. Managed plugin IDs are unique across the install database, so a launch-time lookup without the kind is unambiguous in practice.
func (PluginConfigs) IsEmpty ¶ added in v0.22.0
func (p PluginConfigs) IsEmpty() bool
IsEmpty reports whether no plugin configuration blocks are present.
type PluginsFile ¶ added in v0.22.0
type PluginsFile struct {
Detectors map[string]map[string]any `yaml:"detectors,omitempty"`
Matchers map[string]map[string]any `yaml:"matchers,omitempty"`
Auditors map[string]map[string]any `yaml:"auditors,omitempty"`
Analyzers map[string]map[string]any `yaml:"analyzers,omitempty"`
Legacy map[string]map[string]any `yaml:"-"`
}
PluginsFile is the YAML shape of the `plugins:` block. The canonical form scopes component blocks by kind:
plugins:
detectors: { <name>: {...} }
matchers: { <name>: {...} }
auditors: { <name>: {...} }
analyzers: { <name>: {...} }
The deprecated flat form `plugins.<id>: {...}` keeps working: unknown top-level keys are collected into Legacy and reported as deprecated by ValidatePluginConfigs.
func (PluginsFile) IsEmpty ¶ added in v0.22.0
func (f PluginsFile) IsEmpty() bool
IsEmpty reports whether the file block declares no plugin configuration.
func (*PluginsFile) UnmarshalYAML ¶ added in v0.22.0
func (f *PluginsFile) UnmarshalYAML(value *yaml.Node) error
UnmarshalYAML decodes the plugins block, accepting both the kind-scoped canonical shape and legacy flat `plugins.<id>` entries.
type PolicyFile ¶
type PolicyFile struct {
FailOn *FailOnList `yaml:"fail_on,omitempty" resolved:"FailOn" legacy:"fail_on"`
AllowVulnerabilityIDs *[]string `yaml:"allow_vulnerability_ids,omitempty" resolved:"AllowVulnerabilityIDs" legacy:"allow_vulnerability_ids"`
AllowLicenses *[]string `yaml:"allow_licenses,omitempty" resolved:"AllowLicenses" legacy:"allow_licenses"`
DenyLicenses *[]string `yaml:"deny_licenses,omitempty" resolved:"DenyLicenses" legacy:"deny_licenses"`
LicenseExemptPackages *[]string `yaml:"license_exempt_packages,omitempty" resolved:"LicenseExemptPackages" legacy:"license_exempt_packages"`
DenyPackages *[]string `yaml:"deny_packages,omitempty" resolved:"DenyPackages" legacy:"deny_packages"`
DenyGroups *[]string `yaml:"deny_groups,omitempty" resolved:"DenyGroups" legacy:"deny_groups"`
ProtectedPackages *[]string `yaml:"protected_packages,omitempty" resolved:"ProtectedPackages" legacy:"protected_packages"`
TyposquatThreshold *string `yaml:"typosquat_threshold,omitempty" resolved:"TyposquatThreshold" legacy:"typosquat_threshold"`
TyposquatMode *string `yaml:"typosquat_mode,omitempty" resolved:"TyposquatMode" legacy:"typosquat_mode"`
WarnOnly *bool `yaml:"warn_only,omitempty" resolved:"WarnOnly" legacy:"warn_only"`
Baseline *string `yaml:"baseline,omitempty" resolved:"Baseline" legacy:"baseline"`
}
PolicyFile configures audit policy evaluation.
type ProxyFile ¶
type ProxyFile struct {
URL *string `yaml:"url,omitempty" resolved:"HTTPProxy" legacy:"http_proxy"`
NoProxy *string `yaml:"no_proxy,omitempty" resolved:"HTTPNoProxy" legacy:"http_no_proxy"`
Type *string `yaml:"type,omitempty" resolved:"HTTPProxyType" legacy:"http_proxy_type"`
Host *string `yaml:"host,omitempty" resolved:"HTTPProxyHost" legacy:"http_proxy_host"`
Port *int `yaml:"port,omitempty" resolved:"HTTPProxyPort" legacy:"http_proxy_port"`
Username *string `yaml:"username,omitempty" resolved:"HTTPProxyUsername" legacy:"http_proxy_username"`
Password *string `yaml:"password,omitempty" resolved:"HTTPProxyPassword" legacy:"http_proxy_password"`
}
ProxyFile configures the explicit outbound proxy.
type Resolved ¶
type Resolved struct {
Path string `doc:"Filesystem path to scan" env:"BOMLY_PATH"`
Image string `doc:"Container image to scan (e.g. alpine:latest)" env:"BOMLY_IMAGE" envalias:"BOMLY_CONTAINER"`
URL string `doc:"Remote Git URL to clone and scan" env:"BOMLY_URL"`
Ref string `doc:"Git ref to checkout when scanning a URL" env:"BOMLY_REF"`
SBOM bool `doc:"Treat the selected filesystem target as an SBOM file" env:"BOMLY_SBOM"`
Recursive bool `doc:"Recursively discover nested manifests under the scan root" env:"BOMLY_RECURSIVE"`
MaxDepth int `` /* 131-byte string literal not displayed */
ExcludePaths []string `` /* 159-byte string literal not displayed */
Enrich bool `doc:"Enrich packages with external license and vulnerability data" env:"BOMLY_ENRICH"`
Audit bool `doc:"Evaluate policy and create findings from package vulnerability data" env:"BOMLY_AUDIT"`
Analyze bool `doc:"Run code analysis to confirm whether vulnerabilities are reachable from application code" env:"BOMLY_ANALYZE"`
FailOn []string `` /* 222-byte string literal not displayed */
AllowVulnerabilityIDs []string `doc:"Vulnerability IDs to ignore during policy evaluation" env:"BOMLY_ALLOW_VULNERABILITY_IDS"`
AllowLicenses []string `doc:"Allowed SPDX license identifiers or expressions" env:"BOMLY_ALLOW_LICENSES"`
DenyLicenses []string `doc:"Denied SPDX license identifiers or expressions" env:"BOMLY_DENY_LICENSES"`
LicenseExemptPackages []string `doc:"Package URLs exempt from license policy checks" env:"BOMLY_LICENSE_EXEMPT_PACKAGES"`
DenyPackages []string `doc:"Package URLs to deny" env:"BOMLY_DENY_PACKAGES"`
DenyGroups []string `doc:"Package URL namespaces to deny" env:"BOMLY_DENY_GROUPS"`
ProtectedPackages []string `doc:"Canonical package names to protect from typosquatting" env:"BOMLY_PROTECTED_PACKAGES"`
TyposquatThreshold string `doc:"Similarity threshold for typosquatting detection" env:"BOMLY_TYPOSQUAT_THRESHOLD" default:"0.90"`
TyposquatMode string `doc:"Typosquatting policy mode: warn or fail" env:"BOMLY_TYPOSQUAT_MODE" default:"warn"`
WarnOnly bool `doc:"Downgrade failing findings to warnings" env:"BOMLY_WARN_ONLY"`
Baseline string `doc:"Finding baseline selection: auto, none, or a file path" env:"BOMLY_BASELINE" default:"auto"`
Analyzers string `doc:"Reachability analyzer selectors; supports +name and -name modifiers" env:"BOMLY_ANALYZERS"`
Format string `doc:"Primary output format: text, json, markdown, sarif, spdx, or cyclonedx. SBOM formats are scan-only" env:"BOMLY_FORMAT"`
Outputs []string `` /* 154-byte string literal not displayed */
Interactive bool `doc:"Enable interactive TUI mode" env:"BOMLY_INTERACTIVE"`
Ecosystems string `doc:"Ecosystem selectors; supports +name and -name modifiers" env:"BOMLY_ECOSYSTEMS"`
Detectors string `doc:"Detector selectors; supports +name and -name modifiers" env:"BOMLY_DETECTORS"`
Auditors string `doc:"Auditor selectors; supports +name and -name modifiers" env:"BOMLY_AUDITORS"`
Matchers string `doc:"Matcher selectors; supports +name and -name modifiers" env:"BOMLY_MATCHERS"`
InstallFirst bool `doc:"Run detector-specific dependency installation before resolving graphs" env:"BOMLY_INSTALL_FIRST"`
InstallArgs []string `doc:"Additional detector-specific install arguments" env:"BOMLY_INSTALL_ARGS"`
Config string `doc:"Explicit YAML config file path; repository config files are never loaded automatically" env:"BOMLY_CONFIG"`
Quiet bool `doc:"Suppress all non-error output" env:"BOMLY_QUIET"`
Verbosity int `doc:"Verbosity level (0=normal, 1=verbose, 2+=debug)" env:"BOMLY_VERBOSE"`
LoadedFiles []string
HTTPProxy string `doc:"Outbound HTTP proxy URL; when set, it replaces standard HTTP_PROXY/HTTPS_PROXY URLs" env:"BOMLY_HTTP_PROXY"`
HTTPNoProxy string `doc:"Hosts, domains, or CIDRs added to the standard NO_PROXY/no_proxy bypass list" env:"BOMLY_HTTP_NO_PROXY"`
HTTPProxyType string `` /* 128-byte string literal not displayed */
HTTPProxyHost string `doc:"Outbound proxy hostname or IP address used when http_proxy is not set" env:"BOMLY_HTTP_PROXY_HOST"`
HTTPProxyPort int `doc:"Outbound proxy port used with http_proxy_host" env:"BOMLY_HTTP_PROXY_PORT"`
HTTPProxyUsername string `doc:"Username for proxy authentication when using host/port proxy settings" env:"BOMLY_HTTP_PROXY_USERNAME"`
HTTPProxyPassword string `doc:"Password for proxy authentication when using host/port proxy settings" env:"BOMLY_HTTP_PROXY_PASSWORD"`
HTTPCACertFile string `` /* 138-byte string literal not displayed */
Plugins PluginConfigs `` /* 200-byte string literal not displayed */
// OSV matcher settings
OsvAPIBase string `doc:"Base URL for the OSV vulnerability API" env:"BOMLY_OSV_API_BASE" default:"https://api.osv.dev"`
OsvCacheDir string `doc:"Directory for the OSV response cache" env:"BOMLY_OSV_CACHE_DIR"`
OsvCacheTTL string `doc:"TTL for cached OSV responses (e.g. 24h)" env:"BOMLY_OSV_CACHE_TTL" default:"24h"`
// KEV enrichment settings
KEVCacheDir string `doc:"Directory for the CISA KEV cache" env:"BOMLY_KEV_CACHE_DIR"`
KEVCacheTTL string `doc:"TTL for cached KEV data (e.g. 24h)" env:"BOMLY_KEV_CACHE_TTL" default:"24h"`
// Scorecard matcher settings
ScorecardAPIBase string `doc:"Base URL for the OpenSSF Scorecard public API" env:"BOMLY_SCORECARD_API_BASE" default:"https://api.scorecard.dev"`
ScorecardCacheDir string `doc:"Directory for the Scorecard response cache" env:"BOMLY_SCORECARD_CACHE_DIR"`
ScorecardCacheTTL string `doc:"TTL for cached Scorecard responses (e.g. 24h)" env:"BOMLY_SCORECARD_CACHE_TTL" default:"24h"`
// CoreVersion is the running bomly core version. The CLI populates it at
// startup from the build's version string; it is not user configuration
// and has no flag, environment variable, or YAML key.
CoreVersion string
}
Resolved holds the fully-merged CLI configuration: defaults overridden by the YAML config file, then env vars, then explicit flags.
type ScorecardMatcherFile ¶
type ScorecardMatcherFile struct {
APIBase *string `yaml:"api_base,omitempty" resolved:"ScorecardAPIBase" legacy:"scorecard_api_base"`
CacheDir *string `yaml:"cache_dir,omitempty" resolved:"ScorecardCacheDir" legacy:"scorecard_cache_dir"`
CacheTTL *string `yaml:"cache_ttl,omitempty" resolved:"ScorecardCacheTTL" legacy:"scorecard_cache_ttl"`
}
ScorecardMatcherFile configures OpenSSF Scorecard enrichment.
type TargetFile ¶
type TargetFile struct {
Path *string `yaml:"path,omitempty" resolved:"Path" legacy:"path"`
Container *string `yaml:"container,omitempty" resolved:"Image" legacy:"container"` // deprecated alias for image
Image *string `yaml:"image,omitempty" resolved:"Image" legacy:"image"`
URL *string `yaml:"url,omitempty" resolved:"URL" legacy:"url"`
Ref *string `yaml:"ref,omitempty" resolved:"Ref" legacy:"ref"`
SBOM *bool `yaml:"sbom,omitempty" resolved:"SBOM" legacy:"sbom"`
Recursive *bool `yaml:"recursive,omitempty" resolved:"Recursive" legacy:"recursive"`
MaxDepth *int `yaml:"max_depth,omitempty" resolved:"MaxDepth" legacy:"max_depth"`
Exclude *[]string `yaml:"exclude,omitempty" resolved:"ExcludePaths" legacy:"exclude"`
}
TargetFile configures the execution target selected for a scan.