# Chainloop and Supply Chain Evidence

> **Intro:** Many teams now understand **signing**. Fewer teams understand how to manage the broader problem of **release evidence**: SBOMs, scan reports, signatures, attestations, policies, and whether a release should be considered compliant enough to promote. This is where evidence-oriented platforms such as Chainloop become interesting.
>
> **What this page includes**
>
> * what Chainloop is and where it fits
> * how it differs from “just use Cosign”
> * a practical material / attestation / policy workflow
> * examples of where it helps in a Product Security program

## Where Chainloop fits

A simple way to think about the space:

| Need                                          | Typical tool family                                        |
| --------------------------------------------- | ---------------------------------------------------------- |
| **Sign one artifact**                         | Cosign, Notation                                           |
| **Generate SBOM**                             | Syft, Trivy, CycloneDX generators                          |
| **Scan artifact**                             | Trivy, Grype, vendor scanners                              |
| **Store or govern evidence across workflows** | attestation / evidence platforms such as Chainloop         |
| **Enforce deployment policy**                 | registry, admission controller, GitOps gate, policy engine |

Chainloop is most useful when the problem is not only **“can I sign the image?”** but also:

* can I prove which evidence belongs to this build?
* can I require certain materials before a release is considered compliant?
* can I evaluate policy over those materials?
* can I track evidence across many workflows and products?

## Mental model

The core nouns are simple:

* **material** — a piece of evidence, such as an image digest, SBOM, or SARIF report
* **attestation** — a signed and verifiable statement that bundles evidence for a workflow run
* **contract** — what evidence is expected
* **policy** — what conditions must hold for the evidence to be accepted as compliant

That makes Chainloop closer to an **evidence and policy plane** than to a basic scanner.

## Where it helps most

This model is useful when you want to answer questions like:

* Did this release include an SBOM?
* Was the image signed?
* Did the security scan report pass policy?
* Can we keep evidence even when policy fails?
* Can we link build evidence to promotion evidence?

## Example workflow

A realistic flow looks like this:

1. the build produces an OCI image
2. the pipeline generates an SBOM
3. the pipeline collects scanner outputs
4. the attestation is initialized from a workflow contract
5. required materials are added
6. the attestation is signed and pushed
7. policy marks the run compliant or not compliant
8. promotion systems consume that decision

## Practical snippet — initialize, add, push

See:

* [`../snippets/artifacts/chainloop-attestation.sh`](https://github.com/D3One/Product-Security-Gitbook/blob/main/snippets/artifacts/chainloop-attestation.sh)
* [`../snippets/artifacts/chainloop-policy-example.rego`](https://github.com/D3One/Product-Security-Gitbook/blob/main/snippets/artifacts/chainloop-policy-example.rego)

High-level shape:

```bash
chainloop att init --workflow release-build --project payments-api
chainloop att add --value ghcr.io/example/payments-api:1.4.2
chainloop att add --value sbom.cdx.json --kind SBOM_CYCLONEDX_JSON
chainloop att add --value semgrep.sarif --kind SARIF
chainloop att push
```

## What to put in the attestation

Good candidates:

* OCI image reference by digest
* CycloneDX or SPDX SBOM
* static analysis SARIF
* dependency scan report
* provenance or build metadata
* deployment metadata where relevant

Poor candidates:

* raw, unbounded log dumps
* evidence nobody reads and no policy consumes
* mutable tags without stable digests

## Policy examples

Example acceptance rules:

* image must be signed
* no `latest` tag in promoted OCI references
* SBOM must exist
* binary or dependency scan report must not show high/critical violations above threshold
* required release metadata must be present

## Chainloop vs a lighter stack

### Use a lighter stack when

* one team owns a small number of pipelines
* CI can fail directly on scanner exit code
* artifact signing plus a few upload steps are enough
* you do not need organization-wide evidence reuse

### Consider an evidence platform when

* multiple teams and workflows need common policy
* auditability and reuse matter
* evidence must remain reviewable even when policy fails
* release governance needs more than “pass/fail a single scanner”

## Chainloop vs Sigstore / Cosign

They are not mutually exclusive.

* **Cosign** is great for signing and verifying artifacts and attestations.
* **Chainloop** is useful for organizing evidence, contracts, and policy around those materials.

A common real-world pattern is:

* sign artifacts with Cosign
* generate SBOM with Syft
* collect evidence and evaluate policy with an evidence layer

## Practical implementation tips

* start with a tiny contract and 2–3 required materials
* do not model every possible report on day one
* keep policies readable and few
* prefer digest-based artifact references
* use “warn then enforce” style rollout at the process level
* connect the evidence model to release approval, not only to dashboards

## Common mistakes

* treating evidence collection as a replacement for scanner quality
* collecting reports nobody uses
* using mutable tags instead of digests
* pushing policy too early without an exception path
* confusing “signed” with “safe”

## Related pages

* [📦 Software Supply Chain Foundations](/devsecops-cicd-and-supply-chain/index-1/software-supply-chain-foundations.md)
* [🧾 SCA, SBOM, and Supply Chain Tooling — Legacy vs Current](/devsecops-cicd-and-supply-chain/index-1/sca-sbom-and-supply-chain-tooling-legacy-vs-current.md)
* [✍️ Signing, Attestation, and Verification — Legacy vs Current](/devsecops-cicd-and-supply-chain/index-1/signing-attestation-and-verification-legacy-vs-current.md)
* [📦 Local Artifact Repository Scanning and JFrog Xray](/devsecops-cicd-and-supply-chain/index-1/local-artifact-repository-scanning-and-jfrog-xray.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.product-security.expert/devsecops-cicd-and-supply-chain/index-1/chainloop-and-supply-chain-evidence.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.