Auditing npm Dependencies in SSG Pipelines

A static site ships no server code, but its build is a program — and most of that program was written by strangers. A fresh Astro project installs around 350 packages; a Docusaurus site over 1,100; a Next.js site with a component library can pass 1,500. Every one of them runs during npm install or npm run build, with read access to the repository and the environment, and with the ability to write into the output that gets deployed to every reader. The npm ecosystem has seen maintainer account takeovers, typosquats and protestware repeatedly; a static site is exposed to all of it.

This guide sets up layered controls for a static site's build: deterministic installs, install-script restrictions, vulnerability audits that block what matters, provenance checks, and a review step for new dependencies. It is part of Security Headers and Hardening for Static Sites.

Prerequisites

• A static site built with npm, pnpm or Yarn, with a committed lockfile.
• CI on GitHub Actions or similar.
• Someone who owns dependency decisions — usually whoever reviews package.json changes.

Step 1: Make Installs Deterministic

A lockfile pins every transitive package to an exact version and records an integrity hash for its tarball. npm ci installs exactly what the lockfile says and fails if package.json and the lockfile disagree; npm install may resolve newer versions within ranges. In CI, always use npm ci (or pnpm install --frozen-lockfile).

- uses: actions/setup-node@v4
  with: { node-version: 20, cache: npm }
- run: npm ci --ignore-scripts --no-audit --no-fund

This alone closes the most common attack path: a malicious new version of a transitive dependency cannot enter the build unless someone updates the lockfile, which is a reviewable change.

Step 2: Restrict Install Scripts

preinstall, install and postinstall scripts run arbitrary code at install time. Most static-site dependencies do not need them. On the Astro site used here, 6 of 412 installed packages declared install scripts, and only 2 were needed (sharp for image processing and esbuild for its platform binary).

# list packages with install scripts
npm query ':attr(scripts, [postinstall]), :attr(scripts, [install]), :attr(scripts, [preinstall])' \
  | jq -r '.[] | "\(.name)@\(.version)"'

Install with --ignore-scripts, then run the needed scripts explicitly:

- run: npm ci --ignore-scripts
- run: npm rebuild sharp esbuild     # the two that genuinely need install scripts

pnpm makes this a configuration: onlyBuiltDependencies: [sharp, esbuild] in pnpm-workspace.yaml runs scripts only for listed packages, and pnpm 10 defaults to not running them at all.

Step 3: Audit, and Block on What Matters

npm audit compares installed versions with the GitHub advisory database. Run it in CI, but configure what blocks: a static build uses many packages only at build time, and an advisory about, say, a regular-expression denial of service in a dev server does not affect the generated site. Blocking on every finding teaches the team to ignore the check.

- name: Audit production dependency tree
  run: npm audit --omit=dev --audit-level=high
- name: Audit everything (report only)
  run: npm audit --audit-level=critical || true

For static sites, "production dependencies" still means build-time code — the generator, its plugins and anything bundled into the output. Move tooling that never touches output (linters, test runners, formatters) into devDependencies so --omit=dev narrows the blocking audit to code that shapes what readers receive.

Supplement the advisory database with a tool that checks for signs of malice rather than known CVEs — install scripts that make network requests, obfuscated code, recently transferred ownership. GitHub's dependency review action does this for pull requests:

- uses: actions/dependency-review-action@v4
  with:
    fail-on-severity: high
    deny-licenses: GPL-3.0, AGPL-3.0
    comment-summary-in-pr: always

Step 4: Review New Dependencies

Most risk enters through a new direct dependency, which brings its own transitive tree. Make adding one a deliberate decision with a short checklist in the pull request template: what does it do, could a few lines of our own code replace it, how many transitive packages does it add, is it maintained, does it declare install scripts. The dependency review action's comment shows the added tree size; on this site, a date-formatting library proposed for one component would have added 31 transitive packages, and Intl.DateTimeFormat did the job instead.

Delay routine updates slightly. Most malicious versions are detected and unpublished within days. Configuring the update bot with a minimum release age (Renovate's minimumReleaseAge: "3 days") means the site rarely installs a version in its first, most dangerous window.

Step 5: Check Provenance Where Available

npm packages published from GitHub Actions can carry signed provenance attestations linking the tarball to the source commit and workflow that built it. npm audit signatures verifies registry signatures and provenance for installed packages:

npm audit signatures
# audited 412 packages in 3s
# 412 packages have verified registry signatures
# 118 packages have verified attestations

Provenance does not make a package trustworthy, but it makes certain attacks — a tarball published from a stolen token rather than from the project's CI — visible. Track the count over time and investigate when a previously attested package publishes a version without attestation.

Measured Impact

The Astro documentation site after applying all five steps, compared with its state before:

Where the Build Can Reach

The final control is about blast radius rather than detection. Even with every check above, assume a malicious package might one day run in the build. What can it reach? If the deploy token sits in the job's environment from the first step, the answer is "every page on the site". Moving credentials so they exist only in a separate deploy job — one that installs nothing and runs no third-party code — limits a compromised build to producing a bad artifact, which review, smoke tests and rollback can catch. That separation is the subject of Securing Deploy Credentials with GitHub OIDC. The build job's permissions block should also be minimal — contents: read — so the GITHUB_TOKEN cannot push commits or create releases.

Pitfalls & Rollback

• npm install in CI. It can resolve versions the lockfile never recorded. Use npm ci.
• Blocking on every advisory. Dev-only and unreachable findings create alert fatigue. Block on high and critical in shipped code; report the rest.
• Auto-merging updates on release day. Add a minimum release age so new versions have time to be vetted.
• Secrets in the build job. An install-time compromise can read them. Keep credentials in a separate deploy job.
• Rollback: each control is a CI step or a config line. Removing --ignore-scripts or the audit step restores previous behaviour instantly; the lockfile itself should never be rolled back to an unpinned state.

Conclusion

A static site's build is the part of the stack an attacker can actually reach, and it runs hundreds of packages nobody on the team wrote. Deterministic installs, an allow-list for install scripts, an audit gate focused on shipped code, provenance checks, a review step for new dependencies and credentials kept out of the build together turn that risk from open-ended into bounded. On this site the controls added 14 seconds to CI, removed 81 packages from the tree and left no long-lived secret within reach of third-party code.

FAQ

Why do static sites need dependency auditing?

Because the build runs hundreds of third-party packages with access to the repository, the environment and often deploy credentials. A compromised package can inject code into every generated page or steal a token, even though nothing runs on a server afterwards.

Does npm audit catch malicious packages?

Only after they are reported and added to the advisory database. It catches known vulnerabilities well but cannot detect a freshly published malicious version. Lockfiles, delayed updates and install-script restrictions cover that gap.

Should I disable install scripts entirely?

Where possible, yes. Run npm ci with --ignore-scripts and allow scripts only for the few packages that genuinely need them, such as native image tools. Most static site dependencies need no install scripts at all.

How many audit findings should block a build?

Block on high and critical advisories that affect code which actually runs, and on any new dependency that has not been reviewed. Many advisories in build-only tooling are not exploitable in a static build; triage those rather than letting them block every merge.

Related

• Parent: Security Headers and Hardening for Static Sites — the edge and pipeline controls together.
• Securing Deploy Credentials with GitHub OIDC — limiting what a compromised build can reach.
• Caching node_modules in GitHub Actions for Faster SSG Builds — keeping npm ci fast.
• Upgrading Jekyll and Ruby Versions Safely — the same discipline for Ruby gems.
• Tracking Bundle Size per Pull Request — another reason to question each new dependency.