Evidence Pack Specification

Conformance Levels

Not every tool needs to implement the full spec. A simple validator only needs Level 1 (pack format). A signing tool adds Level 2 (attestations). This layered approach lets you implement exactly what you need.

Pack Format

An Evidence Pack is just a ZIP file with a specific structure. We chose ZIP because it's universally supported, streamable, and already used everywhere. The format is designed so you can verify a pack's integrity without extracting it to disk.

Directory Structure

Every pack has the same basic structure: a manifest at the root, artifacts in a folder, and optional attestations. This predictability means any tool can find what it needs without parsing the manifest first.

pack.epack
+-- manifest.json              # REQUIRED - describes the pack
+-- artifacts/                 # REQUIRED - the actual evidence files
|   +-- {artifact-files}       # May use subdirectories
+-- attestations/              # OPTIONAL - cryptographic signatures
    +-- *.sigstore.json        # Direct children only, no subdirs

Path Requirements

Paths in a pack must work identically on Windows, macOS, and Linux. This means being strict about character encoding, normalization, and avoiding platform-specific gotchas like Windows device names or path traversal attacks.

Manifest

The manifest is the table of contents for your pack. It lists every artifact with its digest, declares the overall pack digest, and optionally tracks where the evidence came from. Think of it as the pack's "bill of materials."

{
  "spec_version": "1.0",
  "stream": "published/acme/prod",
  "generated_at": "2026-01-20T15:30:00Z",
  "pack_digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "sources": [
    {
      "name": "github",
      "version": "1.0.0",
      "source": "github.com/locktivity/epack-collector-github",
      "commit": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
      "binary_digest": "sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "artifacts": 5
    }
  ],
  "artifacts": []
}

Manifest Fields

Source Element

Each element in the sources array describes a collector that contributed artifacts. Sources are informational and do not affect verification or pack_digest computation.

Provenance (Merged Packs)

When a pack is created by merging other packs (for example, combining evidence from multiple vendors), the provenance field tracks where everything came from.

The provenance.source_packs array contains Source Pack objects with the following structure:

Each element of the embedded_attestations array is a complete Sigstore bundle from the source pack, enabling verifiers to validate signatures without fetching the original pack. To verify source pack integrity, verifiers MUST verify each embedded attestation using the Sigstore trusted root and expected signer identities.

Semantic Extensibility (Reserved Fields)

The manifest reserves three fields for future semantic validation: profile, overlays, and profile_lock. These enable a companion specification to define what artifacts a pack should contain and how they should be validated.

{
  "spec_version": "1.0",
  "stream": "published/acme/prod",
  "profile": "evidencepack/soc2-basic@v1",           // Reserved - identifier string
  "overlays": ["evidencepack/hipaa-overlay@v1"],     // Reserved - array of identifier strings
  "profile_lock": [                                  // Reserved - pinned digests for reproducibility
    { "id": "evidencepack/soc2-basic@v1", "digest": "sha256:abc123..." },
    { "id": "evidencepack/hipaa-overlay@v1", "digest": "sha256:def456..." },
    { "id": "evidencepack/soc2-report@v1", "digest": "sha256:789def..." }
  ],
  ...
}

Identifier Shape

Identifiers in profile, overlays, and profile_lock[].id are opaque strings to v1.0 validators. However, to prevent future migration pain, we recommend the following shape:

• Format: namespace/name@vN (e.g., evidencepack/soc2-report@v1)
• Lowercase ASCII alphanumeric, hyphens, underscores; 1-63 characters per segment
• Version: literal v followed by a positive integer with no leading zeros

Artifacts

Artifacts are the actual evidence files in your pack. They come in two flavors: embedded (the bytes are in the ZIP) and referenced (a pointer to an external URL). Most artifacts are embedded, but references are useful for large files or gated content like SOC 2 reports behind NDA portals.

Embedded Artifact

{
  "type": "embedded",
  "path": "artifacts/aws/iam-policies.json",
  "digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "size": 48213,
  "content_type": "application/json",
  "collected_at": "2026-01-20T14:00:00Z",
  "semantic_type": "evidencepack/iam-policies@v1",  // For profile validation (see Profiles spec)
  "metadata": { "region": "us-east-1" },            // Validated against type's metadata_schema
  "controls": ["AC-2", "AC-6"]
}

Referenced Artifact

Referenced artifacts point to external bytes (gated portals, VDRs). They are informational pointers excluded from pack_digest because the bytes aren't in the pack.

{
  "type": "reference",
  "name": "soc2-type-ii-report",
  "uri": "https://trust.vendor.com/portal/soc2",
  "access": { "policy": "nda_required" },
  "digest": "sha256:..."  // Optional - if present and bytes fetched, MUST validate
}

Integrity

The pack digest is a fingerprint of all embedded artifacts. If any artifact changes, the digest changes. This lets you verify a pack's contents with a single hash comparison and enables content-addressed storage (two packs with identical content have identical digests).

Pack Digest Computation

The algorithm is designed to be deterministic across implementations:

1. List all embedded artifacts from the manifest
2. Verify each artifact's SHA256(bytes) matches artifact.digest
3. Build canonical list: {path}\t{digest}\n per artifact (tab = 0x09, newline = 0x0A)
4. Sort lines by byte-wise lexicographic ordering on raw UTF-8 bytes (like memcmp)
5. Concatenate sorted lines. Each line ends with exactly one \n. No trailing newline after final entry.
6. Empty artifact list = empty byte string (zero bytes)
7. Compute SHA256 of concatenated result
8. Format as sha256:{hex} (lowercase)

Verification Steps

Two-Digest Model

Evidence Packs use two digests for different purposes:

Format conventions: pack_digest uses the prefixed format (sha256:hex) as a self-describing content identifier. manifest_digest uses raw hex (no prefix) to match in-toto's digest map structure where the algorithm is the key.

Security Considerations

ZIP files are a common attack vector. Malicious archives can contain path traversal attacks, symlinks that escape extraction directories, or zip bombs that expand to enormous sizes. These requirements ensure packs can be safely extracted and verified.

Size Limits

Implementations MUST enforce limits. Defaults are recommended; minimums are mandatory floors.

Attestation Format

Attestations are cryptographic signatures that prove a pack came from a specific source. Evidence Packs use Sigstore for keyless signing, where the signer authenticates via OIDC (GitHub, Google, Microsoft) and receives a short-lived certificate from Fulcio. All signatures are recorded in Rekor, a public transparency log.

Sigstore Bundle Structure

Attestation files use the Sigstore bundle format with media type application/vnd.dev.sigstore.bundle.v0.3+json:

{
  "mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json",
  "verificationMaterial": {
    "x509CertificateChain": {
      "certificates": [{ "rawBytes": "<base64-encoded-certificate>" }]
    },
    "tlogEntries": [{
      "logIndex": "123456",
      "logId": { "keyId": "<base64>" },
      "integratedTime": "1234567890",
      "inclusionProof": {
        "logIndex": "123456",
        "rootHash": "<base64>",
        "treeSize": "1000000",
        "hashes": ["<base64>", "..."]
      }
    }]
  },
  "dsseEnvelope": {
    "payloadType": "application/vnd.in-toto+json",
    "payload": "<base64(in-toto statement)>",
    "signatures": [{ "keyid": "", "sig": "<base64-signature>" }]
  }
}

in-toto Statement (Decoded Payload)

{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [{
    "name": "manifest.json",
    "digest": {"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"}
  }],
  "predicateType": "https://evidencepack.org/attestation/v1",
  "predicate": {}
}

Attestation File Naming

Attestation files MUST be named {identity-hash}.sigstore.json where identity-hash is the first 8 characters of the SHA-256 hash of the certificate's subject identity.

attestations/
├── a1b2c3d4.sigstore.json    # security@acme.com
├── e5f6g7h8.sigstore.json    # auditor@thirdparty.com
└── i9j0k1l2.sigstore.json    # github.com/org/repo workflow

Signing Process

Signing uses Sigstore for keyless, identity-based signatures. The signer authenticates via OIDC, receives a short-lived certificate from Fulcio, and the signature is recorded in Rekor's transparency log.

Manifest Digest Computation

The manifest digest (used as the attestation subject) is computed using JCS (RFC 8785):

Signing with Sigstore

Using cosign to sign the manifest:

# Extract manifest from pack
unzip -p pack.epack manifest.json > manifest.json

# Sign with Sigstore (opens browser for OIDC authentication)
cosign sign-blob manifest.json \
  --bundle attestations/signer.sigstore.json \
  --yes

# Add attestation to pack
zip pack.epack attestations/signer.sigstore.json

Verification Process

Verification uses the Sigstore trusted root (Fulcio CA, Rekor public key) to validate the bundle. The bundle is self-contained with stapled proofs, enabling offline verification without network access.

Verification Failures

Identity Verification

Sigstore certificates contain the signer's identity from their OIDC provider. Verifiers specify which identities they trust, such as specific email addresses or CI/CD workflow identities.

Common Identity Types

Test Vectors

Test vectors let you verify your implementation is conformant. Each vector includes a pack (valid or invalid) and the expected result. Run them against your code to catch edge cases before they become production bugs.

Level 1: Pack Format

Level 2: Attestation

References

Sigstore & Signing

• Sigstore - Keyless signing for the software supply chain
• Fulcio - Certificate authority for code signing
• Rekor - Transparency log for signatures
• DSSE Specification - Dead Simple Signing Envelope
• in-toto Attestation Framework - in-toto Statement format

RFCs

• RFC 8785 - JSON Canonicalization Scheme (JCS)
• RFC 8259 - The JSON Data Interchange Format
• RFC 4648 - Base Encodings (Base64)
• RFC 6454 - The Web Origin Concept
• RFC 8615 - Well-Known URIs