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, 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.
Nodes and Links
When Chainloop receives an attestation, it adds these nodes to the graph:
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
STRINGmaterial 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.
Examples
Build and Deploy Through a Container Image
Aci 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.
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 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. 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.
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?
Control Gates
A control gate 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-checkpolicy - an SBOM or a scan report exists for the image, with a custom policy that calls
chainloop.discover
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 returns a node and the nodes that link to it:
--kind to start from a specific kind of node, for example a commit:
API
The CLI calls theReferrerService 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 for authentication and the request fields.
Policies
Policies read the graph during an attestation with thechainloop.discover built-in function, which returns the same data as the CLI. The built-in upstream-check policy uses it. See Control Gates above for what these policies can check.