coldpin 0.0.0-stage → 1.5.1
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.
- package/ACCESSIBILITY.md +17 -0
- package/CHANGELOG.md +97 -0
- package/CONTRIBUTING.md +36 -0
- package/LICENSE +98 -0
- package/MAINTENANCE.md +33 -0
- package/README.md +142 -2
- package/SECURITY.md +34 -0
- package/TESTING.md +26 -0
- package/agents/coldpin-auditor.md +47 -0
- package/agents/coldpin-compliance.md +38 -0
- package/agents/coldpin-confusion-auditor.md +38 -0
- package/agents/coldpin-discoverer.md +37 -0
- package/agents/coldpin-forensics.md +38 -0
- package/agents/coldpin-inspector.md +37 -0
- package/agents/coldpin-manifest-auditor.md +38 -0
- package/assets/icon.svg +7 -0
- package/catalog/mcp-schema-pin.json +14 -0
- package/catalog/plugin.oms.sig +19 -0
- package/catalog/sigma/npx-suspicious-child-process-linux.yml +54 -0
- package/catalog/sigma/npx-suspicious-child-process.yml +49 -0
- package/catalog/triage-rules.json +104 -0
- package/docs/assets/readme-header.svg +21 -0
- package/docs/designs/SITEMAP.md +14 -0
- package/docs/designs/coldpin.md +68 -0
- package/docs/fact-ledger.md +36 -0
- package/docs/faq.md +31 -0
- package/docs/getting_started.md +62 -0
- package/docs/harnesses.md +45 -0
- package/docs/privacy.md +27 -0
- package/docs/verification/skill-inspector-self-audit.md +33 -0
- package/examples/.coldpin.policy.example.json +27 -0
- package/examples/.npmrc.example +8 -0
- package/examples/mcp_config.private-registry.example.json +42 -0
- package/hooks.json +47 -0
- package/lib/analysis/parity-and-bisect.mjs +1371 -0
- package/lib/analysis/static-triage.mjs +4572 -0
- package/lib/cache/sqlite-store.mjs +251 -0
- package/lib/cli.mjs +427 -0
- package/lib/compliance/audit-log.mjs +357 -0
- package/lib/config/policy.mjs +780 -0
- package/lib/core/path-confinement.mjs +289 -0
- package/lib/core/workflows.mjs +1205 -0
- package/lib/discovery/slopsquat-guard.mjs +289 -0
- package/lib/hook.mjs +1038 -0
- package/lib/intel/registry-osv.mjs +1681 -0
- package/lib/mcp/report-store.mjs +175 -0
- package/lib/mcp/server.mjs +1387 -0
- package/lib/mcp/stdio-transport.mjs +289 -0
- package/lib/mcp/tool-catalog.mjs +273 -0
- package/lib/mcp/types.mjs +95 -0
- package/lib/mcp.mjs +19 -0
- package/lib/quarantine/safe-unpack.mjs +568 -0
- package/lib/types.mjs +383 -0
- package/lib/verdict/engine-and-formatters.mjs +895 -0
- package/mcp_config.json +21 -0
- package/package.json +71 -3
- package/plugin.json +54 -0
- package/rules/AGENTS.md +18 -0
- package/rules/coldpin-incident-checklist.md +18 -0
- package/rules/coldpin-manifest-guard.md +14 -0
- package/server.json +38 -0
- package/skills/coldpin/BENCHMARK.md +166 -0
- package/skills/coldpin/SKILL.md +110 -0
- package/skills/coldpin/TEST.md +13 -0
- package/skills/coldpin/agents/openai.yaml +6 -0
- package/skills/coldpin/assets/icon.svg +7 -0
- package/skills/coldpin/assets/runtime-contract.yaml +105 -0
- package/skills/coldpin/evals/evals.json +60 -0
- package/skills/coldpin/references/aspect-compliance-audit.md +27 -0
- package/skills/coldpin/references/aspect-discovery.md +26 -0
- package/skills/coldpin/references/aspect-forensics-rea.md +26 -0
- package/skills/coldpin/references/aspect-inspection.md +26 -0
- package/skills/coldpin/references/aspect-manifest-confusion.md +26 -0
- package/skills/coldpin/references/enterprise-policy-schema.md +65 -0
- package/skills/coldpin/references/evidence-card-spec.md +27 -0
- package/skills/coldpin/references/rea-integration-playbook.md +34 -0
- package/skills/coldpin/references/threat-taxonomy.md +35 -0
- package/skills/coldpin/skill-card.md +62 -0
- package/skills/coldpin/skill.oms.sig +19 -0
- package/skills/coldpin/test_scenarios.yaml +61 -0
- package/skills/coldpin-audit/SKILL.md +39 -0
- package/skills/coldpin-incident/SKILL.md +37 -0
- package/src/analysis/parity-and-bisect.ts +1368 -0
- package/src/analysis/static-triage.ts +4569 -0
- package/src/cache/sqlite-store.ts +248 -0
- package/src/cli.ts +424 -0
- package/src/compliance/audit-log.ts +354 -0
- package/src/config/policy.ts +777 -0
- package/src/core/path-confinement.ts +286 -0
- package/src/core/workflows.ts +1202 -0
- package/src/discovery/slopsquat-guard.ts +286 -0
- package/src/hook.ts +1035 -0
- package/src/intel/registry-osv.ts +1678 -0
- package/src/mcp/report-store.ts +172 -0
- package/src/mcp/server.ts +1384 -0
- package/src/mcp/stdio-transport.ts +286 -0
- package/src/mcp/tool-catalog.ts +270 -0
- package/src/mcp/types.ts +92 -0
- package/src/mcp.ts +16 -0
- package/src/quarantine/safe-unpack.ts +565 -0
- package/src/types.ts +380 -0
- package/src/verdict/engine-and-formatters.ts +892 -0
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { chmodSync, mkdirSync } from "node:fs";
|
|
3
|
+
import { homedir } from "node:os";
|
|
4
|
+
import { dirname, join } from "node:path";
|
|
5
|
+
import { DatabaseSync } from "node:sqlite";
|
|
6
|
+
import { CACHE_SCHEMA_VERSION, ENGINE_VERSION } from "../types.mjs";
|
|
7
|
+
|
|
8
|
+
export function defaultCacheDbPath(customDir ) {
|
|
9
|
+
if (customDir === ":memory:") return ":memory:";
|
|
10
|
+
const baseDir =
|
|
11
|
+
customDir ??
|
|
12
|
+
(process.platform === "win32"
|
|
13
|
+
? join(process.env["LOCALAPPDATA"] ?? join(homedir(), "AppData", "Local"), "coldpin")
|
|
14
|
+
: join(process.env["XDG_CACHE_HOME"] ?? join(homedir(), ".cache"), "coldpin"));
|
|
15
|
+
return join(baseDir, "cache.sqlite");
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
function openSqliteWithFallback(preferredPath ) {
|
|
19
|
+
if (preferredPath === ":memory:") {
|
|
20
|
+
return { db: new DatabaseSync(":memory:"), resolvedPath: ":memory:" };
|
|
21
|
+
}
|
|
22
|
+
// Never fall back to world-writable shared tmpdir() (prevents multi-user /tmp cache race [MCP-13]);
|
|
23
|
+
// fall directly to isolated in-memory SQLite when preferred user/plugin cache path is unwritable.
|
|
24
|
+
try {
|
|
25
|
+
const parentDir = dirname(preferredPath);
|
|
26
|
+
mkdirSync(parentDir, { recursive: true, mode: 0o700 });
|
|
27
|
+
if (process.platform !== "win32") {
|
|
28
|
+
try {
|
|
29
|
+
chmodSync(parentDir, 0o700);
|
|
30
|
+
} catch {
|
|
31
|
+
// Best-effort owner-only directory permissions
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
const db = new DatabaseSync(preferredPath);
|
|
35
|
+
if (process.platform !== "win32") {
|
|
36
|
+
try {
|
|
37
|
+
chmodSync(preferredPath, 0o600);
|
|
38
|
+
} catch {
|
|
39
|
+
// Best-effort owner-only database file permissions
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
db.exec("PRAGMA journal_mode = WAL;");
|
|
43
|
+
return { db, resolvedPath: preferredPath };
|
|
44
|
+
} catch {
|
|
45
|
+
return { db: new DatabaseSync(":memory:"), resolvedPath: ":memory:" };
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export function buildFactCacheKey(params
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
) {
|
|
54
|
+
const canonicalOptions = JSON.stringify(
|
|
55
|
+
Object.keys(params.options)
|
|
56
|
+
.sort()
|
|
57
|
+
.reduce ((acc, k) => {
|
|
58
|
+
acc[k] = params.options[k];
|
|
59
|
+
return acc;
|
|
60
|
+
}, {}),
|
|
61
|
+
);
|
|
62
|
+
const raw = [
|
|
63
|
+
params.content_sha,
|
|
64
|
+
params.ruleset_sha256,
|
|
65
|
+
ENGINE_VERSION,
|
|
66
|
+
canonicalOptions,
|
|
67
|
+
CACHE_SCHEMA_VERSION,
|
|
68
|
+
].join("|");
|
|
69
|
+
return createHash("sha256").update(raw).digest("hex");
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
export function raceWithAbort (promise , signal ) {
|
|
73
|
+
if (!signal) return promise;
|
|
74
|
+
if (signal.aborted) {
|
|
75
|
+
return Promise.reject(new Error("Operation aborted"));
|
|
76
|
+
}
|
|
77
|
+
return new Promise ((resolvePromise, rejectPromise) => {
|
|
78
|
+
const onAbort = () => {
|
|
79
|
+
rejectPromise(new Error("Operation aborted"));
|
|
80
|
+
};
|
|
81
|
+
signal.addEventListener("abort", onAbort, { once: true });
|
|
82
|
+
promise.then(
|
|
83
|
+
(val) => {
|
|
84
|
+
signal.removeEventListener("abort", onAbort);
|
|
85
|
+
resolvePromise(val);
|
|
86
|
+
},
|
|
87
|
+
(err) => {
|
|
88
|
+
signal.removeEventListener("abort", onAbort);
|
|
89
|
+
rejectPromise(err);
|
|
90
|
+
},
|
|
91
|
+
);
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Producer-once in-flight deduplicator (REA `rea-analysis-optimization` pattern).
|
|
97
|
+
* Coalesces concurrent identical async lookups so work runs once per key without
|
|
98
|
+
* letting a single caller failure or cancellation corrupt unrelated waiters.
|
|
99
|
+
*/
|
|
100
|
+
export class SingleFlight {
|
|
101
|
+
inflight = new Map ();
|
|
102
|
+
|
|
103
|
+
run(key , producer , callerSignal ) {
|
|
104
|
+
let promise = this.inflight.get(key);
|
|
105
|
+
if (!promise) {
|
|
106
|
+
promise = Promise.resolve()
|
|
107
|
+
.then(producer)
|
|
108
|
+
.finally(() => {
|
|
109
|
+
if (this.inflight.get(key) === promise) {
|
|
110
|
+
this.inflight.delete(key);
|
|
111
|
+
}
|
|
112
|
+
});
|
|
113
|
+
// Prevent unhandled rejection if every waiter aborts before the shared producer settles
|
|
114
|
+
promise.catch(() => undefined);
|
|
115
|
+
this.inflight.set(key, promise);
|
|
116
|
+
}
|
|
117
|
+
return raceWithAbort(promise, callerSignal);
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
get activeCount() {
|
|
121
|
+
return this.inflight.size;
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* Split-Plane SQLite Cache:
|
|
127
|
+
* 1. `artifact_facts`: immutable structural byte facts keyed by 5-tuple SHA-256.
|
|
128
|
+
* 2. `threat_intel_cache`: TTL-bounded mutable OSV/MAL-star/KEV intelligence.
|
|
129
|
+
* Composite verdicts are NEVER cached directly; always recomputed dynamically.
|
|
130
|
+
*/
|
|
131
|
+
export class SplitPlaneCache {
|
|
132
|
+
dbPath ;
|
|
133
|
+
db ;
|
|
134
|
+
|
|
135
|
+
constructor(dbPath ) {
|
|
136
|
+
const opened = openSqliteWithFallback(dbPath ?? defaultCacheDbPath());
|
|
137
|
+
this.dbPath = opened.resolvedPath;
|
|
138
|
+
this.db = opened.db;
|
|
139
|
+
this.db.exec("PRAGMA busy_timeout = 5000;");
|
|
140
|
+
this.db.exec("PRAGMA foreign_keys = ON;");
|
|
141
|
+
this.db.exec(`
|
|
142
|
+
CREATE TABLE IF NOT EXISTS artifact_facts (
|
|
143
|
+
cache_key TEXT PRIMARY KEY,
|
|
144
|
+
content_sha TEXT NOT NULL,
|
|
145
|
+
ruleset_sha256 TEXT NOT NULL,
|
|
146
|
+
engine_version TEXT NOT NULL,
|
|
147
|
+
facts_json TEXT NOT NULL,
|
|
148
|
+
created_at_utc TEXT NOT NULL
|
|
149
|
+
);
|
|
150
|
+
|
|
151
|
+
CREATE TABLE IF NOT EXISTS threat_intel_cache (
|
|
152
|
+
intel_key TEXT PRIMARY KEY,
|
|
153
|
+
source TEXT NOT NULL,
|
|
154
|
+
payload_json TEXT NOT NULL,
|
|
155
|
+
fetched_at_ms INTEGER NOT NULL,
|
|
156
|
+
expires_at_ms INTEGER NOT NULL
|
|
157
|
+
);
|
|
158
|
+
`);
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
getArtifactFacts (cacheKey ) {
|
|
162
|
+
const stmt = this.db.prepare("SELECT facts_json FROM artifact_facts WHERE cache_key = ?");
|
|
163
|
+
const row = stmt.get(cacheKey) ;
|
|
164
|
+
if (!row?.facts_json) return null;
|
|
165
|
+
try {
|
|
166
|
+
return JSON.parse(row.facts_json) ;
|
|
167
|
+
} catch {
|
|
168
|
+
return null;
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
putArtifactFacts(params
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
) {
|
|
178
|
+
const stmt = this.db.prepare(`
|
|
179
|
+
INSERT INTO artifact_facts (cache_key, content_sha, ruleset_sha256, engine_version, facts_json, created_at_utc)
|
|
180
|
+
VALUES (?, ?, ?, ?, ?, ?)
|
|
181
|
+
ON CONFLICT(cache_key) DO UPDATE SET
|
|
182
|
+
facts_json = excluded.facts_json,
|
|
183
|
+
created_at_utc = excluded.created_at_utc
|
|
184
|
+
`);
|
|
185
|
+
stmt.run(
|
|
186
|
+
params.cache_key,
|
|
187
|
+
params.content_sha,
|
|
188
|
+
params.ruleset_sha256,
|
|
189
|
+
ENGINE_VERSION,
|
|
190
|
+
JSON.stringify(params.facts),
|
|
191
|
+
new Date().toISOString(),
|
|
192
|
+
);
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
getThreatIntel (intelKey , nowMs = Date.now()) {
|
|
196
|
+
const stmt = this.db.prepare(
|
|
197
|
+
"SELECT payload_json, expires_at_ms FROM threat_intel_cache WHERE intel_key = ?",
|
|
198
|
+
);
|
|
199
|
+
const row = stmt.get(intelKey) ;
|
|
200
|
+
if (!row?.payload_json || typeof row.expires_at_ms !== "number") return null;
|
|
201
|
+
try {
|
|
202
|
+
const data = JSON.parse(row.payload_json) ;
|
|
203
|
+
return { data, stale: nowMs > row.expires_at_ms };
|
|
204
|
+
} catch {
|
|
205
|
+
return null;
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
putThreatIntel(params
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
) {
|
|
216
|
+
const now = params.now_ms ?? Date.now();
|
|
217
|
+
const expires = now + params.ttl_seconds * 1000;
|
|
218
|
+
const stmt = this.db.prepare(`
|
|
219
|
+
INSERT INTO threat_intel_cache (intel_key, source, payload_json, fetched_at_ms, expires_at_ms)
|
|
220
|
+
VALUES (?, ?, ?, ?, ?)
|
|
221
|
+
ON CONFLICT(intel_key) DO UPDATE SET
|
|
222
|
+
source = excluded.source,
|
|
223
|
+
payload_json = excluded.payload_json,
|
|
224
|
+
fetched_at_ms = excluded.fetched_at_ms,
|
|
225
|
+
expires_at_ms = excluded.expires_at_ms
|
|
226
|
+
`);
|
|
227
|
+
stmt.run(params.intel_key, params.source, JSON.stringify(params.payload), now, expires);
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
pruneExpiredIntel(nowMs = Date.now()) {
|
|
231
|
+
const stmt = this.db.prepare("DELETE FROM threat_intel_cache WHERE expires_at_ms < ?");
|
|
232
|
+
const res = stmt.run(nowMs);
|
|
233
|
+
return Number(res.changes ?? 0);
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
getStats() {
|
|
237
|
+
const a = this.db.prepare("SELECT COUNT(*) AS c FROM artifact_facts").get() ;
|
|
238
|
+
const t = this.db.prepare("SELECT COUNT(*) AS c FROM threat_intel_cache").get() ;
|
|
239
|
+
return {
|
|
240
|
+
artifact_facts_count: Number(a?.c ?? 0),
|
|
241
|
+
threat_intel_count: Number(t?.c ?? 0),
|
|
242
|
+
};
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
close() {
|
|
246
|
+
this.db.close();
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
//# sourceURL=cache/sqlite-store.ts
|
package/lib/cli.mjs
ADDED
|
@@ -0,0 +1,427 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { randomUUID } from "node:crypto";
|
|
3
|
+
import { resolve } from "node:path";
|
|
4
|
+
|
|
5
|
+
function checkNodeVersionFloor() {
|
|
6
|
+
const major = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
|
|
7
|
+
if (!Number.isFinite(major) || major < 24) {
|
|
8
|
+
process.stderr.write(
|
|
9
|
+
`Coldpin requires Node.js >= 24.0.0; detected ${process.version}. Upgrade to Node 24+ LTS.\n`,
|
|
10
|
+
);
|
|
11
|
+
process.exit(1);
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
checkNodeVersionFloor();
|
|
16
|
+
|
|
17
|
+
const { defaultCacheDbPath, SplitPlaneCache } = await import("./cache/sqlite-store.mjs");
|
|
18
|
+
const { logOperationalEvent } = await import("./compliance/audit-log.mjs");
|
|
19
|
+
const { loadNpmrc, loadPolicy, probeHostCapabilitiesAsync } = await import("./config/policy.mjs");
|
|
20
|
+
const {
|
|
21
|
+
runAuditManifestBatch,
|
|
22
|
+
runAuditVerify,
|
|
23
|
+
runDiscover,
|
|
24
|
+
runInspect,
|
|
25
|
+
runResolveAnchor,
|
|
26
|
+
runVerifyConfusion,
|
|
27
|
+
} = await import("./core/workflows.mjs");
|
|
28
|
+
const { ENGINE_VERSION } = await import("./types.mjs");
|
|
29
|
+
const {
|
|
30
|
+
formatAnchorMarkdown,
|
|
31
|
+
formatCycloneDxSbom,
|
|
32
|
+
formatDiscoveryMarkdown,
|
|
33
|
+
formatInspectionMarkdownCard,
|
|
34
|
+
formatSarif210,
|
|
35
|
+
} = await import("./verdict/engine-and-formatters.mjs");
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
const BOOLEAN_FLAGS = new Set([
|
|
47
|
+
"json",
|
|
48
|
+
"sarif",
|
|
49
|
+
"sbom",
|
|
50
|
+
"offline",
|
|
51
|
+
"verbose",
|
|
52
|
+
"check-public",
|
|
53
|
+
"include-dev",
|
|
54
|
+
"help",
|
|
55
|
+
"version",
|
|
56
|
+
]);
|
|
57
|
+
|
|
58
|
+
const VALUE_FLAGS = new Set([
|
|
59
|
+
"tarball",
|
|
60
|
+
"git-dir",
|
|
61
|
+
"repo-url",
|
|
62
|
+
"subdir",
|
|
63
|
+
"org",
|
|
64
|
+
"creator",
|
|
65
|
+
"category",
|
|
66
|
+
"limit",
|
|
67
|
+
"window",
|
|
68
|
+
"policy",
|
|
69
|
+
"cache-dir",
|
|
70
|
+
"audit-log",
|
|
71
|
+
"override-ticket",
|
|
72
|
+
]);
|
|
73
|
+
|
|
74
|
+
function parseCliArgs(argv ) {
|
|
75
|
+
const positionals = [];
|
|
76
|
+
const flags = {};
|
|
77
|
+
const args = argv.slice(2);
|
|
78
|
+
let i = 0;
|
|
79
|
+
let afterDoubleDash = false;
|
|
80
|
+
while (i < args.length) {
|
|
81
|
+
const a = args[i] ;
|
|
82
|
+
if (afterDoubleDash) {
|
|
83
|
+
positionals.push(a);
|
|
84
|
+
i++;
|
|
85
|
+
continue;
|
|
86
|
+
}
|
|
87
|
+
if (a === "--") {
|
|
88
|
+
afterDoubleDash = true;
|
|
89
|
+
i++;
|
|
90
|
+
continue;
|
|
91
|
+
}
|
|
92
|
+
if (a === "-h") {
|
|
93
|
+
flags["help"] = true;
|
|
94
|
+
i++;
|
|
95
|
+
continue;
|
|
96
|
+
}
|
|
97
|
+
if (a === "-V") {
|
|
98
|
+
flags["version"] = true;
|
|
99
|
+
i++;
|
|
100
|
+
continue;
|
|
101
|
+
}
|
|
102
|
+
if (a.startsWith("--")) {
|
|
103
|
+
const eqIdx = a.indexOf("=");
|
|
104
|
+
if (eqIdx > 2) {
|
|
105
|
+
const key = a.slice(2, eqIdx);
|
|
106
|
+
const val = a.slice(eqIdx + 1);
|
|
107
|
+
if (BOOLEAN_FLAGS.has(key)) {
|
|
108
|
+
flags[key] = val === "true" || val === "1";
|
|
109
|
+
} else if (VALUE_FLAGS.has(key)) {
|
|
110
|
+
flags[key] = val;
|
|
111
|
+
} else {
|
|
112
|
+
return { command: "help", positionals, flags, error: `Unknown flag: --${key}` };
|
|
113
|
+
}
|
|
114
|
+
} else {
|
|
115
|
+
const key = a.slice(2);
|
|
116
|
+
if (BOOLEAN_FLAGS.has(key)) {
|
|
117
|
+
flags[key] = true;
|
|
118
|
+
} else if (VALUE_FLAGS.has(key)) {
|
|
119
|
+
const next = args[i + 1];
|
|
120
|
+
if (next === undefined || next.startsWith("--")) {
|
|
121
|
+
return { command: "help", positionals, flags, error: `Flag --${key} requires a value` };
|
|
122
|
+
}
|
|
123
|
+
flags[key] = next;
|
|
124
|
+
i++;
|
|
125
|
+
} else {
|
|
126
|
+
return { command: "help", positionals, flags, error: `Unknown flag: --${key}` };
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
} else {
|
|
130
|
+
positionals.push(a);
|
|
131
|
+
}
|
|
132
|
+
i++;
|
|
133
|
+
}
|
|
134
|
+
const command = positionals.shift() ?? "help";
|
|
135
|
+
return { command, positionals, flags };
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
function strFlag(flags , name ) {
|
|
139
|
+
const v = flags[name];
|
|
140
|
+
return typeof v === "string" ? v : undefined;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
function boolFlag(flags , name ) {
|
|
144
|
+
return flags[name] === true || flags[name] === "true";
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
function printHelp() {
|
|
148
|
+
const help = `coldpin v${ENGINE_VERSION} — Inspect npx packages cold in memory; pin clean releases with verifiable evidence
|
|
149
|
+
|
|
150
|
+
USAGE:
|
|
151
|
+
node src/cli.ts <command> [target] [flags]
|
|
152
|
+
coldpin <command> [target] [flags]
|
|
153
|
+
|
|
154
|
+
COMMANDS:
|
|
155
|
+
discover [query] Search npm packages by query/category/creator/org with slopsquat & policy guards
|
|
156
|
+
inspect <pkg[@ver]> Zero-exec tarball inspection, AST taint triage, parity & verdict card
|
|
157
|
+
resolve-anchor <pkg> Identify patient-zero commit and safe pre-compromise release/alternative
|
|
158
|
+
verify-confusion [path] Audit package.json & .npmrc for dependency confusion (T1195.001)
|
|
159
|
+
audit-batch [path] Batch-screen up to 50 direct dependencies from package.json (squat/policy/OSV)
|
|
160
|
+
audit-verify <jsonl> Verify local hash-chained audit.jsonl integrity
|
|
161
|
+
mcp Start local zero-dependency JSON-RPC 2.0 MCP server over stdio
|
|
162
|
+
|
|
163
|
+
COMMON FLAGS:
|
|
164
|
+
--json Emit canonical JSON to stdout
|
|
165
|
+
--sarif Emit SARIF 2.1.0 JSON (inspect)
|
|
166
|
+
--sbom Emit CycloneDX 1.5 SBOM + VEX JSON (inspect)
|
|
167
|
+
--tarball <file.tgz> Inspect a local tarball offline (inspect)
|
|
168
|
+
--git-dir <dir> Local Git repository path for parity or commit bisect
|
|
169
|
+
--repo-url <url> Git repository URL for treeless commit bisect (resolve-anchor)
|
|
170
|
+
--subdir <path> Monorepo subdirectory inside Git repo
|
|
171
|
+
--org <scope> Filter by npm org/scope (discover)
|
|
172
|
+
--creator <handle> Filter by maintainer/creator (discover)
|
|
173
|
+
--category <keyword> Filter by capability/category keyword (discover)
|
|
174
|
+
--limit <n> Max discovery results (default 10) or batch deps (audit-batch, 1..50)
|
|
175
|
+
--include-dev Include devDependencies in batch screening (audit-batch)
|
|
176
|
+
--window <n> Max commits to bisect (overrides policy bisect_max_commits)
|
|
177
|
+
--policy <file> Explicit .coldpin.policy.json path
|
|
178
|
+
--cache-dir <dir> Cache directory (or :memory:)
|
|
179
|
+
--audit-log <file> Append local hash-chained audit event to JSONL file
|
|
180
|
+
--override-ticket <id> Record security approval ticket ID in audit.jsonl (does not alter verdict)
|
|
181
|
+
--verbose Emit structured operational JSON telemetry to stderr (zero secrets/PII)
|
|
182
|
+
--offline Disable all outbound network queries (fail closed)
|
|
183
|
+
--check-public Probe public npmjs.org for unscoped claimability (verify-confusion)
|
|
184
|
+
--version, -V Print coldpin CLI version and exit
|
|
185
|
+
--help, -h Print this help message and exit
|
|
186
|
+
|
|
187
|
+
EXIT CODES:
|
|
188
|
+
0 = VERIFIED_CLEAN_WITHIN_SCOPE / check passed
|
|
189
|
+
2 = QUARANTINE_SUSPICIOUS or UNVERIFIABLE_UNKNOWN
|
|
190
|
+
3 = MALICIOUS_INDICATORS_FOUND / confusion or audit integrity failure
|
|
191
|
+
1 = CLI usage or runtime error`;
|
|
192
|
+
process.stdout.write(`${help}\n`);
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
async function main() {
|
|
196
|
+
const parsed = parseCliArgs(process.argv);
|
|
197
|
+
if (parsed.error) {
|
|
198
|
+
process.stderr.write(`Error: ${parsed.error}\n`);
|
|
199
|
+
return 1;
|
|
200
|
+
}
|
|
201
|
+
if (boolFlag(parsed.flags, "version")) {
|
|
202
|
+
process.stdout.write(`coldpin v${ENGINE_VERSION}\n`);
|
|
203
|
+
return 0;
|
|
204
|
+
}
|
|
205
|
+
if (parsed.command === "help" || boolFlag(parsed.flags, "help")) {
|
|
206
|
+
printHelp();
|
|
207
|
+
return 0;
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
// Early handoff to MCP stdio server before CLI policy/cache/capability initialization
|
|
211
|
+
if (parsed.command === "mcp") {
|
|
212
|
+
const { startMcpServerFromEnv } = await import("./mcp/server.mjs");
|
|
213
|
+
return (await startMcpServerFromEnv()) ;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
const cwd = process.cwd();
|
|
217
|
+
const { policy, policy_sha256 } = loadPolicy(cwd, strFlag(parsed.flags, "policy"));
|
|
218
|
+
if (boolFlag(parsed.flags, "offline")) policy.offline_mode = true;
|
|
219
|
+
const windowArg = strFlag(parsed.flags, "window");
|
|
220
|
+
let parsedWindow ;
|
|
221
|
+
if (windowArg !== undefined) {
|
|
222
|
+
const n = Number(windowArg);
|
|
223
|
+
if (!Number.isInteger(n) || n < 1) {
|
|
224
|
+
process.stderr.write(`Error: --window must be a positive integer (got '${windowArg}')\n`);
|
|
225
|
+
return 1;
|
|
226
|
+
}
|
|
227
|
+
parsedWindow = n;
|
|
228
|
+
policy.bisect_max_commits = n;
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
const npmrc = loadNpmrc(cwd);
|
|
232
|
+
const hostCaps = await probeHostCapabilitiesAsync();
|
|
233
|
+
const cacheDir = strFlag(parsed.flags, "cache-dir");
|
|
234
|
+
const cache = new SplitPlaneCache(cacheDir ? defaultCacheDbPath(cacheDir) : defaultCacheDbPath());
|
|
235
|
+
const auditLogPath = strFlag(parsed.flags, "audit-log");
|
|
236
|
+
const overrideTicketId = strFlag(parsed.flags, "override-ticket");
|
|
237
|
+
const verbose = boolFlag(parsed.flags, "verbose");
|
|
238
|
+
const requestId = `req_${randomUUID().slice(0, 12)}`;
|
|
239
|
+
const asJson = boolFlag(parsed.flags, "json");
|
|
240
|
+
const stderrWriter = (line ) => {
|
|
241
|
+
process.stderr.write(line);
|
|
242
|
+
};
|
|
243
|
+
|
|
244
|
+
logOperationalEvent(
|
|
245
|
+
verbose,
|
|
246
|
+
{
|
|
247
|
+
request_id: requestId,
|
|
248
|
+
stage: "cli_start",
|
|
249
|
+
command: parsed.command,
|
|
250
|
+
offline: policy.offline_mode,
|
|
251
|
+
},
|
|
252
|
+
stderrWriter,
|
|
253
|
+
);
|
|
254
|
+
|
|
255
|
+
const ctx = {
|
|
256
|
+
cwd,
|
|
257
|
+
workspaceRoots: [cwd],
|
|
258
|
+
enforceRootConfinement: false,
|
|
259
|
+
policy,
|
|
260
|
+
policy_sha256,
|
|
261
|
+
npmrc,
|
|
262
|
+
host_capabilities: hostCaps,
|
|
263
|
+
cache,
|
|
264
|
+
auditLogPath: auditLogPath ? resolve(auditLogPath) : undefined,
|
|
265
|
+
overrideTicketId,
|
|
266
|
+
invokerSurface: "cli" ,
|
|
267
|
+
requestId,
|
|
268
|
+
onTelemetry: verbose
|
|
269
|
+
? (ev ) => {
|
|
270
|
+
logOperationalEvent(true, ev, stderrWriter);
|
|
271
|
+
}
|
|
272
|
+
: undefined,
|
|
273
|
+
};
|
|
274
|
+
|
|
275
|
+
try {
|
|
276
|
+
if (parsed.command === "discover") {
|
|
277
|
+
const query = parsed.positionals.join(" ");
|
|
278
|
+
const limitStr = strFlag(parsed.flags, "limit");
|
|
279
|
+
let limit = 10;
|
|
280
|
+
if (limitStr !== undefined) {
|
|
281
|
+
const parsedLimit = Number(limitStr);
|
|
282
|
+
if (!Number.isInteger(parsedLimit) || parsedLimit < 1) {
|
|
283
|
+
process.stderr.write(`Error: --limit must be a positive integer (got '${limitStr}')\n`);
|
|
284
|
+
return 1;
|
|
285
|
+
}
|
|
286
|
+
limit = parsedLimit;
|
|
287
|
+
}
|
|
288
|
+
const res = await runDiscover(ctx, {
|
|
289
|
+
query,
|
|
290
|
+
org: strFlag(parsed.flags, "org"),
|
|
291
|
+
creator: strFlag(parsed.flags, "creator"),
|
|
292
|
+
category: strFlag(parsed.flags, "category"),
|
|
293
|
+
limit,
|
|
294
|
+
});
|
|
295
|
+
process.stdout.write(asJson ? `${JSON.stringify(res.report, null, 2)}\n` : `${formatDiscoveryMarkdown(res.report)}\n`);
|
|
296
|
+
return res.exitCode;
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
if (parsed.command === "inspect") {
|
|
300
|
+
const res = await runInspect(ctx, {
|
|
301
|
+
packageSpec: parsed.positionals[0],
|
|
302
|
+
tarballPath: strFlag(parsed.flags, "tarball"),
|
|
303
|
+
localGitDir: strFlag(parsed.flags, "git-dir"),
|
|
304
|
+
subdir: strFlag(parsed.flags, "subdir"),
|
|
305
|
+
offline: boolFlag(parsed.flags, "offline"),
|
|
306
|
+
});
|
|
307
|
+
if (!res.ok) {
|
|
308
|
+
process.stderr.write(`${res.error}\n`);
|
|
309
|
+
return res.exitCode;
|
|
310
|
+
}
|
|
311
|
+
if (boolFlag(parsed.flags, "sarif")) {
|
|
312
|
+
process.stdout.write(`${JSON.stringify(formatSarif210(res.report), null, 2)}\n`);
|
|
313
|
+
} else if (boolFlag(parsed.flags, "sbom")) {
|
|
314
|
+
process.stdout.write(`${JSON.stringify(formatCycloneDxSbom(res.report, res.dependencies), null, 2)}\n`);
|
|
315
|
+
} else if (asJson) {
|
|
316
|
+
process.stdout.write(`${JSON.stringify(res.report, null, 2)}\n`);
|
|
317
|
+
} else {
|
|
318
|
+
process.stdout.write(`${formatInspectionMarkdownCard(res.report)}\n`);
|
|
319
|
+
}
|
|
320
|
+
return res.exitCode;
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
if (parsed.command === "resolve-anchor") {
|
|
324
|
+
const res = await runResolveAnchor(ctx, {
|
|
325
|
+
packageName: parsed.positionals[0],
|
|
326
|
+
localGitDir: strFlag(parsed.flags, "git-dir"),
|
|
327
|
+
repoUrl: strFlag(parsed.flags, "repo-url"),
|
|
328
|
+
subdir: strFlag(parsed.flags, "subdir"),
|
|
329
|
+
window: parsedWindow,
|
|
330
|
+
});
|
|
331
|
+
if (!res.ok) {
|
|
332
|
+
process.stderr.write(`${res.error}\n`);
|
|
333
|
+
return res.exitCode;
|
|
334
|
+
}
|
|
335
|
+
process.stdout.write(asJson ? `${JSON.stringify(res.decision, null, 2)}\n` : `${formatAnchorMarkdown(res.decision)}\n`);
|
|
336
|
+
return res.exitCode;
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
if (parsed.command === "verify-confusion") {
|
|
340
|
+
const res = await runVerifyConfusion(ctx, {
|
|
341
|
+
manifestPath: parsed.positionals[0],
|
|
342
|
+
checkPublic: boolFlag(parsed.flags, "check-public"),
|
|
343
|
+
allowPublicProbe: true,
|
|
344
|
+
});
|
|
345
|
+
if (!res.ok) {
|
|
346
|
+
process.stderr.write(`${res.error}\n`);
|
|
347
|
+
return res.exitCode;
|
|
348
|
+
}
|
|
349
|
+
process.stdout.write(`${JSON.stringify(res.report, null, 2)}\n`);
|
|
350
|
+
return res.exitCode;
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
if (parsed.command === "audit-batch") {
|
|
354
|
+
const limitStr = strFlag(parsed.flags, "limit");
|
|
355
|
+
let maxDeps ;
|
|
356
|
+
if (limitStr !== undefined) {
|
|
357
|
+
const parsedLimit = Number(limitStr);
|
|
358
|
+
if (!Number.isInteger(parsedLimit) || parsedLimit < 1 || parsedLimit > 50) {
|
|
359
|
+
process.stderr.write(`Error: --limit for audit-batch must be an integer between 1 and 50 (got '${limitStr}')\n`);
|
|
360
|
+
return 1;
|
|
361
|
+
}
|
|
362
|
+
maxDeps = parsedLimit;
|
|
363
|
+
}
|
|
364
|
+
const res = await runAuditManifestBatch(ctx, {
|
|
365
|
+
manifestPath: parsed.positionals[0],
|
|
366
|
+
includeDev: boolFlag(parsed.flags, "include-dev"),
|
|
367
|
+
maxDeps,
|
|
368
|
+
offline: boolFlag(parsed.flags, "offline"),
|
|
369
|
+
});
|
|
370
|
+
if (!res.ok) {
|
|
371
|
+
process.stderr.write(`${res.error}\n`);
|
|
372
|
+
return res.exitCode;
|
|
373
|
+
}
|
|
374
|
+
if (asJson) {
|
|
375
|
+
process.stdout.write(`${JSON.stringify(res.report, null, 2)}\n`);
|
|
376
|
+
} else {
|
|
377
|
+
const r = res.report;
|
|
378
|
+
const lines = [
|
|
379
|
+
`# Coldpin Batch Dependency Screening`,
|
|
380
|
+
`- Manifest: \`${r.manifest_path}\``,
|
|
381
|
+
`- Evaluated: ${r.evaluated_count} / ${r.total_declared}${r.truncated_at_cap ? " (capped)" : ""}`,
|
|
382
|
+
`- Clean screened: ${r.summary_counts.clean_screened} | Suspicious: ${r.summary_counts.flagged_suspicious} | Malicious/Blocked: ${r.summary_counts.malicious_or_blocked} | Unverifiable/Offline: ${r.summary_counts.unverifiable_offline}`,
|
|
383
|
+
];
|
|
384
|
+
if (r.flagged.length > 0) {
|
|
385
|
+
lines.push("", "| Package | Status | Route | Primary Reason |", "| --- | --- | --- | --- |");
|
|
386
|
+
for (const f of r.flagged) {
|
|
387
|
+
const safeReason = (f.reasons[0] ?? "").replace(/\|/g, "\\|").slice(0, 120);
|
|
388
|
+
lines.push(`| \`${f.package_name}\` | ${f.status} | ${f.route} | ${safeReason} |`);
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
if (r.unknowns.length > 0) {
|
|
392
|
+
lines.push("", "## Unknowns", ...r.unknowns.map((u) => `- ${u}`));
|
|
393
|
+
}
|
|
394
|
+
process.stdout.write(`${lines.join("\n")}\n`);
|
|
395
|
+
}
|
|
396
|
+
return res.exitCode;
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
if (parsed.command === "audit-verify") {
|
|
400
|
+
const target = parsed.positionals[0];
|
|
401
|
+
if (!target) {
|
|
402
|
+
process.stderr.write("Error: audit-verify requires <path-to-audit.jsonl>\n");
|
|
403
|
+
return 1;
|
|
404
|
+
}
|
|
405
|
+
const res = await runAuditVerify(ctx, { auditLogPath: target });
|
|
406
|
+
if (!res.ok) {
|
|
407
|
+
// Preserve existing CLI JSON output on unreadable/missing audit file
|
|
408
|
+
const payload = { valid: false, total_events: 0, reason: res.error };
|
|
409
|
+
process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
|
|
410
|
+
return 3;
|
|
411
|
+
}
|
|
412
|
+
process.stdout.write(`${JSON.stringify(res.result, null, 2)}\n`);
|
|
413
|
+
return res.exitCode;
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
process.stderr.write(`Unknown command: ${parsed.command}\n`);
|
|
417
|
+
printHelp();
|
|
418
|
+
return 1;
|
|
419
|
+
} finally {
|
|
420
|
+
cache.close();
|
|
421
|
+
}
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
process.exitCode = await main();
|
|
425
|
+
|
|
426
|
+
|
|
427
|
+
//# sourceURL=cli.ts
|