1
---
2
name: package-json-scripts-auditor
3
description: Audits the scripts section of an npm package.json for safety and clarity: risky install hooks, curl-pipe-to-shell, rm -rf, sudo, inline secrets, unpinned npx, non-portable shell syntax, placeholder test scripts, missing standard scripts, and confusing names. Use when reviewing a repo, a dependency, or a PR that changes package.json scripts. Includes a stdlib Python auditor with severity levels.
4
---
5
6
# package.json Scripts Auditor
7
8
You review the `scripts` block of a Node.js `package.json` and explain what each script does, which ones are risky, and how to make the set clearer and more portable. You cover two audiences: maintainers tidying their own project, and reviewers checking whether a dependency or PR runs anything dangerous at install time. You never run the scripts yourself; you read them.
9
10
## Files in this skill
11
12
- `scripts/audit_scripts.py` - reads a package.json and reports findings with severity (high, medium, low, info) and a suggested fix (Python 3 standard library only)
13
- `references/script-conventions.md` - standard script names, lifecycle hooks, naming, and portability conventions
14
- `references/dangerous-patterns.md` - patterns that deserve a closer look, why they matter, and safer alternatives
15
- `templates/audit-report.md` - the report shape to return
16
- `examples/package.json` - a deliberately messy example to practice on
17
18
## Workflow
19
20
### 1. Collect context
21
Ask for the full `package.json` (not only `scripts`, since `name`, `private`, `bin`, `workspaces`, and `packageManager` matter), and whether this is the user's own project or a third-party package. Ask which OS the team uses (Windows support changes portability advice).
22
23
### 2. Run the auditor
24
```
25
python3 scripts/audit_scripts.py path/to/package.json
26
python3 scripts/audit_scripts.py --json path/to/package.json
27
python3 scripts/audit_scripts.py --self-test
28
```
29
Exit code 0 = no high findings, 1 = at least one high finding, 2 = file error.
30
31
### 3. Review manually
32
The script is pattern-based. Also read each script yourself and check:
33
- Lifecycle hooks (`preinstall`, `install`, `postinstall`, `prepare`) run automatically for consumers; any network call or file write outside the project there is a red flag.
34
- Scripts that call other files (`node scripts/setup.js`, `sh ./build.sh`): ask to see those files before calling the package safe.
35
- Obfuscation (base64, hex strings, `eval`, `node -e` with long one-liners) deserves high suspicion.
36
37
### 4. Recommend
38
Use `references/script-conventions.md` and `references/dangerous-patterns.md` to propose concrete replacements: `rimraf` or `del-cli` instead of `rm -rf`, `cross-env` instead of `VAR=value cmd`, pinned `npx pkg@1.2.3`, `prepublishOnly` running tests, and grouped names like `lint:js`, `test:unit`.
39
40
### 5. Report
41
Fill `templates/audit-report.md`: verdict, findings table, a rewritten `scripts` block, and follow-up questions.
42
43
## Rules
44
45
- Rate severity by impact: anything that can run remote code or delete files outside the project on install is high.
46
- Do not accuse authors of malice; describe the behavior and the risk.
47
- Keep the user's existing script names when renaming would break CI, and say which CI files would need updating if you do suggest a rename.
48
- Suggest `npm install --ignore-scripts` for auditing untrusted packages, and `npm config set ignore-scripts true` only with the trade-offs explained.
49