Repository navigation
Description
Part of #1774
Problem
APM already produces a lockfile (apm.lock.yaml) with per-file SHA-256 hashes and a content-drift audit. For regulated and security-conscious teams, content hashing alone is not enough: they need a machine-readable bill of materials for what was installed, recorded provenance for where each artifact came from, and - once a signing ecosystem exists - a way to verify who produced an artifact.
What to do (phased, in this order)
- SBOM / inventory export FIRST. Serialize the existing lockfile into a standard format (CycloneDX, optionally SPDX) as a FORMAT on the existing lockfile-export concept:
apm lock export --format cyclonedx. This is an inventory export, not a completeness or security attestation - it reports exactly what the lockfile records (source, resolved commit, hashes), and is honest that license/CVE data is not present unless sourced from each dep's manifest. - Provenance schema SECOND. Formalize the fields the lockfile already records per dependency (resolved_commit, resolved_ref, resolved_url, resolved_at, hashes) into a documented provenance schema. This is re-serialization of data APM already captures - no new capture, and no self-signed attestation (a self-attestation proves nothing to a third-party verifier).
- Signature verification LAST, and deferred. Defer until a real signing ecosystem for agent primitives exists and there is concrete demand (a useful bar: ~5 community requests). When built, APM CONSUMES standard signatures (for example verifying a signed git tag via
git verify-tag); it does NOT build or run signing infrastructure. Surface an informationalverified | unverified | nonestatus; do not gate installs on it until signing is real and a policy key ships together with the enforcement.
How
- New
src/apm_cli/export/package for SBOM/provenance serialization. Do not bolt this onto the already-large commands/audit.py. - Read from lockfile-recorded hashes ONLY; never re-hash the filesystem at export time.
- SBOM output MUST be deterministic: sorted components and a pinned/injected timestamp so the same lockfile yields byte-identical output (golden-file test).
- Component identity: pkg:github/owner/repo@<resolved_commit> for git deps; pkg:generic/@<content_hash> for local.
- For signature verification, extract a verifier behind an interface so it can be tested with a fixture signed repo and a fake verifier (pass / fail / absent), without network and without mocking the security boundary away.
- Each phase ships with tests, docs, and a CHANGELOG entry.
Why
This is the consumer-side assurance layer APM is positioned to own at the package level: with registries emerging as the distribution layer for agent primitives, the inventory/provenance export is what compliance teams will demand, and verification (when it lands) consumes the registry's attestations rather than competing with them. It complements the runtime controls that agent harnesses provide; it does not duplicate them.
Out of scope
Runtime enforcement of any kind. Building or operating signing infrastructure. APM verifies and records at install time; it does not control what a running agent may do.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsDone
Activity
feat(policy): declarable integrity keys (require_hashes, fail_on_drif…
danielmeppiel commentedon Jun 16, 2026
Scope addendum: declared-license dimension (folded into U5/U6)
Folding a license dimension into this issue. APM becomes the declared-license recorder + SBOM passthrough, never a license scanner. This mirrors how npm handles licenses and stays entirely inside the install-and-integrity plane.
The model (mirrors npm exactly)
npm trusts the
licensefield inpackage.json-- an author-declared SPDX expression -- and never parses the LICENSE file text. "Read the text and conclude a license" is the compliance plane (the job of dedicated scanners), out of APM scope. APM does the same: record what the manifest declares, validate its syntax offline, emit it in the SBOM, judge nothing.What ships
declared_licenseto the lockfile entry. Value = SPDX expression as declared by the package manifest atresolved_commit. Syntax-validated offline only (no network, no text scan). Backfilled at resolve time fromapm.ymllicense:(APM packages) orplugin.jsonlicense(ingested plugin manifests -- the parser already reads these and currently drops the field). Undeclared => field omitted from the lockfile.declared_licenseinto the CycloneDXlicenses[]field (and the SPDX-format equivalent). Read the lockfile only -- no re-resolve, no re-hash, no text scan.apm.ymlgains an optional top-levellicense:field (SPDX expression), so even single-file package authors have a place to declare. Pointing a dependency at a lone primitive file is the immature form; this is the ramp up.Not-declared behaviour (the careful part -- three states, npm-faithful)
The hard rule: never collapse "unknown" with "explicitly none."
MIT,(MIT OR Apache-2.0)licenses[].license.id/expressionUNLICENSED,SEE LICENSE IN <file>licenses[].license.name(named, an assertion)license:/ no manifestlicenses[]omitted (SPDX format:NOASSERTION)The three not-declared sub-cases produce the same SBOM output (
NOASSERTION) but differ on the nudge:apm.ymlpresent, nolicense:->NOASSERTION; warn onapm pack/apm publish("No license field; SBOM will record NOASSERTION"). This is the authoring path -- mirror of npm's "No license field" warning.plugin.jsonpresent, nolicense->NOASSERTION; silent (foreign manifest you do not author; you cannot fix it).NOASSERTION; silent at install. You cannot infer a license from a lone file; theapm.yml license:field is the way up.Asymmetry (npm-faithful): warn only on the authoring path (your own
apm.yml); stay silent on the consuming path (installing/exporting others' deps) -- never nag per-install about transitive dependencies.Hard lines (the boundary APM holds)
NOASSERTIONto a license just because aLICENSEfile exists on disk. npm keeps the two strictly separate (the LICENSE file always ships, but the field stays empty); APM does too.NOASSERTIONtoken => omitlicenses[]for that component; the SPDX format writes the literalNOASSERTION. This is exactly hownpm sbomitself behaves.Deferred (v0.2, alongside signatures)
license_file: {path, hash}presence-provenance -- "a file named LICENSE/COPYING exists at this hash" -- pure and non-interpretive, never changesdeclared_license, lets a downstream scanner pick up the text. Not in U5/U6.Build order unchanged: U6 lays the
declared_licensefield, U5 surfaces it. Signatures (U7) stay deferred.feat(export): SBOM export + declared-license recorder (U5 + U6) (#1820)
danielmeppiel commentedon Jun 16, 2026
Closing as done for the non-deferred scope. Phases 1 (SBOM/inventory export) and 2 (provenance schema) -- the entire actionable scope of this issue -- shipped in PR #1820 (merge commit 788a09a).
Phase 1 -- SBOM / inventory export [DONE]
apm lock export --format cyclonedx|spdxlands as a FORMAT flag on the existing lockfile-export concept (not a newapm sbomcommand that would imply completeness the lockfile lacks).src/apm_cli/export/package (not bolted onto commands/audit.py): formats.py, sbom.py, spdx.py, purl.py, declared_license.py, authoring.py.Phase 2 -- provenance schema [DONE]
Bonus folded in scope -- declared-license recorder [DONE]
declared_licenseadded to LockedDependency (npm-faithful: trusts the manifest's declared SPDX expression, never parses LICENSE text; declared != concluded).npm sbom).Supply-chain hard lines held: scrub_url strips userinfo + full query string (no token leakage into SBOM); NOASSERTION never auto-upgraded from an on-disk LICENSE file; export is read-only -- no re-hash/re-resolve/network/fs-scan.
Phase 3 -- signature verification: DEFERRED BY DESIGN (per this issue's own phasing: 'Signature verification LAST, and deferred. Defer until a real signing ecosystem for agent primitives exists and there is concrete demand (~5 community requests). When built, APM CONSUMES standard signatures; it does NOT build signing infrastructure.'). Not lost -- intentionally parked until demand materializes. Reopen or file a fresh issue when the signing ecosystem + ~5 requests arrive.
Verified live:
apm lock export --helpworks on main; export package + declared_license confirmed in origin/main. Out-of-scope items (runtime enforcement, building signing infra) remain out of scope.Merge origin/main into design-loop-issue-1078 (3rd sync)
feat(install): carry the source licence with subdirectory packages (#…