> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Scan Go, npm and container dependencies for vulnerabilities

> Fail CI on vulnerable Go and npm dependencies with govulncheck and npm audit, accept one advisory at a time with a reason and expiry date, and scan the image.

By the end of this guide, a pull request fails when your Go code calls a known-vulnerable function or a frontend depends on a package with a high or critical advisory. When an advisory has no fix and cannot reach your code, you accept that one advisory in `forge.yaml` with a reason and an expiry date, and the gate fails again on that date.

`reliant forge ci vuln-scan` runs govulncheck over every Go module in the project and `npm audit` in every frontend, then makes the pass or fail decision itself, so it can honor reviewed exemptions that neither scanner supports on its own.

## Before you begin

* A Forge project, such as the one from [Add a database table with a CRUD API and pages](https://docs.reliantlabs.io/guides/forge/add-table-crud-api-pages.md). The gate it runs in is set up in [Gate pull requests on lint, tests and generated-code drift](https://docs.reliantlabs.io/guides/forge/gate-prs-forge-lint-tests.md).
* Forge v1.6.1 or later (`reliant forge --version` inside the project).
* Network access: both scanners download advisory data on every run.

**1. Run the scan the way CI does**

The gate runs the scan as two rows, `vuln-go` and `vuln-npm`, and builds govulncheck at forge's pinned version on first use:

```bash terminal theme={null}
task ci
```

```text theme={null}
  vuln-go            PASS        3.8s
  vuln-npm           FAIL       400ms  exit status 1; log: tmp/ci/all/vuln-npm.log
```

These rows are never served from the gate's verdict cache, because advisories change daily. To run the command on its own, put govulncheck on your `PATH` first. Without it the command refuses rather than report a pass it did not check:

```text theme={null}
forge ci vuln-scan: govulncheck is not on PATH, so the Go vulnerability gate cannot run — refusing to report a pass it did not verify.
```

```bash terminal theme={null}
go install golang.org/x/vuln/cmd/govulncheck@v1.7.0
reliant forge ci vuln-scan          # both scanners; --go or --npm for one
```

`reliant forge tools pins` prints the govulncheck version the gate uses.

**2. Fix a Go finding**

govulncheck fails only on advisories your code calls, not on every vulnerable module in `go.sum`. A package that parses YAML with an old `gopkg.in/yaml.v2`:

```text theme={null}
Running govulncheck ./... in .
  .: 3 called vulnerabilit(ies)
Running govulncheck ./... in gen
  ✓ gen: no called vulnerabilities
  ❌ GO-2020-0036 (gopkg.in/yaml.v2@v2.2.2, in .)
      Excessive resource consumption in YAML parsing in gopkg.in/yaml.v2
  ❌ GO-2021-0061 (gopkg.in/yaml.v2@v2.2.2, in .)
      Denial of service in gopkg.in/yaml.v2
  ❌ GO-2022-0956 (gopkg.in/yaml.v2@v2.2.2, in .)
      Excessive resource consumption in gopkg.in/yaml.v2
❌ govulncheck failed: govulncheck found 3 vulnerability/ies your code calls
```

Upgrade the module and scan again:

```bash terminal theme={null}
go get gopkg.in/yaml.v2@latest
reliant forge ci vuln-scan --go
```

```text theme={null}
✅ Vulnerability scan passed — govulncheck (Go modules + stdlib, 2 modules: ., gen).
```

Every Go module is scanned, including nested ones such as `gen/`. `--root-module` limits it to the root.

**3. Read an npm finding**

`npm audit` fails on high and critical advisories and prints lower ones without failing. The scaffolded frontend of a forge v1.6.1 project reports a real one:

```text theme={null}
Running npm audit in frontends/web ...
  🧹 exemption GHSA-vfj7-8cjw-p6xm matched nothing in this scan — the advisory is gone or now unreachable. Remove it from forge.yaml (ci.vuln_scan.exemptions) so it cannot silently accept a future finding.
  ❌ GHSA-mrhx-c7xc-m3w5 (zod <4.6.6, high, in web)
      Zod can exhaust memory while validating oversized constrained collections
      https://github.com/advisories/GHSA-mrhx-c7xc-m3w5
❌ npm audit failed: npm audit found 1 advisory/ies at or above "high"
```

The first line is an exemption the scaffold wrote that no longer matches anything, so delete it. Upgrade the package when a fixed release exists, or use an npm `overrides` entry when only a transitive dependency has the fix. Here the fix is zod 4, a new major that changes the generated forms. Frontends scaffolded by forge v1.8.0 or later already use zod 4, and its upgrade notes cover porting existing forms.

**4. Accept one advisory with an expiry date**

Until you can upgrade, accept the advisory by its ID. Each entry needs a reason and an `expires` date:

```yaml forge.yaml theme={null}
ci:
  vuln_scan:
    exemptions:
      - id: GHSA-mrhx-c7xc-m3w5
        reason: >-
          zod 3 has no fixed release; the fix is zod 4.6.6, a major upgrade of
          every generated form. zod here validates only form input a signed-in
          user types into their own browser. The zod 4 upgrade is tracked in
          issue 42; re-review by the expiry date.
        expires: "2026-12-20"
```

Use the ID the scanner printed: `GO-YYYY-NNNN` for govulncheck, `GHSA-…` for npm audit. One list serves both scanners. An entry accepts that one advisory only, so a new advisory in the same package still fails.

**5. Verify the exemption and its expiry**

```bash terminal theme={null}
reliant forge ci vuln-scan --npm
```

```text theme={null}
  ⚠️  accepted: GHSA-mrhx-c7xc-m3w5 (zod <4.6.6, high, in web)
      reason: zod 3 has no fixed release; ...
      expires: 2026-12-20
✅ Vulnerability scan passed — npm audit (1 frontend(s)), 1 accepted exemption(s).
```

An exemption is honored through the end of its `expires` date. The day after, the same run fails:

```text theme={null}
  ❌ exemption not honored: GHSA-mrhx-c7xc-m3w5 expired on 2026-11-19 — re-review it (is it still unreachable? is there a fix now?) and either extend `expires` with a fresh justification or remove the entry
  ❌ GHSA-mrhx-c7xc-m3w5 (zod <4.6.6, high, in web)
```

An entry with no `expires`, or an ID neither scanner uses, is not honored either and fails the gate.

**6. Scan the container image**

Image scanning is not part of `reliant forge ci vuln-scan`. The generated workflows run Trivy: `ci.yml`'s `docker-build` job scans the images it builds on a pull request, and `build-images.yml` scans the pushed image on `main`, both failing on `HIGH,CRITICAL`. To run the same scan locally:

```bash terminal theme={null}
docker build -t shop:ci .
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  aquasec/trivy:latest image --severity HIGH,CRITICAL --exit-code 1 shop:ci
```

```text theme={null}
WARN  This OS version is no longer supported by the distribution  family="alpine" version="3.21.10"
│ shop:ci (alpine 3.21.10) │  alpine  │        0        │    -    │
│ app/shop                 │ gobinary │        0        │    -    │
```

No findings, but note the warning: the scaffolded Dockerfile's runtime stage is `alpine:3.21`, which no longer gets security data. The Dockerfile is yours, so move its `FROM alpine:3.21` lines to a supported release.

## Choose the scanners

`ci.vuln_scan` in `forge.yaml` takes `go`, `npm` and `docker` (Trivy). Leave all three unset to run every scanner that applies. Setting one to `true` selects only the ones you set. Listing exemptions never turns a scanner off. The workflows are written once, so `docker` changes the Trivy steps only when a workflow is scaffolded; edit the workflow directly afterwards.

## What this does not do

* **Exemptions cover govulncheck and npm audit only.** Trivy findings in the workflows are not read from `forge.yaml`. Trivy's own ignore file is the place for those.
* **npm advisories below high do not fail** the scan. They are printed.
* **No scanning of your own code.** These scanners check dependencies against advisory databases. Secret scanning is the gitleaks pre-commit hook described in the [security model](https://docs.reliantlabs.io/deep-dives/security-model.md#limits-and-what-it-does-not-do).
* **No automatic fixes.** Dependabot's weekly grouped bumps, configured in `.github/dependabot.yml`, open pull requests; the scan does not change files.
* **The image scan needs a build.** It runs in GitHub Actions or wherever you run Docker, not in `task ci`.

## Next steps

> [card] [Gate pull requests](https://docs.reliantlabs.io/guides/forge/gate-prs-forge-lint-tests.md)
>
> Run the whole gate, lint and tests included, locally and on every pull request.

> [card] [Security model](https://docs.reliantlabs.io/deep-dives/security-model.md)
>
> Image signing, SBOMs, fail-closed auth and secret handling.

> [card] [vuln-scan reference](https://docs.reliantlabs.io/reference/cli.md#reliant-forge-ci-vuln-scan)
>
> Every flag of `reliant forge ci vuln-scan`.

> [card] [What forge lint checks](https://docs.reliantlabs.io/forge/linting/overview.md)
>
> The other half of the gate's static checks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.