coldpin 0.0.0-stage → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/ACCESSIBILITY.md +17 -0
  2. package/CHANGELOG.md +89 -0
  3. package/CONTRIBUTING.md +36 -0
  4. package/LICENSE +98 -0
  5. package/MAINTENANCE.md +33 -0
  6. package/README.md +142 -2
  7. package/SECURITY.md +34 -0
  8. package/TESTING.md +26 -0
  9. package/agents/coldpin-auditor.md +47 -0
  10. package/agents/coldpin-compliance.md +38 -0
  11. package/agents/coldpin-confusion-auditor.md +38 -0
  12. package/agents/coldpin-discoverer.md +37 -0
  13. package/agents/coldpin-forensics.md +38 -0
  14. package/agents/coldpin-inspector.md +37 -0
  15. package/agents/coldpin-manifest-auditor.md +38 -0
  16. package/assets/icon.svg +7 -0
  17. package/catalog/mcp-schema-pin.json +14 -0
  18. package/catalog/plugin.oms.sig +19 -0
  19. package/catalog/sigma/npx-suspicious-child-process-linux.yml +54 -0
  20. package/catalog/sigma/npx-suspicious-child-process.yml +49 -0
  21. package/catalog/triage-rules.json +104 -0
  22. package/docs/assets/readme-header.svg +21 -0
  23. package/docs/designs/SITEMAP.md +14 -0
  24. package/docs/designs/coldpin.md +68 -0
  25. package/docs/fact-ledger.md +35 -0
  26. package/docs/faq.md +31 -0
  27. package/docs/getting_started.md +62 -0
  28. package/docs/harnesses.md +45 -0
  29. package/docs/privacy.md +27 -0
  30. package/docs/verification/skill-inspector-self-audit.md +33 -0
  31. package/examples/.coldpin.policy.example.json +27 -0
  32. package/examples/.npmrc.example +8 -0
  33. package/examples/mcp_config.private-registry.example.json +42 -0
  34. package/hooks.json +47 -0
  35. package/lib/analysis/parity-and-bisect.mjs +1371 -0
  36. package/lib/analysis/static-triage.mjs +4572 -0
  37. package/lib/cache/sqlite-store.mjs +251 -0
  38. package/lib/cli.mjs +427 -0
  39. package/lib/compliance/audit-log.mjs +357 -0
  40. package/lib/config/policy.mjs +780 -0
  41. package/lib/core/path-confinement.mjs +289 -0
  42. package/lib/core/workflows.mjs +1205 -0
  43. package/lib/discovery/slopsquat-guard.mjs +289 -0
  44. package/lib/hook.mjs +1038 -0
  45. package/lib/intel/registry-osv.mjs +1681 -0
  46. package/lib/mcp/report-store.mjs +175 -0
  47. package/lib/mcp/server.mjs +1387 -0
  48. package/lib/mcp/stdio-transport.mjs +289 -0
  49. package/lib/mcp/tool-catalog.mjs +273 -0
  50. package/lib/mcp/types.mjs +95 -0
  51. package/lib/mcp.mjs +19 -0
  52. package/lib/quarantine/safe-unpack.mjs +568 -0
  53. package/lib/types.mjs +383 -0
  54. package/lib/verdict/engine-and-formatters.mjs +895 -0
  55. package/mcp_config.json +21 -0
  56. package/package.json +71 -3
  57. package/plugin.json +54 -0
  58. package/rules/AGENTS.md +18 -0
  59. package/rules/coldpin-incident-checklist.md +18 -0
  60. package/rules/coldpin-manifest-guard.md +14 -0
  61. package/server.json +38 -0
  62. package/skills/coldpin/BENCHMARK.md +166 -0
  63. package/skills/coldpin/SKILL.md +110 -0
  64. package/skills/coldpin/TEST.md +13 -0
  65. package/skills/coldpin/agents/openai.yaml +6 -0
  66. package/skills/coldpin/assets/icon.svg +7 -0
  67. package/skills/coldpin/assets/runtime-contract.yaml +105 -0
  68. package/skills/coldpin/evals/evals.json +60 -0
  69. package/skills/coldpin/references/aspect-compliance-audit.md +27 -0
  70. package/skills/coldpin/references/aspect-discovery.md +26 -0
  71. package/skills/coldpin/references/aspect-forensics-rea.md +26 -0
  72. package/skills/coldpin/references/aspect-inspection.md +26 -0
  73. package/skills/coldpin/references/aspect-manifest-confusion.md +26 -0
  74. package/skills/coldpin/references/enterprise-policy-schema.md +65 -0
  75. package/skills/coldpin/references/evidence-card-spec.md +27 -0
  76. package/skills/coldpin/references/rea-integration-playbook.md +34 -0
  77. package/skills/coldpin/references/threat-taxonomy.md +35 -0
  78. package/skills/coldpin/skill-card.md +62 -0
  79. package/skills/coldpin/skill.oms.sig +19 -0
  80. package/skills/coldpin/test_scenarios.yaml +61 -0
  81. package/skills/coldpin-audit/SKILL.md +39 -0
  82. package/skills/coldpin-incident/SKILL.md +37 -0
  83. package/src/analysis/parity-and-bisect.ts +1368 -0
  84. package/src/analysis/static-triage.ts +4569 -0
  85. package/src/cache/sqlite-store.ts +248 -0
  86. package/src/cli.ts +424 -0
  87. package/src/compliance/audit-log.ts +354 -0
  88. package/src/config/policy.ts +777 -0
  89. package/src/core/path-confinement.ts +286 -0
  90. package/src/core/workflows.ts +1202 -0
  91. package/src/discovery/slopsquat-guard.ts +286 -0
  92. package/src/hook.ts +1035 -0
  93. package/src/intel/registry-osv.ts +1678 -0
  94. package/src/mcp/report-store.ts +172 -0
  95. package/src/mcp/server.ts +1384 -0
  96. package/src/mcp/stdio-transport.ts +286 -0
  97. package/src/mcp/tool-catalog.ts +270 -0
  98. package/src/mcp/types.ts +92 -0
  99. package/src/mcp.ts +16 -0
  100. package/src/quarantine/safe-unpack.ts +565 -0
  101. package/src/types.ts +380 -0
  102. package/src/verdict/engine-and-formatters.ts +892 -0
@@ -0,0 +1,35 @@
1
+ ---
2
+ last_reviewed: 2026-11-21
3
+ review_by: 2027-02-21
4
+ status: current
5
+ owner_lens: fact-ledger
6
+ sources: see rows
7
+ ---
8
+
9
+ # Fact Ledger (`coldpin`)
10
+
11
+ Rule: every volatile regulatory date, standard revision, and external security taxonomy claim cited in `coldpin` carries a dated verification row here. Verification levels:
12
+
13
+ - **P** = confirmed against a primary-source page or official gazette
14
+ - **S+** = confirmed by two or more independent reputable sources citing the official host
15
+ - **S** = single secondary source; re-check before compliance-bearing decisions
16
+ - **K** = stable long-standing knowledge (still dated)
17
+
18
+ | # | Claim | Primary Source | Level | Verified | Used In | Next Review |
19
+ | --- | --- | --- | --- | --- | --- | --- |
20
+ | 1 | MITRE ATT&CK techniques `T1195.001` (Compromise Software Dependencies), `T1195.002` (Compromise Software Supply Chain), `T1059.007` (JavaScript), `T1552.001` (Credentials In Files), `T1041` (Exfiltration Over C2), `T1027` (Obfuscated Files), `T1554` (Compromise Host Software Binary), `T1546` (Event Triggered Execution), `T1499` (Endpoint DoS), `T1608.001` (Upload Malware) | `attack.mitre.org/techniques/` | K | 2026-11-19 | `threat-taxonomy.md`, `src/` | 2027-02-19 |
21
+ | 2 | MITRE ATLAS techniques `AML.T0051` / `AML.T0051.001` (Indirect Prompt Injection), `AML.T0054` (LLM Jailbreak), `AML.T0010` (ML/AI Supply Chain Compromise) & OWASP LLM Top 10 `LLM01:2025` | `atlas.mitre.org`, `owasp.org` | K | 2026-11-19 | `threat-taxonomy.md`, `SKILL.md` | 2027-02-19 |
22
+ | 3 | India CERT-In Directions (2022-04-28): 6-hour cyber-incident reporting clock, 180-day ICT log retention in India, NIC/NPL NTP sync | `cert-in.org.in` | K | 2026-11-19 | `enterprise-policy-schema.md` | 2027-02-19 |
23
+ | 4 | India DPDP Act 2023 + DPDP Rules 2025 notified 2025-11-13; consent-manager provisions 2026-11-13; core fiduciary obligations 2027-05-13 (re-check primary Gazette before legal reliance) | `meity.gov.in` Gazette G.S.R. 846(E) | S+ | 2026-11-19 | `enterprise-policy-schema.md` | 2027-02-19 |
24
+ | 5 | EU Cyber Resilience Act Reg. (EU) 2024/2847: reporting duties 2026-09-11 (24h early warning, 72h notification); main obligations including SBOM 2027-12-11 (re-check OJ text before legal reliance) | `eur-lex.europa.eu` OJ L 2024/2847 | S+ | 2026-11-19 | `enterprise-policy-schema.md` | 2027-02-19 |
25
+ | 6 | EU NIS2 Dir. (EU) 2022/2555 (24h early warning / 72h notification) & GDPR Art. 33 (72h supervisory breach notification) | `eur-lex.europa.eu` | K | 2026-11-19 | `enterprise-policy-schema.md` | 2027-02-19 |
26
+ | 7 | SARIF 2.1.0 OASIS Standard & CycloneDX 1.5 OWASP Standard & CISA TLP 2.0 | `oasis-open.org`, `cyclonedx.org`, `cisa.gov/tlp` | K | 2026-11-19 | `evidence-card-spec.md`, `src/verdict/` | 2027-05-19 |
27
+ | 8 | SLSA v1.0 Build Track (L0–L3) & in-toto Attestation Statement v1 (`application/vnd.in-toto+json`, `model_signing/signature/v1.0`) | `slsa.dev`, `in-toto.io`, `sigstore.dev` | K | 2026-11-19 | `sign_and_verify_skill.ts`, `enterprise-policy-schema.md` | 2027-05-19 |
28
+ | 9 | Node.js `v24.1.0` enables `node:sqlite` (`DatabaseSync`) and native TypeScript type-stripping (`stripTypeScriptTypes`) by default; Node 24 receives security updates through `2028-04-30`, and Node 26 ("Lithium") entered Active LTS on `2026-10-28` (`v26.13.0`, EOL `2029-04-30`) | `nodejs.org`, verified locally via `node --version` | P | 2026-11-21 | `package.json`, `.github/workflows/ci.yml`, `docs/designs/coldpin.md` | 2027-02-21 |
29
+ | 10 | Model Context Protocol (`2025-11-25`, `2025-06-18`, `2025-03-26`), Official MCP Registry `server.json` (`2025-12-11` schema, `description <= 100` chars, `package.json` `mcpName` verification), & OWASP MCP Top 10:2025 (`MCP01:2025`–`MCP10:2025`) | `modelcontextprotocol.io`, `static.modelcontextprotocol.io`, `registry.modelcontextprotocol.io`, `owasp.org` | S+ | 2026-11-20 | `server.json`, `src/mcp/`, `docs/harnesses.md` | 2027-02-20 |
30
+ | 11 | npm Trusted Publishing keyless GitHub Actions OIDC (`npm >= 11.5.1`) with automatic Sigstore provenance & Antigravity plugin CLI strict validation (`agy.exe v1.5.13`) | `npmjs.com`, `antigravity.google`, verified locally via `agy.exe` | P | 2026-11-21 | `.github/workflows/release.yml`, `mcp_config.json`, `docs/harnesses.md` | 2027-02-21 |
31
+ | 12 | Antigravity plugin schema (`schemas/v1/plugin.json`), Marketplace partner submission (`forms.gle/2EX5RFYPoJe1UgxR9`), `PreToolUse` hook contract (`agy >= v1.5.13`), and OAuth 2.1 / RFC 9728 / RFC 8707 / CIMD specifications | `antigravity.google`, `forms.gle`, `datatracker.ietf.org` | P | 2026-11-21 | `plugin.json`, `hooks.json`, `README.md`, `docs/harnesses.md`, `docs/privacy.md` | 2027-02-21 |
32
+
33
+ ## Approved URL Host Allow-List (Checked by `scripts/verify_hygiene.py`)
34
+
35
+ `registry.npmjs.org`, `api.osv.dev`, `json.schemastore.org`, `github.com`, `attack.mitre.org`, `atlas.mitre.org`, `owasp.org`, `cert-in.org.in`, `meity.gov.in`, `eur-lex.europa.eu`, `oasis-open.org`, `cyclonedx.org`, `cisa.gov`, `slsa.dev`, `in-toto.io`, `sigstore.dev`, `www.apache.org`, `artifactory.acme.internal`, `model_signing`, `keepachangelog.com`, `modelcontextprotocol.io`, `static.modelcontextprotocol.io`, `registry.modelcontextprotocol.io`, `antigravity.google`, `npmjs.com`, `nodejs.org`, `forms.gle`, `datatracker.ietf.org`.
package/docs/faq.md ADDED
@@ -0,0 +1,31 @@
1
+ # FAQ
2
+
3
+ #### Q: Are there alternatives?
4
+
5
+ **A**: Yes. Many.
6
+
7
+ `Socket.dev`, `Snyk`, `GuardDog`, `OSV-Scanner`, and private npm proxies (Verdaccio, Artifactory) solve overlapping parts of npm supply-chain security. `coldpin` focuses specifically on the agentic pre-`npx` workflow: zero-execution in-memory discovery and triage, 3-tier tarball-vs-Git parity, patient-zero commit bisection, and honest pinned commands with zero external runtime dependencies. Regardless of the tool you choose, *you own the execution decision.*
8
+
9
+ #### Q: Does `VERIFIED_CLEAN_WITHIN_SCOPE` prove a package has zero malware?
10
+
11
+ **A**: No.
12
+
13
+ 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.
14
+
15
+ #### Q: Why does the emitted `npx` command carry a SHA-512 and transitive caveat?
16
+
17
+ **A**: Stock `npx` (`npm exec`) has no `--integrity <sha512>` command-line flag and ignores any `package-lock.json` inside a published npm package, resolving floating `^x.y.z` transitive dependencies live at runtime. Pretending a bare `npx` command enforces SHA-512 or transitive locks would be dishonest. Always combine `--ignore-scripts` and exact version pins with a private caching proxy or shrinkwrapped install for regulated builds.
18
+
19
+ #### Q: Why doesn't `resolve-anchor` tell me to run `npx github:org/repo#<clean_sha>` when a clean Git commit has no npm tarball?
20
+
21
+ **A**: Running `npx` directly from a Git commit executes `prepare`/`postinstall` build scripts on your machine and pulls live floating transitive dependencies. When a clean commit has no matching verified npm release tarball, `coldpin` emits `FORENSIC_COMMIT_ONLY` (suppressing runnable commands) and recommends either building in an isolated sandbox or switching to a vetted category alternative (`SWITCH_TO_ALTERNATIVE`).
22
+
23
+ #### Q: Do I need `rea-agents` installed to use `coldpin`?
24
+
25
+ **A**: No.
26
+
27
+ Tier-0 metadata/OSV checks, Tier-1 in-memory unpacking, JS/TS lexical taint analysis, hidden-Unicode detection, 3-tier tarball parity, and Git commit bisection all run locally on pure Node.js 24 with zero external packages. When an artifact contains obfuscated bundles or compiled `.node`/WASM/ELF/PE/Mach-O binaries, the CLI fails closed (`QUARANTINE_SUSPICIOUS` / `UNVERIFIABLE_UNKNOWN`) and points you to a pre-registered REA MCP server or pre-installed `rea` binary—never auto-downloading `rea-agents` via `npx -y`.
28
+
29
+ #### Q: Why does `BENCHMARK.md` mark Tier 3 Live Multi-Agent Evaluation as `NOT RUN`?
30
+
31
+ **A**: Epistemic honesty. Running Tier 3 requires live LLM API calls in isolated sandbox containers across multiple agent harnesses (Antigravity, Claude Code, Codex). Rather than fabricating synthetic uplift numbers, `BENCHMARK.md` reports real measured Tier 1–2 execution metrics (49-fixture security corpus recall/FPR, latency, cache speedup, 35 mutation proofs, and positive+decoy trigger selection) and leaves Tier 3 explicitly `N/A` until run in CI/sandbox.
@@ -0,0 +1,62 @@
1
+ # Getting Started with `coldpin` (Coldpin)
2
+
3
+ ## Prerequisites
4
+
5
+ - **Node.js `>= 24.0.0`** (verified on `v24.1.0`; uses native TypeScript type-stripping, `node:sqlite`, `node:zlib`, `node:crypto`, `node:module`, `node:test`, and `fetch` — zero `npm install` required).
6
+ - **Git `>= 2.25`** (required for `resolve-anchor` commit history walks and local tarball-vs-Git parity checks).
7
+ - **Python `>= 3.11`** (zero external pip packages; used only for skill lint, hygiene, staleness, static eval, SkillSpector self-audit, and reproducible bundle packaging).
8
+ - **Optional Tier-2 Deep Forensics:** A pre-registered REA (`rea-agents`) MCP server or pre-installed `rea` binary on `PATH` when inspecting obfuscated bundles or native `.node`/WASM/ELF/PE/Mach-O artifacts. Never bootstrap REA with `npx -y rea-agents`.
9
+
10
+ ## Setup
11
+
12
+ Clone the repository directly (no `npm install` step required):
13
+
14
+ ```sh
15
+ git clone https://github.com/hynko431/Coldpin-npx-Safe-Finder.git
16
+ cd Coldpin-npx-Safe-Finder
17
+ node --no-warnings lib/cli.mjs --help
18
+ node --no-warnings lib/mcp.mjs # or: coldpin mcp
19
+ ```
20
+
21
+ ## Core Workflow Loop
22
+
23
+ 1. **Configure Enterprise Policy (Optional for Public Use, Required for Private Orgs):**
24
+ Copy [examples/.coldpin.policy.example.json](../examples/.coldpin.policy.example.json) and [examples/.npmrc.example](../examples/.npmrc.example) into your repository root declaring `private_scopes`, `private_prefixes`, `private_registries`, `cooldown_hours`, and CVE/KEV thresholds. In MCP mode, pin operator policy via `COLDPIN_POLICY_PATH` and allowed local roots via `COLDPIN_ALLOWED_ROOTS` (or use [examples/mcp_config.private-registry.example.json](../examples/mcp_config.private-registry.example.json) with Antigravity `variables`). See [enterprise-policy-schema.md](../skills/coldpin/references/enterprise-policy-schema.md).
25
+ 2. **Discover Candidates (`discover`):**
26
+ ```sh
27
+ node --no-warnings src/cli.ts discover "lint" --category cli --limit 10
28
+ ```
29
+ Filters out denied orgs and flags 7 typosquatting/slopsquatting mutation primitives before any tarball is downloaded.
30
+ 3. **Inspect Before Running (`inspect`):**
31
+ ```sh
32
+ node --no-warnings src/cli.ts inspect <pkg>@<ver>
33
+ ```
34
+ Or offline against a downloaded tarball and local Git checkout:
35
+ ```sh
36
+ node --no-warnings src/cli.ts inspect --tarball ./pkg.tgz --git-dir ./repo --offline --audit-log ./audit.jsonl
37
+ ```
38
+ Inspect the returned `Title + Info + Evidence` card, verify the `verdict` and `unknowns`, and export `--sarif` (GitHub Code Scanning) or `--sbom` (CycloneDX 1.5) when needed.
39
+ 4. **Recover When Compromised (`resolve-anchor`):**
40
+ When `inspect` returns exit code `3` (`MALICIOUS_INDICATORS_FOUND`) or `2` (`QUARANTINE_SUSPICIOUS`), run:
41
+ ```sh
42
+ node --no-warnings src/cli.ts resolve-anchor <pkg> --git-dir ./repo --window 200
43
+ ```
44
+ This pinpoints the patient-zero commit, scans unique Git blobs once via the Split-Plane SQLite cache, checks residual CVEs/KEV on the last clean commit, and tells you whether a verified npm tarball rollback (`ROLLBACK_TO_SAFE_ANCHOR`) is safe or whether you must switch to an alternative (`SWITCH_TO_ALTERNATIVE`).
45
+ 5. **Audit Workspace Dependency Confusion (`verify-confusion`):**
46
+ ```sh
47
+ node --no-warnings src/cli.ts verify-confusion ./package.json
48
+ ```
49
+ 6. **Verify Local Audit Trail (`audit-verify`):**
50
+ ```sh
51
+ node --no-warnings src/cli.ts audit-verify ./audit.jsonl
52
+ ```
53
+
54
+ ## Full Verification Suite
55
+
56
+ Run all 10 automated pipeline commands (`39/39` tests, 13-manifest & vertical-slice lint, hygiene, staleness, static eval, SkillSpector `SS-03`–`SS-15` self-audit, 49-fixture/35-mutation benchmark verification, dual DSSE signature verification, and reproducible multi-host packaging) with one command:
57
+
58
+ ```sh
59
+ npm run verify:all
60
+ ```
61
+
62
+ See [TESTING.md](../TESTING.md) for the exact scope of each gate and what remains outside offline automated coverage.
@@ -0,0 +1,45 @@
1
+ # Harnesses & Cross-Platform Distribution
2
+
3
+ `coldpin` maintains **one canonical skill source** under `skills/coldpin/` and **one compiled zero-dependency ESM runtime** under `lib/` (built deterministically from `src/` via `npm run build`). No agent harness receives a forked copy of the skill prose; host-specific runtime packages are compiled deterministically from the same source tree by `scripts/pack_plugin.py`.
4
+
5
+ ## Install Matrix
6
+
7
+ | Harness | Manifest | Skill / MCP Entrypoint | Install / Sync Command | Verification Status |
8
+ |---|---|---|---|---|
9
+ | **Antigravity (CLI / Workspace / App / IDEs, `>= v1.5.13`)** | `plugin.json` (`schemas/v1/plugin.json`), `mcp_config.json`, `hooks.json` | `rules/` (3) + `agents/` (7 read-only aspect agents) + `skills/` (3: `coldpin`, `coldpin-audit`, `coldpin-incident`) + `.agents/skills/coldpin/` + `${PLUGIN_ROOT}/lib/mcp.mjs` (`timeoutSeconds: 300`, 7 eager tools, `COLDPIN_CACHE_DIR=${PLUGIN_DATA}`) + `./lib/hook.mjs` | Extract `dist/coldpin-antigravity.zip` → `agy plugin install <dir>` or `python scripts/pack_plugin.py --target antigravity --verify --sync-workspace` | Live `agy plugin validate --strict` (`agents: 7, hooks: 3, mcpServers: 1, rules: 3, skills: 3, findings: []`) verified locally |
10
+ | **Claude Code** | `.claude-plugin/plugin.json` (inline `mcpServers`), `.claude-plugin/marketplace.json` | `skills/coldpin/` + `${CLAUDE_PLUGIN_ROOT}/lib/mcp.mjs` | `python scripts/pack_plugin.py --target claude --verify` | Manifest schema + reproducible archive verified; live Claude Code host trace not executed here |
11
+ | **Codex CLI / ChatGPT Desktop** | `.codex-plugin/plugin.json`, `.agents/plugins/marketplace.json` | `skills/coldpin/` | `python scripts/pack_plugin.py --target openai --verify` | Manifest schema + reproducible archive verified; live Codex host trace not executed here |
12
+ | **Official MCP Registry / npm / Cursor** | `server.json` (`2025-12-11`), `package.json` (`mcpName`) | `npx --ignore-scripts coldpin@1.5.0 mcp` (`lib/mcp.mjs`) | `npm install -g coldpin` or `npx --ignore-scripts coldpin@1.5.0 mcp` | Schema parity, `node_modules` execution smoke test, and JSON-RPC `stdio` MCP suite verified locally on Node `v24.1.0` |
13
+ | **Standalone Node.js 24 CLI / CI** | `package.json` | `lib/cli.mjs` (or `src/cli.ts`) | `node --no-warnings lib/cli.mjs --help` | End-to-end tests + benchmarks verified locally on Node `v24.1.0` |
14
+
15
+ ## Antigravity App and Antigravity for IDEs
16
+
17
+ Build the clean allowlisted bundle with `python scripts/pack_plugin.py --target antigravity --verify` (or download `coldpin-antigravity.zip` + `SHA256SUMS.txt` from [GitHub Releases](https://github.com/hynko431/Coldpin-npx-Safe-Finder/releases)), extract it to a clean directory (without `.git/`), and install via the Antigravity CLI:
18
+
19
+ ```sh
20
+ python -m zipfile -e dist/coldpin-antigravity.zip ./coldpin-antigravity
21
+ agy plugin install ./coldpin-antigravity
22
+ ```
23
+
24
+ For workspace-scoped discovery inside this repository, run:
25
+
26
+ ```sh
27
+ python scripts/pack_plugin.py --verify --sync-workspace
28
+ ```
29
+
30
+ For manual installation without the CLI, extract `coldpin-antigravity.zip` into `~/.gemini/config/plugins/coldpin/` (remove any prior version first so stale files do not linger), then reload the window and verify `coldpin` appears in `agy plugin list`.
31
+
32
+ ## Manifest Ownership & Drift Prevention
33
+
34
+ - Root `plugin.json` conforms strictly to `https://antigravity.google/schemas/v1/plugin.json` (`additionalProperties: false`, zero `"mcpServers"`, zero `"hooks"`, zero `"category"` at root) and is the single source of truth for plugin identity (`name`, `version`, `description`, `license`, `author`). MCP registration lives in root `mcp_config.json` (zero mandatory `variables` so public installs activate immediately; enterprises may apply `examples/mcp_config.private-registry.example.json`) for Antigravity and inline inside `.claude-plugin/plugin.json` for Claude Code; no root `.mcp.json` or `mcp.json` is emitted.
35
+ - `package.json`, `server.json`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.codex-plugin/plugin.json`, `src/types.ts` (`ENGINE_VERSION`), `catalog/triage-rules.json`, `catalog/mcp-schema-pin.json`, `skills/coldpin/SKILL.md`, `skills/coldpin/skill-card.md`, `skills/coldpin-audit/SKILL.md`, and `skills/coldpin-incident/SKILL.md` (13 files total) are validated automatically against root `plugin.json` by `scripts/lint_skill.py` (any metadata or version drift fails lint).
36
+ - Runtime packages generated by `scripts/pack_plugin.py` enforce:
37
+ - Explicit allowlist only (excludes `.git/`, `.github/`, `tests/`, `node_modules/`, `audit.jsonl`, `*.sqlite`, temporary artifacts) with Antigravity-only primitives (`rules/*.md`, `agents/*.md`, `hooks.json`, `skills/coldpin-{audit,incident}/SKILL.md`, `catalog/plugin.oms.sig`) scoped strictly to `HOST_GLOBS["antigravity"]`.
38
+ - Zero symlinks, zero paths escaping repo root, zero automatic permission-approval hooks.
39
+ - Sorted archive entries, fixed timestamp (`2026-01-01 00:00:00 UTC`), explicit POSIX metadata (`create_system=3`, `0100755` for `lib/{cli,mcp,hook}.mjs`, `0100644` otherwise), and byte-for-byte SHA-256 verification across two consecutive builds.
40
+ - Relative Markdown link, HTML `href`/`src`, YAML asset, MCP `${PLUGIN_ROOT}` target, and `#heading-anchor` validation inside the packaged tree.
41
+
42
+ ## Host Execution Boundaries
43
+
44
+ - Coldpin requires a local Node.js `>= 24.0.0` runtime (`git >= 2.25` for Git parity/bisect; Antigravity `>= v1.5.13` for `PreToolUse` hooks). Cloud-only chat sessions without local process execution cannot run `lib/mcp.mjs` or `lib/cli.mjs` and must fail closed (`UNVERIFIABLE_UNKNOWN`) rather than guessing verdicts from package names.
45
+ - Never install or enable automatic command-approval hooks (`auto_approve`, `permissionOverrides`, `overwrite`) for `coldpin`; the human user must explicitly approve any recommended `npx` command before execution.
@@ -0,0 +1,27 @@
1
+ <!-- SPDX-License-Identifier: Apache-2.0 -->
2
+
3
+ # Data Handling & Privacy Notice (`coldpin`)
4
+
5
+ `coldpin` is a local Node.js CLI, zero-dependency `stdio` MCP server (`lib/mcp.mjs`), and agent skill package. It does not operate a hosted backend service, telemetry endpoint, analytics collector, or external database. It requires no separate `coldpin` account or license key.
6
+
7
+ ## Local Inputs and Outputs
8
+
9
+ - **Inputs read locally:** CLI arguments or MCP tool parameters, operator startup environment variables (`COLDPIN_POLICY_PATH`, `COLDPIN_ALLOWED_ROOTS`, `COLDPIN_AUDIT_LOG`, `COLDPIN_CACHE_DIR`, `COLDPIN_OFFLINE`, and optional enterprise `COLDPIN_PRIVATE_SCOPES`, `COLDPIN_PRIVATE_REGISTRY_URL`, `COLDPIN_REGISTRY_TOKEN` — rejecting any literal unexpanded `${VAR}` placeholder), `.npmrc` (`:_authToken` read strictly from `$HOME/.npmrc` or operator-pinned config, never untrusted workspace `.npmrc`), `.coldpin.policy.json` (or legacy `.npx-guard.policy.json`), local `package.json`, `package-lock.json`, `pnpm-lock.yaml`, and `yarn.lock` (when running `verify-confusion` or workspace compromise checks), local tarballs (`--tarball` / `tarball_path`), and local Git directories (`--git-dir` / `git_dir`).
10
+ - **Local persistence:**
11
+ - Split-Plane SQLite cache (`%LOCALAPPDATA%\coldpin\cache.sqlite` on Windows, `~/.cache/coldpin/cache.sqlite` on POSIX, or `${PLUGIN_DATA}/cache.sqlite` in Antigravity, with owner-only `0700`/`0600` POSIX permissions and direct `:memory:` fallback — never shared `/tmp`) storing structural static observations and base-URL-namespaced TTL-bounded OSV advisory payloads.
12
+ - Ephemeral session-only bounded LRU report store in MCP server memory (max `25` reports, `30`-minute TTL, `15 MiB` total cap) — never persisted to SQLite.
13
+ - Optional local append-only `audit.jsonl` (only written when `--audit-log <file>` or operator `COLDPIN_AUDIT_LOG` is explicitly set), storing a SHA-256 pseudonymous `actor_id_hash` instead of raw usernames or emails.
14
+ - **No automatic retention enforcement locally:** Local cache and audit files remain on disk until deleted or shipped to an enterprise WORM log archive by the user or organization.
15
+
16
+ ## Outbound Network Egress & Private-Scope Isolation
17
+
18
+ - **Offline mode (`--offline` / `COLDPIN_OFFLINE=1`):** Performs zero outbound network requests (including blocking remote `git clone`) and fails closed (`UNVERIFIABLE_UNKNOWN` / `OFFLINE_MODE_GIT_CLONE_BLOCKED`) when live threat intelligence is unavailable.
19
+ - **Public package inspection (online):** Contacts the configured npm registry (`https://registry.npmjs.org` by default) to retrieve package metadata, tarballs, and declared SLSA attestation bundles (`dist.attestations.url`, suppressed if off-origin for private scopes), `https://api.osv.dev` for OSV/OpenSSF `MAL-*` advisories, and the declared HTTPS Git remote only when `resolve-anchor` is invoked with a remote URL (with Git HTTP redirects disabled).
20
+ - **Private-scope non-leakage guarantee:** Any package matching `private_scopes`, `private_prefixes`, or private `.npmrc` scoped registries NEVER queries public `registry.npmjs.org` or `api.osv.dev`. Scopes within 1 edit or adjacent transposition of a configured private scope (`@amce` vs `@acme`) are hard-blocked (`blocked_typo`) before any network request is made. In MCP mode, `verify_confusion(check_public: true)` is suppressed unless the operator explicitly sets `COLDPIN_ALLOW_PUBLIC_CONFUSION_PROBE=1`.
21
+ - **Secrets handling:** Registry authentication tokens (`_authToken=${ENV_VAR}` in `$HOME/.npmrc` or optional operator `COLDPIN_REGISTRY_TOKEN`) are read strictly from process environment variables, rejected if they contain unexpanded `${VAR}` placeholders, matched only by exact host or `/`-segment boundary, sent only over `https://` to their matching private registry origin (never to public `registry.npmjs.org`), and never written to stdout, stderr, SQLite cache, SARIF, SBOM, audit logs, or LLM prompt context.
22
+
23
+ ## Host Agent Processing
24
+
25
+ When invoked through an AI agent harness (Antigravity, Claude Code, Codex, Cursor), the selected host processes prompts and tool/CLI outputs under that host's own account terms and privacy policy. `coldpin` exposes a strictly local `stdio`-only MCP server (`lib/mcp.mjs`, zero listening network sockets, operator-only control plane), ships read-only aspect subagents and fail-safe `PreToolUse` guarding hooks with zero auto-approval (`hooks.json` → `lib/hook.mjs`, zero network calls), and runs no untrusted package scripts.
26
+
27
+ *Engineering guidance, not legal, medical or financial advice; confirm decisions with qualified counsel.*
@@ -0,0 +1,33 @@
1
+ <!-- SPDX-License-Identifier: Apache-2.0 -->
2
+
3
+ ## Skill Inspector: `coldpin`
4
+
5
+ **Source:** `skills/` (3 skills) + `src/` + `lib/` (1:1 parity-verified) + `scripts/` + `catalog/` + `rules/` (3) + `agents/` (7) + `hooks.json` (3 groups) + multi-harness & MCP manifests
6
+ **Verdict:** `APPROVE` — Zero blocking HIGH/CRITICAL findings; documented network and read-only async git/probe surfaces are bounded, hardened, and controllable; MCP schema pin, read-only agents, fail-safe PreToolUse hooks, rules hygiene, and compiled lib/ parity verified.
7
+ **Risk:** 12/100 · LOW · ALLOW_WITH_STANDARD_CONTROLS
8
+ **Install posture:** Suitable for local developer workspaces, Antigravity App/CLI (`>= v1.5.13`), IDE MCP hosts (stdio), and CI verification pipelines on Node.js >= 24; not a substitute for runtime EDR or isolated detonation on dynamically fetched payloads.
9
+
10
+ ### Bottom Line
11
+ Deterministic SkillSpector-class static scanning (`--no-llm` equivalent, with zero whole-file skips on `src/`) and source-aware review found **0 blocking findings** and **3 documented low-risk capabilities**. The implementation matches the stated zero-execution `npx` discovery, vetting, local `stdio` MCP server, read-only aspect subagents, and fail-safe `PreToolUse` guarding purpose without auto-approval hooks, listening sockets, persistence, symlinks, dynamic `eval`, silent package installs, or compiled runtime drift.
12
+
13
+ ### Signal Overview
14
+ | Source | Result | Interpretation |
15
+ |---|---|---|
16
+ | Deterministic static self-audit (`SS-03`–`SS-15`) | `0` blocking, `3` documented LOW | Clean across Unicode, secrets, `shell=True`, import-aware child_process, dynamic `eval`, persistence, symlinks, `SS-08` hook least privilege, MCP schema pin, MCP config least privilege, `src/` ↔ `lib/` 1:1 parity, `SS-14` read-only agents, and `SS-15` rules hygiene. |
17
+ | Source-aware semantic review | Purpose & permission fit verified | `SKILL.md`, `rules/`, `agents/`, `hooks.json`, and `lib/mcp.mjs` enforce operator-only control plane, human confirmation, private-scope isolation, and non-LLM verdict authority. |
18
+ | Sensitive surface | Hardened read-only async `git` (`core.fsmonitor=false`, `core.hooksPath=/dev/null`, `http.followRedirects=false`, minimal env), SSRF/DNS/redirect-hardened HTTPS `fetch`, read-only `--version` probe | Strictly scoped, disabled in `--offline` mode, private scopes never hit public endpoints, HTTPS-only Bearer auth, cross-origin redirects strip credentials. |
19
+
20
+ ### Key Evidence
21
+ | Rule | Severity | Location | Review judgment |
22
+ |---|---|---|---|
23
+ | `SS-03-BOUNDED-EXEC` | `LOW` | `src/analysis/parity-and-bisect.ts:1` | Acceptable: required for Git parity/bisect or --version probe; never executes untrusted package scripts. |
24
+ | `SS-03-BOUNDED-EXEC` | `LOW` | `src/config/policy.ts:1` | Acceptable: required for Git parity/bisect or --version probe; never executes untrusted package scripts. |
25
+ | `SS-09-BOUNDED-NETWORK` | `LOW` | `src/intel/registry-osv.ts:271` | Acceptable: documented core capability, blocked for private scopes and --offline. |
26
+
27
+ ### Diagnosis
28
+ Every observed sensitive call site (`src/intel/registry-osv.ts` HTTPS registry/OSV fetch, `src/analysis/parity-and-bisect.ts` hardened read-only async `git`, and `src/config/policy.ts` read-only async `git`/`rea` `--version` probe) was located dynamically by line number, verified to disable shell interpolation, Git redirects, and Git hooks, and remains controllable via `--offline` / `COLDPIN_OFFLINE=1` and operator policy. All 20 compiled ESM files under `lib/` match `src/` 1:1 cryptographically (`SS-13`), and the canonical MCP `tools/list` + `resources/list` + `prompts/list` catalog matches `catalog/mcp-schema-pin.json` (`SS-11`). External `skillspector` CLI binary was not installed on `PATH` on this host, so this report reflects the repo's deterministic SkillSpector-equivalent static checker plus manual source review.
29
+
30
+ ### Guardrails
31
+ 1. Keep `.coldpin.policy.json` configured with `private_scopes` and `private_prefixes` before running against internal organization repositories; in MCP mode configure policy via `COLDPIN_POLICY_PATH` or `COLDPIN_PRIVATE_*` env vars.
32
+ 2. Never add automatic command-approval hooks (`auto_approve`, `permissionOverrides`, `overwrite`) to `hooks.json` or `plugin.json`; require explicit human confirmation before executing any emitted `npx` command.
33
+ 3. Re-run `npm run audit:self` and inspect `dist/skillspector-self-audit.sarif` on every PR and release.
@@ -0,0 +1,27 @@
1
+ {
2
+ "private_scopes": ["@acme", "@acme-internal"],
3
+ "private_prefixes": ["acme-internal-"],
4
+ "private_registries": {
5
+ "@acme": "https://artifactory.acme.internal/api/npm/npm-internal",
6
+ "@acme-internal": "https://artifactory.acme.internal/api/npm/npm-internal"
7
+ },
8
+ "default_registry": "https://registry.npmjs.org",
9
+ "allow_public_fallback": false,
10
+ "allowed_orgs": [],
11
+ "denied_orgs": ["@known-compromised-org"],
12
+ "blocked_licenses": ["AGPL-3.0", "AGPL-3.0-only", "SSPL-1.0"],
13
+ "cooldown_hours": 72,
14
+ "max_compressed_bytes": 20971520,
15
+ "max_uncompressed_bytes": 52428800,
16
+ "max_files": 5000,
17
+ "max_single_file_bytes": 10485760,
18
+ "block_on_kev": true,
19
+ "block_on_critical_cve": true,
20
+ "block_on_high_cve": false,
21
+ "require_provenance": false,
22
+ "require_source_link": false,
23
+ "bisect_max_commits": 200,
24
+ "bisect_max_days": 180,
25
+ "intel_ttl_seconds": 21600,
26
+ "offline_mode": false
27
+ }
@@ -0,0 +1,8 @@
1
+ # Example Enterprise .npmrc for Dependency Confusion Isolation (MITRE ATT&CK T1195.001)
2
+ # Bind every internal organization scope explicitly to your private registry.
3
+ # Keep secrets strictly in environment variables (never hardcode raw tokens).
4
+
5
+ @acme:registry=https://artifactory.acme.internal/api/npm/npm-internal/
6
+ @acme-internal:registry=https://artifactory.acme.internal/api/npm/npm-internal/
7
+ //artifactory.acme.internal/api/npm/npm-internal/:_authToken=${NPM_TOKEN}
8
+ ignore-scripts=true
@@ -0,0 +1,42 @@
1
+ {
2
+ "mcpServers": {
3
+ "coldpin": {
4
+ "command": "node",
5
+ "args": ["--no-warnings", "${PLUGIN_ROOT}/lib/mcp.mjs"],
6
+ "env": {
7
+ "COLDPIN_CACHE_DIR": "${PLUGIN_DATA}",
8
+ "COLDPIN_PRIVATE_SCOPES": "${COLDPIN_PRIVATE_SCOPES}",
9
+ "COLDPIN_PRIVATE_REGISTRY_URL": "${COLDPIN_PRIVATE_REGISTRY_URL}",
10
+ "COLDPIN_REGISTRY_TOKEN": "${COLDPIN_REGISTRY_TOKEN}"
11
+ },
12
+ "timeoutSeconds": 300,
13
+ "variables": [
14
+ {
15
+ "name": "COLDPIN_PRIVATE_SCOPES",
16
+ "title": "Private npm Scopes (comma-separated)",
17
+ "description": "Internal npm scopes routed exclusively to your private registry (for example @acme,@acme-internal). Never queried against public registry.npmjs.org or api.osv.dev."
18
+ },
19
+ {
20
+ "name": "COLDPIN_PRIVATE_REGISTRY_URL",
21
+ "title": "Private npm Registry URL (HTTPS)",
22
+ "description": "HTTPS private npm registry endpoint (for example https://artifactory.acme.internal/api/npm/npm-local). Must be HTTPS and non-metadata/non-loopback."
23
+ },
24
+ {
25
+ "name": "COLDPIN_REGISTRY_TOKEN",
26
+ "title": "Private Registry Read-Only Token",
27
+ "description": "Least-privilege read-only bearer token sent strictly over HTTPS to the exact configured private registry host. Never passed via CLI args.",
28
+ "link": "https://artifactory.acme.internal/docs/npm-tokens"
29
+ }
30
+ ],
31
+ "tools": {
32
+ "discover_packages": { "eager": true },
33
+ "inspect_package_artifact": { "eager": true },
34
+ "resolve_safe_anchor": { "eager": true },
35
+ "verify_confusion": { "eager": true },
36
+ "audit_manifest_batch": { "eager": true },
37
+ "audit_verify": { "eager": true },
38
+ "get_artifact_report": { "eager": true }
39
+ }
40
+ }
41
+ }
42
+ }
package/hooks.json ADDED
@@ -0,0 +1,47 @@
1
+ {
2
+ "coldpin-npx-guard": {
3
+ "enabled": true,
4
+ "PreToolUse": [
5
+ {
6
+ "matcher": "run_command|manage_task",
7
+ "hooks": [
8
+ {
9
+ "type": "command",
10
+ "command": "node --no-warnings ./lib/hook.mjs",
11
+ "timeout": 5
12
+ }
13
+ ]
14
+ }
15
+ ]
16
+ },
17
+ "coldpin-config-guard": {
18
+ "enabled": true,
19
+ "PreToolUse": [
20
+ {
21
+ "matcher": "write_to_file|replace_file_content|multi_replace_file_content|write_file|edit_file|sed_file",
22
+ "hooks": [
23
+ {
24
+ "type": "command",
25
+ "command": "node --no-warnings ./lib/hook.mjs",
26
+ "timeout": 5
27
+ }
28
+ ]
29
+ }
30
+ ]
31
+ },
32
+ "coldpin-delegation-guard": {
33
+ "enabled": true,
34
+ "PreToolUse": [
35
+ {
36
+ "matcher": "define_subagent",
37
+ "hooks": [
38
+ {
39
+ "type": "command",
40
+ "command": "node --no-warnings ./lib/hook.mjs",
41
+ "timeout": 5
42
+ }
43
+ ]
44
+ }
45
+ ]
46
+ }
47
+ }