Skip to content

Deepen install-time integrity: signature verification, SBOM, provenance #1777

Closed

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)

  1. 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.
  2. 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).
  3. 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 informational verified | unverified | none status; 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.

Activity

  1. added
    enhancementLegacy classification name; prefer type/feature. Retained for history.
    securityLegacy classification name; prefer theme/security. Retained for history.
    area/content-securityUnicode scanning, Glassworm, apm audit content checks, SARIF output.
    area/lockfileLockfile schema, per-file provenance, integrity hashes, drift detection.
    on Jun 15, 2026
  2. added
    type/featureNew capability, new flag, new primitive.
    and removed
    enhancementLegacy classification name; prefer type/feature. Retained for history.
    securityLegacy classification name; prefer theme/security. Retained for history.
    on Jun 15, 2026
  3. danielmeppiel commented on Jun 16, 2026

    @danielmeppiel
    CollaboratorAuthor

    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 license field in package.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

    • U6 (provenance, first): add declared_license to the lockfile entry. Value = SPDX expression as declared by the package manifest at resolved_commit. Syntax-validated offline only (no network, no text scan). Backfilled at resolve time from apm.yml license: (APM packages) or plugin.json license (ingested plugin manifests -- the parser already reads these and currently drops the field). Undeclared => field omitted from the lockfile.
    • U5 (SBOM): surface declared_license into the CycloneDX licenses[] field (and the SPDX-format equivalent). Read the lockfile only -- no re-resolve, no re-hash, no text scan.
    • New maturity surface: apm.yml gains an optional top-level license: 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."

    State Example Lockfile SBOM (CycloneDX) Author nudge
    Declared, valid SPDX MIT, (MIT OR Apache-2.0) recorded verbatim licenses[].license.id / expression none
    Declared special token UNLICENSED, SEE LICENSE IN <file> recorded verbatim licenses[].license.name (named, an assertion) none
    Not declared no license: / no manifest field omitted licenses[] omitted (SPDX format: NOASSERTION) see below

    The three not-declared sub-cases produce the same SBOM output (NOASSERTION) but differ on the nudge:

    • (a) apm.yml present, no license: -> NOASSERTION; warn on apm pack / apm publish ("No license field; SBOM will record NOASSERTION"). This is the authoring path -- mirror of npm's "No license field" warning.
    • (b) plugin.json present, no license -> NOASSERTION; silent (foreign manifest you do not author; you cannot fix it).
    • (c) dependency is a single primitive file / no manifest at all -> NOASSERTION; silent at install. You cannot infer a license from a lone file; the apm.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)

    • Declared != concluded. Do NOT auto-promote NOASSERTION to a license just because a LICENSE file exists on disk. npm keeps the two strictly separate (the LICENSE file always ships, but the field stays empty); APM does too.
    • Never block. Invalid SPDX syntax => warn + record verbatim + emit as a named license. Never fail pack/publish/install. Consistent with the no-policy-gate stance.
    • CycloneDX has no NOASSERTION token => omit licenses[] for that component; the SPDX format writes the literal NOASSERTION. This is exactly how npm sbom itself 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 changes declared_license, lets a downstream scanner pick up the text. Not in U5/U6.

    Build order unchanged: U6 lays the declared_license field, U5 surfaces it. Signatures (U7) stay deferred.

  4. danielmeppiel commented on Jun 16, 2026

    @danielmeppiel
    CollaboratorAuthor

    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|spdx lands as a FORMAT flag on the existing lockfile-export concept (not a new apm sbom command that would imply completeness the lockfile lacks).
    • New src/apm_cli/export/ package (not bolted onto commands/audit.py): formats.py, sbom.py, spdx.py, purl.py, declared_license.py, authoring.py.
    • Reads lockfile-recorded hashes ONLY -- never re-hashes the filesystem at export (verified by a corrupted-on-disk-tree-still-exports-recorded-hash test).
    • Deterministic, byte-identical output: sorted components + injectable timestamp (SOURCE_DATE_EPOCH / --timestamp), golden-file tested.
    • Component identity = purl: pkg:github/owner/repo@<resolved_commit> for git; pkg:generic/@<content_hash> for local. purl segments percent-encoded to prevent identity spoofing.
    • Honest about scope: inventory, not attestation.

    Phase 2 -- provenance schema [DONE]

    • Formalizes the resolved_commit/resolved_ref/resolved_url/resolved_at/content_hash fields the lockfile already records -- re-serialization of captured data, no new capture, no self-attestation.

    Bonus folded in scope -- declared-license recorder [DONE]

    • declared_license added to LockedDependency (npm-faithful: trusts the manifest's declared SPDX expression, never parses LICENSE text; declared != concluded).
    • Three-state model: valid SPDX passthrough / special tokens (UNLICENSED, SEE LICENSE IN ) as named assertions / undeclared -> NOASSERTION.
    • Format-honest emptiness: CycloneDX omits licenses[]; SPDX writes literal NOASSERTION (matches npm sbom).
    • Authoring-path WARN only (pack/publish on your own apm.yml); SILENT on consume/install/export.

    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 --help works on main; export package + declared_license confirmed in origin/main. Out-of-scope items (runtime enforcement, building signing infra) remain out of scope.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/content-securityUnicode scanning, Glassworm, apm audit content checks, SARIF output.area/lockfileLockfile schema, per-file provenance, integrity hashes, drift detection.type/featureNew capability, new flag, new primitive.

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions