> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainloop.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Evidence Graph

> How Chainloop connects attestations from different workflows through the evidence and commits that they share, and how to query the result.

## Overview

Chainloop stores everything that you attest as a graph. You do not define the layout of your pipelines in advance, and you do not tell Chainloop which workflows are related. Chainloop builds the connections when it receives each [attestation](https://docs.chainloop.dev/concepts/attestations.md), from the data that the attestation contains.

Chainloop follows one rule: **two attestations that reference the same node are connected.**

A node is a piece of data in the graph, such as an artifact, a file, or a commit. Some examples of connections:

* Two workflow runs that attest the same container image are connected through the image.
* Two workflow runs on the same git commit are connected through the commit.

A workflow does not need to know about the other workflows. It only attests what it builds, scans, or deploys. The graph grows each time a workflow pushes an attestation.

## Nodes and Links

When Chainloop receives an attestation, it adds these nodes to the graph:

| Node | Identifier | Example |
| - | - | - |
| The attestation | Digest of the signed attestation, kind `ATTESTATION` | `sha256:f8d322ec...` |
| Each [material](https://docs.chainloop.dev/concepts/material-types.md) | Digest of the material content and its kind | A `CONTAINER_IMAGE` with the digest of the image, an `SBOM_CYCLONEDX_JSON` with the digest of the file |
| The git head commit | Commit hash, kind `GIT_HEAD_COMMIT` | `sha1:3f2a9c1...` |

Chainloop links the attestation to each of these nodes, in both directions. When a later attestation references a node that is already in the graph, Chainloop links it to the same node. In the diagrams on this page, an arrow goes from an attestation to a node that it references.

Chainloop identifies a node by its digest and its kind. As a result:

* A container image is identified by its image digest, not by its tag. Two images with the same tag and different content are two nodes.
* A `STRING` material is identified by the digest of its value. Two workflow runs that attest the same value, for example the same build ID, are connected.
* The CLI records the git head commit when it runs in a git repository. You do not need to add the commit as a material.

The graph covers one organization. Attestations in different organizations are not connected.

## Examples

### Build and Deploy Through a Container Image

A `ci` workflow builds a container image and attests it with its SBOM. Later, a `deploy-staging` workflow attests the same image before it deploys it. Both attestations reference the image digest, so Chainloop connects them.

```mermaid theme={"dark"}
graph LR
  B["Attestation: ci"] --> IMG["CONTAINER_IMAGE<br/>sha256:8edec5..."]
  B --> SBOM["SBOM_CYCLONEDX_JSON<br/>sha256:5a2a7d..."]
  D["Attestation: deploy-staging"] --> IMG
```

From the image, you can find the `ci` attestation, the SBOM, and each deploy attestation. From the deploy attestation, you can go back to the `ci` run that produced the image. [Model Your CI/CD Pipeline](https://docs.chainloop.dev/guides/model-ci-cd-pipeline.md) uses this link to stop a deployment when the build did not pass its policies.

### Security Scans Connected Through a Commit

Three workflows scan the same repository: a SAST scan, a dependency (SCA) scan, and a secrets scan. Each workflow runs in its own pipeline and attests its own report. None of them adds the commit as a material, but the CLI records the git head commit in each attestation. Chainloop connects all three through the commit.

```mermaid theme={"dark"}
graph LR
  S1["Attestation: sast"] --> C["GIT_HEAD_COMMIT<br/>sha1:3f2a9c..."]
  S2["Attestation: sca"] --> C
  S3["Attestation: secrets"] --> C
  S1 --> R1["SARIF<br/>sha256:7890ab..."]
  S2 --> R2["SARIF<br/>sha256:d4e5f6..."]
  S3 --> R3["SARIF<br/>sha256:12cd34..."]
```

From the commit, you can find all the scans that ran on that commit, and their policy results.

## What You Can Do with the Graph

The graph connects evidence that different teams, pipelines, and tools send at different times. Provenance, auditability, and control gates all use it.

### Provenance

Start from any node and follow the links to see where it came from and what happened to it. For example, from a container image that runs in production:

* Find the build that produced the image, and the commit that the build used.
* Find the SBOM, the scan reports, and the test results that other workflows attested for the same image or commit.
* Find each deployment workflow that attested the image.

You get this end-to-end view without a central definition of your pipelines. Each workflow only attests its own step.

### Auditability

Each node in the graph comes from a signed attestation, and each piece of evidence is stored under its content digest. An auditor can follow the same links as you. On the way, the auditor can check the signature of each attestation and the digest of each piece of evidence. The graph lets you answer audit questions with data, for example:

* Which evidence existed for this artifact before it was deployed?
* Which workflow runs touched this commit, and did they pass their policies?
* Which artifacts include this SBOM, and where were they deployed?

The graph also keeps the attestations that failed their policies, so the record includes the failures and the [bypasses](https://docs.chainloop.dev/concepts/control-gates.md#bypassing-control-gates), not only the successes.

### Control Gates

A [control gate](https://docs.chainloop.dev/concepts/control-gates.md) decides if a pipeline can continue. When the decision depends on what other workflows did, the gate reads the graph. For example, a deployment workflow can check that:

* the build workflow attested the same image with no policy violations, with the built-in [`upstream-check`](https://docs.chainloop.dev/reference/policies#upstream-check) policy
* an SBOM or a scan report exists for the image, with a custom policy that calls [`chainloop.discover`](https://docs.chainloop.dev/reference/builtin-functions#chainloop-discover)

The gate needs only the material that the deployment workflow already attests. It uses the link between the material in the current attestation and the evidence that the upstream workflows already sent. [Model Your CI/CD Pipeline](https://docs.chainloop.dev/guides/model-ci-cd-pipeline.md) shows a full example.

## Query the Graph

You can read the graph in four ways. Each one starts from a digest: of an artifact, a piece of evidence, an attestation, or a commit.

### Chainloop UI

Open a workflow run or an artifact and select the **Provenance** tab. The tab shows the graph around the node: the attestations that reference it, and the evidence and artifacts of those attestations.

To start from any digest, open **Labs > Trust Hub** and enter the digest. Trust Hub shows the same graph, and you can select a node to explore the graph from it.

### CLI

[`chainloop discover`](https://docs.chainloop.dev/cli/reference#chainloop-discover) returns a node and the nodes that link to it:

```bash theme={"dark"}
chainloop discover --digest sha256:8edec5932ca50412dfb50c5f55cbd4e31a735c19618749b909e2e8e311754c6a
```

For an attestation, the output includes its metadata: the workflow name, project, version, contract, and whether the run has policy violations. Use `--kind` to start from a specific kind of node, for example a commit:

```bash theme={"dark"}
chainloop discover --digest sha1:3f2a9c1b7e5d4a6f8c0b2d4e6f8a0c2e4b6d8f0a --kind GIT_HEAD_COMMIT
```

### API

The CLI calls the `ReferrerService` of the control plane API (`GET /discover/{digest}`). The API can also limit the results to a project, or to a project version. See the [API reference](https://docs.chainloop.dev/api-reference/overview.md) for authentication and the request fields.

### Policies

Policies read the graph during an attestation with the [`chainloop.discover`](https://docs.chainloop.dev/reference/builtin-functions#chainloop-discover) built-in function, which returns the same data as the CLI. The built-in `upstream-check` policy uses it. See [Control Gates](#control-gates) above for what these policies can check.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.