Erzwingt Supply-Chain-Security-Policies für npm, pnpm und bun, indem das Alter des Releases, die Provenance und Typosquatting geprüft werden, bevor ein Package installiert wird.
Auch bekannt als Mickdownunder/SafeInstall, safeinstall-cli
- Stars
- 3
- Tools
- —
- Downloads, 30 Tage
- —
- Neueste Version
- 0.12.0
- Letzter Commit
- 13. Nov. 2026
- Lizenz
- MIT
Was ist SafeInstall MCP?
Erzwingt Supply-Chain-Security-Policies für npm, pnpm und bun, indem das Alter des Releases, die Provenance und Typosquatting geprüft werden, bevor ein Package installiert wird.
Zusammenfassung generiert aus dem README des Projekts
Über SafeInstall MCP server
SafeInstall bietet eine Security-Layer für Entwickler und AI Agents, die npm, pnpm oder bun nutzen. Es fungiert als Local-first-Gate, das Security-Policies ausführt, bevor ein Package Manager eine Installation startet. Da es lokal läuft und keine Konten oder Cloud-Konnektivität erfordert, wird sichergestellt, dass Supply-Chain-Risiken direkt am Point of Execution gemindert werden. Das Tool ist darauf ausgelegt, gegen gängige Bedrohungen wie Typosquatting, bösartige Lifecycle-Scripts und kompromittierte Maintainer-Accounts zu schützen.
Nutzer können mit dem System interagieren, indem sie Befehle präfixen, zum Beispiel durch die Verwendung von safeinstall pnpm add, um ein Package zu verifizieren, bevor es einem Projekt hinzugefügt wird. Für AI-gestützte Workflows bietet es ein MCP Tool und einen Shell Guard an, um Befehle in Umgebungen wie Claude Code, Codex oder Cursor abzufangen. Das System verifiziert Package-Metadaten, einschließlich des Release-Alters, der kryptografischen Provenance via Sigstore und der Source-Repository-Kontinuität, um sicherzustellen, dass die installierte Software der erwarteten Identität und Herkunft entspricht.
Was du damit machen kannst
- 1Verhindern von bösartigen Package-InstallationenEin AI Agent kann das MCP Tool nutzen, um zu verifizieren, dass ein angefordertes Package nicht zu neu ist und keine gefährlichen Install-Scripts enthält.
- 2Erkennen von kompromittierten Maintainer-AccountsEin Entwickler kann die Provenance-Verifizierung nutzen, um sicherzustellen, dass ein Package aus dem korrekten Source-Repository veröffentlicht wird.
- 3Schutz vor Typosquatting-AngriffenDas Tool kann so konfiguriert werden, dass Installationsversuche für Packages blockiert werden, die populären Libraries sehr ähnlich sehen.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
So installierst du SafeInstall MCP
Formate geprüft am 10. Nov. 2026Zu Cursor hinzufügenZu Goose hinzufügenSafeInstall MCP in Claude Code installieren
$ claude mcp add safeinstall -- npx -y safeinstall-cliSafeInstall MCP in Cursor installieren
~/.cursor/mcp.json
{
"mcpServers": {
"safeinstall": {
"command": "npx",
"args": [
"-y",
"safeinstall-cli"
]
}
}
}SafeInstall MCP in VS Code installieren
.vscode/mcp.json
{
"servers": {
"safeinstall": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"safeinstall-cli"
]
}
}
}SafeInstall MCP in VS Code CLI installieren
$ code --add-mcp '{"name":"safeinstall","type":"stdio","command":"npx","args":["-y","safeinstall-cli"]}'SafeInstall MCP in Claude Desktop installieren
claude_desktop_config.json
{
"mcpServers": {
"safeinstall": {
"command": "npx",
"args": [
"-y",
"safeinstall-cli"
]
}
}
}SafeInstall MCP in Codex installieren
$ codex mcp add safeinstall -- npx -y safeinstall-cliSafeInstall MCP in Codex config.toml installieren
~/.codex/config.toml
[mcp_servers.safeinstall] command = "npx" args = ["-y", "safeinstall-cli"]
SafeInstall MCP in Gemini CLI installieren
$ gemini mcp add -s user safeinstall npx -- -y safeinstall-cliSafeInstall MCP in Gemini settings.json installieren
~/.gemini/settings.json
{
"mcpServers": {
"safeinstall": {
"command": "npx",
"args": [
"-y",
"safeinstall-cli"
]
}
}
}Automatisierte Checks
Geluften am 14. Nov. 2026Vollständiger Bericht →Unsere automatisierten Checks bestanden. Das ist kein Security-Audit: Lies den Code und gib dem Server nur den minimal notwendigen Zugriff. Wie die Checks funktionieren
- Source Repository verknüpft und erreichbarmickdownunder/safeinstall is public and reachablegithub.com/mickdownunder/safeinstall ↗Bestanden
- Paket nennt dieses Repository als Quellesafeinstall-cli names mickdownunder/safeinstall as sourcenpmjs.com/package/safeinstall-cli ↗Bestanden
- Build-Provenienz (Sigstore-Attestierung)Sigstore attestation for safeinstall-clinpmjs.com/package/safeinstall-cli/v/0.12.0#provenance ↗Bestanden
- Open Source Lizenz (OSI)MITspdx.org/licenses/MIT.html ↗Bestanden
- Commit oder Release im letzten JahrLast commit or release 2026-10-08github.com/mickdownunder/safeinstall ↗Bestanden
- OpenSSF ScorecardNicht geprüft
- Package-Name ähnelt keinem populären PackageNo popular package one edit away from safeinstall-cliBestanden
- Keine kritischen Advisories im Paket oder seinen Abhängigkeiten8 resolved dependencies checked; no critical advisoryosv.dev ↗Bestanden
- Keine versteckten Anweisungen an das Modell0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersBestanden
- Destruktive Tools sind markiertNicht geprüft
- Remote-Endpoint beantwortet den MCP-HandshakeNicht geprüft
README
Auf GitHub ansehenWhat 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)
- 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 ciorpnpm install --frozen-lockfilewith 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 | Blocked: untrusted source |
| Trust downgrade | Detects registry→git/url or new scripts on update | 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 |
| Transitive dependencies | Off by default; opt in via transitive.mode |
Blocked: transitive install script / untrusted source |
| 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.
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 (theua-parser-jsattack 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 withtypoSquat: { "mode": "warn" }or"block" - False-positive mitigation: exact matches to the list are never flagged, short names (< 4 chars) are skipped, per-project
ignorelist 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
sigstorepackage (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
trustedPublisherspatterns — catching not only tampered tarballs but also maintainer-compromise attacks where an attacker republishes a legitimate-looking package from a fork they control - Publisher mismatches always block, even in
"warn"mode, because a valid signature from the wrong repo is exactly what maintainer compromise looks like
Default mode is "off". Opt in by setting provenance.mode to "warn" or "require".
Usage
# Ad-hoc installs
safeinstall pnpm add axios
safeinstall npm install react@19.2.0
# Project installs (lockfile-aware for npm/pnpm)
safeinstall pnpm install
safeinstall npm ci
# Monorepo — select a package; shared-lockfile installs review all importers
safeinstall pnpm -C packages/app install
safeinstall npm --prefix packages/app ci
# Utilities
safeinstall check # direct dependency audit
safeinstall check --json # machine-readable
safeinstall init # one-command onboarding: config, guard hooks for
# detected agents (.claude/, .codex/, .cursor/), trust lock
safeinstall init --force # overwrite an existing config (hooks/lock stay idempotent)
safeinstall init --client codex # force specific agents instead of detection
safeinstall init --no-guard --no-lock # config only (the old behavior)
safeinstall mcp # MCP server for AI coding agents
safeinstall guard install # register agent shell hooks (Claude Code, Codex, Cursor)
safeinstall trust lock # baseline the Agent Trust Surface
safeinstall trust lock --ci github # ...and scaffold the CI re-verification workflow
safeinstall trust status # reconcile the trust surface (exit 2 on drift; read-only)
safeinstall trust approve # review drift and re-baseline (interactive)
safeinstall trust unlock # remove the baseline (lock, ledger, head mirror)
safeinstall --help
safeinstall --version
# JSON output (CI/automation)
safeinstall --json pnpm add axios
# Explicit config file (skips upward discovery)
safeinstall --config ./ci/safeinstall.config.json check
Project installs
For pnpm install and npm install / npm ci, dependency versions come from the lockfile — not loose ranges in package.json.
pnpm-lock.yamlfor pnpmpackage-lock.jsonornpm-shrinkwrap.jsonfor npm- Stale, missing, or mismatched lockfile entries fail closed
- If
packageManageris set inpackage.json, using a different CLI is blocked - Workspace-targeting flags (
--filter,--workspace) are blocked — use-Cor--prefix bun add/bun installfail closed until artifact-bound Bun installation is implemented;checkand MCP policy queries remain available
Artifact-bound installation contract
Installation requires one canonical SHA-512 digest in the checked registry manifest and the matching lockfile entry. SHA-1-only or missing-integrity entries block. A different command-line registry, script-enabling flags, global installs, and unknown installation options block. Registry selection in environment variables or scoped .npmrc settings cannot authorize a different artifact: the resulting lockfile must still match the checked binding.
Explicit additions resolve into a lockfile with the evaluated exact version before installation. Preparation can update package.json and the lockfile, and can populate the manager's cache, even if the later binding/policy check blocks. Those files are left for inspection, not automatically rolled back. npm's frozen phase uses ci, which replaces node_modules. Shared workspace lockfiles cause all recorded importers' direct dependencies to be reviewed under the selected policy, not just the selected package.
Lifecycle scripts are always disabled, including when legacy packageManagerDefaults.*.ignoreScripts is false. allowedScripts permits a policy exception, not script execution. pnpm's executable .pnpmfile.cjs hooks are disabled too. Explicit non-registry additions currently block; existing local/workspace dependencies remain governed by allowedSources and are not claimed to have registry-artifact binding.
MCP server / AI agents
The CLI reaches humans who type safeinstall. The MCP server reaches AI coding agents — Claude Code, Codex, Cursor, Windsurf, Cline — so the policy engine can be consulted before an agent suggests or runs an install, without anyone typing anything.
safeinstall mcp starts a Model Context Protocol server over stdio that exposes one tool, check_package, backed by the exact same engine as the CLI (release age, install scripts, untrusted sources, typo-squat, Sigstore provenance, and provenance continuity).
[!IMPORTANT] MCP tools are advisory. Installing the server makes
check_packageavailable; it does not force an agent to call it. "Install once, protected forever" = one MCP config block + one rule snippet (mcp/agent-rule.md) telling the agent to call the tool before every install.
Wire it into your agent
Claude Code / Claude Desktop — add to your MCP config (claude_desktop_config.json or .mcp.json):
{
"mcpServers": {
"safeinstall": { "command": "npx", "args": ["safeinstall-cli", "mcp"] }
}
}
Cursor — add the same block to .cursor/mcp.json.
Then paste the rule from mcp/agent-rule.md into your CLAUDE.md / Cursor Rules. Full setup details: mcp/README.md.
What the agent sees
check_package accepts name (required), version (optional, defaults to latest), and manager (optional, informational) and returns a JSON verdict:
{
"verdict": "block",
"name": "raect",
"version": null,
"reasons": [
{ "code": "typo-squat-suspected", "message": "Blocked: Suspected typo-squat: \"raect\" is 2 edit(s) away from popular package \"react\".", "suggestion": "Verify you meant to install \"react\"." }
],
"warnings": [],
"infos": [],
"sourceRepository": null,
"ageHours": null
}
verdict is "block" when any policy reason blocks the install, otherwise "allow".
When no safeinstall.config.json is found, the MCP server uses a recommended secure preset — the built-in defaults with typoSquat and continuity promoted to "block", because the agent use case wants maximum signal. When a config file is found, it is respected exactly (same resolution as the CLI).
The MCP SDK ships as an optional dependency, lazily loaded only when safeinstall mcp runs — CLI-only users never install it. If it is missing, the command prints an install hint and exits non-zero.
Agent guard — enforcement, not advice
The MCP tool is advisory: an agent can consult it. The guard is a stronger layer: it hooks into the agent's shell layer and screens commands before they run, firing even when the agent doesn't know SafeInstall exists. This is best-effort shell interception — one layer of defense in depth, not a complete boundary; its command parsing is not exhaustive (see Guard limitations).
safeinstall guard install # Claude Code, Codex, and Cursor
safeinstall guard install --client codex # or just one client
This writes project-level hook configuration (merged non-destructively, idempotent on re-runs):
- Claude Code — a
PreToolUsehook on theBashtool in.claude/settings.json; raw installs are rewritten in-place through the SafeInstall CLI viaupdatedInputwith nopermissionDecision, so Claude's normal permission prompt still fires and shows the user the rewritten command to approve - Codex — a
PreToolUsehook onBashin.codex/hooks.json; raw installs are rewritten in-place through the SafeInstall CLI via CodexupdatedInput. Open/hooksin Codex after installation and trust the new project hook before expecting it to run. - Cursor — a
beforeShellExecutionhook in.cursor/hooks.json, registered withfailClosed: trueso a crashed or timed-out guard blocks instead of silently allowing
After registration, the CLI reports the Trust Surface step that matches the project state. A project without a baseline is directed to safeinstall trust lock. If a baseline already exists and the guard changed it, review the complete drift with safeinstall trust status and run safeinstall trust approve only when every change is intentional. Re-running an already-registered guard does not require re-approval unless status reports drift.
How the guard decides
The guard never evaluates policy itself — it detects package installs and routes them through the CLI, which owns the decision:
| Agent runs | Guard response |
|---|---|
git status, npm test, ... |
Allowed — not an install |
npm install axios (also npm i, pnpm add, bun a, npm ci, corepack pnpm add, pnpm --dir app add, ...) |
Claude/Codex: rewritten in-place to safeinstall npm install axios before execution (the permission prompt shows the routed command). Cursor: denied with the SafeInstall replacement |
cd app && npm i axios && npm test |
Rewrite prefixes only the install segment; Claude/Codex apply it directly, Cursor returns it to the agent |
safeinstall npm install axios |
Allowed — already routed through the policy engine |
npm install $(cat list.txt), bash -c "npm install ..." |
Denied — cannot be analyzed safely (fail-closed) |
yarn add axios |
Denied — SafeInstall cannot policy-check yarn |
npx tsc with typescript installed locally |
Allowed — npx resolves the local binary, nothing is downloaded |
npx create-next-app, pnpm dlx ..., bunx ..., yarn dlx ... |
Claude/Cursor: ask. Codex: deny because Codex PreToolUse does not currently support an ask decision |
Routing through the CLI matters more than a simple allow/deny: a vetted-but-raw npm install would still execute lifecycle scripts. Through SafeInstall, the same install gets the full policy evaluation and runs with install scripts disabled.
Claude and Codex apply the rewrite in-place through updatedInput, so the user's normal permission prompt shows the SafeInstall-routed command to approve rather than the raw install. Cursor receives the exact rewritten command in the block message so a well-behaved agent self-corrects in one step. The guard needs no network access and answers in milliseconds.
Guard limitations
- The
safeinstallbinary must be on the agent'sPATH(npm install -g safeinstall-cli). - Codex requires users to review and trust new or changed project hooks with
/hooks; until then Codex skips the hook. Codex currently intercepts only supported simple shell calls, not everyunified_execpath, so the hook is still a defense-in-depth guardrail rather than a complete boundary. npxand friends are not policy-checked: SafeInstall's engine evaluates installs, not one-off executions. Claude/Cursor request approval; Codex fails closed because itsPreToolUsehook does not currently supportask. The local-binary fast path mirrors the runners' own resolution (nearestnode_modules/.bin), so approved project tooling does not trigger the remote-runner gate.- A determined adversary can bypass shell-level analysis — installs can run out of band (a script file written first,
node -e, and similar), and command-line parsing itself is not exhaustive. Do not rely on the shell layer alone: it raises the bar as one layer of defense in depth — combine it with the MCP tool and CI checks.
SafeInstall MCP Fragen
Wie füge ich SafeInstall MCP zu Claude Code hinzu?
Führe claude mcp add safeinstall -- npx -y safeinstall-cli in deinem Terminal aus. Füge --scope user hinzu, damit der Server in jedem Projekt verfügbar ist.
Wie füge ich SafeInstall MCP zu Cursor hinzu?
Öffne ~/.cursor/mcp.json und füge den Server unter mcpServers hinzu, mit der Cursor-Config aus dem Installationsabschnitt oben.
Benötigt SafeInstall ein Cloud-Konto oder eine Internetverbindung für die Durchsetzung der Policies?
Nein, es ist ein Local-first-Tool, das keine Cloud-Abhängigkeit, kein Konto und kein Dashboard benötigt.
Wie geht SafeInstall mit Maintainer-Compromise-Angriffen um?
Es nutzt Provenance-Kontinuität, um zu erkennen, ob eine Package-Version von einem anderen Source-Repository attestiert wurde als der etablierte Baseline-Wert, selbst wenn die Signatur gültig ist.