SafeInstall

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 any command: safeinstall pnpm add axios. Policy runs, then pnpm. Release age, install scripts, untrusted sources, typo-squats, and cryptographic provenance are checked before anything touches disk.
• 🤖 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

┌─────────────────────┐     ┌──────────────┐     ┌─────────────────┐
│  safeinstall pnpm   │ ──▶ │  Resolve &   │ ──▶ │  Policy check   │
│  add axios          │     │  fetch meta  │     │  (age, scripts, │
└─────────────────────┘     └──────────────┘     │  sources, ...)  │
                                                  └────────┬────────┘
                                                           │
                                                 ┌─────────▼─────────┐
                                          pass → │  Invoke pnpm add  │
                                          fail → │  Exit 2 (blocked) │
                                                 └───────────────────┘

1. Resolves what would be installed
2. Fetches registry metadata (publish time, declared scripts)
3. Evaluates policy rules
4. Blocks (exit 2) or invokes the real package manager

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 and project installs (pnpm install, npm ci), which have a resolved lockfile.

{
  "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/<pkg>@<version> 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-compromise attacks where an attacker r

…