diff --git a/docs/modules/ROOT/pages/types-of-attestations-and-manifests.adoc b/docs/modules/ROOT/pages/types-of-attestations-and-manifests.adoc new file mode 100644 index 000000000..5ef7eb874 --- /dev/null +++ b/docs/modules/ROOT/pages/types-of-attestations-and-manifests.adoc @@ -0,0 +1,422 @@ += 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. + +=== a. Provenance Attestations + +Provenance attestations describe how a software artifact was built. Conforma primarily supports SLSA (Supply-chain Levels for Software Artifacts) Provenance v0.2. + +**Predicate Type:** `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 and pushed to registry +* Can be retrieved and verified for previously validated images +* Used to track validation history and results + +**Storage:** + +* Can be stored as OCI artifacts in registry +* Linked to the validated image by digest +* Format: DSSE envelope containing in-toto Statement + +=== c. SBOM Attestations + +SBOMs (Software Bill of Materials) list all components and dependencies in a software artifact. + +**Supported Formats:** + +* **SPDX:** Predicate type `https://spdx.dev/Document` +* **CycloneDX:** (Planned for future support) + +**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 + +== 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 Relationship:** +[source,text] +---- +Image Index (sha256:abc123) + ├── linux/amd64 → Image Manifest (sha256:def456) + ├── linux/arm64 → Image Manifest (sha256:ghi789) + └── linux/s390x → Image Manifest (sha256:jkl012) +---- + +=== 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 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` + +**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 + +**Example:** +[source,text] +---- +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) +---- + +**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 + +**Example:** +[source,text] +---- +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 +---- + +**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 + +**Example Structure:** +[source,text] +---- +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} +---- + +=== 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 + +**Example:** +[source,text] +---- +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 +---- + +**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: + +. **Resolve Image Reference:** + ** If a tag is provided, resolve it to a digest + ** Digest references are used directly + +. **Fetch Image Manifest:** + ** Retrieve the OCI image manifest + ** Extract configuration and layer information + +. **Fetch Attestations:** + ** Use cosign to find all attestations linked to the image digest + ** Retrieve DSSE envelopes for each attestation + ** Verify signatures on each envelope + +. **Parse Attestations:** + ** Decode DSSE payloads + ** Parse in-toto Statements + ** Extract predicate data based on predicate type + ** Validate statement structure + +. **Expand Image Indexes (if applicable):** + ** If image is an index, fetch all platform manifests + ** Repeat attestation retrieval for each platform + ** Track relationships + +. **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: + +. **Signature Verification:** + ** Verify image signatures + ** Verify attestation signatures + ** Check against provided public keys or certificate identities + ** Optionally verify against Rekor transparency log + +. **Attestation Syntax Validation:** + ** Validate in-toto Statement structure + ** Validate predicate schemas (e.g., SLSA Provenance v0.2) + ** Check required fields and data types + +. **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 diff --git a/docs/modules/ROOT/partials/main_nav.adoc b/docs/modules/ROOT/partials/main_nav.adoc index 552563370..47a1834db 100644 --- a/docs/modules/ROOT/partials/main_nav.adoc +++ b/docs/modules/ROOT/partials/main_nav.adoc @@ -1,6 +1,7 @@ * xref:index.adoc[Home] * xref:configuration.adoc[Configuration] * xref:policy_input.adoc[Policy Input] +* xref:types-of-attestations-and-manifests.adoc[Types of Attestations and Manifests] * xref:signing.adoc[Signing] * xref:release-process.adoc[Release Process] * xref:troubleshooting.adoc[Troubleshooting]