> ## 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. | | | [Attestation]() | ATTESTATION | Existing Chainloop attestations. | | | [BlackDuck SCA]() | BLACKDUCK\_SCA\_JSON | | | | [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 | Gitleaks secrets detection report in JSON format | | | [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 | | | | [OpenVEX](https://github.com/openvex) | OPENVEX | Open Vulnerability and Exposure eXchange (OpenVEX) format | | | [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 | | | | [PrismaCloud Twistcli Scan](https://docs.prismacloud.io/en/compute-edition/30/admin-guide/tools/twistcli-scan-images) | TWISTCLI\_SCAN\_JSON | | | | [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 aiagent` 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 security scanner results (e.g. SonarQube, custom SAST tools), 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: Importing Issues from the SonarQube API This example shows how to extract issues from SonarQube's API and send them to Chainloop as custom evidence. The end result is a JSON file that wraps the SonarQube API response in the recommended evidence format: ```json theme={"dark"} { "chainloop.material.evidence.id": "sonarqube-search-issues-api", "data": { "total": 2, "p": 1, "ps": 500, "paging": { "pageIndex": 1, "pageSize": 500, "total": 2 }, "issues": [ { "key": "AYx...", "rule": "java:S1234", "severity": "CRITICAL", "component": "com.example:my-service:src/main/java/App.java", "message": "Refactor this method to reduce its Cognitive Complexity.", "status": "OPEN", "type": "CODE_SMELL" }, { "key": "AYy...", "rule": "java:S5678", "severity": "MAJOR", "component": "com.example:my-service:src/main/java/Handler.java", "message": "Remove this unused private field.", "status": "OPEN", "type": "CODE_SMELL" } ] } } ``` Here's how to get there: #### Step 1: Export issues from the SonarQube API Use the [SonarQube Issues Search API](https://next.sonarqube.com/sonarqube/web_api/api/issues/search) to export issues for your project. You can filter by severity, status, and other parameters: ```bash theme={"dark"} curl -s -u "$SONARQUBE_TOKEN:" \ "$SONARQUBE_URL/api/issues/search?componentKeys=$PROJECT_KEY&resolved=false&severities=CRITICAL,MAJOR&ps=500" \ > sonarqube-raw.json ``` #### Step 2: Wrap the response in evidence format Wrap the API response using the recommended structure with a descriptive identifier: ```bash theme={"dark"} jq '{ "chainloop.material.evidence.id": "sonarqube-search-issues-api", "data": . }' sonarqube-raw.json > sonarqube-evidence.json ``` #### Step 3: Add it to your contract and attest In your workflow contract, declare the material as `EVIDENCE` and use the built-in [`sast-scan-present`](/reference/policies#sast-scan-present) and [`sast`](/reference/policies#sast) policies to validate it: ```yaml theme={"dark"} apiVersion: chainloop.dev/v1 kind: Contract metadata: name: sonarqube-contract spec: materials: - type: EVIDENCE name: sonarqube-issues 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 evidence during attestation: ```bash theme={"dark"} chainloop att add --name sonarqube-issues --value sonarqube-evidence.json ``` You can also write [custom policies](/guides/custom-policies) for additional validation logic specific to your needs.