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.
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.
npx --ignore-scripts coldpin@1.5.2 mcp
npx --ignore-scripts coldpin@1.5.2 inspect semver@7.7.1
npx --ignore-scripts coldpin@1.5.2 audit-batch ./package.json --limit 50
Published as coldpin@1.5.2 on npm and indexed in the
Official MCP Registry as io.github.hynko431/coldpin.
sha256sum -c SHA256SUMS.txt
python -m zipfile -e coldpin-antigravity.zip ./coldpin-antigravity
agy plugin validate --strict ./coldpin-antigravity
agy plugin install ./coldpin-antigravity
Reproducible host archives for Antigravity, Claude Code, and Codex CLI ship with SHA-256 digests and GitHub SLSA build provenance on Release v1.5.2.
COLDPIN_OFFLINE=1 node --no-warnings lib/cli.mjs inspect \
--tarball ./vendor/pkg.tgz \
--git-dir ./vendor/repo \
--offline --sarif --audit-log ./audit.jsonl
Performs zero outbound HTTP requests, blocks remote git clone, and fails closed as UNVERIFIABLE_UNKNOWN when live OSV intelligence is absent.
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.
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."
}
semver@7.7.1
VERIFIED_CLEAN_WITHIN_SCOPE (exit 0)- Archive & Integrity
- sha512-verified (in-memory stream, 14 files, 0 lifecycle hooks)
- Tarball-vs-Git Parity
- Tier 1 + Tier 2 verified (Git tag matches tarball files)
- Observed Findings
- 0 malicious indicators, 0 OSV/MAL-* advisories, 0 hidden Unicode or taint chains
- Explicit Unknowns
- Runtime behavior of floating transitive dependencies is outside static tarball scope.
npx --yes --ignore-scripts --package=semver@7.7.1 -- semver --help
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.
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.
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.
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.
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.
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.
{
"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
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).
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?
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?
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?
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?
.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?
npx workflow.
Report bugs or detection gaps publicly at GitHub Issues; report security vulnerabilities via SECURITY.md.