auditing-dependency-bumps

name	auditing-dependency-bumps
description	Use when reviewing a Dependabot (or similar) dependency-bump PR — npm/pnpm minor/patch group bumps or GitHub Actions SHA bumps — and you need to do a supply-chain audit before approving and merging. Covers downloading and inspecting package contents, checking for known compromises, the git-tap trick for Dependabot CI, and the approve/merge flow.

Auditing dependency-bump PRs

Overview

Dependabot opens PRs that bump dependencies. Before merging, audit the actual package contents — a version number and changelog tell you nothing about whether the published tarball was tampered with. The npm ecosystem has had multiple supply-chain worms (e.g. the May 2026 "Mini Shai-Hulud" TanStack compromise) where a legitimate-looking version shipped credential-stealing, self-propagating malware with valid SLSA provenance. The audit is cheap (a few minutes, scriptable) and is the whole point of reviewing these PRs.

The end-to-end flow is:

1. Identify what actually changed (filter out lockfile noise).
2. Audit each changed package (download + inspect + known-compromise check).
3. Approve with a Claude Code:-prefixed summary of the audit.
4. git tap — push an empty commit so CI re-runs with full secrets (Dependabot PRs don't get repo secrets).
5. Wait for CI green, then squash-merge.

Do steps 3–5 only after the user has asked you to "approve and tap" / "get it merged" — they involve outward-facing actions. The audit itself (steps 1–2) you can always do.

Step 1 — Identify what actually changed

package.json shows the direct bumps. The lockfile (pnpm-lock.yaml / package-lock.json) is noisy: most of its diff is peer-dependency resolution strings being rewritten, not real new code. For example, when @types/react bumps, every pkg(@types/react@X) bracket in the lockfile changes even though those packages got no new code.

gh pr diff <PR> --repo <owner>/<repo> > /tmp/pr.diff
# direct bumps:
grep -nE '^\s*[-+].*"[@a-z].*":\s*"[\^~]?[0-9]' /tmp/pr.diff
# real version changes in the lockfile (a node whose own version moved):
grep -nE '^[-+]\s+(\S+@[0-9]|"\S+@[0-9])' /tmp/pr.diff

Build the real audit list: direct bumps plus transitive packages whose own version actually moved (e.g. react-router-dom bumps drag react-router). Ignore packages whose only change is a bracketed peer-dep string.

Step 2 — Audit each changed package

For npm/pnpm packages, download old + new tarballs straight from the registry and compare. Run downloads in parallel.

cd /tmp && rm -rf scaudit && mkdir scaudit && cd scaudit
# metadata + install scripts (the most important single check):
for p in "pkg@OLD" "pkg@NEW"; do
  echo "### $p"
  npm view "$p" dist.tarball dist.integrity scripts 2>/dev/null
done
# download + extract. You are handling UNTRUSTED archives, so:
#   1. curl -fsSL          -> fail fast on any HTTP error or redirect.
#   2. fresh dedicated dir + NEVER pass -P/--absolute-names. Default tar (bsdtar
#      on macOS, GNU tar on Linux) strips leading "/" and refuses ".." members
#      that would escape the dir -- bsdtar hard-errors (non-zero exit, caught
#      below). -P is the only thing that turns this protection off, so don't.
dl() {
  curl -fsSL "$1" -o "$2.tgz" || { echo "download failed: $1" >&2; return 1; }
  rm -rf "$2" && mkdir -p "$2"
  tar xzf "$2.tgz" -C "$2" || { echo "extract failed (corrupt or unsafe archive?): $2.tgz" >&2; return 1; }
}
dl "$(npm view pkg@NEW dist.tarball)" new & p_new=$!
dl "$(npm view pkg@OLD dist.tarball)" old & p_old=$!
wait "$p_new" && wait "$p_old" || { echo "a download/extract failed -- re-check before trusting the diff" >&2; }

Then check, in order of signal:

• Install hooks (highest signal). scripts should have no preinstall / install / postinstall. These run automatically on npm/pnpm install and are the #1 malware vector. build / test / dev / lint scripts are fine — they don't run from a published tarball. A prepare: husky is also fine: prepare only runs when installing from a git source, not from a registry tarball.
• Binary blobs. No unexpected executables. .map (source maps) and package.json classify as "JSON data" — those are fine.

  find new -type f -exec sh -c 'file "$1" | grep -qiE "ELF|Mach-O|PE32|executable" && echo "$1: $(file -b "$1")"' _ {} \;
  

• File-list diff. New files should be explainable (a new LICENSE-*, shipped docs/*.md, content-hash-renamed bundle chunks). A new .js in a package that's supposed to be types-only is a red flag.

  diff <(cd old/package && find . -type f | sort) <(cd new/package && find . -type f | sort)
  

• Suspicious patterns — and check they're NOT pre-existing. Grep the new build for child_process, eval(, atob(, fromCharCode, XMLHttpRequest, require('http, env-var exfil. Crucially, also grep the OLD build: many libraries legitimately use atob/fromCharCode (e.g. react-router's base64/turbo-stream encoding). If the pattern is already in the old version, the bump didn't introduce it.

  grep -rIlE "child_process|eval\(|atob\(|fromCharCode|XMLHttpRequest" new/package | grep -v '\.map$'
  grep -rIlE "child_process|eval\(|atob\(|fromCharCode|XMLHttpRequest" old/package | grep -v '\.map$'  # baseline
  

• Source diff for small/patch bumps. For patch releases, actually read the diff — it should match the stated fix. (e.g. dompurify 3.4.8 was a Trusted Types re-entrancy guard; that's exactly what the diff showed.)

  diff -u old/package/dist/<entry>.mjs new/package/dist/<entry>.mjs | grep -E '^[+-]' | grep -vE '^[+-]{3}|version'
  

• npm audit on the new set:

  mkdir audit && cd audit
  npm install --package-lock-only --silent <pkg@NEW> ...   # or write a minimal package.json
  npm audit
  

• Known-compromise web search. Search for recent supply-chain incidents naming these packages/versions. Note that incidents are often family-scoped: in the May 2026 TanStack attack, @tanstack/react-router was compromised but @tanstack/query* (which includes @tanstack/react-query) was explicitly confirmed clean — read the advisory carefully to see which exact packages and version windows are affected.

For GitHub Actions SHA bumps, the audit is different: verify each new SHA resolves in the canonical upstream repo (gh api repos/<owner>/<repo>/commits/<sha>), is reachable from a signed/annotated release tag, was merged by a known maintainer, and that action.yml didn't gain new pre/post scripts or credential-handling inputs. Large dist/ churn is often a benign bundler migration (e.g. ncc→esbuild) — confirm against the public release commits.

Step 3 — Approve

gh pr review <PR> --approve --body "Claude Code: Approved after supply-chain audit of all N bumps (...).
Method: downloaded old+new tarballs, diffed file lists, scanned for install hooks / binary blobs / exec+network patterns, ran npm audit, checked known compromises.
Findings — all clean: <one bullet per package>."

Step 4 — git tap (the key trick for Dependabot CI)

Dependabot-triggered workflow runs don't have access to repository secrets, so any job needing a secret fails — classically Pulumi Preview (prd) with The 'private-key' input must be set to a non-empty string. This is not a real failure of the change. Pushing an empty commit as yourself re-runs CI with full credentials and the secret-gated jobs pass.

git tap is a local alias for commit --allow-empty -m 'empty commit':

git fetch origin && gh pr checkout <PR>
git commit --allow-empty -m 'empty commit'   # = git tap
git push

Step 5 — Wait for CI, then merge

# poll until no pending checks:
for i in $(seq 1 60); do
  s=$(gh pr checks <PR> --json name,bucket,state 2>/dev/null)
  if [ -n "$s" ] && ! jq -e 'any(.[]; .bucket=="pending")' <<<"$s" >/dev/null; then
    jq -r '.[] | "  \(.bucket|ascii_upcase)\t\(.name)"' <<<"$s" | sort
    jq -e 'all(.[]; .bucket=="pass" or .bucket=="skipping")' <<<"$s" >/dev/null \
      && echo "ALL GREEN" || echo "NOT ALL GREEN"
    break
  fi
  sleep 30
done
# if green:
gh pr merge <PR> --squash --delete-branch

Gotchas

• Don't trust the lockfile diff size. Hundreds of changed lines are usually peer-dep-string churn from one type-package bump, not new code. Filter to packages whose own version moved.
• prepare/build/test scripts are not install hooks. Only preinstall/install/postinstall auto-run from a registry tarball.
• Check the OLD version before flagging a "suspicious" pattern — most are pre-existing and benign.
• Advisories are family- and version-scoped. A compromised sibling package doesn't mean the one you're bumping is affected, and vice versa. Verify the exact name and version window.
• A failing secret-gated CI job on a Dependabot PR is expected — fix it with git tap, don't treat it as a blocker or try to unlock/skip it.