SafeInstall
Supply-chain security for the AI-agent era.
The artifact-bound install gate for npm and pnpm — for the humans who type install, the AI agents that run it for them, and the config that programs those agents.
Policy runs first. Then your package manager. Not the other way around.
Local-first · No cloud · No account · MIT · Free forever
What it does
SafeInstall runs your policy before your package manager — locally, blocking by default. One tool, three layers of defense:
- 🧑‍💻 For the humans who install — prefix supported install commands:
safeinstall pnpm add axios. Policy runs first; the resolved lockfile is then checked against the approved version and SHA-512 before the frozen install. Release age, install scripts, untrusted sources, typo-squats, and cryptographic provenance are policy checks.
- 🤖 For the AI agents that install for you — an MCP tool agents can call, plus a shell guard that intercepts install commands in Claude Code, Codex, and Cursor before they run. Best-effort shell interception — one defense layer that fires even when the agent isn't cooperating, not a lossless guarantee.
- 🔒 For the files that program the agents — the Agent Trust Surface: a committed hash baseline of your config, hooks, rules, and MCP files, reconciled locally and re-verified in CI, so tampering with the rules surfaces as drift instead of silently owning every future session — with a fully consistent rewrite caught by human review of the diff, not the automated check alone.
Why SafeInstall
AI coding tools suggest packages in seconds. They don't check publish dates. They don't read install scripts. They don't verify the source. You type "yes" and move on.
SafeInstall is the gate between suggestion and execution.
$ safeinstall pnpm add compromised-pkg@9.9.9
Install blocked.
- compromised-pkg@9.9.9
Blocked: release too new (published 3 hours ago; minimum is 72 hours).
Blocked: install script present (has postinstall).
No dashboard. No account. No cloud. One command prefix — policy runs locally, blocks by default, then invokes the real tool.
Catching a maintainer-compromise attack
A valid Sigstore signature is not enough. An attacker who compromises an npm maintainer account can publish a malicious version of a package you already trust, and the attestation on that malicious version will cryptographically verify — signed by a GitHub Actions workflow the attacker controls in a fork of the real repository.
SafeInstall catches this. Pin the expected source repository with provenance.trustedPublishers and any build that comes from anywhere else is blocked, even if the signature is valid:
$ safeinstall check
Using config: ./safeinstall.config.json
Check blocked.
- axios@1.99.0
Blocked: publisher mismatch for axios (expected axios/axios, got evil-org/axios).
Suggestion: Verify the package source. Update provenance.trustedPublishers only if the change is intentional.
This is the only check of its kind in an install-time policy gate. CVE scanners look for known vulnerabilities. Content analyzers look for suspicious code. SafeInstall enforces that the cryptographic chain of trust points at the repository you agreed to trust — and refuses anything else, no matter how legitimate it looks.
SafeInstall itself is published with a Sigstore attestation. You can eat your own dog food: enable provenance verification, pin safeinstall-cli to Mickdownunder/SafeInstall, and watch SafeInstall verify its own trust chain against the public Sigstore transparency log.
$ safeinstall check
Using config: ./safeinstall.config.json
Info: safeinstall-cli: provenance verified from Mickdownunder/SafeInstall via .github/workflows/release.yml.
Check passed: no direct dependency policy violations found.
Install
npm install -g safeinstall-cli
Node.js >=20 · macOS, Linux, Windows · Command: safeinstall
Quickstart
safeinstall init # config + shell guard hooks + trust lock, in one command
safeinstall pnpm add axios # policy runs, then pnpm
safeinstall npm install # lockfile-aware project install
safeinstall check # audit direct deps against policy
How it works
Resolve → Policy → Lockfile-only preparation → Verify artifact binding → Frozen install
Any failed policy or binding check → Exit 2 (blocked)
- Resolves the requested version and captures the registry's tarball URL and SHA-512
- Fetches registry metadata (publish time, declared scripts)
- Evaluates policy rules
- For explicit package additions, pins the evaluated version and runs a scripts-disabled, lockfile-only preparation
- Checks every direct registry dependency in the affected lockfile scope against its evaluated version, SHA-512, and tarball URL where recorded; applies configured transitive checks
- Runs
npm ci or pnpm install --frozen-lockfile with scripts disabled and the configured registry enforced; rejects manifest/lockfile changes during evaluation or installation
No registry proxy. No tarball rewriting. No cloud dependency.
Policy defaults
| Rule | Default | Block message |
|---|
| Release age | 72 hours minimum | Blocked: release too new |
| Lifecycle scripts | preinstall, install, postinstall blocked | Blocked: install script present |
| Source types | registry, workspace, file, directory allowed. First-party workspace packages (workspace:, or a path matched by the workspace globs) are always allowed; any other local directory counts as directory and a local tarball as file | Blocked: untrusted source |
| Trust downgrade | Flags a dependency that was registry in the committed manifest and is now git/url/tarball or any local source (file:, link:, directory, workspace:). A dependency that was already local at the baseline is not flagged. decisions authorize compares against the base commit's manifest (never the config); check and installs compare against the manifest at git HEAD. sourceBaselines applies only when there is no HEAD manifest (no git, unborn HEAD, untracked manifest), and then missing history fails closed | Blocked: trust level dropped |
| Typo-squat detection | Off by default; opt in via typoSquat.mode | Blocked: suspected typo-squat |
| Provenance verification | Off by default; opt in via provenance.mode | Blocked: attestation missing/invalid/publisher mismatch |
| Lockfile sources | Every entry of an npm or pnpm lockfile, direct or transitive, must come from a source in allowedSources | Blocked: transitive dependency resolves from an untrusted source |
| Transitive install scripts | Off by default; opt in via transitive.mode | Blocked: transitive install script |
| Provenance continuity | Off by default; opt in via continuity.mode | Blocked: provenance downgrade / identity discontinuity |
All rules are configurable. Ambiguous or incomplete metadata blocks instead of allowing.
Provenance continuity — catching what npm defaults can't
This is SafeInstall's most distinctive check, and the one no other consumer-side tool does. npm verifies provenance at publish time and binds a package to a source repository — but it does not enforce continuity between versions. A compromised maintainer account can publish a new version with no attestation (from a stolen token), or from a different repository, and npm raises no alarm. This is the signature of the 2026 attack wave (Mastra, the dormant-account republishes).
Continuity learns a per-package trust baseline from the provenance identity of recent versions, then blocks deviations:
provenance-downgrade — recent versions were attested, this one isn't. The fingerprint of an account-compromise publish from a personal token. (This is the Mastra case.)
identity-discontinuity — this version is attested from a different source repository than the established baseline.
Because the baseline is learned per package, there are no false positives on the large majority of packages that never adopted provenance — they simply have no baseline and the check stays silent. No global "require provenance" sledgehammer.