mod sbom¶
- module sbom¶
Planned CycloneDX 1.5 SBOM from a stack lock (pre-install inventory).
Built with the official
cyclonedx_bomcrate (same models ascargo-cyclonedx/ CycloneDX Rust Cargo). Documents are serialized as JSON 1.5 with serial numbers, tool metadata, lifecycle phase, and declared dependency edges — not a post-build compliance scan.Functions
- fn artifact_facts_for_lock(lock: &StackLock) -> HashMap<String, ArtifactFacts>¶
Read the easyconfigs a lock names, for the facts only they carry.
This is the one place the module touches the filesystem, and it earns it: a lock records which easyconfig was selected, and the checksums and source URLs that make the document verifiable live in that file rather than in the lock. A path that cannot be read or parsed contributes nothing rather than failing the document, since an SBOM missing one component’s hashes is worth more than no SBOM, and the count of what was read is reported to the caller.
- fn build_dep_map_from_universe(lock: &StackLock, universe: &Universe) -> HashMap<String, Vec<String>>¶
Build dep map name -> build-time dependency names (
builddependencies) from universe candidates matching the lock.
- fn closure_edges_for_lock(lock: &StackLock, lock_file: &Path) -> HashMap<String, Vec<String>>¶
Runtime and build edges for every locked module, keyed by lock identity.
Each tuple is resolved with
resolve_locked_dep, the same walk the SBOM uses, so a build list ordered on this map puts every dependency before the module that needs it and keeps two versions of one name. A bare tuple still contributes: the walk inherits the parent toolchain, so the list waits for the selected module rather than every package that shares the name. An unreadable recipe contributes no edges.lock_fileis the path the lock was written to; relative recipe paths resolve the waylock_to_cyclonedx_from_recipesresolves them.This is what
stack solveuses for--build-list-outand--jenkins-build-list-out.dep_map_from_universestays for a caller that already holds the universe and has not written the recipes.
- fn dep_map_from_universe(lock: &StackLock, universe: &Universe) -> HashMap<String, Vec<String>>¶
Build dep map name -> runtime dependency names from universe candidates matching the lock. Build-time deps are intentionally omitted here so SBOM
dependsOnedges stay role-specific; usebuild_dep_map_from_universefor the build-time list (same shape, separate map).The solve path does not call this. Its build list reads
closure_edges_for_lockfrom the recipes the lock names. This function stays for a caller that holds the universe in memory and has no recipe files to read, which is how the JSON fixture tests build a name map.
- fn dep_maps_for_lock(lock: &StackLock) -> (HashMap<String, Vec<String>>, HashMap<String, Vec<String>>)¶
Runtime and build-time dependency maps read from the easyconfigs a lock names, keeping only dependencies that are themselves in the lock.
A lock records what was chosen, not why; the edges live in the recipes. A solve has them in memory, but an SBOM written later from the lock alone would otherwise carry no
dependsOnat all. Unreadable paths contribute no edges, as inartifact_facts_for_lock.
- fn host_build_environment() -> BTreeMap<String, String>¶
Build-environment metadata from the current host for SBOM/test qualification.
- fn lock_to_bom(lock: &StackLock, runtime_dep_map: Option<&HashMap<String, Vec<String>>>, build_dep_map: Option<&HashMap<String, Vec<String>>>) -> Bom¶
Typed CycloneDX BOM (1.5 models) — preferred when callers want validation.
- fn lock_to_bom_with_facts(lock: &StackLock, facts: SbomFacts<'_>) -> Bom¶
Build the BOM from a lock plus whatever else the caller knows.
Everything beyond the lock is optional, and what is absent is left absent rather than guessed: a component with no stated checksum carries no
hashes, and a plan with nothing unresolved is the only one that claimscomplete.
- fn lock_to_cyclonedx(lock: &StackLock) -> Value¶
Build a CycloneDX JSON document from a lock only (no dependency map).
Without declared edges each component gets an empty
dependsOnlist — never all-to-all co-stack edges (those create invalid cyclic BOMs).
- fn lock_to_cyclonedx_from_recipes(lock: &StackLock, lock_file: &Path) -> (Value, SbomReadStats)¶
CycloneDX for a lock, reading edges and checksums from its easyconfigs.
lock_fileis the path the lock was read from. Relative recipe paths resolve throughresolve_lock_easyconfig. The host optarch, CPU model, and architecture are recorded on the formulation so a generic-optarch document is not mistaken for a native one.
- fn lock_to_cyclonedx_with_deps(lock: &StackLock, selected_dep_map: Option<&HashMap<String, Vec<String>>>) -> Value¶
Preferred: when the selected candidates (or full universe selection map) are known, emit dependsOn from each package’s declared EasyBuild-style dependency list intersected with co-selected lock members. When
selected_dep_mapisNone, each package’sdependsOnis empty (unknown), not all-to-all.
- fn lock_to_cyclonedx_with_facts(lock: &StackLock, facts: SbomFacts<'_>) -> Value¶
JSON document from a lock plus caller-supplied facts.
- fn lock_to_cyclonedx_with_runtime_and_build(lock: &StackLock, runtime_dep_map: Option<&HashMap<String, Vec<String>>>, build_dep_map: Option<&HashMap<String, Vec<String>>>) -> Value¶
Like
lock_to_cyclonedx_with_deps, also records build-time edges as a component property (eb_stack:buildDependsOn) while runtime edges fill the CycloneDXdependenciesgraph.
- fn resolve_lock_easyconfig(lock_dir: &Path, easyconfig_path: &str) -> PathBuf¶
Where a lock’s
easyconfig_pathis on disk.An absolute path is used as written. A relative path is the file next to the lock when that file exists, and otherwise the path against the process directory. A solve run from the repository root still finds
fixtures/...paths; a laterstack sbomwhose working directory is elsewhere still finds paths stored relative to the lock.
- fn solved_dependency_dot(lock: &StackLock, lock_file: &Path) -> String¶
Graphviz DOT for the dependency DAG of a solved lock.
A node is
name/versionplus the toolchain, and the versionsuffix when the selected recipe has one. An edge points from a package to a dependency it selected. The label is the requirement as the solver read it, plus a versionsuffix or an explicit toolchain when the tuple carries one. A builddependency that is not also a runtime dependency is dashed.Edges come from the easyconfigs the lock names, the same walk as
closure_edges_for_lock. A dependency the lock did not select is left out. Node order is the lock’s package order made deterministic by name, version, versionsuffix, and toolchain.
- fn write_solved_dependency_graph(lock: &StackLock, lock_file: &Path, out: &Path) -> Result<(), String>¶
Write the solved dependency DAG.
.svgand.pngare rendered with the Graphvizdotprogram. Any other suffix, including.dot, is the DOT source.
Structs and Unions
- struct ArtifactFacts¶
What an easyconfig states about the artifact one component builds from.
A lock records a selection, not an artifact. These are the fields that make the difference between an inventory and a document someone can verify: which bytes were expected, and where they were fetched from.
- checksums: Vec<String>¶
Checksums the easyconfig states, in the order it states them. Only 64-character hex values are emitted as SHA-256; anything else is carried as a property rather than asserted as a hash of the wrong kind.
- source_urls: Vec<String>¶
Source URLs the easyconfig downloads from.
- patches: Vec<String>¶
Patch filenames applied on top of the source.
- struct SbomFacts<'a>¶
Everything a caller can tell the SBOM builder beyond the lock itself.
Grouped into one struct so the builder keeps a single entry point as more of the spec is filled in, rather than growing another positional argument per field.
- runtime_dep_map: Option<&'a HashMap<String, Vec<String>>>¶
Runtime edges, which become the
dependenciesgraph. Keyed by lock identity. A map keyed by package name still works when that name occurs once in the lock.
- build_dep_map: Option<&'a HashMap<String, Vec<String>>>¶
Build edges, kept as a property because CycloneDX
dependenciesdoes not distinguish build from runtime in 1.5. Same key asSelf::runtime_dep_map.
- artifacts: Option<&'a HashMap<String, ArtifactFacts>>¶
Per-package artifact facts. Keyed by lock identity, or by package name when the lock carries one version of that name.
- unresolved: Option<&'a [String]>¶
Requirements the plan could not resolve. Their presence is what makes the document’s
compositionssayincompleterather thancomplete.
- input_hashes: Option<&'a HashMap<String, String>>¶
Input hash per package name, from
crate::input_hash. Used as theuidof the task that builds it, which is what CycloneDX means by a unique identifier for a resource instance: two plans producing the same hash describe the same build.
- build_environment: Option<&'a BTreeMap<String, String>>¶
The build environment the plan targets: optimisation flags, compute capabilities, the EasyBuild version. A build is reproducible only against a stated environment, since the same recipe compiled with different flags is a different binary, and an SBOM that omits it describes something nobody can reproduce (doi:10.1109/ms.2021.3073045).