> ## 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.
# 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](https://www.asyncapi.com/docs/reference/specification/latest) | ASYNCAPI\_SPEC | An AsyncAPI specification document (v2.6, v3.0) |
| Attestation | ATTESTATION | Existing Chainloop attestations. |
| BlackDuck SCA | BLACKDUCK\_SCA\_JSON | |
| [CERT/CC Dranzer](https://github.com/CERTCC/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](https://github.com/Checkmarx/ast-cli/blob/main/internal/wrappers/results-json.go) | CHECKMARX\_JSON | Checkmarx One native JSON report (ScanResultsCollection) |
| [Cobertura XML report](https://github.com/cobertura/cobertura) | COBERTURA\_XML | Code coverage report in Cobertura XML format |
| [Container Image Reference](https://github.com/opencontainers/image-spec) | CONTAINER\_IMAGE | A reference to a container image. It will get resolved and referenced by its sha |
| [CSAF Informational Advisory](https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html#43-profile-3-informational-advisory) | CSAF\_INFORMATIONAL\_ADVISORY | |
| [CSAF Security Advisory](https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html#44-profile-4-security-advisory) | CSAF\_SECURITY\_ADVISORY | |
| [CSAF Security Incident Report](https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html#42-profile-2-security-incident-response) | CSAF\_SECURITY\_INCIDENT\_RESPONSE | |
| [CSAF VEX](https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html#45-profile-5-vex) | CSAF\_VEX | |
| [Custom Evidence Type](#custom-material-types) | 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](https://docs.github.com/en/rest/code-scanning/code-scanning?apiVersion=2022-11-28) | GHAS\_CODE\_SCAN | |
| [GitHub Advanced Security Dependency scans](https://docs.github.com/en/rest/dependabot/alerts?apiVersion=2022-11-28) | GHAS\_DEPENDENCY\_SCAN | |
| [GitHub Advanced Security Secret scans](https://docs.github.com/en/rest/secret-scanning/secret-scanning?apiVersion=2022-11-28) | GHAS\_SECRET\_SCAN | |
| [GitLab Security report](https://docs.gitlab.com/ee/user/application_security/) | GITLAB\_SECURITY\_REPORT | GitLab Security reports in JSON format |
| [Gitleaks Secret Scan](https://github.com/gitleaks/gitleaks) | GITLEAKS\_JSON | Secrets detection report in the gitleaks JSON format, as produced by gitleaks or a compatible tool |
| [GraphQL SDL schema](https://spec.graphql.org/) | GRAPHQL\_SPEC | GraphQL SDL schema definition |
| [Helm Chart](https://helm.sh/docs/topics/charts/) | HELM\_CHART | A released Helm chart in tarball format |
| [JaCoCo XML Report](https://www.jacoco.org/jacoco/trunk/doc/) | JACOCO\_XML | |
| [JUnit](https://www.ibm.com/docs/en/developer-for-zos/14.1?topic=formats-junit-xml-format) | JUNIT\_XML | |
| [OpenAPI specification](https://spec.openapis.org/oas/latest.html) | OPENAPI\_SPEC | An OpenAPI specification document (v3.0, v3.1) |
| [OpenVEX](https://github.com/openvex) | OPENVEX | Open Vulnerability and Exposure eXchange (OpenVEX) format |
| [OpenSSF Scorecard](https://github.com/ossf/scorecard) | OSSF\_SCORECARD\_JSON | OpenSSF Scorecard results in JSON format |
| [Oversecured scan report](https://docs.oversecured.com/docs/guide-exporting-reports) | OVERSECURED\_JSON | Mobile (Android/iOS) scan report, whole-scan JSON export |
| [PIT mutation testing report](https://pitest.org/) | PITEST\_XML | Mutation testing report in PIT's native XML format (mutations.xml) |
| [Radamsa crashing inputs](https://gitlab.com/akihe/radamsa) | RADAMSA\_CRASHES | Radamsa crashing inputs, a single file or a crashes/ archive (tar.gz or zip) |
| [Radamsa metadata log](https://gitlab.com/akihe/radamsa) | RADAMSA\_REPORT | Radamsa `-M` metadata log, one record per generated iteration |
| [SARIF](https://docs.oasis-open.org/sarif/sarif/v2.1.0/) | SARIF | |
| [CycloneDX SBOM](https://github.com/CycloneDX/specification) | SBOM\_CYCLONEDX\_JSON | A CycloneDX Software Bill of Materials (SBOM) in JSON format |
| [SPDX SBOM](https://spdx.dev/specifications/) | SBOM\_SPDX\_JSON | An SPDX Software Bill of Materials (SBOM) in JSON format |
| Key-Value metadata pairs | STRING | |
| [Sysinternals AccessChk](https://learn.microsoft.com/en-us/sysinternals/downloads/accesschk) | SYSINTERNALS\_ACCESSCHK | Sysinternals AccessChk text output |
| [Sysinternals Sigcheck](https://learn.microsoft.com/en-us/sysinternals/downloads/sigcheck) | SYSINTERNALS\_SIGCHECK | Sysinternals Sigcheck output in CSV format |
| [TruffleHog secret scan](https://github.com/trufflesecurity/trufflehog) | TRUFFLEHOG\_JSON | Secret scanning report in TruffleHog JSONL format (one JSON finding per line) |
| [PrismaCloud Twistcli Scan](https://docs.prismacloud.io/en/compute-edition/30/admin-guide/tools/twistcli-scan-images) | TWISTCLI\_SCAN\_JSON | |
| [detect-secrets baseline](https://github.com/Yelp/detect-secrets) | YELP\_DETECT\_SECRETS\_BASELINE | detect-secrets baseline file |
| [ZAP DAST zip report](https://github.com/marketplace/actions/zap-baseline-scan) | ZAP\_DAST\_ZIP | Zap DAST report in zip format that matches the format returned from Zap's GitHub Action |
| [SLSA provenance attestation](https://slsa.dev/spec/v1.1/provenance) | 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](https://github.com/chainloop-dev/chainloop/blob/main/internal/schemavalidators/internal_schemas/prinfo) | 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](/guides/ai-config-collector) | CHAINLOOP\_AI\_AGENT\_CONFIG | AI agent configuration files gathered automatically via the `--collectors aiconfig` option |
| [AI Coding Session](/concepts/ai-coding-sessions) | 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](/concepts/contracts#writing-contracts) to learn more about how to use them.
```yaml skynet.contract.yaml theme={"dark"}
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](/concepts/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](/concepts/policies) only supports JSON.
* The document should have an **identifier** and a clear **separation between metadata and data**.
Instead of this:
```json theme={"dark"}
{
"foo": "bar"
}
```
Structure it like this:
```json theme={"dark"}
{
"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:
```rego theme={"dark"}
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:
```json theme={"dark"}
{
"chainloop.material.evidence.id": "release-approval-report",
"data": {
"release": "my-service v1.4.0",
"ticket": "CHANGE-4821",
"approvals": [
{
"role": "engineering-manager",
"approver": "alice@example.com",
"decision": "approved",
"timestamp": "2025-11-03T09:12:00Z"
},
{
"role": "security",
"approver": "bob@example.com",
"decision": "approved",
"timestamp": "2025-11-03T11:47:00Z"
}
]
}
}
```
In your workflow contract, declare the material as `EVIDENCE`:
```yaml theme={"dark"}
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:
```bash theme={"dark"}
chainloop att add --name release-approval --value release-approval.json
```
Since no built-in policy understands your document's shape, write a [custom policy](/guides/custom-policies) 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](https://docs.oasis-open.org/sarif/sarif/v2.1.0/), which you attest as a `SARIF` material.
`chainloop transform` is part of the [Enterprise Edition CLI](/command-line-reference/cli-ee-reference#chainloop-transform-sonarqube).
```bash theme={"dark"}
export SONARQUBE_URL=https://sonarqube.example.com
export SONARQUBE_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](/command-line-reference/cli-ee-reference#chainloop-transform-sonarqube) 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`](/reference/policies#sast-scan-present) and [`sast`](/reference/policies#sast) policies:
```yaml theme={"dark"}
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:
```bash theme={"dark"}
chainloop att add --name sast-scan --value sonarqube-results.sarif
```