Repository avatar
Version Control
v1.5.2
active

coldpin

io.github.hynko431/coldpin

Zero-execution npx/npm security auditor: static taint, Git parity, clean anchors, batch triage.

Documentation

Coldpin

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

LayerTrust BoundaryResponsibility
Deterministic CLI & Local MCP (lib/)Zero execution; in-memory archive parsing; stdio-only (0 listening sockets); operator-only control planeComputes 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 unknownsOrchestrates the 7 MCP tools / 6 CLI verbs with 5 modular aspect playbooks plus Antigravity /coldpin-audit and /coldpin-incident workflows.
YouHuman approval gate before any host executionReview 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 ToolExit CodesUse it to…
 discover / discover_packages0 / 2 / 1Search npm tools by query, org, creator, or category with typosquat and policy filters.
 inspect / inspect_package_artifact0 / 2 / 3 / 1Vet a package or local .tgz without execution and emit Card, JSON, SARIF 2.1.0, or CycloneDX SBOM.
 resolve-anchor / resolve_safe_anchor0 / 2 / 3 / 1Find patient-zero commit and recover a verified pre-compromise release or clean alternative.
 verify-confusion / verify_confusion0 / 3 / 1Audit package.json and .npmrc for unpinned private scopes and claimable internal names (T1195.001).
 audit-batch / audit_manifest_batch0 / 2 / 3 / 1Batch-screen up to 50 direct dependencies in package.json (squat, policy, route-isolated OSV/MAL-*/KEV) with <= 500-token MCP summaries.
 audit-verify / audit_verify0 / 3 / 1Verify local hash-chained audit.jsonl sequence and digest integrity.
 mcp / get_artifact_report0 / 1Serve 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 npx limits, 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.

NPM
coldpin
Install Command
npm install coldpin
Runtime: npx