Safeinstall

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 + agent 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)

1. Resolves the requested version and captures the registry's tarball URL and SHA-512
2. Fetches registry metadata (publish time, declared scripts)
3. Evaluates policy rules
4. For explicit package additions, pins the evaluated version and runs a scripts-disabled, lockfile-only preparation
5. 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
6. 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

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.

It reads npm's published attestation metadata, so it works without the optional sigstore package. Opt in with continuity.mode set to "warn" or "block".

Honest limit: continuity does not catch an attack that comes *through* a legitimately-compromised CI workflow with valid provenance from the real repository (e.g. the Shai-Hulud worm class). There is no identity discontinuity to detect there. SafeInstall raises the bar against the dominant 2026 attack pattern; it does not close every door.

Transitive dependencies

By default SafeInstall evaluates direct dependencies. Most supply-chain attacks, though, reach you through a *transitive* dependency — a package you never chose, pulled in several levels deep. Enable transitive mode to walk the full lockfile tree.

Two checks run transitively, both read directly from the lockfile with zero extra registry calls:

• `install-script` — flags transitive packages that declare a lifecycle script (the ua-parser-js attack class: a deeply nested dependency running code at install time). npm records this in the lockfile; pnpm lockfiles do not, so this check is npm-only for now.
• `untrusted-source` — flags transitive packages resolving from git, url, or tarball sources instead of the registry. Works for both npm and pnpm.

Release-age, typo-squat, and provenance are deliberately not run transitively — they would either flood you with noise or require a registry round-trip per package. Transitive evaluation applies to safeinstall check, project installs, and the prepared lockfile for explicit npm/pnpm additions.

{

"transitive": { "mode": "warn", "checks": ["install-script", "untrusted-source"] } }

Typo-squat detection

Flags install requests whose package name is a close-but-not-exact match to a well-known popular package — the most common supply-chain attack pattern: lodsh for lodash, axois for axios, raect for react, and so on.

• Algorithm: Damerau-Levenshtein distance (transpositions count as a single edit)
• Target list: curated set of popular ecosystem packages, embedded at build time (no runtime network fetch)
• Default mode: "off" — opt in with typoSquat: { "mode": "warn" } or "block"
• False-positive mitigation: exact matches to the list are never flagged, short names (< 4 chars) are skipped, per-project ignore list is supported

Provenance verification

Cryptographically verifies the npm provenance attestation for registry installs and optionally pins the source repository via per-package trusted publisher patterns.

• Fetches the attestation bundle from the npm registry's /-/npm/v1/attestations/ @ endpoint
• Verifies the Sigstore bundle via the official sigstore package (signatures, Rekor transparency log, Sigstore public trust root)
• Extracts source repository, commit ref, and workflow path from the SLSA v1 provenance statement
• Matches the source repository slug against per-package trustedPublishers patterns — catching not only tampered tarballs but also **maintainer-compromis