Documentation
¶
Overview ¶
Package cbom discovers cryptographic usage in a codebase — in source, config, certificates/keys on disk and declared crypto libraries — and maps it to a CycloneDX Cryptography Bill of Materials, classifying each algorithm for post-quantum posture (quantum-safe | quantum-vulnerable | deprecated | hybrid).
All detection is driven by a declarative catalog (internal/cbom/catalog/*.json) so the rules — algorithm aliases, per-language source patterns, config patterns, crypto-library imports and the per-country approval matrix — can be maintained without code changes. The catalog is embedded in the binary and can be extended or overridden at runtime with --catalog.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Detect ¶
func Detect(opts Options) (cdx.CryptoDetections, error)
Detect runs the enabled passes and returns CycloneDX-ready crypto detections.
func Normalize ¶
Normalize folds a cryptographic-algorithm token to a canonical comparison key: lower-cased with every non-alphanumeric character (spaces, '-', '_', '.', '/') removed. This is what makes "SHA256", "Sha256", "sha256" and "SHA_256" all resolve to the same algorithm and be stored under one canonical SPDX name.
Normalize("SHA-256") == "sha256"
Normalize("Sha_256") == "sha256"
Normalize("ML-KEM-768") == "mlkem768"
Types ¶
type AlgorithmDef ¶
type AlgorithmDef struct {
ID string `json:"id"` // canonical SPDX id (override key)
Name string `json:"name"` // canonical stored name
SPDXClass string `json:"spdx_class,omitempty"`
OID string `json:"oid,omitempty"`
Aliases []string `json:"aliases,omitempty"`
Primitive string `json:"primitive,omitempty"` // CycloneDX primitive enum
ParameterSet string `json:"parameter_set,omitempty"`
Curve string `json:"curve,omitempty"`
Mode string `json:"mode,omitempty"` // CycloneDX mode enum
Padding string `json:"padding,omitempty"` // CycloneDX padding enum
CryptoFunctions []string `json:"crypto_functions,omitempty"`
ClassicalSecurityLevel int `json:"classical_security_level,omitempty"`
NISTQuantumLevel int `json:"nist_quantum_security_level,omitempty"`
PQCStatus string `json:"pqc_status,omitempty"`
Standards map[string]string `json:"standards,omitempty"`
SourcePatterns map[string][]string `json:"source_patterns,omitempty"` // language -> patterns
ConfigPatterns []string `json:"config_patterns,omitempty"`
}
AlgorithmDef describes one cryptographic algorithm: how to detect it, its canonical SPDX identity, its CycloneDX algorithmProperties and its PQC posture.
type Catalog ¶
type Catalog struct {
Version string `json:"version"`
Extractors []ExtractorDef `json:"call_extractors,omitempty"`
Algorithms []AlgorithmDef `json:"algorithms"`
Libraries []LibraryDef `json:"libraries"`
}
Catalog is the raw (uncompiled) detection catalog.
func DefaultCatalog ¶
DefaultCatalog loads and merges the embedded catalog/*.json files.
func LoadCatalog ¶
LoadCatalog loads the builtin catalog (unless noBuiltin) and merges an optional override file on top (upsert by id).
func (*Catalog) Compile ¶
func (c *Catalog) Compile() (*CompiledCatalog, error)
Compile validates and compiles every pattern and builds the alias index. It is the single validation gate: an invalid regex, duplicate id, or out-of-enum CycloneDX value fails here.
type CompiledAlgorithm ¶
type CompiledCatalog ¶
type CompiledCatalog struct {
Version string
Algorithms []CompiledAlgorithm
Libraries []CompiledLibrary
Extractors []CompiledExtractor
// contains filtered or unexported fields
}
CompiledCatalog is the catalog with all regexes compiled and the alias index built. It is the single matching surface used by every detection pass.
func (*CompiledCatalog) Lookup ¶
func (c *CompiledCatalog) Lookup(token string) (*CompiledAlgorithm, bool)
Lookup resolves a raw token (e.g. "SHA256", "Sha256", "SHA_256") to its canonical algorithm via the normalized alias index. This is what makes case/separator variants equivalent for detection.
type CompiledExtractor ¶
type CompiledLibrary ¶
type CompiledLibrary struct {
Def LibraryDef
Imports []*regexp.Regexp
}
type ExtractorDef ¶
type ExtractorDef struct {
Languages []string `json:"languages,omitempty"` // empty = any file
Pattern string `json:"pattern"` // one capture group = the token
Role string `json:"role,omitempty"` // algorithm | transform | jwt
}
ExtractorDef captures an algorithm token from a generic crypto-API call. The captured token is normalized and looked up in the alias index, so arbitrary case/separator variants (sha256, SHA-256, SHA_256, …) resolve to one algorithm.
type LibraryDef ¶
type LibraryDef struct {
ID string `json:"id"`
Name string `json:"name"`
Provider string `json:"provider,omitempty"`
Languages []string `json:"languages,omitempty"`
PurlNames map[string]string `json:"purl_names,omitempty"`
ImportPatterns []string `json:"import_patterns,omitempty"`
}
LibraryDef describes a cryptographic library / SDK.
type Options ¶
type Options struct {
Root string
MaxDepth int
Ignore []string
ScanSource bool
ScanConfig bool
ScanCerts bool
ScanDeps bool
IncludeHome bool
Catalog *CompiledCatalog
// RespectGitignore prunes .gitignored paths (default off; the cbom command
// sets it true unless --cbom-include-ignored is passed).
RespectGitignore bool
}
Options controls a CBOM detection run.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Command cbomgen renders the CBOM detection documentation from the single source of truth: the embedded catalog (internal/cbom/catalog/*.json).
|
Command cbomgen renders the CBOM detection documentation from the single source of truth: the embedded catalog (internal/cbom/catalog/*.json). |