> ## 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. Your CI or a Chainloop built-in scanner attests a vulnerability report, a policy turns it into findings, and the **Security** tab fills in: deduplicated findings, components, artifacts, risk assessments, VEX feed, and PDF reports.

## 1. Get a vulnerability report into Chainloop

Findings come from a workflow that attests a vulnerability report. The quickest way to create one is from a [workflow template](/concepts/workflow-templates): in your project, click **Create Workflow** and search for "vulnerability". Three templates cover the three ways to produce the report:

<Frame>
  <img src="https://mintcdn.com/chainloop/KklhDFP_zAoMZ57V/guides/img/vulnerability-management/choose-template.png?fit=max&auto=format&n=KklhDFP_zAoMZ57V&q=85&s=c7de6c919e3af5ca181dc4dd27ed3e22" alt="Create Workflow template picker filtered by 'vulnerabil', showing the Vulnerability Scan and Vulnerability Scan from SBOMs templates under the Automated by Chainloop tab, next to the Manual push from your CI tab" width="878" height="992" data-path="guides/img/vulnerability-management/choose-template.png" />
</Frame>

| Template                          | Tab                      | Where the report comes from                                                                                                                  |
| --------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Vulnerability Scan**            | Automated by Chainloop   | Chainloop builds an SBOM from your connected repository with syft and scans it with grype, periodically and on pull requests. No CI changes. |
| **Vulnerability Scan from SBOMs** | Automated by Chainloop   | Chainloop periodically scans the SBOMs already attested in the project with grype. No access to your source needed.                          |
| **Vulnerability Scan**            | Manual push from your CI | Your own scanner (Trivy, Grype, Snyk, and so on) produces the report and your pipeline pushes it with the Chainloop CLI.                     |

All three attach the same `vulnerability-management` policy group, so the **Security** tab looks the same whichever you pick. Each exposes a `severity` input (default `HIGH`) that sets the lowest severity ingested as a finding.

### Automated by Chainloop

Pick either automated template, choose its run modes and severity in **Configure**, and you're done. The scan runs server-side against a repository connected through GitHub or GitLab. [Generate and Continuously Scan SBOMs](/guides/generate-and-scan-sboms) walks through both modes, and [Built-in Scanners](/reference/scanners#vulnerability-scan) lists their inputs and the materials they produce.

### Manual push from your CI

Pick **Vulnerability Scan** under the **Manual push from your CI** tab. Chainloop creates the workflow and this [contract](/concepts/contracts) for it:

```yaml chainloop.contract.yaml theme={"dark"}
apiVersion: chainloop.dev/v1
kind: Contract
metadata:
  name: vulnerabilities
spec:
  materials:
    - type: SARIF
      name: vulnerability-report
    - type: SBOM_CYCLONEDX_JSON
      name: sbom
      optional: true
  policies:
    attestation:
      - ref: source-commit   # verifies the commit that produced the report
    materials:
      - ref: cves-in-kev     # fails the run on CVEs listed in the CISA KEV catalog
  policyGroups:
    - ref: vulnerability-management
      with:
        severity: "HIGH"   # entries below this level never become findings
```

If you already have a workflow, add the `policyGroups` block to its contract instead.

Only the vulnerability report is required. The other two materials are optional but unlock additional views and traceability; for a report format other than SARIF, change the `vulnerability-report` material type accordingly.

| 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:...`), declared as a `CONTAINER_IMAGE` material                                                                                                            | Each finding links back to the exact build output it came from                                               |

A CycloneDX SBOM that carries vulnerabilities covers the 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.

#### 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
chainloop attestation init --workflow my-workflow --project my-project

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

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

### Run the workflow

Whichever path you chose, once 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.

## Next Steps

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

## 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 or the `vulnerabilities` policy. Vulnerabilities only surface when a policy parses the report — without it, the material is attested but not turned into findings. If neither is attached, add one to the workflow's [contract](/concepts/contracts) and re-run.
    * 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 see fewer vulnerabilities than my scanner reports">
    Expected. Entries below the policy's `severity` threshold are never ingested, and entries for the same vulnerability and package collapse into one finding. To see lower severities, lower `severity` in the workflow's contract (or the template's **Configure** panel) and re-run. See [What becomes a finding](/concepts/vulnerability-management#what-becomes-a-finding).
  </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>