Material Types

Built-in Material Types

Chainloop supports the following pieces of evidence types that can be attached during the attestation process.

Name	ID	Description
Artifact Type	ARTIFACT	It represents a software artifact.
AsyncAPI specification	ASYNCAPI_SPEC	An AsyncAPI specification document (v2.6, v3.0)
Attestation	ATTESTATION	Existing Chainloop attestations.
BlackDuck SCA	BLACKDUCK_SCA_JSON
CERT/CC Dranzer	CERTCC_DRANZER	ActiveX/COM control test report, a single plain-text report or an archive (zip or tar.gz) holding the per-mode reports of one run (-b, -p, -s, -t)
Checkmarx One	CHECKMARX_JSON	Checkmarx One native JSON report (ScanResultsCollection)
Cobertura XML report	COBERTURA_XML	Code coverage report in Cobertura XML format
Container Image Reference	CONTAINER_IMAGE	A reference to a container image. It will get resolved and referenced by its sha
CSAF Informational Advisory	CSAF_INFORMATIONAL_ADVISORY
CSAF Security Advisory	CSAF_SECURITY_ADVISORY
CSAF Security Incident Report	CSAF_SECURITY_INCIDENT_RESPONSE
CSAF VEX	CSAF_VEX
Custom Evidence Type	EVIDENCE	Custom piece of evidence that doesn’t fit in any other category, for instance, an approval report in json format, etc.
GitHub Advanced Security Code scans	GHAS_CODE_SCAN
GitHub Advanced Security Dependency scans	GHAS_DEPENDENCY_SCAN
GitHub Advanced Security Secret scans	GHAS_SECRET_SCAN
GitLab Security report	GITLAB_SECURITY_REPORT	GitLab Security reports in JSON format
Gitleaks Secret Scan	GITLEAKS_JSON	Secrets detection report in the gitleaks JSON format, as produced by gitleaks or a compatible tool
GraphQL SDL schema	GRAPHQL_SPEC	GraphQL SDL schema definition
Helm Chart	HELM_CHART	A released Helm chart in tarball format
JaCoCo XML Report	JACOCO_XML
JUnit	JUNIT_XML
OpenAPI specification	OPENAPI_SPEC	An OpenAPI specification document (v3.0, v3.1)
OpenVEX	OPENVEX	Open Vulnerability and Exposure eXchange (OpenVEX) format
OpenSSF Scorecard	OSSF_SCORECARD_JSON	OpenSSF Scorecard results in JSON format
Oversecured scan report	OVERSECURED_JSON	Mobile (Android/iOS) scan report, whole-scan JSON export
PIT mutation testing report	PITEST_XML	Mutation testing report in PIT’s native XML format (mutations.xml)
Radamsa crashing inputs	RADAMSA_CRASHES	Radamsa crashing inputs, a single file or a crashes/ archive (tar.gz or zip)
Radamsa metadata log	RADAMSA_REPORT	Radamsa `-M` metadata log, one record per generated iteration
SARIF	SARIF
CycloneDX SBOM	SBOM_CYCLONEDX_JSON	A CycloneDX Software Bill of Materials (SBOM) in JSON format
SPDX SBOM	SBOM_SPDX_JSON	An SPDX Software Bill of Materials (SBOM) in JSON format
Key-Value metadata pairs	STRING
Sysinternals AccessChk	SYSINTERNALS_ACCESSCHK	Sysinternals AccessChk text output
Sysinternals Sigcheck	SYSINTERNALS_SIGCHECK	Sysinternals Sigcheck output in CSV format
TruffleHog secret scan	TRUFFLEHOG_JSON	Secret scanning report in TruffleHog JSONL format (one JSON finding per line)
PrismaCloud Twistcli Scan	TWISTCLI_SCAN_JSON
detect-secrets baseline	YELP_DETECT_SECRETS_BASELINE	detect-secrets baseline file
ZAP DAST zip report	ZAP_DAST_ZIP	Zap DAST report in zip format that matches the format returned from Zap’s GitHub Action
SLSA provenance attestation	SLSA_PROVENANCE	SLSA provenance file generated by GitHub or upstream slsa-generator
Chainloop Runner Context	CHAINLOOP_RUNNER_CONTEXT	Represents the runner context in which the attestation is crafted in a JSON format
Pull request metadata from GitHub or GitLab	CHAINLOOP_PR_INFO	Gathered automatically by the Chainloop CLI when a pull request or merge request is detected. Includes author identity with bot detection support
AI Agent Configuration	CHAINLOOP_AI_AGENT_CONFIG	AI agent configuration files gathered automatically via the `--collectors aiconfig` option
AI Coding Session	CHAINLOOP_AI_CODING_SESSION	AI coding session evidence captured automatically via `chainloop trace` hooks

See below an example on how to use them in your contract or refer to this guide to learn more about how to use them.

skynet.contract.yaml

apiVersion: chainloop.dev/v1
kind: Contract
metadata:
  name: skynet-contract
spec:
  # Arbitrary set of annotations can be added to the contract and will be part of the attestation
  annotations:
    - name: version
      value: oss # if the value is left empty, it will be required and resolved at attestation time
  # https://docs.chainloop.dev/concepts/operator/material-types
  materials:
    # CONTAINER_IMAGE kinds will get resolved to retrieve their repository digest
    - type: CONTAINER_IMAGE
      name:
        skynet-control-plane
        # The output flag indicates that the material will be part of the attestation subject
      output: true
      # Arbitrary annotations can be added to the material
      annotations:
        - name: component
          value: control-plane
        # The value can be left empty so it can be provided at attestation time
        - name: asset
    # ARTIFACT kinds will first get uploaded to your artifact registry via the built-in Content Addressable Storage (CAS)
    # Optional dockerfile
    - type: ARTIFACT
      name: dockerfile
      optional: true
    # SBOMs will be uploaded to the artifact registry and referenced in the attestation
    # Both SBOM_CYCLONEDX_JSON and SBOM_SPDX_JSON are supported
    - type: SBOM_CYCLONEDX_JSON
      name: skynet-sbom
    # CSAF_VEX and OPENVEX are supported
    - type: OPENVEX
      name: disclosure
    # And static analysis reports in SARIF format
    - type: SARIF
      name: static-out
    # or additional tools
    - type: TWISTCLI_SCAN_JSON
      name: scan-result

  # https://docs.chainloop.dev/concepts/policies
  policies:
    materials: # policies applied to materials
      - ref: file://cyclonedx-licenses.yaml
    attestation: # policies applied to the whole attestation
      - ref: https://github.com/chainloop/chainloop-dev/blob/main/docs/examples/policies/chainloop-commit.yaml # (2)

  # Env vars we want the system to resolve and inject during attestation initialization
  # Additional ones can be inherited from the specified runner context below
  envAllowList:
    - CUSTOM_VAR

  # Enforce in what runner context the attestation must happen
  # If not specified, the attestation crafting process is allowed to run anywhere
  runner:
    type: "GITHUB_ACTION"

Custom Material Types

When your data doesn’t fit any of the built-in types listed above, use the EVIDENCE material type. This is a general-purpose type that lets you attest arbitrary JSON data and run policies against it. Common use cases include in-house scanner output, approval reports, deployment manifests, or any structured data relevant to your supply chain.

Structure Guidelines

We recommend that custom evidence follows these conventions:

It must be in JSON format, since the policy engine only supports JSON.
The document should have an identifier and a clear separation between metadata and data.

Instead of this:

{
  "foo": "bar"
}

Structure it like this:

{
  "chainloop.material.evidence.id": "my-custom-evidence",
  "data": {
    "foo": "bar"
  }
}

This pattern lets you write policies that identify the evidence type, skip irrelevant evidence, or route to the correct validation logic. For example, a policy can skip evaluation if the evidence doesn’t match:

valid_input if {
    input["chainloop.material.evidence.id"] == "my-custom-evidence"
}

Example: Attesting a Release Approval Report

This example shows how to send an internal release approval record to Chainloop as custom evidence. Following the structure guidelines above, the approval report is wrapped with a descriptive identifier:

{
  "chainloop.material.evidence.id": "release-approval-report",
  "data": {
    "release": "my-service v1.4.0",
    "ticket": "CHANGE-4821",
    "approvals": [
      {
        "role": "engineering-manager",
        "approver": "[email protected]",
        "decision": "approved",
        "timestamp": "2025-11-03T09:12:00Z"
      },
      {
        "role": "security",
        "approver": "[email protected]",
        "decision": "approved",
        "timestamp": "2025-11-03T11:47:00Z"
      }
    ]
  }
}

In your workflow contract, declare the material as EVIDENCE:

apiVersion: chainloop.dev/v1
kind: Contract
metadata:
  name: release-approval-contract
spec:
  materials:
    - type: EVIDENCE
      name: release-approval
  policies:
    materials:
      - ref: file://require-two-approvals.yaml

Then attach the evidence during attestation:

chainloop att add --name release-approval --value release-approval.json

Since no built-in policy understands your document’s shape, write a custom policy to validate it — for example, one that requires an approval from the security role before the attestation can be pushed.

Importing SonarQube Findings

To bring SonarQube results into an attestation, use the chainloop transform sonarqube command. It fetches issues and Security Hotspots from the SonarQube REST API, enriches them with CWE IDs, and writes SARIF 2.1.0, which you attest as a SARIF material.

chainloop transform is part of the Enterprise Edition CLI.

export SONARQUBE_URL=https://sonarqube.example.com
export SONARQUBE_TOKEN=<your-token>

chainloop transform sonarqube \
  --project my-service \
  --branch main \
  --output-file sonarqube-results.sarif

By default the command fetches only Security-quality issues that are OPEN, plus HIGH and MEDIUM priority hotspots. Broaden the scope with --software-qualities MAINTAINABILITY,RELIABILITY to also cover dead, unreachable, and unused code, or narrow it to specific rule keys with --rules. See the command reference for the full flag list. Declare the result as a SARIF material in your contract and validate it with the built-in sast-scan-present and sast policies:

apiVersion: chainloop.dev/v1
kind: Contract
metadata:
  name: sonarqube-contract
spec:
  materials:
    - type: SARIF
      name: sast-scan
  policies:
    attestation:
      - ref: sast-scan-present
    materials:
      - ref: sast
        with:
          severity: "HIGH"

The sast-scan-present policy checks that a SAST scan material is present in the attestation, while the sast policy evaluates the actual findings against a severity threshold. Then attach the report during attestation:

chainloop att add --name sast-scan --value sonarqube-results.sarif

Getting Started

Concepts

Guides

References

Misc

Built-in Material Types

Custom Material Types

Structure Guidelines

Example: Attesting a Release Approval Report

Importing SonarQube Findings

​Built-in Material Types

​Custom Material Types

​Structure Guidelines

​Example: Attesting a Release Approval Report

​Importing SonarQube Findings

Built-in Material Types

Custom Material Types

Structure Guidelines

Example: Attesting a Release Approval Report

Importing SonarQube Findings