Skip to content
PREFLIGHT 0.9.0
Menu

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:

  1. No lock, nothing to audit. With no package-lock.json (or npm-shrinkwrap.json) the job prints npm-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.
  2. The gate. npm audit --omit=dev --audit-level=<audit_level> --audit=true --offline=false (no --omit=dev when omit_dev is false). npm exits non-zero on an advisory at or above the level, and the job keeps that exit code.
  3. The full report. When omit_dev is true, a second npm audit lists 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.