Types of Attestations and Manifests

Conforma interacts with various types of attestations and manifests throughout the software supply chain verification process. This page describes these artifacts, how Conforma uses them, and how they relate to each other in OCI registries like Quay.

1. Attestations

Attestations are cryptographically signed statements about software artifacts. They provide metadata and evidence about how software was built, what it contains, and who verified it. Conforma retrieves and validates attestations associated with container images.

Example Relationship:

Image: quay.io/example/app@sha256:image123
  ├── Provenance: quay.io/example/app:sha256-image123.att (subject: sha256:image123)
  ├── SBOM: quay.io/example/app:sha256-image123.sbom (subject: sha256:image123)
  └── Signature: quay.io/example/app:sha256-image123.sig (references: sha256:image123)

a. Provenance Attestations

Provenance attestations describe how a software artifact was built. Conforma supports SLSA (Supply-chain Levels for Software Artifacts) Provenance v1.0 and v0.2.

Predicate Type: https://slsa.dev/provenance/v1 or https://slsa.dev/provenance/v0.2

Structure:

  • Wrapped in an in-toto Statement v0.1

  • Contains build information including:

    • Build type and invocation details

    • Source materials (git repositories, dependencies)

    • Build environment details

    • Build outputs

How Conforma Uses It:

  • Retrieved from OCI registry using cosign

  • Validated for signature authenticity

  • Parsed and made available to policy evaluation

  • Used by policy rules to verify build processes, source code integrity, and build environment compliance

Storage:

  • Stored as OCI artifacts in the same registry as the image

  • Linked to the image by digest (SHA256)

  • Format: DSSE (Dead Simple Signing Envelope) JSON

b. Verification Summary Attestations (VSA)

VSAs are attestations that summarize the results of policy validation. They are generated by Conforma after validating an image and its attestations.

Predicate Type: https://conforma.dev/verification_summary/v1

Structure:

  • Contains validation results including:

    • Policy evaluation outcomes

    • Attestation verification status

    • Image signature verification status

    • Timestamps and metadata

How Conforma Uses It:

  • Generated by the ec validate image command when --vsa flag is used

  • Can be signed using --vsa-signing-key flag

  • Optionally uploaded to storage backends via --vsa-upload flag

  • Can be retrieved and verified for previously validated images

  • Used to track validation history and results

Storage:

  • VSAs are generated as DSSE envelopes in temporary files

  • Optionally uploaded to configured storage backends:

    • rekor@url - Uploaded to Rekor transparency log (e.g., rekor@https://rekor.sigstore.dev)

    • local@path - Saved to local filesystem directory (e.g., local@./vsa-dir)

  • If no --vsa-upload is specified, VSAs are generated but not uploaded

  • Format: DSSE envelope containing in-toto Statement

  • VSAs are NOT automatically stored as OCI artifacts in the image registry

c. SBOM Attestations

SBOMs (Software Bill of Materials) list all components and dependencies in a software artifact.

Supported Formats:

Structure:

  • Contains detailed inventory of:

    • Software components

    • Dependencies and their versions

    • Licenses

    • Vulnerability information

How Conforma Uses It:

  • Retrieved from OCI registry alongside other attestations

  • Made available to policy evaluation

  • Can be used by policies to verify component compliance, license requirements, and security policies

Storage:

  • Stored as OCI artifacts in the same registry as the image

  • Linked to the image by digest

  • Format: DSSE envelope containing in-toto Statement with SBOM predicate

d. Signatures

Signatures provide cryptographic proof of authenticity and integrity. Conforma uses Sigstore (cosign) signatures.

Types:

  • Image Signatures: Direct signatures on container image manifests

  • Attestation Signatures: Signatures on attestation envelopes

How Conforma Uses It:

  • Verifies image signatures to ensure image authenticity

  • Verifies attestation signatures to ensure attestation authenticity

  • Supports multiple signature methods:

    • Long-lived keys

    • Identity-based short-lived keys (keyless signing)

  • Signature information is made available to policy evaluation

Storage:

  • Image signatures stored as OCI artifacts with media type application/vnd.dev.cosign.simplesigning.v1+json

  • Attestation signatures embedded in DSSE envelopes

  • Linked to images/attestations by digest

e. Envelopes (DSSE)

DSSE (Dead Simple Signing Envelope) is the format used to wrap and sign attestations.

Structure:

  • Contains:

    • payload: Base64-encoded in-toto Statement

    • payloadType: Media type of the payload

    • signatures: Array of signature objects

How Conforma Uses It:

  • All attestations are wrapped in DSSE envelopes

  • Envelopes are parsed to extract the in-toto Statement

  • Signatures in the envelope are verified

  • The payload is decoded and validated

Storage:

  • Stored as OCI artifacts in registry

  • Media type: application/vnd.in-toto+json

  • Linked to images by digest

Example Structure:

DSSE Envelope (OCI artifact)
  ├── Signatures (array)
  │   ├── Signature 1
  │   └── Signature 2
  └── Payload (base64-encoded)
      └── In-toto Statement
          ├── Subject: [{"name": "quay.io/example/app", "digest": {"sha256": "image123"}}]
          └── Predicate: {provenance data}

2. Manifests

Manifests are metadata structures that describe OCI artifacts. Conforma works with several types of manifests.

a. OCI Image Manifests

Image manifests describe container images, including their layers, configuration, and metadata.

Structure:

  • schemaVersion: OCI manifest schema version (typically 2)

  • mediaType: Media type of the manifest

  • config: Reference to image configuration blob

  • layers: Array of layer descriptors

  • annotations: Optional metadata annotations

  • subject: Optional reference to related artifact (OCI 1.1+)

How Conforma Uses It:

  • Retrieved when validating images

  • Used to understand image structure

  • Layer information used for file extraction

  • Config information used for policy evaluation

  • Accessed via ec.oci.image_manifest Rego builtin

Storage:

  • Stored in OCI registry

  • Referenced by digest (SHA256)

  • Can be referenced by tag (which resolves to digest)

b. Image Indexes

Image indexes (also called manifest lists) describe multi-platform images, containing references to platform-specific manifests.

Structure:

  • schemaVersion: OCI manifest schema version

  • mediaType: Media type (typically application/vnd.oci.image.index.v1+json)

  • manifests: Array of manifest descriptors, each with:

    • Platform information (OS, architecture, variant)

    • Digest reference to platform-specific manifest

  • annotations: Optional metadata

  • subject: Optional reference to related artifact

How Conforma Uses It:

  • Automatically expanded when processing Application Snapshots

  • Each platform-specific manifest is validated separately

  • Creates separate components in the snapshot for each platform

  • Tracks parent-child relationships between index and platform manifests

  • Accessed via ec.oci.image_index Rego builtin

Storage:

  • Stored in OCI registry

  • Referenced by digest

  • Platform manifests referenced within the index

Example:

Image Index: quay.io/example/app@sha256:index123
  ├── linux/amd64 → sha256:manifest-amd64
  ├── linux/arm64 → sha256:manifest-arm64
  └── windows/amd64 → sha256:manifest-win

Each platform manifest can have its own attestations:
  sha256:manifest-amd64
    └── Provenance: sha256:manifest-amd64.att

c. Tekton Task Bundles

Tekton task bundles are OCI artifacts that package Tekton Task and Pipeline definitions.

Structure:

  • OCI image with special annotations

  • Layers contain YAML definitions of Tekton resources

  • Each layer annotated with:

    • org.tekton.bundle.kind: Resource kind (e.g., "task", "pipeline")

    • org.tekton.bundle.name: Resource name

How Conforma Uses It:

  • Retrieved when using ec track bundle command

  • Task definitions extracted from bundle layers

  • Used to track which task images are used in Tekton pipelines

  • Can be referenced in Application Snapshots

Storage:

  • Stored as OCI artifacts in registry

  • Referenced by tag or digest

  • Example: quay.io/conforma/tekton-task:0.1

Example:

Task Bundle: quay.io/conforma/tekton-task:0.1 (sha256:bundle123)
  └── Layer: verify-task.yaml
      └── spec.steps[].image: quay.io/conforma/cli@sha256:cli456
          └── This image can be validated by Conforma

Note: When task bundles are created during release, image references in task definitions are pinned to specific digests, ensuring immutability.

d. Tekton Manifests (in Kubernetes)

Tekton manifests are the actual Task, Pipeline, and other resource definitions visible in Kubernetes clusters via kubectl.

Relationship to Bundles:

  • Task bundles contain the source definitions

  • When bundles are referenced in Tekton Pipelines, the definitions are extracted and applied to the cluster

  • The cluster contains the runtime instances of these definitions

How Conforma Uses It:

  • Conforma primarily works with task bundles (OCI artifacts)

  • The CLI itself can be run as a Tekton Task

  • Task definitions reference container images that Conforma validates

Artifact Relationships on Quay

All artifacts in OCI registries like Quay are linked by SHA256 digests. Understanding these relationships is crucial for understanding how Conforma validates software supply chains.

Image-to-Attestation Relationships

Primary Relationship:

  • Container images and their attestations are linked by digest

  • Attestations are stored as separate OCI artifacts

  • The attestation’s subject field references the image digest

  • See the example in the Attestations section above

Key Properties:

  • Digest-based linking: Attestations reference images by SHA256 digest, not tag

  • Portability: Images and attestations can be copied together to different registries without breaking relationships

  • Immutability: Each digest uniquely identifies content; changing content changes the digest

  • One-to-many: One image can have multiple attestations (provenance, SBOM, VSA, etc.)

Image Index Relationships

Hierarchical Structure:

  • Image Index contains references to multiple platform-specific manifests

  • Each reference includes the platform (OS/arch) and the manifest digest

  • The index itself has its own digest

  • See the example in the Image Indexes section above

How Conforma Handles It:

  • When an image index is encountered, Conforma expands it

  • Each platform-specific manifest is validated independently

  • Attestations are expected for each platform manifest

  • Parent-child relationships are tracked in the expansion process

Attestation Envelope Structure

Nested Relationships:

  • Attestations are wrapped in DSSE envelopes

  • The envelope contains signatures

  • The payload contains the in-toto Statement

  • The Statement’s subject references the image digest

  • See the example in the Envelopes (DSSE) section above

Tekton Bundle Relationships

Bundle Contents:

  • Task bundles are OCI artifacts containing Tekton resource definitions

  • Bundle layers contain YAML definitions

  • Task definitions within bundles reference container images

  • See the example in the Tekton Task Bundles section above

Release Process:

  • During release, image references in task definitions are pinned to digests

  • This creates an immutable relationship between bundle version and CLI image version

  • Ensures reproducibility and traceability

How Conforma Interacts with Artifacts

Retrieval Process

When Conforma validates an image, it follows this process:

  1. Resolve Image Reference:

    • If a tag is provided, resolve it to a digest

    • Digest references are used directly

  2. Fetch Image Manifest:

    • Retrieve the OCI image manifest

    • Extract configuration and layer information

  3. Fetch Attestations:

    • Use cosign to find all attestations linked to the image digest

    • Retrieve DSSE envelopes for each attestation

    • Verify signatures on each envelope

  4. Parse Attestations:

    • Decode DSSE payloads

    • Parse in-toto Statements

    • Extract predicate data based on predicate type

    • Validate statement structure

  5. Expand Image Indexes (if applicable):

    • If image is an index, fetch all platform manifests

    • Repeat attestation retrieval for each platform

    • Track relationships

  6. Policy Evaluation:

    • Make all artifact data available to Rego policies

    • Policies can access:

      • Image metadata and configuration

      • All attestations and their predicates

      • Signature information

      • Relationships between artifacts

Validation Stages

Conforma performs validation in multiple stages:

  1. Signature Verification:

    • Verify image signatures

    • Verify attestation signatures

    • Check against provided public keys or certificate identities

    • Optionally verify against Rekor transparency log

  2. Attestation Syntax Validation:

    • Validate in-toto Statement structure

    • Validate predicate schemas (e.g., SLSA Provenance v0.2)

    • Check required fields and data types

  3. Policy Evaluation:

    • Execute Rego policies against artifact data

    • Policies can check:

      • Build process compliance

      • Source code requirements

      • Security requirements

      • License compliance

      • Any custom business rules

Output and Reporting

Conforma can generate various outputs:

  • Validation Results: Pass/fail status for each policy rule

  • VSA Generation: Create Verification Summary Attestations

  • Policy Input Export: Export the data structure used for policy evaluation

  • Detailed Reports: JSON, YAML, or text format reports