The npm-audit component#
The front-end half of composer-audit: this component runs npm audit on the app's
package-lock.json and fails the pipeline on an advisory at or above audit_level (high by default) in a runtime
dependency. Then it prints a full report, dev dependencies included, that never fails. This page shows how to add it,
what each input does, and how CREED's severity words map to npm's.
Include the component#
Goal: your app's pipeline fails whenever a locked runtime npm package has a known high or critical advisory. Add the
include to your app's .gitlab-ci.yml:
include:
- component: $CI_SERVER_FQDN/enterprise-apps/preflight/npm-audit@fb73b538f3980292119b5b306ff64383d760a214 # 0.9.0
inputs:
working_dir: .
npm-audit ships in Preflight 0.5.0; 0.4.0 does not include it. Pin that tag's full commit SHA, with the tag in a trailing comment, or the full commit SHA of a commit at or after it. The Upgrading page has the 0.5.0 checklist.
Inputs#
| Input | Type | Default | What it does |
|---|---|---|---|
stage |
string | test |
Pipeline stage for the job. |
job_name |
string | npm-audit |
Name of the job. Set it when you include this component more than once. |
image |
string | node:22.13-alpine@sha256:e2b39f7b64281324929257d0f8004fb6cb4bf0fdfb9aa8cedb235a766aec31da |
Docker image for the job: the same Node image and digest the eslint component pins. |
image_prefix |
string | ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX} |
Registry path in front of image: the job pulls image_prefix/image. The default is the group's GitLab Dependency Proxy, so Docker Hub is asked once and GitLab serves the cached copy. Outside a group with the proxy, set docker.io. No trailing slash. |
working_dir |
string | . |
Directory that holds package-lock.json, relative to the project root. |
audit_level |
string | high |
Lowest severity that fails the job: low, moderate, high or critical. medium is accepted too and means moderate (see Severity words below). |
omit_dev |
boolean | true |
Whether the failing audit leaves dev dependencies out. The full report after it always lists them and never fails. |
What the job does#
The job is interruptible: true with a timeout: 10 minutes. Its script changes into working_dir, then:
- No lock, nothing to audit. With no
package-lock.json(ornpm-shrinkwrap.json) the job printsnpm-audit: no lock file (package-lock.json or npm-shrinkwrap.json) in <dir>, nothing to audit.and passes. An app with no front end never goes red. - The gate.
npm audit --omit=dev --audit-level=<audit_level> --audit=true --offline=false(no--omit=devwhenomit_devisfalse). npm exits non-zero on an advisory at or above the level, and the job keeps that exit code. - The full report. When
omit_devistrue, a secondnpm auditlists every finding, dev dependencies included, and never fails the job. A dev-only finding shows up in the log without stopping the merge.
npm audit reads only the lock. Nothing is installed, so no package's install script runs in this job.
Why --audit=true --offline=false#
An app's own .npmrc can carry audit=false or offline=true. Either one makes npm audit skip the request,
print found 0 vulnerabilities and exit 0: a pass that audited nothing. The two flags override the file, so the job
always asks the registry.
When the registry cannot be reached#
npm audit posts the lock's package tree to the registry's audit endpoint, so the job needs outbound HTTPS to the
registry (registry.npmjs.org unless the app's .npmrc names another). When the endpoint cannot be reached, or the
registry does not offer one, npm exits non-zero with audit endpoint returned an error, and the job adds
npm-audit: the registry's audit endpoint could not be reached or refused the request, so nothing was audited. It
fails rather than passes unchecked. A private registry that proxies npm must also serve
npm's audit endpoints (/-/npm/v1/security/advisories/bulk, with /-/npm/v1/security/audits/quick as npm's
fallback), or the job fails on every run.
Severity words#
CREED's policy (rules.audit_severity_threshold in policy.json, read by PROCTOR) and Composer use low, medium,
high and critical. npm uses low, moderate, high and critical (plus info and none, which this component
does not accept: none would never fail and info fails on notes). The map:
| CREED and Composer | npm (--audit-level) |
|---|---|
low |
low |
medium |
moderate |
high |
high |
critical |
critical |
So audit_level takes the policy's value as it is: audit_level: medium runs npm audit --audit-level=moderate, and
the log says failing on moderate or higher. The default, high, matches the stack policy's
audit_severity_threshold.
Caching#
The job installs nothing, but npm fetches package metadata while it reports. It reads the app's own npm cache: the fixed
key npm and the path .cache/npm/ (npm_config_cache points there), the ones Sourdough's generated pipelines use,
with policy: pull. The audit never uploads, so an audit running next to the app's install job cannot overwrite the
packages that job just downloaded. In an app with no npm cache of its own the job simply starts cold.
Proof#
Preflight's own pipeline keeps these promises with the must-fail-npm-audit job. It runs this template's own script on
fixed locks: lodash 4.17.20 (GHSA-35jh-r3h4-6jhm, high) fails at high and medium and passes at critical, an
.npmrc that turns the audit off still fails, the same lodash as a dev dependency fails only with omit_dev: false, a
clean lock and an app with no lock pass, and an unreachable registry fails a clean lock. The pipeline also includes the
component on the clean fixture, where it must pass. A smoke detector is only worth the batteries if someone pressed the
test button.
Run it on a schedule#
New advisories are published after code is merged. The weekly pipeline schedule from
composer-audit covers this job too: it carries no rules: block,
so it runs in scheduled pipelines like any other.