> ## 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.

# Set up Vulnerability Management in your project

> Wire Vulnerability Management and Risk Assessment onto a project

This guide walks through wiring [Vulnerability Management and Risk Assessment](/concepts/vulnerability-management) onto a project. After the first workflow run, the **Security** tab fills in: deduplicated findings, components, artifacts, risk assessments, VEX feed, and PDF reports.

<Note>
  For the full picture of how this feature works — data model, AI agents, VEX outputs, compliance — see [Vulnerability Management and Risk Assessment](/concepts/vulnerability-management).
</Note>

## What you're wiring up

Your CI produces the inputs; Chainloop does the rest:

| Stage          | Owner                  | What happens                                                                                                     |
| -------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Ingest**     | Your CI/CD             | Attest a vulnerability scan report — and, optionally, an SBOM and an artifact reference (e.g. a container image) |
| **Normalize**  | Chainloop policy       | Deduplicate findings across scanners and runs, extract components and artifacts, scope to the project version    |
| **Decide**     | Your team or AI agents | Triage findings and record risk assessments                                                                      |
| **Distribute** | Chainloop              | Produce a live VEX feed, PDF reports, and inputs to control gates                                                |
| **Audit**      | Chainloop              | Sign 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.

| Evidence                      | Required | Supported formats                                                                                                                                                                                      | Unlocks                                                                                                      |
| ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| **Vulnerability scan report** | Yes      | **SARIF** from Trivy, Grype, Stackhawk, Prisma Cloud, WizCLI, or Snyk; **BlackDuck SCA JSON**; **TwistCLI scan JSON**; **GHAS dependency scan**; or a **CycloneDX SBOM with vulnerabilities embedded** | Findings, severity, KEV flag, fixability                                                                     |
| **SBOM**                      | Optional | Any **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 reference**        | Optional | Container 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](/reference/policies#vulnerabilities).

## 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](/concepts/workflows) 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](/concepts/contracts):

```yaml chainloop.contract.yaml theme={"dark"}
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:

```bash theme={"dark"}
# 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](/concepts/attestations).

<Note>
  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.
</Note>

### 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

* **Attach a [compliance framework](/concepts/compliance-frameworks)** to your product — for example, the [Cyber Resilience Act (CRA)](/reference/cyber-resilience-act), [SSDF](/reference/ssdf), or your own best-practices framework — so the same SBOMs, scanner reports, and assessments drive your compliance posture automatically
* **Enable the Vulnerabilities Agent** to draft assessments automatically *(Preview)*
* **Wire [notifications](/concepts/notifications)** to Slack, Teams, or email
* **Update your [control-gate policies](/concepts/control-gates)** to read assessments, so dismissed findings stop blocking the release
* **Learn more about [Vulnerability Management and Risk Assessment](/concepts/vulnerability-management)** — the data model, AI agents, VEX outputs, and compliance mapping

## Troubleshooting and FAQ

<AccordionGroup>
  <Accordion title="I don't see any vulnerabilities">
    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.
  </Accordion>

  <Accordion title="I don't see any components">
    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.
  </Accordion>
</AccordionGroup>