feat: perry install — secure wrapper around bun/npm with offline malware scan

[proggeramlug]

Summary

perry install wraps bun install --ignore-scripts (or npm install --ignore-scripts as fallback) so no package code executes during install, then scans the inert node_modules/ with bundled offline rules and refuses to proceed on any P0 hit. Lifecycle scripts only run for packages on a curated trust allowlist (~40 well-known native-binding packages: esbuild, sharp, prisma family, swc, biome, lightningcss, @next/swc-, @esbuild/, @napi-rs/*, etc.) or the user's explicit opt-in via package.json -> perry.allowScripts / --run-scripts <pkg>.

Works on any standard npm project — no Perry-specific config required.

Why

After-the-fact scanners (Socket, GuardDog, npm audit) run too late on the postinstall-exfil vector that the 2024–2026 supply-chain wave (Shai-Hulud, SANDWORM_MODE, QIX maintainer compromise) leans on. Plugging the gate between extract and script execution catches the attack before any code runs.

Architecture

perry install
  ├─ detect installer        (bun preferred, npm fallback)
  ├─ <installer> install --ignore-scripts   (resolver/fetch/extract — battle-tested)
  ├─ scan node_modules/      (4 rule modules, offline, ~ms)
  │    └─ block here if any P0 hit; node_modules/ on disk but inert
  └─ run lifecycle scripts   (only for trust-gate packages)

Scan rules (P0 — block by default)

Module	Catches
scripts.rs	curl
patterns.rs	Same exfil shapes + hardcoded webhook URLs in declared entry-point JS (main / module / bin / exports leaves)
typosquat.rs	Levenshtein ≤ 2 with length-diff ≤ 1 against ~300 popular npm names (expres/epxress/reactnative flagged; expressjs not)
obfuscation.rs	Dropper-shape: small (< 50 KB) non-min entry with > 5 K-char line; OR ≥ 1 K-char base64 blob in any entry file

CLI surface

perry install [pkg...]                  # install from package.json or named packages
perry install --installer=bun|npm       # force backend (auto: bun → npm)
perry install --allow-risky <pkg>       # bypass scan for one package
perry install --allow-risky-all         # CI/emergency bypass
perry install --run-scripts <pkg>       # allow scripts beyond bundled allowlist
perry install --run-scripts-all         # npm-equivalent (unsafe)
perry install --skip-scan               # just wrap installer
perry install --json                    # machine-readable

End-to-end validation

• Clean install of lodash + chalk → verdict clean, exit 0.
• --installer=npm fallback → works, npm output passes through.
• Inject lodass (typosquat of lodash) with malicious postinstall into node_modules/ → exit 1, two P0 findings cited (lifecycle-shell-pipe-exec + typosquat-close-to-popular), no scripts ran.
• Same with --allow-risky lodass → exit 0, findings annotated overridden, scripts still skipped because not on allowlist.
• Real-world: project depending on esbuild@^0.21 → bun-install + scan-clean + allowlist runs esbuild's postinstall → 9.4 MB platform binary lands in node_modules/esbuild/bin/esbuild.
• --skip-scan → installer runs, scanner skipped, no scripts (because we still pass --ignore-scripts to the underlying installer).
• .perry/install-report.json written on every run with timestamp, package count, findings array (each with overridden: bool), verdict.

Test plan

• 65 unit tests under crates/perry/src/commands/install/ (installer detection, package walker, each scan rule with positive + negative fixtures, allow-risky matcher, report writer, trust gate, real-shell lifecycle execution)
• Workspace cargo build --release -p perry clean (44 warnings, all pre-existing)
• End-to-end smokes above all pass against the release binary
• CI: lint, cargo-test, parity, compile-smoke, api-docs-drift, security-audit

Out of scope (filed as follow-ups)

• Sandboxed lifecycle execution (macOS sandbox-exec / Linux bubblewrap+seccomp / Windows AppContainer with redacted env + filesystem confinement + network allowlist). v1 runs allowlisted scripts un-sandboxed; v2 will add the jail. This is the strongest reason to ship v2 soon — a compromised allowlisted package's postinstall still runs with full privileges today.
• Scoped-package typosquat detection.
• P1 freshness / maintainer-drift / SLSA-provenance checks (CLI flag --check-freshness reserved, not implemented).
• Private registries / .npmrc auth / yarn / pnpm backends.

Design rationale

Full plan + alternatives considered (full-installer-from-scratch vs. wrapper) lives in the linked design doc.