SafeInstall

Overview

Installation

1. Use Node.js >=20.
2. Install globally or invoke with npx — no account or registry auth required.

Open source · MIT licensed · Source on GitHub

Usage

Pass through the same arguments you would use with the underlying tool. Since 0.9.0 the documented package-manager aliases work too — npm i, pnpm i, bun a, npm clean-install.

Project installs

Policy (defaults)

These are the main gates. Adjust or exempt via config where documented below.

Configuration

Optional safeinstall.config.json is discovered by walking upward from the effective project directory; the nearest file wins. Since 0.9.0 you can also pass an explicit path with the global --config <path> flag — an explicit path that cannot be read is a hard error (exit 1), never a silent fallback to defaults, so CI cannot accidentally run with a weaker policy than intended.

CI and exit codes

0 — success or policy allowed. 1 — runtime or config error. 2 — blocked by policy. Use 2 like any other failing step in a pipeline.

safeinstall check

Evaluates direct dependencies only. On success, stderr includes: Check passed: no direct dependency policy violations found.

safeinstall init

Writes a starter safeinstall.config.json in the current directory. Refuses if the file exists unless you pass --force.

JSON output

Put --json anywhere in argv. Structured output goes to stdout; human-oriented messages stay separate. Field details are stable in the CLI version you install.

GitHub Action

SafeInstall is available as a reusable GitHub Action at Mickdownunder/SafeInstall@v1. The action is a composite action that installs safeinstall-cli and runs policy checks. No Docker image or custom Node runtime is required.

Basic usage

By default the action runs safeinstall check --json against direct dependencies. The job fails if any dependency is blocked by policy.

Install mode

In install mode the action runs the package manager through SafeInstall so policy is enforced before packages are written to disk.

Inputs

Outputs

Job summary

The action writes a job summary to the GitHub Actions UI. Allowed runs show a green checkmark and the summary line. Blocked runs show the full JSON output in a collapsible details block so reviewers can see exactly what was blocked and why without clicking into the logs.

MCP server / AI agents

The CLI protects people who type safeinstall. The MCP server reaches the AI coding agent itself — Claude Code, Claude Desktop, Cursor, Windsurf, Cline — so the policy engine is consulted before an agent suggests or runs an install, without anyone typing the prefix.

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).

Connect your client

Add the server to your MCP config — .mcp.json / claude_desktop_config.json for Claude Code/Desktop, .cursor/mcp.json for Cursor. Windsurf, Cline, and other MCP clients use the same shape.

If SafeInstall is installed globally you can instead use "command": "safeinstall", "args": ["mcp"].

check_package

Accepts name (required), version (optional, defaults to latest), and manager (optional, informational), and returns a JSON verdict:

verdict is block whenever the engine produces any blocking reason, otherwise allow. sourceRepository is the GitHub owner/repo the version was published from (from verified provenance or the continuity baseline) when available.

Config resolution

The server resolves safeinstall.config.json exactly like the CLI. When a config file is found it is respected exactly. When none is found, the server uses a recommended secure preset — the built-in defaults with typoSquat.mode and continuity.mode promoted to block, because the agent use case wants maximum signal.

The MCP SDK (@modelcontextprotocol/sdk) is an optional dependency, loaded lazily only when safeinstall mcp runs — CLI-only users never install it. npx safeinstall-cli mcp pulls it in automatically; if it is missing the command prints an install hint and exits non-zero. Full setup: mcp/README.md.

Agent guard — enforcement, not advice

New in 0.9.0. The MCP tool is advisory — an agent can consult it. The agent guard is enforcement: SafeInstall registers as a pre-shell-execution hook for Claude Code and Cursor, so every shell command an agent wants to run is intercepted before it executes — whether or not the agent cooperates.

The guard never evaluates policy itself. It detects package installs — including aliases (npm i, bun a), env-var prefixes, wrappers like sudo and corepack, chained commands, and pipes — and denies them with the exact rewritten command routed through SafeInstall. Blocking becomes steering: a well-behaved agent self-corrects in one step, and the install then runs with full policy evaluation and lifecycle scripts disabled.

Decision model

The guard needs no network access and answers in milliseconds. Hook registration is idempotent and conservative: existing hooks are preserved, a malformed settings file is left untouched and reported. For Cursor the hook is registered with failClosed: true, so a crashed hook blocks instead of silently allowing.

Honest limit: the guard sees shell commands, not intent. An install performed by a program the agent writes and runs (a Node script calling npm programmatically) is not intercepted. It raises the bar for the common path; it is not a sandbox.

Agent Trust Surface — self-defending policy

New in 0.10.0. The guard stops raw installs — but a prompt-injected agent does not have to fight it. It can rewrite the rules: weaken safeinstall.config.json, delete the hook from .cursor/hooks.json, plant an invisible-Unicode instruction in CLAUDE.md, or register a malicious MCP server. Those files program the next agent session — in the agent era, they are the persistence surface.

safeinstall trust lock records a hash baseline of that surface. SafeInstall reconciles the real state against it before every guard decision and every install/check, so tampering is detected — even a bypass the guard never sees (a node -e install, or deleting the hook to silence the guard).

The three zones

Instruction content drift only warns by default because Claude Code writes to CLAUDE.md itself (its memory feature); hidden Unicode has no legitimate purpose in these files and always blocks.

Commands

trust status is read-only and exits 2 on drift — use it in CI. trust approve and trust unlock read confirmation from the controlling terminal and refuse to run in CI or agent-hook contexts, so an agent cannot re-baseline or remove the surface on its own.

CI is the durable anchor

trust lock --ci github scaffolds .github/workflows/safeinstall-trust.yml, which re-verifies the committed baseline on every pull request with the CLI pinned to an exact version. It runs on a machine the agent does not control, so tampering done on a compromised local machine does not survive review. The workflow file is itself part of the tracked surface — disabling it is drift.

Honest scope

Locally this is tamper-evident, not tamper-proof, and it is user-space: a scheme-aware agent in your own account can bypass interception, rewrite the in-repo lock and ledger into a consistent state, and delete the local head mirror — user space cannot stop that. What it cannot subvert is CI re-verification of the committed lock on a machine it does not control. Rely on the CI check for a real adversary; the local layer catches mistakes and non-targeted tampering.

Exceptions

allowedPackages — exact name match skips release-age, install-script, and typo-squat checks (with a warning); source, trust-downgrade, and provenance checks still apply. allowedScripts — per-package lifecycle phases you accept for policy; SafeInstall may still forward ignore-scripts by default via packageManagerDefaults.

Limitations

• —Not a CVE scanner — pair with npm audit or other tools for vulnerability data.
• —Transitive dependencies are evaluated for install scripts and untrusted sources when transitive.mode is enabled. Release-age, typo-squat, and provenance still apply to direct dependencies only.
• —Transitive install-script detection is npm-only — pnpm lockfiles do not record install-script presence. Transitive untrusted-source detection works for both npm and pnpm.
• —Trust script comparison needs the previous resolved tree under node_modules.
• —Bun project installs are not fully lockfile-aware.
• —peerDependencies are not evaluated unless also declared as direct dependencies.
• —Ambiguous metadata leads to a block, not a silent allow.
• —Typo-squat target list is curated and refreshed manually between releases; brand-new packages published in the last day may not yet appear on the list.
• —Provenance verification supports GitHub Actions trusted publishers on the public Sigstore root only. GitLab CI, self-hosted Sigstore, and other trust roots are currently out of scope.
• —Provenance continuity catches attestation downgrades and source-repository changes between versions; it cannot catch an attack delivered through a legitimately-compromised CI workflow that still produces valid provenance from the real repository (the Shai-Hulud worm class). There is no identity discontinuity to detect there.
• —MCP tools are advisory. The check_package tool is available once the server is configured, but the agent only consults it if instructed to by a rule snippet. For enforcement at the shell layer, use the agent guard.
• —The agent guard intercepts shell commands in Claude Code and Cursor. It does not see installs performed by programs the agent writes and runs, and a human at a plain terminal is not gated. It raises the bar for the common agent path; it is not a sandbox.
• —Git sources are identified by URL for allowlist and trusted-publisher purposes, not by inferred package name. This is intentional: conflating registry axios with github:any-fork/axios would be dangerous.

Out of scope

SafeInstall is a pre-install guard, not a full platform.

License

SafeInstall is open source, released under the MIT license. Source code is on GitHub. Free forever for individual use. Team features (shared policy, org-wide enforcement) are a planned commercial addition — not part of the current CLI.