From source to SBOM

Artefact 1: the capability manifest

capa --manifest emits Capa-native JSON describing every function's authority. Here is the entry for summarise, shortened with ellipses but otherwise verbatim:

$ capa --manifest report.capa
{
  "capa_version": "1.15.1",
  "schema_version": 1,
  "filename": "report.capa",
  "functions": [
    ...
    {
      "name": "summarise",
      "pos": "report.capa:10:1",
      "declared_capabilities": ["Stdio", "Fs", "Env"],
      "transitively_reachable_capabilities": ["Env", "Fs", "Stdio"],
      "provably_excluded_capabilities": [
        "Clock", "Db", "Net", "Proc", "Random", "Unsafe"
      ],
      "has_unsafe": false,
      ...
      "declassifications": [
        {
          "reason": "audit trail: last 4 chars identify the reporting token",
          "value": "\"token ending ${...}\"",
          "pos": "24:26"
        }
      ]
    },
    ...
  ],
  "summary": {
    "total_functions": 3,
    "functions_with_capabilities": 2,
    "functions_with_attributes": 1,
    "functions_crossing_unsafe": 0,
    "declassification_sites": 1,
    "protocol_states": 0,
    "foreign_components": 0,
    "functions_calling_foreign_components": 0
  }
}

Three fields carry the audit weight. declared_capabilities is the signature's claim. provably_excluded_capabilities is the type system's counter-claim: summarise can never touch Net or Proc, because those names are not in scope and the analyzer rejected every path to them. And declassifications lists every sanctioned secret disclosure with its stated reason, the record chapter 13 promised.

The manifest also captures attenuation. Inside main's entry, the call to summarise records that the Fs argument was narrowed before being handed down:

"args_flow": [
  null,
  {
    "name": "logs_fs",
    "attenuations": [
      { "method": "restrict_to", "args": ["\"logs/\""] }
    ]
  },
  null,
  null
]

An auditor reads this as: the filesystem authority that reaches summarise is not the program's full Fs, it is Fs restricted to logs/, and the compiler extracted that fact from the source, not from a questionnaire.

Artefact 3: the SPDX companion

capa --spdx emits the same content in SPDX 2.3, the Linux Foundation's format. Pick whichever your downstream consumer standardises on; the information is identical. Functions become packages related to the program by CONTAINS, capabilities by DEPENDS_ON, and the per-function metadata rides in annotations[]:

$ capa --spdx report.capa
{
  "spdxVersion": "SPDX-2.3",
  "name": "report.capa",
  ...
  "packages": [ "report.capa", "Env", "Fs", "Stdio",
                "count_errors", "summarise", "main" ],
  "relationships": [
    { "spdxElementId": "SPDXRef-Package-report.capa",
      "relationshipType": "DEPENDS_ON",
      "relatedSpdxElement": "SPDXRef-Builtin-report.capa-Fs" },
    { "spdxElementId": "SPDXRef-Package-report.capa",
      "relationshipType": "CONTAINS",
      "relatedSpdxElement": "SPDXRef-Fn-report.capa-summarise" },
    ...
  ]
}

(The packages array is abbreviated to names here; each entry is a full SPDX package object with annotations[] carrying the capa:* key-value pairs.)

Artefact 5: provenance

The last artefact answers "where did this come from?". capa --provenance emits a SLSA Build L1 attestation, an in-toto Statement v1 binding the artefact to the SHA-256 of its source:

$ capa --provenance report.capa
{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [
    {
      "name": "report.capa",
      "digest": { "sha256": "f0878f4a6bdb56dbe9657a77c21b491a..." }
    }
  ],
  "predicateType": "https://slsa.dev/provenance/v1",
  "predicate": {
    "buildDefinition": {
      "buildType": "https://capa-language.com/build/transpile-to-python/v1",
      "externalParameters": { "source": "report.capa" },
      "internalParameters": { "capaVersion": "1.15.1",
                              "target": "python>=3.10" },
      ...
    },
    ...
  }
}

(The digest, externalParameters, and internalParameters objects are compacted here for readability; the compiler emits each across multiple lines.)

Anyone holding the source can recompute the digest and confirm this attestation describes exactly this file, no more, no less. L1 is the unsigned tier of the SLSA ladder; signing and a hardened builder are deliberately left to CI infrastructure, where they belong.

Scaling up: from one file to a whole product

The five artefacts above describe one file. But you do not ship a file, you ship a product: a root package wired over a tree of dependencies, some third-party, some not even written in Capa. The same discipline scales, and four more flags carry it up that tree. To keep this concrete, the rest of the chapter switches from report.capa to the flagship demo, capa_ci_pipeline: a build orchestrator that runs four untrusted third-party "actions" (fetch, parse, build, publish) as sandbox-confined foreign Wasm components. Every command and output below was run against it.

The composed product SBOM: --compose-sbom

capa --compose-sbom re-introduces the package boundary the loader flattens away and rolls each function's capabilities up the dependency graph, attributing them per package. On the demo, under the Wasm-sandbox posture:

$ capa --compose-sbom --wasm main.capa
{
  ...
  "enforcement_posture": "wasm-sandbox",
  "composed": {
    "authority_unknown": false,
    "capabilities": ["Fs", "Net", "Stdio"],
    ...
  },
  "packages": [
    { "name": "capa_ci_pipeline", "composed_capabilities": ["Fs", "Net", "Stdio"], ... },
    { "name": "build_action",     "composed_capabilities": ["Fs"],  ... },
    { "name": "fetch_action",     "composed_capabilities": ["Net"], ... },
    { "name": "parse_action",     "composed_capabilities": [],      ... },
    { "name": "pipeline_core",    "composed_capabilities": [],      ... },
    { "name": "publish_action",   "composed_capabilities": ["Net"], ... }
  ],
  ...
}

(Reflowed and abbreviated from the single canonical line; each package object also carries attributed_capabilities and a reason string.) The attribution is precise, not a module-wide union: fetch and publish compose to Net, build to Fs, the parser to nothing, and the pure pipeline_core to nothing. That precision is the point. A coarse roll-up that credited every action the product's whole {Fs, Net, Stdio} would be sound but useless; the precise composed graph is what lets a policy forbid Net on the parser specifically.

The composed value lives in a small lattice: capability sets, plus one distinguished TOP element, "authority unknown". A dependency the compiler cannot read (a native library, an absent capa.toml, a package that crosses Unsafe) composes as TOP, and TOP is absorbing: one unknown anywhere marks the whole roll-up authority_unknown: true, and it is never treated as the empty set. That is the property no scanner has. A dependency scanner handed a subtree it cannot read attributes it nothing, and nothing reads as clean: an SBOM that is dishonestly clean in exactly the dangerous direction. Here the gap is a first-class verdict. The demo ships negatives/native_action, whose dependency carries a capa.toml but no Capa source; composing it yields authority_unknown: true. (The same boundary is why the default, non---wasm posture composes the four foreign actions as TOP too; only --wasm makes them bounded, which the last section explains.)

The per-package gate that reads this SBOM is capa --check-capabilities: each package that declares a [capabilities] ceiling in its capa.toml must compose within it, and an authority-unknown package fails closed. Wrap report.capa in a package that declares its ceiling:

[package]
name = "report"
version = "1.0.0"

[capabilities]
max = ["Stdio", "Fs", "Env"]

$ capa --check-capabilities report.capa
capa: --check-capabilities: OK - every declared capability ceiling holds.

Tighten the ceiling to forbid Env and the gate names the breach and exits non-zero:

$ capa --check-capabilities report.capa
capa: --check-capabilities: FAILED - 1 ceiling violation(s):
  - package 'report' declares max=['Fs', 'Stdio'] but its own code introduces 'Env'

Compliance policies: --check-policies and --conformance-report

A diff needs a previous release to compare against. A policy needs only a rule. An organization writes a product-level capa-policy.toml, owned by the security team and distinct from any per-package ceiling, from a fixed, enumerated set of predicate kinds: exclusion, product-subset, purity, forbid-capability, forbid-dependency, and no-unresolved-dependencies (an unknown kind is a hard parse error, never a silently-ignored rule). The demo's file declares four: the core library is pure, the parse action must not hold Net (the confined-parser rule), the build action must not hold Net and Fs together (the exfil vector), and product authority stays within {Net, Fs, Stdio}. On the clean product every rule holds:

$ capa --check-policies --wasm main.capa
capa: --check-policies: OK - every declared compliance policy holds.

capa --conformance-report --wasm main.capa emits the same result as signable evidence: a canonical report with pass: true, one entry per policy, and the content-integrity envelope. Now run the gate on the same compromised build action from the diff:

$ cd v2 && capa --check-policies --wasm main.capa
capa: --check-policies: FAILED - 1 policy(ies), 1 violation(s):
  policy 'build-no-net-and-fs' (kind exclusion):
    - [violation] package 'build_action' holds all of ['Fs', 'Net'] simultaneously (composed capabilities), which policy 'build-no-net-and-fs' forbids

One change, caught twice, by two independent controls on the same SBOM. The diff caught it as a release-over-release widening with no policy file present; the policy catches it as a standing-rule violation with no previous release needed. A regression that evaded one (a first release with no baseline, or a widening the org had not thought to forbid) is caught by the other. And the fail-closed discipline carries into the verdicts. Point the gate at the native-dependency negative and the product-subset policy returns a distinct authority_unknown verdict, not a pass:

$ cd negatives/native_action && capa --check-policies --wasm main.capa
capa: --check-policies: FAILED - 1 policy(ies), 1 violation(s):
  policy 'product-authority' (kind product-subset):
    - [authority_unknown] the product's composed authority is UNKNOWN: 'legacy_action' of 'native_prod' (package has a capa.toml but no Capa source (native / non-Capa dependency; its authority cannot be derived)) (via native_prod); a product-subset policy cannot be proven over an unanalyzable subtree. Set allow_unknown = true to waive.

"Part of this product is unanalyzable, so the policy is unverifiable" is a different verdict from "this product reaches a forbidden capability", and neither reads as clean. The compliance gate distinguishes them.

Where you go next

That is the whole tour, source to evidence. To see the same artefacts generated for a real codebase, read capa_paymentguard: its conformity/ directory ships the manifest, both SBOMs, the VEX, the provenance, and a CONFORMITY.md that walks an auditor through them. To start a project with that layout from day one, capa_cra_template is the scaffold. And the clause-by-clause mapping of these artefacts onto CRA, NIS2, DORA, NIST SSDF, and OWASP SCVS lives on the regulatory page.

If you build something with Capa, send it. Real use is the best feedback.