Inspect npx packages cold. Pin clean releases.

Coldpin is a zero-dependency Node.js 24 CLI, local stdio MCP server (io.github.hynko431/coldpin), and native Antigravity plugin that vets npm tarballs in memory, verifies tarball-to-source parity, and recovers pre-compromise release anchors without executing untrusted install scripts.

Runtime & Cost
Node >= 24, 0 deps, $0/mo
Antigravity Strict
0 findings (5 primitives)
Benchmark Corpus
100.0% recall, 0.0% FPR
Self-Audit & Proofs
APPROVE 12/100, 35/35

Quickstart Install

Coldpin runs 100% locally with zero mandatory credentials or MCP variables. Prerequisites: Node.js >= 24.0.0, Git >= 2.25 (for commit bisection and Git parity), and Antigravity >= v1.5.23 for native PreToolUse hooks.

Antigravity CLI (macOS, Linux, Windows)
agy plugin install https://github.com/hynko431/Coldpin-npx-Safe-Finder
agy plugin list
agy --agent coldpin-auditor

Installs enabled immediately (zero mandatory variables) with 3 skills (including /coldpin-audit and /coldpin-incident), 7 read-only aspect agents, 3 rules, 1 local stdio MCP server, and 3 fail-safe PreToolUse hook groups.

Interactive Policy Lab

Test Coldpin's PreToolUse hook evaluator (lib/hook.mjs) and inspect its 4-state Title + Info + Evidence output cards directly in your browser. Everything runs locally with zero network requests.

DENY coldpin-npx-guard | UNVETTED_OR_OBFUSCATED_RUNNER | exit 0

Blocked unpinned, obfuscated, or non-canonical package runner. Inspect cold via Coldpin MCP before running.

{
  "decision": "deny",
  "reason": "[UNVETTED_OR_OBFUSCATED_RUNNER] Blocked unpinned, obfuscated, or non-canonical package runner."
}

Antigravity 5-Component Architecture

Coldpin aligns strictly to the official Antigravity plugin manifest schema (https://antigravity.google/schemas/v1/plugin.json). Scanner rule data lives cleanly in catalog/ so rules/ holds only agent Markdown rules.

Skills3 bundled

skills/coldpin/ is the canonical cross-harness skill with 5 modular playbooks under references/aspect-*.md.

Two Antigravity slash commands (/coldpin-audit and /coldpin-incident) provide guided audit and compromise recovery workflows.

Read-Only Agents7 bundled

Primary orchestrator coldpin-auditor (mainAgent: true) delegates across 6 isolated background specialists.

All 7 agents enforce commandExecutionPolicy: "off" and canonical view_file allowlists; all 6 background subagents set inheritCustomizations: false to prevent workspace rule poisoning.

Markdown Rules3 bundled

rules/AGENTS.md stays under 1,800 bytes (1,599 bytes measured) with a compact 6-aspect delegation routing table.

rules/coldpin-manifest-guard.md activates via trigger: glob on manifests and lockfiles; rules/coldpin-incident-checklist.md activates via trigger: model_decision.

Lifecycle Hooks3 enabled groups

Root hooks.json executes pure ES2020 lib/hook.mjs across coldpin-npx-guard, coldpin-config-guard, and coldpin-delegation-guard.

Always exits 0 with strictly allow, deny, or force_ask. Never emits auto-approval.

Local MCP Server1 stdio server

Root mcp_config.json runs node --no-warnings ${PLUGIN_ROOT}/lib/mcp.mjs with timeoutSeconds: 300, ${PLUGIN_DATA} cache isolation, and all 7 read-only tools marked eager: true (1,563 tokens).

Zero mandatory variables keeps public installs enabled on first click. Enterprise private registries can apply examples/mcp_config.private-registry.example.json.

Measured Output: agy plugin validate . --strict --json
{
  "manifest": "plugin.json",
  "name": "coldpin",
  "components": { "agents": 7, "hooks": 3, "mcpServers": 1, "rules": 3, "sidecars": 0, "skills": 3 },
  "findings": []
}

7 Aspect Agents & 3 Guardrail Hooks

Each security aspect runs in an isolated read-only subagent with private body rules and a scoped MCP tool allowlist.

Agent Role & Mode Scoped Coldpin Tools Isolation
coldpin-auditor Primary orchestrator (mainAgent: true) Delegates via invoke_subagent + all 7 read-only MCP tools commandExecutionPolicy: "off"
coldpin-discoverer Capability search & squat screening discover_packages inheritCustomizations: false
coldpin-inspector In-memory tarball triage & taint inspect_package_artifact, get_artifact_report inheritCustomizations: false
coldpin-manifest-auditor Batch screening of package.json (up to 50 deps) audit_manifest_batch, get_artifact_report inheritCustomizations: false
coldpin-confusion-auditor Private-scope & .npmrc confusion audit (T1195.001) verify_confusion inheritCustomizations: false
coldpin-forensics Patient-zero commit bisect & REA triage handoff resolve_safe_anchor, inspect_package_artifact inheritCustomizations: false
coldpin-compliance Audit log chain verification & disclosure clocks audit_verify, get_artifact_report inheritCustomizations: false

7 MCP Tools & 6 CLI Verbs

Both the CLI (lib/cli.mjs) and local stdio MCP server (lib/mcp.mjs) execute the same pure async workflows. Exit codes remain deterministic across terminals and CI pipelines: 0 clean within scope, 2 suspicious or unknown, 3 malicious indicators found, and 1 invalid usage or error.

MCP Tool CLI Verb Exit Codes Capability
discover_packages discover 0 / 2 / 1 Search npm by capability, category, org, or creator with org allow/deny policy, release cooldown, and 7-primitive typosquat/slopsquat filters.
inspect_package_artifact inspect 0 / 2 / 3 / 1 Stream tarball over HTTPS (or local .tgz), verify SHA-512, unpack strictly in memory, run linear-time JS/TS taint and hidden-Unicode triage, check OSV/MAL-*, and verify 3-tier tarball-to-Git parity.
resolve_safe_anchor resolve-anchor 0 / 2 / 3 / 1 Walk --first-parent history with blob-cached SQLite scans to isolate patient-zero commit, evaluate residual CVEs/KEV, and emit ROLLBACK_TO_SAFE_ANCHOR only when a verified npm tarball exists.
verify_confusion verify-confusion 0 / 3 / 1 Inspect workspace package.json and .npmrc for unpinned private scopes and claimable internal names (T1195.001).
audit_manifest_batch audit-batch 0 / 2 / 3 / 1 Screen up to 50 direct dependencies in package.json with private-scope OSV non-leakage and compact <= 500-token MCP summaries.
audit_verify audit-verify 0 / 3 / 1 Verify sequence numbers, extra-field tamper protection, and SHA-256 hash chain integrity of local audit.jsonl logs.
get_artifact_report mcp 0 / 1 Page full inspection or batch reports from the bounded in-memory LRU cache (25 entries, 30-minute TTL, 15 MiB cap; never persisted to SQLite).

Harnesses & Multi-Host Distribution

One canonical skill source (skills/coldpin/) and one zero-dependency ESM build (lib/) target every harness without forked prose. scripts/pack_plugin.py produces deterministic, checksum-verified archives with explicit POSIX 0755 modes on entrypoints.

Harness / Channel Manifest / Identifier Entrypoint
Antigravity App, CLI & IDEs plugin.json, mcp_config.json, hooks.json agy plugin install https://github.com/hynko431/Coldpin-npx-Safe-Finder
Official MCP Registry io.github.hynko431/coldpin (server.json) npx --ignore-scripts coldpin@1.5.2 mcp
npm & Standalone CLI coldpin@1.5.2 (package.json) coldpin / coldpin-mcp
Claude Code .claude-plugin/plugin.json (inline mcpServers) coldpin-claude.zip
Codex CLI / ChatGPT .codex-plugin/plugin.json coldpin-openai.zip

Full harness packaging details: docs/harnesses.md.

Enterprise Configuration & Data Handling

Zero Telemetry & Private-Scope Isolation: Coldpin runs no hosted backend, analytics collector, or external database. Any scope listed in COLDPIN_PRIVATE_SCOPES, .coldpin.policy.json, or $HOME/.npmrc never contacts public registry.npmjs.org or api.osv.dev, and 1-edit typos of private scopes are hard-blocked before any network call.
Environment Variable Required Behavior & Guardrails
COLDPIN_POLICY_PATH No Operator-pinned immutable .coldpin.policy.json (overrides workspace policy and env scope defaults).
COLDPIN_ALLOWED_ROOTS No OS-delimited local workspace root allowlist for local tarball, lockfile, and Git directory reads.
COLDPIN_AUDIT_LOG No Path to optional append-only hash-chained audit.jsonl using pseudonymous SHA-256 actor_id_hash.
COLDPIN_OFFLINE No Set to 1 to forbid all outbound network traffic and remote Git clones (fails closed).
COLDPIN_PRIVATE_SCOPES No Comma-separated internal @scope list routed exclusively to COLDPIN_PRIVATE_REGISTRY_URL.
COLDPIN_PRIVATE_REGISTRY_URL No HTTPS-only private registry origin validated against SSRF loopback, link-local, IMDS, and RFC 1918 IP ranges.
COLDPIN_REGISTRY_TOKEN No (Secret) Read-only bearer token sent strictly over HTTPS to the exact matching private host. Unexpanded ${VAR} placeholders are rejected and tokens are never logged.

Compliance & Incident Reference

rules/coldpin-incident-checklist.md and /coldpin-incident surface standard regulatory notification clocks when malicious indicators are confirmed: India CERT-In (6 hours) and DPDP Act/Rules, EU CRA and NIS2 (24-hour early warning, 72-hour notification), GDPR Art. 33 (72 hours), and NIST SSDF / SOC 2 evidence trails. Read full disclosures in docs/privacy.md and SECURITY.md.

Verification & Supply-Chain Provenance

Every release runs a 14-gate pipeline across ubuntu-latest and windows-latest on Node 24 and Node 26: 39/39 deterministic tests, 49-fixture corpus (100.0% recall, 0.0% FPR), 35/35 mutation proofs, SkillSpector self-audit (SS-03 through SS-15: APPROVE, risk 12/100, 0 blocking), dual in-toto DSSE signatures (skills/coldpin/skill.oms.sig across 18 files and catalog/plugin.oms.sig across 40 files), and GitHub SLSA Build Provenance attestations (SLSA attestations).

Release v1.5.2 Verified SHA256SUMS.txt
5fad53fcbb621427977fc91684483b87866e97303804bfa95f87cbb4e8caafd8  coldpin-antigravity.zip
9bec08170f203d458941e7de4659aa028665cc9c704c81c11eae8c712c99bc7f  coldpin-claude.zip
57c064f256bdab77510d425ff2e42a4a8c9544906eeff2ab9a97fbcf06ecedf5  coldpin-openai.zip
7206e35a3daf88525c1c335e55a6f902ac6849ba20f317e0b7f66a8a95c2135c  skillspector-self-audit.sarif

Full evidence reports: BENCHMARK.md, SkillSpector Self-Audit, and TESTING.md.

FAQ & Epistemic Limits

Does VERIFIED_CLEAN_WITHIN_SCOPE prove a package has zero malware?
No. Static analysis cannot prove absence of malware on dynamically fetched remote payloads, time-bombed triggers, or uninspected compiled binaries. VERIFIED_CLEAN_WITHIN_SCOPE means only that no malicious, suspicious, policy-violating, or uninspected-binary indicators were observed within the stated static inspection boundary.
Why does the recommended npx command include a SHA-512 and transitive caveat?
Stock npx (npm exec) has no --integrity CLI flag and ignores lockfiles inside published packages, resolving floating transitive ranges live at runtime. Coldpin states that boundary honestly instead of implying a bare npx command enforces full transitive locks. Combine exact version pins and --ignore-scripts with a private caching proxy for regulated builds.
Why does resolve-anchor emit FORENSIC_COMMIT_ONLY when no npm tarball matches?
Running npx github:org/repo#sha executes prepare and postinstall build scripts locally and pulls floating dependencies. When a verified clean commit has no matching published npm tarball, Coldpin suppresses runnable commands and recommends either building in an isolated sandbox or switching to a vetted category alternative (SWITCH_TO_ALTERNATIVE).
Do I need REA (rea-agents) installed to use Coldpin?
No. Discovery, in-memory archive quarantine, JS/TS lexical taint analysis, hidden-Unicode detection, 3-tier tarball parity, and Git commit bisection run on pure Node.js 24 with zero external packages. When a tarball contains obfuscated bundles or compiled .node, WASM, ELF, PE, or Mach-O binaries, Coldpin fails closed and points to a pre-registered REA server without ever running npx -y rea-agents.
Are there alternatives, and where do I get support?
Yes: Socket.dev, Snyk, GuardDog, OSV-Scanner, and private registries (Verdaccio, Artifactory) cover overlapping areas. Coldpin focuses on the local, zero-dependency, agentic pre-npx workflow. Report bugs or detection gaps publicly at GitHub Issues; report security vulnerabilities via SECURITY.md.