Skip to main content

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.

This guide walks through wiring Vulnerability Management and Risk Assessment onto a project. After the first workflow run, the Security tab fills in: deduplicated findings, components, artifacts, risk assessments, VEX feed, and PDF reports.
For the full picture of how this feature works — data model, AI agents, VEX outputs, compliance — see Vulnerability Management and Risk Assessment.

​
What you’re wiring up

Your CI produces the inputs; Chainloop does the rest:
StageOwnerWhat happens
IngestYour CI/CDAttest a vulnerability scan report — and, optionally, an SBOM and an artifact reference (e.g. a container image)
NormalizeChainloop policyDeduplicate findings across scanners and runs, extract components and artifacts, scope to the project version
DecideYour team or AI agentsTriage findings and record risk assessments
DistributeChainloopProduce a live VEX feed, PDF reports, and inputs to control gates
AuditChainloopSign every signal — evidence, policy evaluation, every revision of every assessment

​
Pieces of Evidence Used

Only the vulnerability report is required. The other two are optional but unlock additional views and traceability.
EvidenceRequiredSupported formatsUnlocks
Vulnerability scan reportYesSARIF from Trivy, Grype, Stackhawk, Prisma Cloud, WizCLI, or Snyk; BlackDuck SCA JSON; TwistCLI scan JSON; GHAS dependency scan; or a CycloneDX SBOM with vulnerabilities embeddedFindings, severity, KEV flag, fixability
SBOMOptionalAny CycloneDX JSON (SBOM_CYCLONEDX_JSON) or SPDX JSON (SBOM_SPDX_JSON). Tool-agnostic: Syft, Trivy, cdxgen, Maven/Gradle plugins all work.Components view, package PURLs, and the project/version scoping that lets one assessment cover many releases
Artifact referenceOptionalContainer image digest (ghcr.io/...@sha256:...)Each finding links back to the exact build output it came from
A CycloneDX SBOM that carries vulnerabilities can cover the vuln-report and SBOM inputs in one file. Without an artifact reference, Chainloop uses the one declared inside the SBOM, but it won’t be tied to an attested build. The full list of accepted material types and the policies that consume them lives in the vulnerabilities policy reference.

​
1. Instrument your CI to populate the Security tab

Wire your CI/CD pipeline to attest the vulnerability report (and any optional materials). Once the workflow runs, the Security tab fills in.

​
Prerequisites

  • A Chainloop project and workflow for the artifact you want to track
  • A vulnerability report in one of the supported formats listed above (Trivy and Grype produce these out of the box)
  • Optional but recommended: an SBOM (CycloneDX JSON or SPDX JSON) to populate the Components view, and a container image reference from your build so findings trace back to a specific attested build output

​
Add the policy group to your contract

Reference the built-in vulnerability-management policy group in your workflow contract:
chainloop.contract.yaml
apiVersion: chainloop.dev/v1
kind: Contract
metadata:
  name: vulnerabilities
spec:
  policyGroups:
    - ref: vulnerability-management
      with:
        severity: "HIGH"   # optional: ignore findings below this level

​
Attest your materials

Inside your CI/CD pipeline, initialize an attestation, add the vulnerability report (plus any optional materials), and push it to Chainloop: 
# Initialize the attestation against your workflow and contract
chainloop attestation init --workflow my-workflow --project my-project --contract my-contract

# Add vulnerability scan report (required)
chainloop attestation add --name vuln-report --value trivy-report.json

# Add SBOM (optional — populates the Components view)
chainloop attestation add --name sbom --value sbom.cyclonedx.json

# Add container image reference (optional — links findings to attested builds)
chainloop attestation add --name image --value ghcr.io/acme/app@sha256:...

# Sign and push the attestation
chainloop attestation push
For the full set of options (signing modes, runner detection, dry-run, kms backends, and more), see Attestations.
If your SBOM already contains vulnerability data (a CycloneDX file with both components and vulnerabilities), you can skip the separate vuln-report attestation. Chainloop extracts findings directly from the SBOM.

​
Run the workflow

After the first run lands and the policy evaluates the evidence, the Security tab fills in:
  • Components as soon as the SBOM is parsed
  • Vulnerabilities when the scan report runs through the policy
  • Artifacts under the image reference
  • Reports with PDFs and VEX once you approve assessments

​
2. Perform your first risk assessment

With findings flowing into the Security tab, walk through the triage loop end-to-end on a single CVE so you’ve seen every step before scaling up.
  1. Open Overview and check the unassessed Critical/High count.
  2. Click View Unassessed to land on the filtered Vulnerabilities list.
  3. Open a finding and write (or accept the agent’s draft) assessment.
  4. Approve the assessment. The finding moves out of the active backlog.
  5. Share the auto-generated VEX feed URL with your customers and control gates.

​
Going further

​
Troubleshooting and FAQ

Two things to check:
  • Confirm your vulnerability report is being evaluated by the built-in vulnerability-management policy group. Vulnerabilities only surface when a policy parses the report — without it, the material is attested but not turned into findings.
  • Make sure you’re on the Enterprise Edition CLI v1.73.0 or later. Earlier versions don’t emit findings into the Security tab.
Components are extracted from the SBOM. If the Components view is empty, your attestation is missing an SBOM material — add a SBOM_CYCLONEDX_JSON (or SBOM_SPDX_JSON) to the run and re-attest.