Add docs to describe the Types of Attestations and Manifests

[dheerajodha]

User description

resolves: EC-1474

---

PR Type

Documentation

---

Description

• Add comprehensive documentation on attestations and manifests

• Describe SLSA provenance, VSA, SBOM, signatures, and DSSE envelopes

• Explain OCI image manifests, indexes, and Tekton task bundles

• Document artifact relationships and Conforma's validation process

---

Diagram Walkthrough

flowchart LR
  A["Documentation Structure"] --> B["Attestations"]
  A --> C["Manifests"]
  B --> B1["Provenance"]
  B --> B2["VSA"]
  B --> B3["SBOM"]
  B --> B4["Signatures"]
  B --> B5["DSSE Envelopes"]
  C --> C1["OCI Image Manifests"]
  C --> C2["Image Indexes"]
  C --> C3["Tekton Task Bundles"]
  C --> C4["Tekton Manifests"]
  D["Artifact Relationships"] --> E["Image-to-Attestation"]
  D --> F["Image Index Hierarchy"]
  D --> G["Envelope Structure"]
  D --> H["Tekton Bundle Links"]
  I["Conforma Interaction"] --> J["Retrieval Process"]
  I --> K["Validation Stages"]
  I --> L["Output & Reporting"]

Loading

File Walkthrough

Relevant files

Documentation

types-of-attestations-and-manifests.adoc New comprehensive attestations and manifests documentation docs/modules/ROOT/pages/types-of-attestations-and-manifests.adoc New comprehensive documentation page covering attestations (provenance, VSA, SBOM, signatures, DSSE) Detailed explanation of manifests (OCI image manifests, image indexes, Tekton task bundles) Documentation of artifact relationships and linking mechanisms in OCI registries Description of Conforma's retrieval, validation, and reporting processes +422/-0  main_nav.adoc Add navigation link to attestations documentation                docs/modules/ROOT/partials/main_nav.adoc Add navigation link to new types-of-attestations-and-manifests documentation page Link positioned between Policy Input and Signing sections +1/-0

---

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

❗ There is a different number of reports uploaded between BASE (1a6ca15) and HEAD (172f8cb). Click for more details.

HEAD has 1 upload less than BASE

Flag	BASE (1a6ca15)	HEAD (172f8cb)
acceptance	1	0

Flag	Coverage Δ
acceptance	?
generative	19.01% <ø> (ø)
integration	27.89% <ø> (ø)
unit	67.57% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.
see 49 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Non-code Docs: The PR adds only documentation without executable code or logging changes, so audit trail compliance cannot be assessed from the diff. Referred Code = 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 ... (clipped 401 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Not Applicable: The changes are prose documentation and navigation entries, not code with identifiers, so naming compliance cannot be evaluated here. Referred Code = 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 ... (clipped 401 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: No Runtime Path: The diff contains only documentation and a nav link with no executable logic, so error handling cannot be assessed. Referred Code = 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 ... (clipped 401 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Documentation Only: No user-facing error surfaces are introduced or modified in this PR, so secure error handling cannot be evaluated from the diff. Referred Code = 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 ... (clipped 401 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: No Inputs Added: The PR adds navigation and documentation only, with no new data inputs or processing paths to validate for security. Referred Code * 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] Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Clarify distinction between image signatures and attestations Refactor the "Signatures" section to focus solely on image signatures. Move the discussion of attestation signatures to the "Envelopes (DSSE)" section to clarify that they are part of the attestation artifact, not a separate type. docs/modules/ROOT/pages/types-of-attestations-and-manifests.adoc [93-115] -=== d. Signatures +=== d. Image 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 +Image signatures provide cryptographic proof of an image's authenticity and integrity. Conforma uses Sigstore (cosign) to work with image signatures. **How Conforma Uses It:** -* Verifies image signatures to ensure image authenticity -* Verifies attestation signatures to ensure attestation authenticity +* Verifies image signatures to ensure the image has not been tampered with and was signed by a trusted party. * Supports multiple signature methods: ** Long-lived keys ** Identity-based short-lived keys (keyless signing) -* Signature information is made available to policy evaluation +* 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 +* Stored as separate OCI artifacts, often referred to as "signature layers". +* Linked to the image manifest by digest. +* The media type is typically `application/vnd.dev.cosign.simplesigning.v1+json`. [Suggestion processed] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a conceptual ambiguity in the documentation by clarifying that an image signature is a distinct artifact, while an attestation's signature is an integral part of the attestation itself. This improves the accuracy and clarity of the technical documentation.	Medium
	Clarify that DSSE envelopes contain attestation signatures Update the "Envelopes (DSSE)" section to explicitly state that the DSSE envelope is the mechanism for signing attestations. This change reinforces that attestation signatures are an integral part of the attestation artifact. docs/modules/ROOT/pages/types-of-attestations-and-manifests.adoc [117-139] === e. Envelopes (DSSE) -DSSE (Dead Simple Signing Envelope) is the format used to wrap and sign attestations. +DSSE (Dead Simple Signing Envelope) is the format used to wrap and sign attestations, making them verifiable statements. **Structure:** * Contains: - ** `payload`: Base64-encoded in-toto Statement + ** `payload`: Base64-encoded in-toto Statement (the attestation data) ** `payloadType`: Media type of the payload - ** `signatures`: Array of signature objects + ** `signatures`: An array of one or more signature objects. This is how attestations are signed. **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 +* All attestations (Provenance, SBOMs, etc.) are expected to be wrapped in DSSE envelopes. +* The signatures within the envelope are verified to ensure the authenticity and integrity of the attestation. +* The `payload` is decoded to parse the in-toto Statement and its predicate. **Storage:** -* Stored as OCI artifacts in registry -* Media type: `application/vnd.in-toto+json` -* Linked to images by digest +* Stored as OCI artifacts in a registry. +* The media type for the OCI artifact is `application/vnd.in-toto+json`. +* Linked to the subject image via the image's digest. Apply / Chat Suggestion importance[1-10]: 6 __ Why: This suggestion logically follows from the first one, reinforcing the concept that attestation signatures are part of the DSSE envelope. While the original text already implies this, the proposed change makes it more explicit, which improves the documentation's clarity.	Low
Possible issue	Correct misleading artifact relationship example Correct the example under "Image-to-Attestation Relationships" to distinguish between attestations (like Provenance and SBOM) and a separate image signature. This clarifies their distinct roles and relationships to the image. docs/modules/ROOT/pages/types-of-attestations-and-manifests.adoc [264-271] **Example:** [source,text] ---- +An image can have multiple attestations and a separate image signature. + 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) + +Attestations (linked via subject digest): + ├── Provenance: quay.io/example/app:sha256-image123.att + └── SBOM: quay.io/example/app:sha256-image123.sbom + +Image Signature (linked via digest tag): + └── Signature: quay.io/example/app:sha256-image123.sig ---- Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly points out that the example conflates attestations and image signatures, which are distinct artifact types. The proposed correction clarifies this distinction, significantly improving the accuracy and educational value of the example.	Medium
More

[qodo-code-review]

Suggestion: Clarify distinction between image signatures and attestations

Suggested change

	=== 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
	=== d. Image Signatures
	Image signatures provide cryptographic proof of an image's authenticity and integrity. Conforma uses Sigstore (cosign) to work with image signatures.
	**How Conforma Uses It:**
	* Verifies image signatures to ensure the image has not been tampered with and was signed by a trusted party.
	* Supports multiple signature methods:
	** Long-lived keys
	** Identity-based short-lived keys (keyless signing)
	* Signature information is made available to policy evaluation.
	**Storage:**
	* Stored as separate OCI artifacts, often referred to as "signature layers".
	* Linked to the image manifest by digest.
	* The media type is typically `application/vnd.dev.cosign.simplesigning.v1+json`.