|
| 1 | +# NPM Lockfile Audit Fix |
| 2 | + |
| 3 | +Status: candidate |
| 4 | + |
| 5 | +Use this workflow when a public JavaScript/TypeScript repository has an open dependency audit issue and the vulnerable dependency chain can be resolved by refreshing `package-lock.json` within existing semver ranges. |
| 6 | + |
| 7 | +## Trigger |
| 8 | + |
| 9 | +Good fits: |
| 10 | + |
| 11 | +- A public issue reports `npm audit` findings with clear package names. |
| 12 | +- The repository has `package.json` and `package-lock.json`. |
| 13 | +- No open PR already fixes the same dependency chain. |
| 14 | +- `npm audit` reproduces locally from public files. |
| 15 | +- A lockfile-only change clears the relevant findings. |
| 16 | + |
| 17 | +Do not use this for runtime dependency major upgrades, private advisories, or packages that require security-sensitive migration decisions. |
| 18 | + |
| 19 | +## Inputs |
| 20 | + |
| 21 | +- Public issue URL. |
| 22 | +- `package.json`. |
| 23 | +- `package-lock.json`. |
| 24 | +- Local `npm audit` output. |
| 25 | +- Project test command. |
| 26 | + |
| 27 | +Never include credentials, private registry tokens, exploit instructions, or private audit output. |
| 28 | + |
| 29 | +## Workflow |
| 30 | + |
| 31 | +1. Confirm the issue is open and no duplicate PR exists. |
| 32 | +2. Clone the public repo into ignored `local/` workspace. |
| 33 | +3. Read repository instructions such as `AGENTS.md`. |
| 34 | +4. Run `npm audit --json` to reproduce findings. |
| 35 | +5. Prefer the smallest safe remediation: |
| 36 | + - `npm update <direct-parent> --package-lock-only` |
| 37 | + - leave `package.json` unchanged if existing ranges permit patched versions |
| 38 | +6. Run `npm ci`. |
| 39 | +7. Run `npm audit --audit-level=moderate`. |
| 40 | +8. Run the narrowest relevant test command. |
| 41 | +9. Open a PR with before/after audit and test results. |
| 42 | +10. Log the exact PR body under `leads/sent/`. |
| 43 | + |
| 44 | +## Validation |
| 45 | + |
| 46 | +Expected checks: |
| 47 | + |
| 48 | +- `npm audit --audit-level=moderate` exits successfully. |
| 49 | +- Relevant tests pass. |
| 50 | +- Diff is lockfile-only unless a manifest change is clearly required. |
| 51 | +- PR body has no payment link and makes no certified security claim. |
| 52 | + |
| 53 | +## Failure Modes |
| 54 | + |
| 55 | +Stop or revise when: |
| 56 | + |
| 57 | +- audit fix requires a major runtime dependency upgrade |
| 58 | +- tests fail for reasons connected to the dependency update |
| 59 | +- `npm audit fix --force` would be required |
| 60 | +- lockfile refresh changes package manager format unexpectedly |
| 61 | +- the vulnerability is dev-only and maintainers already documented it as non-actionable |
| 62 | + |
| 63 | +## Evidence |
| 64 | + |
| 65 | +- ms365-cli dependency issue: https://github.com/arkangelai/ms365-cli/issues/4 |
| 66 | +- Lockfile-only PR: https://github.com/arkangelai/ms365-cli/pull/7 |
| 67 | + |
| 68 | +Outcome interpretation: |
| 69 | + |
| 70 | +- Count as proof-of-work if the PR gets merged, receives maintainer review, or triggers a concrete maintainer response. |
| 71 | +- Keep as `candidate` until at least two public dependency-audit fixes pass review. |
0 commit comments