
coldpin
io.github.hynko431/coldpin
Zero-execution npx/npm security auditor: static taint, Git parity, clean anchors, batch triage.
Documentation
Inspect npx packages cold in memory. Pin clean releases with verifiable evidence.
Install · Quickstart · Documentation · Benchmarks
Discover npx CLI packages by capability, category, creator, or organization without executing untrusted install scripts. Coldpin (coldpin) is a zero-dependency Node.js 24 CLI, local-first JSON-RPC 2.0 stdio MCP server (lib/mcp.mjs), and multi-harness AI agent plugin.
Deterministic CLI & Local MCP Server fetch tarballs over HTTPS, verify SHA-512 integrity, unpack strictly in memory, run linear-time JS/TS lexical taint and hidden-Unicode triage, check OSV/OpenSSF MAL-* advisories, and validate 3-tier tarball-to-Git parity. Safe-Anchor Resolver walks release history and cached Git commits (--first-parent) to isolate the patient-zero commit and recover a verified pre-compromise release or vetted alternative. You review the Title + Info + Evidence card and decide whether to run any command.
Install
Choose your coding agent, MCP client, or run the CLI standalone.
Standalone CLI & Local MCP Server (Node.js >= 24.0.0, zero runtime dependencies)
git clone https://github.com/hynko431/Coldpin-npx-Safe-Finder.git
cd Coldpin-npx-Safe-Finder
node --no-warnings lib/cli.mjs --help
node --no-warnings lib/mcp.mjs # Start local stdio MCP server (or: coldpin mcp)
Or install via npm (npx --ignore-scripts coldpin@1.5.2 mcp) or download a checksum-verified host bundle (coldpin-{antigravity,claude,openai}.zip + SHA256SUMS.txt) from GitHub Releases.
Antigravity (CLI / Workspace / App / IDEs — requires agy >= v1.5.13)
Build (or download from GitHub Releases) the clean allowlisted Antigravity plugin bundle — shipping all 5 native primitives (rules/: 3 Markdown rules, agents/: 7 strictly read-only aspect agents, skills/: 3 skills including /coldpin-audit and /coldpin-incident, hooks.json: 3 default-enabled fail-safe PreToolUse groups, and mcp_config.json: local zero-variable stdio with 7 eager tools and ${PLUGIN_DATA} cache isolation):
python scripts/pack_plugin.py --target antigravity --verify
python -m zipfile -e dist/coldpin-antigravity.zip ./coldpin-antigravity
agy plugin install ./coldpin-antigravity
agy --agent coldpin-auditor
For enterprise private registries, copy mcp_config.private-registry.example.json as an opt-in Antigravity variables overlay. For workspace-scoped discovery inside this repository, run python scripts/pack_plugin.py --verify --sync-workspace (syncs .agents/skills/coldpin/). For manual global installation into ~/.gemini/config/plugins/coldpin/, see Harnesses.
Claude Code, Codex CLI & Official MCP Registry
Build host-specific reproducible archives from this single source tree (no forked skill text):
python scripts/pack_plugin.py --target all --verify
See Harnesses for mcp_config.json, server.json (io.github.hynko431/coldpin), .claude-plugin/plugin.json, .codex-plugin/plugin.json, and marketplace catalog setup.
Try your first audit
Run any step below directly from your terminal or ask your coding agent to invoke Coldpin's 7 MCP tools (discover_packages, inspect_package_artifact, resolve_safe_anchor, verify_confusion, audit_manifest_batch, audit_verify, get_artifact_report).
1. Discover
npx tools safely
node --no-warnings lib/cli.mjs discover "json formatter" --category cli --limit 10
Screens candidates against org allow/deny policy, 7 typosquatting/slopsquatting mutation primitives, and release age cooldowns while routing private scopes exclusively to private registries.
2. Inspect a package or offline tarball
node --no-warnings lib/cli.mjs inspect semver@7.7.1
node --no-warnings lib/cli.mjs inspect --tarball ./pkg.tgz --git-dir ./repo --offline --sarif
Emits a deterministic Title + Info + Evidence card (or --json, --sarif, --sbom) with exit code 0 (clean within scope), 2 (suspicious or unknown), or 3 (malicious indicators found).
3. Recover a clean commit/release anchor
node --no-warnings lib/cli.mjs resolve-anchor @org/tool --git-dir ./repo --window 200
Pinpoints the patient-zero commit, checks cached full-tree blobs across history, verifies CVE/KEV gates, and emits ROLLBACK_TO_SAFE_ANCHOR only when a verified npm tarball exists (otherwise FORENSIC_COMMIT_ONLY or SWITCH_TO_ALTERNATIVE).
4. Batch-screen
package.json, audit dependency confusion & verify local audit trail
node --no-warnings lib/cli.mjs audit-batch ./package.json --limit 50
node --no-warnings lib/cli.mjs verify-confusion ./package.json
node --no-warnings lib/cli.mjs audit-verify ./audit.jsonl
How it works
| Layer | Trust Boundary | Responsibility |
|---|---|---|
Deterministic CLI & Local MCP (lib/) | Zero execution; in-memory archive parsing; stdio-only (0 listening sockets); operator-only control plane | Computes 4-state verdict, SHA-512 verification, AST taint, parity, defanged IOCs, SARIF 2.1.0, CycloneDX 1.5 SBOM, and summary-first MCP paging. |
Native Guardrails (rules/, agents/, hooks.json) | Read-only aspect subagents (commandExecutionPolicy: "off"); fail-safe ES2020 PreToolUse hook (exit 0, zero auto-approval) | Routes 6 security aspects across isolated subagents, blocks unvetted/evasive npx commands, and forces confirmation on pinned runs, config edits, and writable define_subagent requests. |
Agent Skills (skills/) | Untrusted package prose isolated as data; fails closed on unknowns | Orchestrates the 7 MCP tools / 6 CLI verbs with 5 modular aspect playbooks plus Antigravity /coldpin-audit and /coldpin-incident workflows. |
| You | Human approval gate before any host execution | Review observations, inferences, unknowns, and transitive caveats before running any pinned command. |
Static triage does not replace runtime isolation or human judgment. See FAQ and Benchmarks for measured detection coverage and explicit unknowns.
Choose a workflow
| CLI Verb / MCP Tool | Exit Codes | Use it to… |
|---|---|---|
discover / discover_packages | 0 / 2 / 1 | Search npm tools by query, org, creator, or category with typosquat and policy filters. |
inspect / inspect_package_artifact | 0 / 2 / 3 / 1 | Vet a package or local .tgz without execution and emit Card, JSON, SARIF 2.1.0, or CycloneDX SBOM. |
resolve-anchor / resolve_safe_anchor | 0 / 2 / 3 / 1 | Find patient-zero commit and recover a verified pre-compromise release or clean alternative. |
verify-confusion / verify_confusion | 0 / 3 / 1 | Audit package.json and .npmrc for unpinned private scopes and claimable internal names (T1195.001). |
audit-batch / audit_manifest_batch | 0 / 2 / 3 / 1 | Batch-screen up to 50 direct dependencies in package.json (squat, policy, route-isolated OSV/MAL-*/KEV) with <= 500-token MCP summaries. |
audit-verify / audit_verify | 0 / 3 / 1 | Verify local hash-chained audit.jsonl sequence and digest integrity. |
mcp / get_artifact_report | 0 / 1 | Serve the local stdio MCP server and page session-scoped inspection reports without SQLite verdict caching. |
Learn more
- Getting started: end-to-end workflows, policy setup, MCP env vars, and offline usage.
- Harnesses: Antigravity, Claude Code, Codex CLI, Official MCP Registry (
server.json), and verified support status. - Privacy & data handling: exact network egress, private-scope non-leakage, and credential boundaries.
- FAQ: trade-offs, false-positive controls, stock
npxlimits, and REA optionality. - Design specification & Design sitemap: locked architecture and design records.
- Testing & verification: deterministic unit/E2E/MCP/hook tests, 14 automated verification gates, cross-platform CI matrix, SkillSpector self-audit (
SS-03–SS-15), and reproducible build gates. - Benchmarks & Skill Card: real executed Tier 1–2 measurements (
49-fixture corpus, mutation proofs) and honest Tier 3 status. - Fact Ledger, Maintenance Cadence, & Changelog.
Contribute & Security
- Read SECURITY.md for security boundaries and responsible vulnerability disclosure.
- Read CONTRIBUTING.md for zero-dependency rules, Detection-as-Code requirements, and pre-PR gates.
- See ACCESSIBILITY.md for CLI/card accessibility practices and known harness limits.
License
Apache 2.0. Engineering guidance, not legal, medical or financial advice; confirm decisions with qualified counsel.
coldpinnpm install coldpin