Skip to main content

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.
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. 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 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. 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.
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, not only the successes.

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-check policy
  • an SBOM or a scan report exists for the image, with a custom policy that calls 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 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 returns a node and the nodes that link to it:
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:

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 for authentication and the request fields.

Policies

Policies read the graph during an attestation with the chainloop.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.