패키지 설치 전 릴리스 기간, provenance, typosquatting을 확인하여 npm, pnpm, bun의 공급망 보안 정책을 강제합니다.
다른 이름 Mickdownunder/SafeInstall, safeinstall-cli
- 스타
- 3
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- 0.12.0
- 마지막 커밋
- 2026년 11월 13일
- 라이선스
- MIT
SafeInstall MCP란?
패키지 설치 전 릴리스 기간, provenance, typosquatting을 확인하여 npm, pnpm, bun의 공급망 보안 정책을 강제합니다.
프로젝트 README에서 생성된 요약
SafeInstall MCP server 정보
SafeInstall은 npm, pnpm 또는 bun을 사용하는 개발자와 AI agent를 위한 보안 계층을 제공합니다. 패키지 매니저가 설치를 실행하기 전에 보안 정책을 수행하는 로컬 우선 게이트 역할을 합니다. 계정이나 클라우드 연결 없이 로컬에서 실행되므로, 실행 시점에서 공급망 리스크를 완화할 수 있습니다. 이 도구는 typosquatting, 악성 라이프사이클 스크립트, 탈취된 유지 관리자 계정과 같은 일반적인 위협으로부터 보호하도록 설계되었습니다.
사용자는 명령어 앞에 접두사를 붙여 시스템과 상호작용할 수 있습니다. 예를 들어 safeinstall pnpm add를 사용하여 프로젝트에 패키지를 추가하기 전에 검증할 수 있습니다. AI 기반 워크플로우의 경우, Claude Code, Codex 또는 Cursor와 같은 환경에서 명령어를 가로챌 수 있는 MCP tool 및 shell guard를 제공합니다. 시스템은 릴리스 기간, Sigstore를 통한 암호화된 provenance, 소스 저장소 연속성을 포함한 패키지 메타데이터를 검증하여 설치되는 소프트웨어가 예상된 ID 및 출처와 일치하는지 확인합니다.
활용 사례
- 1악성 패키지 설치 방지AI agent는 MCP tool을 사용하여 요청된 패키지가 너무 최신이 아니며 위험한 install 스크립트가 없는지 확인할 수 있습니다.
- 2유지 관리자 계정 탈취 감지개발자는 provenance 검증을 사용하여 패키지가 올바른 소스 저장소에서 게시되고 있는지 확인할 수 있습니다.
- 3typosquatting 공격 방어인기 라이브러리와 유사한 패키지에 대한 설치 시도를 차단하도록 도구를 구성할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
SafeInstall MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 SafeInstall MCP 설치
$ claude mcp add safeinstall -- npx -y safeinstall-cliCursor에 SafeInstall MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"safeinstall": {
"command": "npx",
"args": [
"-y",
"safeinstall-cli"
]
}
}
}VS Code에 SafeInstall MCP 설치
.vscode/mcp.json
{
"servers": {
"safeinstall": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"safeinstall-cli"
]
}
}
}VS Code CLI에 SafeInstall MCP 설치
$ code --add-mcp '{"name":"safeinstall","type":"stdio","command":"npx","args":["-y","safeinstall-cli"]}'Claude Desktop에 SafeInstall MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"safeinstall": {
"command": "npx",
"args": [
"-y",
"safeinstall-cli"
]
}
}
}Codex에 SafeInstall MCP 설치
$ codex mcp add safeinstall -- npx -y safeinstall-cliCodex config.toml에 SafeInstall MCP 설치
~/.codex/config.toml
[mcp_servers.safeinstall] command = "npx" args = ["-y", "safeinstall-cli"]
Gemini CLI에 SafeInstall MCP 설치
$ gemini mcp add -s user safeinstall npx -- -y safeinstall-cliGemini settings.json에 SafeInstall MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"safeinstall": {
"command": "npx",
"args": [
"-y",
"safeinstall-cli"
]
}
}
}자동 검사
2026년 11월 14일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능mickdownunder/safeinstall is public and reachablegithub.com/mickdownunder/safeinstall ↗통과
- 패키지가 이 저장소를 소스로 명시safeinstall-cli names mickdownunder/safeinstall as sourcenpmjs.com/package/safeinstall-cli ↗통과
- 빌드 출처(Sigstore 증명)Sigstore attestation for safeinstall-clinpmjs.com/package/safeinstall-cli/v/0.12.0#provenance ↗통과
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-10-08github.com/mickdownunder/safeinstall ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음No popular package one edit away from safeinstall-cli통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음8 resolved dependencies checked; no critical advisoryosv.dev ↗통과
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기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)
- 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 질문
SafeInstall MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add safeinstall -- npx -y safeinstall-cli를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
SafeInstall MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
정책 적용을 위해 SafeInstall이 클라우드 계정이나 인터넷 연결을 필요로 하나요?
아니요, SafeInstall은 클라우드 의존성, 계정, 대시보드가 필요 없는 로컬 우선 도구입니다.
SafeInstall은 유지 관리자 계정 탈취 공격을 어떻게 처리하나요?
provenance 연속성을 사용하여, 서명이 유효하더라도 패키지 버전이 기존 기준과 다른 소스 저장소에서 인증되었는지 감지합니다.