# Review dependency alerts

See which locked dependencies have known vulnerabilities, scan again, and dismiss what does not apply.

The lockfiles and manifests on the default branch (`package-lock.json`, `pnpm-lock.yaml`,
`yarn.lock`, `bun.lock`, `go.mod`, `go.sum`, `Cargo.lock`, `poetry.lock`, `Pipfile.lock`,
`uv.lock`, `requirements.txt`, `Gemfile.lock`, `composer.lock`, `pom.xml`, `gradle.lockfile` and
others) are matched against the vulnerability database a minute after a push and once a day.
Lockfiles under `node_modules`, `vendor`, `third_party` and fixture or `testdata` directories are
skipped. Each finding names the package, the installed and the fixed version, the advisory and
the lockfile. The examples use the repository id `5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60`.

## Prerequisites

- Permission for `git:ListSecurityAlerts` to read alerts, and `git:UpdateSecurityAlert` to scan,
  dismiss or reopen.
- In the Deutsche Cloud Console, also `git:GetRepository` to open the repository's **Security** section
  (without it the page is not found).
- Dependency alerts are on for the repository (the default). With them off, **Scan now** is not
  shown and a scan is refused with 409 `Dependency alerts are off for this repository`.

## Scan now

**Console**
1. In the repository, choose **Security**.
2. On **Overview**, next to **Dependency alerts**, choose **Scan now**. The line under
   **Dependency alerts** says when the scan is running and when it ends; the findings are listed
   under **Dependencies**.

**CLI**
```sh
dcloud git security scan-dependencies 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60
```

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/security/dependency-alerts/scan
```

## Dismiss an alert

A dismissal takes a reason (`false positive`, `not exploitable`, `accepted risk`, `fix later`, or
your own words) and an optional comment, and stays through later scans until you reopen the
alert.

**Console**
1. In the repository, choose **Security**, then **Dependencies**.
2. Choose **All findings**, then choose the finding.
3. Under **Dismiss**, choose a reason and (optional) enter a comment.
4. Choose **Dismiss**. The alert leaves the list; **Show … dismissed** lists it again, with
   **Reopen**.

**CLI**
```sh
dcloud git security set-dependency-alert 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  f0e1d2c3-b4a5-4968-8776-655443322110 --state dismissed --reason "not exploitable"
```

**API**
```http
PATCH /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/security/dependency-alerts/f0e1d2c3-b4a5-4968-8776-655443322110
{ "state": "dismissed", "reason": "not exploitable" }
```

## Result

An open finding the next scan no longer reports becomes `fixed`; one that comes back is open
again.

For `npm` and `pnpm` lockfiles, **Open a fix pull request** on a package (or **Fix all fixable**)
has the platform push a branch that bumps the versions and open a pull request, so CI runs; it
never merges (`dcloud git security fix-dependencies`, which also needs `git:PushRepository` and
`git:CreatePullRequest`). A second fix for a package whose fix pull request is open is refused
with 409 `A fix pull request is already open: #<n>`. For other ecosystems, upgrade to the fixed
version yourself.

## Fix automatically

A repository can open that fix pull request by itself. **Automatic fix pull requests** on the
**Overview** takes `exploited` (an alert on a vulnerability CISA lists as exploited in the wild) or
`critical` (those, and critical alerts with a fixed version); `off` is the default. The pull
request bumps to the lowest fixed version, runs as the person who turned the setting on, and says
so in the commit. Their permission is checked at every run: when they may no longer open pull
requests, the setting turns itself off and the page says why. One automatic fix pull request is
open at a time.

**Merge them automatically** also turns on auto-merge for that pull request, as the same person:
it merges once the required checks pass, and an app that deploys from the branch redeploys. It can
only be turned on when a protection rule on the default branch requires status checks (otherwise
"when the checks pass" would always be true), and a bump across a major version always waits for a
person.

```sh
dcloud git security update-settings 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  --auto-fix exploited --auto-fix-merge
```

## Related

- [Repository security features](security-features.md)
- `git.security.list-dependency-alerts` · `dcloud git security list-dependency-alerts`
