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,1371 @@
1
+ import { execFile } from "node:child_process";
2
+ import { createHash } from "node:crypto";
3
+ import { mkdtempSync, rmSync } from "node:fs";
4
+ import { tmpdir } from "node:os";
5
+ import { join } from "node:path";
6
+ import { promisify } from "node:util";
7
+ import { buildFactCacheKey, } from "../cache/sqlite-store.mjs";
8
+ import { isPrivateOrReservedIp, } from "../intel/registry-osv.mjs";
9
+
10
+
11
+
12
+
13
+
14
+
15
+
16
+
17
+
18
+
19
+
20
+
21
+
22
+ import {
23
+ analyzeSourceBlob,
24
+ DANGEROUS_LIFECYCLE_CMD_RE,
25
+ hasModuleTaintData,
26
+ isSafeNpmBinName,
27
+ isSafeNpmPackageName,
28
+ isSafeNpmVersion,
29
+ LIFECYCLE_HOOKS,
30
+ resolveCrossFileTaint,
31
+ RULESET_SHA256,
32
+ sanitizeUntrustedText,
33
+
34
+ } from "./static-triage.mjs";
35
+
36
+ const execFileAsync = promisify(execFile);
37
+
38
+ const SAFE_GIT_CONFIG_ARGS = [
39
+ "-c",
40
+ "core.fsmonitor=false",
41
+ "-c",
42
+ "core.hooksPath=/dev/null",
43
+ "-c",
44
+ "protocol.allow=never",
45
+ "-c",
46
+ "protocol.https.allow=always",
47
+ "-c",
48
+ "http.followRedirects=false",
49
+ "-c",
50
+ "credential.helper=",
51
+ "-c",
52
+ "diff.external=",
53
+ ];
54
+
55
+ const ALLOWLISTED_GIT_ENV_KEYS = [
56
+ "PATH",
57
+ "Path",
58
+ "PATHEXT",
59
+ "SYSTEMROOT",
60
+ "SystemRoot",
61
+ "COMSPEC",
62
+ "ComSpec",
63
+ "WINDIR",
64
+ "TEMP",
65
+ "TMP",
66
+ "TMPDIR",
67
+ "HOME",
68
+ "USERPROFILE",
69
+ "LANG",
70
+ "LC_ALL",
71
+ "SSL_CERT_FILE",
72
+ "SSL_CERT_DIR",
73
+ "NODE_EXTRA_CA_CERTS",
74
+ ] ;
75
+
76
+ function buildSafeGitEnv() {
77
+ // Security [MCP-09]: never spread full process.env (prevents leaking GITHUB_TOKEN, AWS_*, NPM_TOKEN to git subprocesses)
78
+ const env = {
79
+ GIT_TERMINAL_PROMPT: "0",
80
+ GIT_CONFIG_NOSYSTEM: "1",
81
+ GIT_CONFIG_GLOBAL: process.platform === "win32" ? "NUL" : "/dev/null",
82
+ };
83
+ for (const key of ALLOWLISTED_GIT_ENV_KEYS) {
84
+ const val = process.env[key];
85
+ if (val !== undefined) env[key] = val;
86
+ }
87
+ return env;
88
+ }
89
+
90
+ const ACTIVE_GIT_TEMP_DIRS = new Set ();
91
+
92
+ export function cleanupActiveGitTempDirs() {
93
+ for (const dir of Array.from(ACTIVE_GIT_TEMP_DIRS)) {
94
+ try {
95
+ rmSync(dir, { recursive: true, force: true });
96
+ } catch {
97
+ // Best-effort shutdown cleanup
98
+ }
99
+ ACTIVE_GIT_TEMP_DIRS.delete(dir);
100
+ }
101
+ }
102
+
103
+ function isBlockedRemoteGitHost(rawHost ) {
104
+ const host = rawHost.toLowerCase().replace(/^\[|\]$/g, "");
105
+ if (isPrivateOrReservedIp(host)) return true;
106
+ if (
107
+ host === "localhost" ||
108
+ host.endsWith(".localhost") ||
109
+ host === "metadata.google.internal" ||
110
+ host === "metadata.goog" ||
111
+ host === "100.100.100.200" ||
112
+ host === "::1" ||
113
+ host === "::" ||
114
+ host === "0:0:0:0:0:0:0:1" ||
115
+ host === "0:0:0:0:0:0:0:0" ||
116
+ host === "fd00:ec2::254"
117
+ ) {
118
+ return true;
119
+ }
120
+ // IPv4 loopback, link-local/metadata, unspecified, RFC1918, CGNAT 100.64.0.0/10
121
+ if (
122
+ host.startsWith("127.") ||
123
+ host.startsWith("0.") ||
124
+ host.startsWith("169.254.") ||
125
+ host.startsWith("10.") ||
126
+ host.startsWith("192.168.") ||
127
+ /^100\.(?:6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(host) ||
128
+ /^172\.(?:1[6-9]|2\d|3[01])\./.test(host)
129
+ ) {
130
+ return true;
131
+ }
132
+ // IPv6 link-local (fe80::/10) and ULA (fc00::/7)
133
+ if (/^fe[89ab][0-9a-f]:/.test(host) || /^f[cd][0-9a-f]{2}:/.test(host)) {
134
+ return true;
135
+ }
136
+ if (host.startsWith("::ffff:")) {
137
+ const mapped = host.slice("::ffff:".length);
138
+ if (mapped.includes(".")) return isBlockedRemoteGitHost(mapped);
139
+ const hexParts = mapped.split(":");
140
+ if (hexParts.length === 2) {
141
+ const hi = Number.parseInt(hexParts[0] , 16);
142
+ const lo = Number.parseInt(hexParts[1] , 16);
143
+ if (Number.isFinite(hi) && Number.isFinite(lo)) {
144
+ const ipv4 = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
145
+ return isBlockedRemoteGitHost(ipv4);
146
+ }
147
+ }
148
+ return true;
149
+ }
150
+ return false;
151
+ }
152
+
153
+ export function validateRemoteGitUrl(rawUrl ) {
154
+ const trimmed = rawUrl.trim();
155
+ if (!trimmed || trimmed.length > 256 || trimmed.startsWith("-") || /[\x00-\x1f\s]/.test(trimmed)) {
156
+ return { valid: false, reason: "Invalid, oversized (>256 chars), or option-like Git URL rejected (CWE-88 defense)." };
157
+ }
158
+ if (/^ext::/i.test(trimmed)) {
159
+ return { valid: false, reason: "Git ext:: remote helper protocol is forbidden." };
160
+ }
161
+ let parsed ;
162
+ try {
163
+ parsed = new URL(trimmed);
164
+ } catch {
165
+ return { valid: false, reason: "Malformed remote Git URL." };
166
+ }
167
+ if (parsed.protocol !== "https:") {
168
+ return { valid: false, reason: `Remote Git protocol '${parsed.protocol}' rejected; only https:// is permitted.` };
169
+ }
170
+ // Security [MCP-04]: reject query strings, fragments, and embedded userinfo to prevent exfil beacons
171
+ if (parsed.username || parsed.password) {
172
+ return { valid: false, reason: "Remote Git URL with embedded userinfo/credentials is forbidden." };
173
+ }
174
+ if (parsed.search || trimmed.includes("?") || parsed.hash || trimmed.includes("#")) {
175
+ return { valid: false, reason: "Remote Git URL query parameters and fragments are forbidden." };
176
+ }
177
+ const host = parsed.hostname.toLowerCase();
178
+ if (isBlockedRemoteGitHost(host)) {
179
+ return { valid: false, reason: `Remote Git host '${host}' blocked by SSRF guard.` };
180
+ }
181
+ return { valid: true };
182
+ }
183
+
184
+ export function validateGitRef(ref ) {
185
+ return ref === "HEAD" || /^[0-9a-f]{40}$/i.test(ref);
186
+ }
187
+
188
+ export function validateGitSubdir(subdir ) {
189
+ if (!subdir) return true;
190
+ if (subdir.startsWith("-") || subdir.startsWith("/") || subdir.includes("\\") || /[\x00-\x1f]/.test(subdir)) {
191
+ return false;
192
+ }
193
+ return !subdir.split("/").some((seg) => seg === ".." || seg === ".");
194
+ }
195
+
196
+ async function runGit(
197
+ args ,
198
+ cwd ,
199
+ timeoutMs = 15000,
200
+ signal ,
201
+ ) {
202
+ try {
203
+ const { stdout, stderr } = await execFileAsync("git", [...SAFE_GIT_CONFIG_ARGS, ...args], {
204
+ cwd,
205
+ encoding: "utf8",
206
+ env: buildSafeGitEnv(),
207
+ timeout: timeoutMs,
208
+ maxBuffer: 24 * 1024 * 1024,
209
+ windowsHide: true,
210
+ ...(signal ? { signal } : {}),
211
+ });
212
+ return { ok: true, stdout, stderr: stderr ?? "" };
213
+ } catch (err) {
214
+ const e = err ;
215
+ return {
216
+ ok: false,
217
+ stdout: "",
218
+ stderr: typeof e.stderr === "string" ? e.stderr : e.stderr?.toString("utf8") ?? e.message ?? "git error",
219
+ };
220
+ }
221
+ }
222
+
223
+ async function runGitBuffer(
224
+ args ,
225
+ cwd ,
226
+ timeoutMs = 15000,
227
+ signal ,
228
+ ) {
229
+ try {
230
+ // CRITICAL: explicit `encoding: "buffer"` is mandatory under promisify(execFile)
231
+ // because default encoding is "utf8" (unlike execFileSync), which corrupts binary .wasm/.node blobs!
232
+ const { stdout } = await execFileAsync("git", [...SAFE_GIT_CONFIG_ARGS, ...args], {
233
+ cwd,
234
+ encoding: "buffer",
235
+ env: buildSafeGitEnv(),
236
+ timeout: timeoutMs,
237
+ maxBuffer: 16 * 1024 * 1024,
238
+ windowsHide: true,
239
+ ...(signal ? { signal } : {}),
240
+ });
241
+ return Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout);
242
+ } catch {
243
+ return null;
244
+ }
245
+ }
246
+
247
+ export async function extractCommitDirectDependencies(
248
+ localGitDir ,
249
+ commitSha ,
250
+ subdir ,
251
+ signal ,
252
+ ) {
253
+ if (!validateGitRef(commitSha) || (subdir && !validateGitSubdir(subdir))) {
254
+ return { deps: [] };
255
+ }
256
+ const prefix = subdir ? `${subdir.replace(/^\/+|\/+$/g, "")}/` : "";
257
+ const buf = await runGitBuffer(["show", `${commitSha}:${prefix}package.json`], localGitDir, 15000, signal);
258
+ if (!buf) return { deps: [] };
259
+ try {
260
+ const pkg = JSON.parse(buf.toString("utf8")) ;
261
+ const combined = { ...(pkg.dependencies ?? {}), ...(pkg.optionalDependencies ?? {}) };
262
+ const deps = Object.entries(combined)
263
+ .slice(0, 50)
264
+ .map(([name, range]) => {
265
+ const clean = typeof range === "string" ? range.trim() : "";
266
+ const exact = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(clean);
267
+ return { name, version: exact ? clean : undefined, isFloating: !exact };
268
+ });
269
+ let binName ;
270
+ if (typeof pkg.bin === "string" && pkg.name) {
271
+ binName = pkg.name.includes("/") ? pkg.name.slice(pkg.name.indexOf("/") + 1) : pkg.name;
272
+ } else if (pkg.bin && typeof pkg.bin === "object") {
273
+ binName = Object.keys(pkg.bin)[0];
274
+ }
275
+ return { deps, binName };
276
+ } catch {
277
+ return { deps: [] };
278
+ }
279
+ }
280
+
281
+ function normalizedRecord(rec ) {
282
+ if (!rec) return "{}";
283
+ return JSON.stringify(
284
+ Object.keys(rec)
285
+ .sort()
286
+ .reduce ((acc, k) => {
287
+ acc[k] = rec[k] ;
288
+ return acc;
289
+ }, {}),
290
+ );
291
+ }
292
+
293
+ /**
294
+ * 3-Tier Provenance-Aware Tarball-vs-Git Parity Verification:
295
+ * - Gold: PROVENANCE_ATTESTED (ONLY when full Sigstore/SLSA cryptographic verification succeeded)
296
+ * - Unanchored / Metadata-Only: PROVENANCE_UNANCHORED_DSSE or PROVENANCE_METADATA_UNVERIFIED
297
+ * (explicitly sets provenance_attested=false and discloses Fulcio/Rekor trust boundaries)
298
+ * - Silver: MANIFEST_PARITY_VERIFIED (package.json scripts/bin/dependencies match gitHead)
299
+ * - Bronze: COMPILED_DIST_UNATTESTED vs TARBALL_SOURCE_DRIFT (handles TypeScript dist/ cleanly!)
300
+ */
301
+ export async function verifyTarballVsGitParity(params
302
+
303
+
304
+
305
+
306
+
307
+
308
+
309
+
310
+
311
+
312
+
313
+ ) {
314
+ const observations = [];
315
+ const unknowns = [];
316
+
317
+ const effectiveStatus =
318
+ params.provenanceInspection?.status ??
319
+ params.provenanceStatus ??
320
+ (params.provenanceAttested ? "sigstore_verified" : params.provenanceUrl ? "metadata_url_only" : "none");
321
+ const cryptoVerified = effectiveStatus === "sigstore_verified" && params.provenanceAttested;
322
+ const provUrl = params.provenanceInspection?.provenance_url ?? params.provenanceUrl;
323
+
324
+ if (params.provenanceInspection) {
325
+ observations.push(...params.provenanceInspection.observations);
326
+ unknowns.push(...params.provenanceInspection.unknowns);
327
+ } else if (effectiveStatus === "metadata_url_only") {
328
+ unknowns.push(
329
+ "PROVENANCE_CRYPTO_UNVERIFIED: registry metadata advertises dist.attestations.url, but Sigstore/SLSA cryptographic verification (Fulcio CA chain + Rekor transparency log) was not performed.",
330
+ );
331
+ } else if (effectiveStatus === "dsse_leaf_verified_unanchored") {
332
+ unknowns.push(
333
+ "PROVENANCE_TRUST_ROOT_UNVERIFIED: SLSA DSSE signature verified against bundled leaf certificate, but Sigstore Fulcio CA chain and Rekor transparency-log proofs were NOT verified locally.",
334
+ );
335
+ }
336
+
337
+ if (!params.localGitDir) {
338
+ if (effectiveStatus === "verification_failed") {
339
+ return {
340
+ tier: "TARBALL_SOURCE_DRIFT",
341
+ git_head: params.gitHead,
342
+ repository_url: params.repositoryUrl,
343
+ provenance_attested: false,
344
+ provenance_status: "verification_failed",
345
+ provenance_url: provUrl,
346
+ observations,
347
+ unknowns,
348
+ };
349
+ }
350
+ if (cryptoVerified) {
351
+ return {
352
+ tier: "PROVENANCE_ATTESTED",
353
+ git_head: params.gitHead,
354
+ repository_url: params.repositoryUrl,
355
+ provenance_attested: true,
356
+ provenance_status: "sigstore_verified",
357
+ provenance_url: provUrl,
358
+ observations,
359
+ unknowns,
360
+ };
361
+ }
362
+ if (effectiveStatus === "dsse_leaf_verified_unanchored") {
363
+ return {
364
+ tier: "PROVENANCE_UNANCHORED_DSSE",
365
+ git_head: params.gitHead,
366
+ repository_url: params.repositoryUrl,
367
+ provenance_attested: false,
368
+ provenance_status: "dsse_leaf_verified_unanchored",
369
+ provenance_url: provUrl,
370
+ observations,
371
+ unknowns,
372
+ };
373
+ }
374
+ if (effectiveStatus === "metadata_url_only") {
375
+ return {
376
+ tier: "PROVENANCE_METADATA_UNVERIFIED",
377
+ git_head: params.gitHead,
378
+ repository_url: params.repositoryUrl,
379
+ provenance_attested: false,
380
+ provenance_status: "metadata_url_only",
381
+ provenance_url: provUrl,
382
+ observations,
383
+ unknowns,
384
+ };
385
+ }
386
+ if (!params.gitHead) {
387
+ unknowns.push("SOURCE_UNLINKED: no npm provenance attestation and no gitHead/repository linked.");
388
+ return {
389
+ tier: "SOURCE_UNLINKED",
390
+ repository_url: params.repositoryUrl,
391
+ provenance_attested: false,
392
+ provenance_status: effectiveStatus,
393
+ provenance_url: provUrl,
394
+ observations,
395
+ unknowns,
396
+ };
397
+ }
398
+ unknowns.push(
399
+ `PARITY_GIT_NOT_FETCHED: gitHead '${params.gitHead}' recorded, but local Git checkout was not supplied for manifest diff.`,
400
+ );
401
+ return {
402
+ tier: "COMPILED_DIST_UNATTESTED",
403
+ git_head: params.gitHead,
404
+ repository_url: params.repositoryUrl,
405
+ provenance_attested: false,
406
+ provenance_status: effectiveStatus,
407
+ provenance_url: provUrl,
408
+ observations,
409
+ unknowns,
410
+ };
411
+ }
412
+
413
+ const ref = params.gitHead ?? "HEAD";
414
+ if (!validateGitRef(ref)) {
415
+ observations.push({
416
+ code: "TARBALL_SOURCE_DRIFT_INVALID_GIT_HEAD",
417
+ severity: "CRITICAL",
418
+ path: "package.json",
419
+ attack_id: "T1195.002",
420
+ detail: `Rejected malformed or option-like gitHead value '${sanitizeUntrustedText(ref, 64)}' (must be 40-char hex SHA).`,
421
+ });
422
+ return {
423
+ tier: "TARBALL_SOURCE_DRIFT",
424
+ git_head: undefined,
425
+ repository_url: params.repositoryUrl,
426
+ provenance_attested: false,
427
+ provenance_status: effectiveStatus,
428
+ provenance_url: provUrl,
429
+ observations,
430
+ unknowns,
431
+ };
432
+ }
433
+ if (params.subdir && !validateGitSubdir(params.subdir)) {
434
+ unknowns.push(`INVALID_GIT_SUBDIR: rejected unsafe subdir '${sanitizeUntrustedText(params.subdir, 64)}'.`);
435
+ return {
436
+ tier: effectiveStatus === "verification_failed" ? "TARBALL_SOURCE_DRIFT" : "SOURCE_UNLINKED",
437
+ git_head: params.gitHead,
438
+ repository_url: params.repositoryUrl,
439
+ provenance_attested: false,
440
+ provenance_status: effectiveStatus,
441
+ provenance_url: provUrl,
442
+ observations,
443
+ unknowns,
444
+ };
445
+ }
446
+ const prefix = params.subdir ? `${params.subdir.replace(/^\/+|\/+$/g, "")}/` : "";
447
+ const gitPkgBuf = await runGitBuffer(["show", `${ref}:${prefix}package.json`], params.localGitDir, 15000, params.signal);
448
+ if (!gitPkgBuf || !params.tarballManifest) {
449
+ unknowns.push(`GIT_MANIFEST_UNREADABLE: could not read '${ref}:${prefix}package.json' from local Git repo.`);
450
+ return {
451
+ tier: effectiveStatus === "verification_failed" ? "TARBALL_SOURCE_DRIFT" : "SOURCE_UNLINKED",
452
+ git_head: params.gitHead,
453
+ repository_url: params.repositoryUrl,
454
+ provenance_attested: false,
455
+ provenance_status: effectiveStatus,
456
+ provenance_url: provUrl,
457
+ observations,
458
+ unknowns,
459
+ };
460
+ }
461
+
462
+ let gitManifest ;
463
+ try {
464
+ gitManifest = JSON.parse(gitPkgBuf.toString("utf8")) ;
465
+ } catch {
466
+ unknowns.push("GIT_MANIFEST_INVALID_JSON");
467
+ return {
468
+ tier: effectiveStatus === "verification_failed" ? "TARBALL_SOURCE_DRIFT" : "SOURCE_UNLINKED",
469
+ git_head: params.gitHead,
470
+ repository_url: params.repositoryUrl,
471
+ provenance_attested: false,
472
+ provenance_status: effectiveStatus,
473
+ provenance_url: provUrl,
474
+ observations,
475
+ unknowns,
476
+ };
477
+ }
478
+
479
+ // Silver check: compare security-critical manifest fields (scripts, bin, dependencies, optionalDependencies)
480
+ let driftDetected = false;
481
+
482
+ if (normalizedRecord(params.tarballManifest.scripts) !== normalizedRecord(gitManifest.scripts)) {
483
+ driftDetected = true;
484
+ observations.push({
485
+ code: "TARBALL_SOURCE_DRIFT_SCRIPTS",
486
+ severity: "CRITICAL",
487
+ path: "package.json",
488
+ attack_id: "T1195.002",
489
+ detail: "Tarball package.json 'scripts' diverge from Git source commit (potential tarball-only lifecycle hook injection).",
490
+ });
491
+ }
492
+
493
+ if (JSON.stringify(params.tarballManifest.bin ?? null) !== JSON.stringify(gitManifest.bin ?? null)) {
494
+ driftDetected = true;
495
+ observations.push({
496
+ code: "TARBALL_SOURCE_DRIFT_BIN",
497
+ severity: "HIGH",
498
+ path: "package.json",
499
+ attack_id: "T1195.002",
500
+ detail: "Tarball package.json 'bin' entrypoints diverge from Git source commit.",
501
+ });
502
+ }
503
+
504
+ if (
505
+ normalizedRecord(params.tarballManifest.dependencies) !== normalizedRecord(gitManifest.dependencies) ||
506
+ normalizedRecord(params.tarballManifest.optionalDependencies) !== normalizedRecord(gitManifest.optionalDependencies)
507
+ ) {
508
+ driftDetected = true;
509
+ observations.push({
510
+ code: "TARBALL_SOURCE_DRIFT_DEPS",
511
+ severity: "HIGH",
512
+ path: "package.json",
513
+ attack_id: "T1195.002",
514
+ detail: "Tarball package.json dependencies or optionalDependencies diverge from Git source commit.",
515
+ });
516
+ }
517
+
518
+ // Check if non-build JS files in tarball exist in Git and match SHA-256
519
+ const treeList = await runGit(
520
+ ["ls-tree", "-r", ref, ...(prefix ? [prefix.slice(0, -1)] : [])],
521
+ params.localGitDir,
522
+ 15000,
523
+ params.signal,
524
+ );
525
+ const gitFilePaths = new Set ();
526
+ let hasBuildConfig = false;
527
+ if (treeList.ok) {
528
+ for (const line of treeList.stdout.split(/\r?\n/)) {
529
+ const tabIdx = line.indexOf("\t");
530
+ if (tabIdx === -1) continue;
531
+ let p = line.slice(tabIdx + 1).trim();
532
+ if (prefix && p.startsWith(prefix)) p = p.slice(prefix.length);
533
+ gitFilePaths.add(p);
534
+ if (
535
+ p === "tsconfig.json" ||
536
+ p.startsWith("tsup.config") ||
537
+ p.startsWith("esbuild") ||
538
+ p.startsWith("rollup.config") ||
539
+ p.startsWith("webpack.config") ||
540
+ p.startsWith("vite.config")
541
+ ) {
542
+ hasBuildConfig = true;
543
+ }
544
+ }
545
+ }
546
+
547
+ let hasCompiledDistOnly = false;
548
+ for (const entry of params.tarballEntries) {
549
+ if (entry.path === "package.json") continue;
550
+ if (gitFilePaths.has(entry.path)) {
551
+ const gitBlob = await runGitBuffer(["show", `${ref}:${prefix}${entry.path}`], params.localGitDir, 15000, params.signal);
552
+ if (gitBlob) {
553
+ const gitSha = createHash("sha256").update(gitBlob).digest("hex");
554
+ if (gitSha !== entry.sha256) {
555
+ driftDetected = true;
556
+ observations.push({
557
+ code: "TARBALL_SOURCE_DRIFT_FILE_MODIFIED",
558
+ severity: "CRITICAL",
559
+ path: entry.path,
560
+ digest_sha256: entry.sha256,
561
+ attack_id: "T1195.002",
562
+ detail: `Published tarball file '${entry.path}' differs byte-for-byte from Git commit '${ref}'.`,
563
+ });
564
+ }
565
+ }
566
+ } else if (/^(dist|build|lib|out)\//.test(entry.path) && hasBuildConfig) {
567
+ hasCompiledDistOnly = true;
568
+ } else if (/\.(js|mjs|cjs|sh|ps1|bat|cmd|node|wasm)$/i.test(entry.path)) {
569
+ driftDetected = true;
570
+ observations.push({
571
+ code: "TARBALL_SOURCE_DRIFT_EXTRA_EXEC",
572
+ severity: "CRITICAL",
573
+ path: entry.path,
574
+ digest_sha256: entry.sha256,
575
+ attack_id: "T1195.002",
576
+ detail: `Unexplained executable/script file '${entry.path}' in tarball is absent from Git source commit '${ref}'.`,
577
+ });
578
+ }
579
+ }
580
+
581
+ if (driftDetected || effectiveStatus === "verification_failed") {
582
+ return {
583
+ tier: "TARBALL_SOURCE_DRIFT",
584
+ git_head: params.gitHead,
585
+ repository_url: params.repositoryUrl,
586
+ provenance_attested: false,
587
+ provenance_status: effectiveStatus === "verification_failed" ? "verification_failed" : effectiveStatus,
588
+ provenance_url: provUrl,
589
+ observations,
590
+ unknowns,
591
+ };
592
+ }
593
+
594
+ if (hasCompiledDistOnly) {
595
+ if (cryptoVerified) {
596
+ return {
597
+ tier: "PROVENANCE_ATTESTED",
598
+ git_head: params.gitHead,
599
+ repository_url: params.repositoryUrl,
600
+ provenance_attested: true,
601
+ provenance_status: "sigstore_verified",
602
+ provenance_url: provUrl,
603
+ observations,
604
+ unknowns,
605
+ };
606
+ }
607
+ unknowns.push("COMPILED_DIST_UNATTESTED: compiled build output present in tarball without cryptographically verified SLSA provenance; manifest & source files match gitHead.");
608
+ return {
609
+ tier: "COMPILED_DIST_UNATTESTED",
610
+ git_head: params.gitHead,
611
+ repository_url: params.repositoryUrl,
612
+ provenance_attested: false,
613
+ provenance_status: effectiveStatus,
614
+ provenance_url: provUrl,
615
+ observations,
616
+ unknowns,
617
+ };
618
+ }
619
+
620
+ return {
621
+ tier: cryptoVerified ? "PROVENANCE_ATTESTED" : "MANIFEST_PARITY_VERIFIED",
622
+ git_head: params.gitHead,
623
+ repository_url: params.repositoryUrl,
624
+ provenance_attested: cryptoVerified,
625
+ provenance_status: effectiveStatus,
626
+ provenance_url: provUrl,
627
+ observations,
628
+ unknowns,
629
+ };
630
+ }
631
+
632
+
633
+
634
+
635
+
636
+
637
+
638
+
639
+
640
+
641
+ function isAdvisoryPolicyBlocking(advisories , policy ) {
642
+ return advisories.some(
643
+ (a) =>
644
+ a.is_malicious ||
645
+ (policy.block_on_kev && a.kev) ||
646
+ (policy.block_on_critical_cve && a.severity === "CRITICAL") ||
647
+ (policy.block_on_high_cve && a.severity === "HIGH"),
648
+ );
649
+ }
650
+
651
+ function isReleaseProvenanceVerified(
652
+ rel ,
653
+ ) {
654
+ if (!rel?.provenance_attested) return false;
655
+ const status = rel.provenance_status ?? "sigstore_verified";
656
+ return status === "sigstore_verified";
657
+ }
658
+
659
+ function safePinnedNpxCommand(pkgName , version , binName ) {
660
+ if (!version) return null;
661
+ if (!isSafeNpmPackageName(pkgName) || !isSafeNpmVersion(version) || !isSafeNpmBinName(binName)) {
662
+ return null;
663
+ }
664
+ return `npx --yes --ignore-scripts --package=${pkgName}@${version} -- ${binName}`;
665
+ }
666
+
667
+ function classifyCommitObservations(obs , unknowns ) {
668
+ if (
669
+ obs.some(
670
+ (o) =>
671
+ o.severity === "CRITICAL" ||
672
+ o.code === "TAINT_CRED_TO_NETWORK_OR_EXEC" ||
673
+ o.code === "ENV_SERIALIZATION_EXFIL" ||
674
+ o.code === "BASE64_PAYLOAD_SUSPICIOUS" ||
675
+ o.code === "LIFECYCLE_HOOK_DANGEROUS_CMD" ||
676
+ o.code === "SHADY_WEBHOOK_OR_RAW_IP",
677
+ )
678
+ ) {
679
+ return "MALICIOUS_INDICATORS_FOUND";
680
+ }
681
+ if (obs.some((o) => o.severity === "HIGH" || o.code === "HIDDEN_UNICODE_TROJAN_SOURCE" || o.code === "HIGH_ENTROPY_OBFUSCATION")) {
682
+ return "QUARANTINE_SUSPICIOUS";
683
+ }
684
+ if (unknowns.some((u) => u.startsWith("REA_DEEP_FORENSICS_REQUIRED") || u.startsWith("OBFUSCATED_CODE_UNRECOVERED"))) {
685
+ return "UNVERIFIABLE_UNKNOWN";
686
+ }
687
+ return "VERIFIED_CLEAN_WITHIN_SCOPE";
688
+ }
689
+
690
+ /**
691
+ * Safe Clean-Commit & Patient-Zero Resolver.
692
+ * Uses `git rev-list --first-parent`, `git ls-tree -r`, and content-addressed blob-SHA caching
693
+ * in SplitPlaneCache so unchanged files across commits are scanned at most once.
694
+ * Aggregates findings across the FULL tree of each commit (catching multi-file split payloads).
695
+ */
696
+ export async function walkGitHistoryForCleanAnchor(params
697
+
698
+
699
+
700
+
701
+
702
+
703
+
704
+
705
+
706
+
707
+
708
+
709
+
710
+
711
+
712
+
713
+
714
+ ) {
715
+ const unknowns = [];
716
+ const inspected_commits = [];
717
+ const evidence = [];
718
+ let workDir = params.repoUrlOrLocalPath;
719
+ let tempCloneDir = null;
720
+ const resolvedBin =
721
+ params.binName ??
722
+ (params.package_name.includes("/")
723
+ ? params.package_name.slice(params.package_name.indexOf("/") + 1)
724
+ : params.package_name);
725
+
726
+ if (params.subdir && !validateGitSubdir(params.subdir)) {
727
+ unknowns.push(`INVALID_GIT_SUBDIR: rejected unsafe subdir '${sanitizeUntrustedText(params.subdir, 64)}'.`);
728
+ return {
729
+ schema_version: "1",
730
+ package_name: params.package_name,
731
+ compromised_latest: { reason: "Rejected unsafe Git subdirectory argument." },
732
+ recommended_action: params.alternatives?.length ? "SWITCH_TO_ALTERNATIVE" : "BLOCK_NO_SAFE_PATH",
733
+ alternatives: params.alternatives ?? [],
734
+ inspected_commits,
735
+ evidence,
736
+ unknowns,
737
+ };
738
+ }
739
+
740
+ try {
741
+ if (!params.isLocalDir) {
742
+ // Security [MCP-03]: fail closed on remote git clone whenever offline_mode is enabled
743
+ if (params.policy.offline_mode) {
744
+ unknowns.push("OFFLINE_MODE_GIT_CLONE_BLOCKED: remote git clone is disabled while offline_mode is enabled.");
745
+ return {
746
+ schema_version: "1",
747
+ package_name: params.package_name,
748
+ compromised_latest: { reason: "Remote git clone blocked in offline mode; supply a local git_dir instead." },
749
+ recommended_action: params.alternatives?.length ? "SWITCH_TO_ALTERNATIVE" : "BLOCK_NO_SAFE_PATH",
750
+ alternatives: params.alternatives ?? [],
751
+ inspected_commits,
752
+ evidence,
753
+ unknowns,
754
+ };
755
+ }
756
+ const urlCheck = validateRemoteGitUrl(params.repoUrlOrLocalPath);
757
+ if (!urlCheck.valid) {
758
+ unknowns.push(`GIT_REMOTE_URL_REJECTED: ${urlCheck.reason ?? "invalid URL"}`);
759
+ return {
760
+ schema_version: "1",
761
+ package_name: params.package_name,
762
+ compromised_latest: { reason: urlCheck.reason ?? "Rejected untrusted remote Git URL." },
763
+ recommended_action: params.alternatives?.length ? "SWITCH_TO_ALTERNATIVE" : "BLOCK_NO_SAFE_PATH",
764
+ alternatives: params.alternatives ?? [],
765
+ inspected_commits,
766
+ evidence,
767
+ unknowns,
768
+ };
769
+ }
770
+ tempCloneDir = mkdtempSync(join(tmpdir(), "coldpin-git-"));
771
+ ACTIVE_GIT_TEMP_DIRS.add(tempCloneDir);
772
+ const cloneArgs = [
773
+ "clone",
774
+ "--filter=blob:none",
775
+ "--no-checkout",
776
+ "--single-branch",
777
+ "--",
778
+ params.repoUrlOrLocalPath,
779
+ tempCloneDir,
780
+ ];
781
+ const cloneRes = await runGit(cloneArgs, tmpdir(), 30000, params.signal);
782
+ if (!cloneRes.ok) {
783
+ unknowns.push(`GIT_CLONE_FAILED: ${cloneRes.stderr.trim()}`);
784
+ return {
785
+ schema_version: "1",
786
+ package_name: params.package_name,
787
+ compromised_latest: { reason: "Could not clone repository for commit history inspection." },
788
+ recommended_action: params.alternatives?.length ? "SWITCH_TO_ALTERNATIVE" : "BLOCK_NO_SAFE_PATH",
789
+ alternatives: params.alternatives ?? [],
790
+ inspected_commits,
791
+ evidence,
792
+ unknowns,
793
+ };
794
+ }
795
+ workDir = tempCloneDir;
796
+ }
797
+
798
+ const maxCommits = Math.max(1, params.policy.bisect_max_commits);
799
+ const sinceArg = `--since=${params.policy.bisect_max_days}.days`;
800
+ const logArgs = [
801
+ "rev-list",
802
+ "--first-parent",
803
+ `-n`,
804
+ String(maxCommits),
805
+ sinceArg,
806
+ "--format=%H%x1f%cI%x1f%s",
807
+ "HEAD",
808
+ ];
809
+ if (params.subdir) logArgs.push("--", params.subdir);
810
+
811
+ const logRes = await runGit(logArgs, workDir, 15000, params.signal);
812
+ if (!logRes.ok) {
813
+ unknowns.push(`GIT_REV_LIST_FAILED: ${logRes.stderr.trim()}`);
814
+ return {
815
+ schema_version: "1",
816
+ package_name: params.package_name,
817
+ compromised_latest: { reason: "Failed to read Git commit history." },
818
+ recommended_action: params.alternatives?.length ? "SWITCH_TO_ALTERNATIVE" : "BLOCK_NO_SAFE_PATH",
819
+ alternatives: params.alternatives ?? [],
820
+ inspected_commits,
821
+ evidence,
822
+ unknowns,
823
+ };
824
+ }
825
+
826
+ const commits = [];
827
+ for (const line of logRes.stdout.split(/\r?\n/)) {
828
+ if (!line.includes("\x1f")) continue;
829
+ const parts = line.split("\x1f");
830
+ if (parts[0] && parts[0].length === 40) {
831
+ commits.push({
832
+ sha: parts[0],
833
+ date: parts[1] ?? "",
834
+ subject: sanitizeUntrustedText(parts[2] ?? "", 100),
835
+ });
836
+ }
837
+ }
838
+
839
+ if (commits.length === 0) {
840
+ unknowns.push("GIT_NO_COMMITS_IN_WINDOW: no commits matched the bounded bisect window.");
841
+ }
842
+
843
+ let latestVerdict = "UNVERIFIABLE_UNKNOWN";
844
+ let patientZeroSha ;
845
+ let cleanCandidate ;
846
+ let lookbehindRemaining = -1;
847
+ const NON_MONOTONIC_LOOKBEHIND = 3;
848
+
849
+ const blobMemoryCache = new Map ();
850
+
851
+ for (let idx = 0; idx < commits.length; idx++) {
852
+ if (params.signal?.aborted) {
853
+ throw new Error("Operation aborted");
854
+ }
855
+ const c = commits[idx] ;
856
+ // Use diff-tree --root --first-parent to count changed blobs safely (even on root commits)
857
+ const diffRes = await runGit(
858
+ ["diff-tree", "--root", "--first-parent", "-r", "--no-commit-id", "--name-only", c.sha],
859
+ workDir,
860
+ 15000,
861
+ params.signal,
862
+ );
863
+ const changedCount = diffRes.ok
864
+ ? diffRes.stdout.split(/\r?\n/).filter((l) => l.trim().length > 0).length
865
+ : 0;
866
+
867
+ // Full-tree listing so multi-file split payloads across blobs in commit C are evaluated together
868
+ const treeArgs = ["ls-tree", "-r", c.sha, ...(params.subdir ? [params.subdir] : [])];
869
+ const treeRes = await runGit(treeArgs, workDir, 15000, params.signal);
870
+ if (!treeRes.ok) {
871
+ unknowns.push(`GIT_LS_TREE_FAILED:${c.sha}`);
872
+ continue;
873
+ }
874
+
875
+ const commitObs = [];
876
+ const commitInferences = [];
877
+ const commitUnknowns = [];
878
+ const commitModuleTaint = new Map ();
879
+ let cacheHits = 0;
880
+ let filesInspected = 0;
881
+
882
+ for (const line of treeRes.stdout.split(/\r?\n/)) {
883
+ const tabIdx = line.indexOf("\t");
884
+ if (tabIdx === -1) continue;
885
+ const metaParts = line.slice(0, tabIdx).trim().split(/\s+/);
886
+ const objType = metaParts[1];
887
+ const blobSha = metaParts[2];
888
+ const filePath = line.slice(tabIdx + 1).trim();
889
+ if (objType !== "blob" || !blobSha) continue;
890
+
891
+ const cacheKey = buildFactCacheKey({
892
+ content_sha: `${blobSha}:${filePath}`,
893
+ ruleset_sha256: RULESET_SHA256,
894
+ options: { max_single_file_bytes: params.policy.max_single_file_bytes },
895
+ });
896
+
897
+ let blobFacts = blobMemoryCache.get(cacheKey) ?? params.cache?.getArtifactFacts (cacheKey) ?? null;
898
+ if (blobFacts) {
899
+ cacheHits++;
900
+ } else {
901
+ const blobBuf = await runGitBuffer(["cat-file", "blob", blobSha], workDir, 15000, params.signal);
902
+ if (!blobBuf) {
903
+ commitUnknowns.push(`GIT_BLOB_READ_FAILED:${blobSha}:${filePath}`);
904
+ continue;
905
+ }
906
+ const analyzed = analyzeSourceBlob(filePath, blobBuf, blobSha, params.policy);
907
+
908
+ // Also inspect package.json lifecycle hooks & shell-safe metadata inside the commit
909
+ if (filePath === "package.json" || filePath.endsWith("/package.json")) {
910
+ try {
911
+ const pkg = JSON.parse(blobBuf.toString("utf8")) ;
912
+ if (typeof pkg.name === "string" && !isSafeNpmPackageName(pkg.name)) {
913
+ analyzed.observations.push({
914
+ code: "MANIFEST_SHELL_INJECTION_META",
915
+ severity: "CRITICAL",
916
+ path: filePath,
917
+ digest_sha256: blobSha,
918
+ attack_id: "T1059",
919
+ detail: `Unsafe package.json 'name' in commit ${c.sha.slice(0, 8)}.`,
920
+ });
921
+ }
922
+ if (pkg.bin && typeof pkg.bin === "object") {
923
+ for (const binKey of Object.keys(pkg.bin)) {
924
+ if (!isSafeNpmBinName(binKey)) {
925
+ analyzed.observations.push({
926
+ code: "MANIFEST_SHELL_INJECTION_META",
927
+ severity: "CRITICAL",
928
+ path: filePath,
929
+ digest_sha256: blobSha,
930
+ attack_id: "T1059",
931
+ detail: `Unsafe package.json 'bin' key in commit ${c.sha.slice(0, 8)}.`,
932
+ });
933
+ }
934
+ }
935
+ }
936
+ for (const [hook, cmd] of Object.entries(pkg.scripts ?? {})) {
937
+ if (LIFECYCLE_HOOKS.has(hook.toLowerCase()) && typeof cmd === "string") {
938
+ const dangerous = DANGEROUS_LIFECYCLE_CMD_RE.test(cmd);
939
+ analyzed.observations.push({
940
+ code: dangerous ? "LIFECYCLE_HOOK_DANGEROUS_CMD" : "LIFECYCLE_HOOK_PRESENT",
941
+ severity: dangerous ? "CRITICAL" : "MEDIUM",
942
+ path: filePath,
943
+ digest_sha256: blobSha,
944
+ attack_id: "T1195.002",
945
+ detail: `Lifecycle script '${hook}' in commit ${c.sha.slice(0, 8)}: "${sanitizeUntrustedText(cmd, 120)}".`,
946
+ });
947
+ }
948
+ }
949
+ } catch {
950
+ analyzed.unknowns.push(`COMMIT_MANIFEST_PARSE_ERROR:${c.sha}`);
951
+ }
952
+ }
953
+
954
+ blobFacts = {
955
+ observations: analyzed.observations,
956
+ inferences: analyzed.inferences,
957
+ unknowns: analyzed.unknowns,
958
+ has_obfuscation: analyzed.has_obfuscation,
959
+ has_native_or_wasm: analyzed.has_native_or_wasm,
960
+ module_taint: analyzed.module_taint,
961
+ };
962
+ blobMemoryCache.set(cacheKey, blobFacts);
963
+ params.cache?.putArtifactFacts({
964
+ cache_key: cacheKey,
965
+ content_sha: `${blobSha}:${filePath}`,
966
+ ruleset_sha256: RULESET_SHA256,
967
+ facts: blobFacts,
968
+ });
969
+ }
970
+
971
+ filesInspected++;
972
+ commitObs.push(...blobFacts.observations);
973
+ commitInferences.push(...blobFacts.inferences);
974
+ commitUnknowns.push(...blobFacts.unknowns);
975
+ if (hasModuleTaintData(blobFacts.module_taint)) {
976
+ commitModuleTaint.set(filePath, { sha256: blobSha, taint: blobFacts.module_taint });
977
+ }
978
+ }
979
+
980
+ if (commitModuleTaint.size > 1) {
981
+ commitObs.push(...resolveCrossFileTaint(commitModuleTaint));
982
+ }
983
+
984
+ const relForCommit = params.releaseTarballByCommit?.get(c.sha);
985
+ const isReleaseCompromised = Boolean(
986
+ params.compromisedCommits?.has(c.sha) ||
987
+ (relForCommit?.version && params.compromisedVersions?.has(relForCommit.version)),
988
+ );
989
+ let verdict = classifyCommitObservations(commitObs, commitUnknowns);
990
+ if (isReleaseCompromised && verdict === "VERIFIED_CLEAN_WITHIN_SCOPE") {
991
+ verdict = "MALICIOUS_INDICATORS_FOUND";
992
+ commitObs.push({
993
+ code: "TARBALL_ONLY_RELEASE_COMPROMISE",
994
+ severity: "CRITICAL",
995
+ path: "<npm-release>",
996
+ attack_id: "T1195.002",
997
+ detail:
998
+ params.compromisedReason ??
999
+ `Published npm release ${relForCommit?.version ?? c.sha.slice(0, 10)} is flagged compromised despite clean Git source tree.`,
1000
+ });
1001
+ }
1002
+ const evId = `ev_bisect_${c.sha.slice(0, 12)}`;
1003
+ if (idx === 0) latestVerdict = verdict;
1004
+
1005
+ inspected_commits.push({
1006
+ commit_sha: c.sha,
1007
+ committed_at_utc: c.date,
1008
+ subject: c.subject,
1009
+ verdict,
1010
+ changed_blobs: changedCount,
1011
+ cache_hits: cacheHits,
1012
+ observations_count: commitObs.length,
1013
+ });
1014
+
1015
+ if (verdict !== "VERIFIED_CLEAN_WITHIN_SCOPE") {
1016
+ if (!cleanCandidate) {
1017
+ // Track oldest contiguous infected commit as patient-zero candidate
1018
+ patientZeroSha = c.sha;
1019
+ } else {
1020
+ // Non-monotonic history: earlier commit before our clean candidate was also infected
1021
+ unknowns.push(
1022
+ `HISTORICAL_NON_MONOTONIC_COMPROMISE: earlier commit ${c.sha.slice(0, 10)} before clean candidate ${cleanCandidate.sha.slice(0, 10)} also exhibited ${verdict}.`,
1023
+ );
1024
+ break;
1025
+ }
1026
+ if (idx === 0 || idx === commits.length - 1) {
1027
+ evidence.push({
1028
+ evidence_id: evId,
1029
+ source: "tier3_bisect",
1030
+ commit_sha: c.sha,
1031
+ observations: commitObs,
1032
+ inferences: commitInferences,
1033
+ unknowns: commitUnknowns,
1034
+ coverage: {
1035
+ files_inspected: filesInspected,
1036
+ files_skipped: 0,
1037
+ rea_invoked: false,
1038
+ transitive_checked: false,
1039
+ },
1040
+ });
1041
+ }
1042
+ } else {
1043
+ const hasVerifiedTarball = Boolean(relForCommit?.tarball_sha512);
1044
+ const hasReleaseMap = Boolean(params.releaseTarballByCommit && params.releaseTarballByCommit.size > 0);
1045
+ if (!cleanCandidate) {
1046
+ cleanCandidate = { sha: c.sha, obsCount: commitObs.length, evidenceId: evId, hasVerifiedTarball };
1047
+ if (idx > 0) {
1048
+ patientZeroSha = commits[idx - 1]?.sha;
1049
+ }
1050
+ evidence.push({
1051
+ evidence_id: evId,
1052
+ source: "tier3_bisect",
1053
+ commit_sha: c.sha,
1054
+ observations: commitObs,
1055
+ inferences: commitInferences,
1056
+ unknowns: commitUnknowns,
1057
+ coverage: {
1058
+ files_inspected: filesInspected,
1059
+ files_skipped: 0,
1060
+ rea_invoked: false,
1061
+ transitive_checked: Boolean(params.residualAdvisoriesByCommit?.has(c.sha)),
1062
+ },
1063
+ });
1064
+ } else if (hasVerifiedTarball && !cleanCandidate.hasVerifiedTarball) {
1065
+ // Promote to the latest clean commit that also has a verified npm release tarball
1066
+ cleanCandidate = { sha: c.sha, obsCount: commitObs.length, evidenceId: evId, hasVerifiedTarball: true };
1067
+ evidence.push({
1068
+ evidence_id: evId,
1069
+ source: "tier3_bisect",
1070
+ commit_sha: c.sha,
1071
+ observations: commitObs,
1072
+ inferences: commitInferences,
1073
+ unknowns: commitUnknowns,
1074
+ coverage: {
1075
+ files_inspected: filesInspected,
1076
+ files_skipped: 0,
1077
+ rea_invoked: false,
1078
+ transitive_checked: Boolean(params.residualAdvisoriesByCommit?.has(c.sha)),
1079
+ },
1080
+ });
1081
+ }
1082
+
1083
+ if (idx === 0) {
1084
+ break;
1085
+ }
1086
+ // Once we have a finalized clean candidate, scan a bounded lookbehind to detect non-monotonic history
1087
+ const candidateFinalized = !hasReleaseMap || cleanCandidate.hasVerifiedTarball;
1088
+ if (candidateFinalized) {
1089
+ if (lookbehindRemaining === -1) {
1090
+ lookbehindRemaining = NON_MONOTONIC_LOOKBEHIND;
1091
+ } else {
1092
+ lookbehindRemaining--;
1093
+ }
1094
+ if (lookbehindRemaining <= 0) {
1095
+ break;
1096
+ }
1097
+ }
1098
+ }
1099
+ }
1100
+
1101
+ const headSha = commits[0]?.sha;
1102
+ if (latestVerdict === "VERIFIED_CLEAN_WITHIN_SCOPE" && headSha) {
1103
+ const rel = params.releaseTarballByCommit?.get(headSha);
1104
+ const headAdvisories = params.residualAdvisoriesByCommit?.get(headSha) ?? [];
1105
+ if (isAdvisoryPolicyBlocking(headAdvisories, params.policy)) {
1106
+ return {
1107
+ schema_version: "1",
1108
+ package_name: params.package_name,
1109
+ compromised_latest: {
1110
+ version: rel?.version,
1111
+ commit_sha: headSha,
1112
+ reason: `HEAD commit (${headSha.slice(0, 10)}) has clean static source but failed enterprise CVE/KEV/MAL advisory policy gate.`,
1113
+ },
1114
+ recommended_action: params.alternatives?.length ? "SWITCH_TO_ALTERNATIVE" : "BLOCK_NO_SAFE_PATH",
1115
+ safe_anchor: {
1116
+ version: rel?.version,
1117
+ commit_sha: headSha,
1118
+ tarball_sha512: rel?.tarball_sha512,
1119
+ provenance_attested: rel?.provenance_attested ?? false,
1120
+ provenance_status: rel?.provenance_status ?? (rel?.provenance_attested ? "sigstore_verified" : "none"),
1121
+ pinned_execution: {
1122
+ command: null,
1123
+ exact_version: rel?.version,
1124
+ tarball_sha512: rel?.tarball_sha512,
1125
+ caveat: "Latest release blocked by enterprise CVE/KEV/MAL advisory policy; switch to a vetted alternative.",
1126
+ },
1127
+ residual_advisories: headAdvisories,
1128
+ },
1129
+ alternatives: params.alternatives ?? [],
1130
+ inspected_commits,
1131
+ evidence,
1132
+ unknowns,
1133
+ };
1134
+ }
1135
+ const headProvStatus =
1136
+ rel?.provenance_status ?? (rel?.provenance_attested ? "sigstore_verified" : "none");
1137
+ if (params.policy.require_provenance && !isReleaseProvenanceVerified(rel)) {
1138
+ unknowns.push(
1139
+ `PROVENANCE_REQUIRED_NOT_VERIFIED: enterprise policy requires cryptographically verified Sigstore/SLSA provenance (observed '${headProvStatus}', sigstore_verified=${isReleaseProvenanceVerified(rel)}).`,
1140
+ );
1141
+ return {
1142
+ schema_version: "1",
1143
+ package_name: params.package_name,
1144
+ compromised_latest: {
1145
+ version: rel?.version,
1146
+ commit_sha: headSha,
1147
+ reason: `HEAD commit (${headSha.slice(0, 10)}) lacks cryptographically verified Sigstore/SLSA provenance required by policy.`,
1148
+ },
1149
+ recommended_action: params.alternatives?.length ? "SWITCH_TO_ALTERNATIVE" : "BLOCK_NO_SAFE_PATH",
1150
+ safe_anchor: {
1151
+ version: rel?.version,
1152
+ commit_sha: headSha,
1153
+ tarball_sha512: rel?.tarball_sha512,
1154
+ provenance_attested: false,
1155
+ provenance_status: headProvStatus,
1156
+ pinned_execution: {
1157
+ command: null,
1158
+ exact_version: rel?.version,
1159
+ tarball_sha512: rel?.tarball_sha512,
1160
+ caveat: "Execution command suppressed: require_provenance=true requires full Sigstore Fulcio/Rekor verification.",
1161
+ },
1162
+ residual_advisories: headAdvisories,
1163
+ },
1164
+ alternatives: params.alternatives ?? [],
1165
+ inspected_commits,
1166
+ evidence,
1167
+ unknowns,
1168
+ };
1169
+ }
1170
+ const latestCmd = safePinnedNpxCommand(params.package_name, rel?.version, resolvedBin);
1171
+ return {
1172
+ schema_version: "1",
1173
+ package_name: params.package_name,
1174
+ compromised_latest: {
1175
+ commit_sha: headSha,
1176
+ reason: "HEAD commit shows no static malicious indicators within inspected scope.",
1177
+ },
1178
+ recommended_action: "USE_PINNED_LATEST",
1179
+ safe_anchor: {
1180
+ version: rel?.version,
1181
+ commit_sha: headSha,
1182
+ tarball_sha512: rel?.tarball_sha512,
1183
+ provenance_attested: isReleaseProvenanceVerified(rel),
1184
+ provenance_status: headProvStatus,
1185
+ pinned_execution: {
1186
+ command: latestCmd,
1187
+ exact_version: rel?.version,
1188
+ tarball_sha512: rel?.tarball_sha512,
1189
+ caveat: latestCmd
1190
+ ? "Stock npx pins top-level version only; verify tarball SHA-512 and lock transitive dependencies before execution."
1191
+ : "No safe executable command emitted (missing verified npm release version or unsafe package/bin identifier).",
1192
+ },
1193
+ residual_advisories: headAdvisories,
1194
+ },
1195
+ alternatives: params.alternatives ?? [],
1196
+ inspected_commits,
1197
+ evidence,
1198
+ unknowns,
1199
+ };
1200
+ }
1201
+
1202
+ if (!cleanCandidate) {
1203
+ unknowns.push(
1204
+ `NO_CLEAN_COMMIT_IN_WINDOW: scanned ${inspected_commits.length} commits (limit ${params.policy.bisect_max_commits}) without finding a clean ancestor.`,
1205
+ );
1206
+ return {
1207
+ schema_version: "1",
1208
+ package_name: params.package_name,
1209
+ compromised_latest: {
1210
+ commit_sha: headSha,
1211
+ patient_zero_sha: patientZeroSha,
1212
+ reason: `Latest commit (${headSha?.slice(0, 10) ?? "unknown"}) flagged ${latestVerdict}; no clean ancestor found in window.`,
1213
+ },
1214
+ recommended_action: params.alternatives?.length ? "SWITCH_TO_ALTERNATIVE" : "BLOCK_NO_SAFE_PATH",
1215
+ alternatives: params.alternatives ?? [],
1216
+ inspected_commits,
1217
+ evidence,
1218
+ unknowns,
1219
+ };
1220
+ }
1221
+
1222
+ // Dual-Gate CVE & Tarball Parity Check on cleanCandidate
1223
+ const residualAdvisories = params.residualAdvisoriesByCommit?.get(cleanCandidate.sha) ?? [];
1224
+ const blockedByCve = isAdvisoryPolicyBlocking(residualAdvisories, params.policy);
1225
+
1226
+ const matchingRelease = params.releaseTarballByCommit?.get(cleanCandidate.sha);
1227
+
1228
+ if (blockedByCve) {
1229
+ return {
1230
+ schema_version: "1",
1231
+ package_name: params.package_name,
1232
+ compromised_latest: {
1233
+ commit_sha: headSha,
1234
+ patient_zero_sha: patientZeroSha,
1235
+ reason: `Latest commit compromised; clean ancestor ${cleanCandidate.sha.slice(0, 10)} failed CVE/KEV policy gate.`,
1236
+ },
1237
+ recommended_action: params.alternatives?.length ? "SWITCH_TO_ALTERNATIVE" : "BLOCK_NO_SAFE_PATH",
1238
+ safe_anchor: {
1239
+ version: matchingRelease?.version,
1240
+ commit_sha: cleanCandidate.sha,
1241
+ tarball_sha512: matchingRelease?.tarball_sha512,
1242
+ provenance_attested: isReleaseProvenanceVerified(matchingRelease),
1243
+ provenance_status:
1244
+ matchingRelease?.provenance_status ?? (matchingRelease?.provenance_attested ? "sigstore_verified" : "none"),
1245
+ pinned_execution: {
1246
+ command: null,
1247
+ exact_version: matchingRelease?.version,
1248
+ tarball_sha512: matchingRelease?.tarball_sha512,
1249
+ caveat: "Rollback blocked by enterprise CVE/KEV policy; switch to a vetted alternative.",
1250
+ },
1251
+ residual_advisories: residualAdvisories,
1252
+ },
1253
+ alternatives: params.alternatives ?? [],
1254
+ inspected_commits,
1255
+ evidence,
1256
+ unknowns,
1257
+ };
1258
+ }
1259
+
1260
+ if (!matchingRelease?.tarball_sha512) {
1261
+ unknowns.push(
1262
+ `NO_VERIFIED_NPM_TARBALL_FOR_COMMIT: clean commit ${cleanCandidate.sha} has no verified npm tarball; direct 'npx github:...' execution is blocked to avoid unverified build scripts and floating transitives.`,
1263
+ );
1264
+ return {
1265
+ schema_version: "1",
1266
+ package_name: params.package_name,
1267
+ compromised_latest: {
1268
+ commit_sha: headSha,
1269
+ patient_zero_sha: patientZeroSha,
1270
+ reason: `Malicious indicators introduced at ${patientZeroSha?.slice(0, 10) ?? "unknown"}; last clean source commit is ${cleanCandidate.sha.slice(0, 10)} (no published verified tarball).`,
1271
+ },
1272
+ recommended_action: params.alternatives?.length ? "SWITCH_TO_ALTERNATIVE" : "FORENSIC_COMMIT_ONLY",
1273
+ safe_anchor: {
1274
+ commit_sha: cleanCandidate.sha,
1275
+ provenance_attested: false,
1276
+ provenance_status: "none",
1277
+ pinned_execution: {
1278
+ command: null,
1279
+ caveat:
1280
+ "Forensic anchor only: no matching verified npm tarball exists. Build in an isolated sandbox or switch to a vetted alternative.",
1281
+ },
1282
+ residual_advisories: residualAdvisories,
1283
+ },
1284
+ alternatives: params.alternatives ?? [],
1285
+ inspected_commits,
1286
+ evidence,
1287
+ unknowns,
1288
+ };
1289
+ }
1290
+
1291
+ const rollbackProvStatus =
1292
+ matchingRelease.provenance_status ?? (matchingRelease.provenance_attested ? "sigstore_verified" : "none");
1293
+ if (params.policy.require_provenance && !isReleaseProvenanceVerified(matchingRelease)) {
1294
+ unknowns.push(
1295
+ `PROVENANCE_REQUIRED_NOT_VERIFIED: enterprise policy requires cryptographically verified Sigstore/SLSA provenance for rollback release ${matchingRelease.version} (observed '${rollbackProvStatus}', sigstore_verified=false).`,
1296
+ );
1297
+ return {
1298
+ schema_version: "1",
1299
+ package_name: params.package_name,
1300
+ compromised_latest: {
1301
+ commit_sha: headSha,
1302
+ patient_zero_sha: patientZeroSha,
1303
+ reason: `Latest commit compromised; clean release ${matchingRelease.version} lacks cryptographically verified Sigstore/SLSA provenance required by policy.`,
1304
+ },
1305
+ recommended_action: params.alternatives?.length ? "SWITCH_TO_ALTERNATIVE" : "BLOCK_NO_SAFE_PATH",
1306
+ safe_anchor: {
1307
+ version: matchingRelease.version,
1308
+ commit_sha: cleanCandidate.sha,
1309
+ tarball_sha512: matchingRelease.tarball_sha512,
1310
+ provenance_attested: false,
1311
+ provenance_status: rollbackProvStatus,
1312
+ pinned_execution: {
1313
+ command: null,
1314
+ exact_version: matchingRelease.version,
1315
+ tarball_sha512: matchingRelease.tarball_sha512,
1316
+ caveat: "Rollback command suppressed: require_provenance=true requires full Sigstore Fulcio/Rekor verification.",
1317
+ },
1318
+ residual_advisories: residualAdvisories,
1319
+ },
1320
+ alternatives: params.alternatives ?? [],
1321
+ inspected_commits,
1322
+ evidence,
1323
+ unknowns,
1324
+ };
1325
+ }
1326
+
1327
+ const rollbackCmd = safePinnedNpxCommand(params.package_name, matchingRelease.version, resolvedBin);
1328
+ return {
1329
+ schema_version: "1",
1330
+ package_name: params.package_name,
1331
+ compromised_latest: {
1332
+ commit_sha: headSha,
1333
+ patient_zero_sha: patientZeroSha,
1334
+ reason: `Malicious indicators introduced at ${patientZeroSha?.slice(0, 10) ?? "unknown"}; safe verified release ${matchingRelease.version} mapped to clean commit ${cleanCandidate.sha.slice(0, 10)}.`,
1335
+ },
1336
+ recommended_action: rollbackCmd ? "ROLLBACK_TO_SAFE_ANCHOR" : "BLOCK_NO_SAFE_PATH",
1337
+ safe_anchor: {
1338
+ version: matchingRelease.version,
1339
+ commit_sha: cleanCandidate.sha,
1340
+ tarball_sha512: matchingRelease.tarball_sha512,
1341
+ provenance_attested: isReleaseProvenanceVerified(matchingRelease),
1342
+ provenance_status: rollbackProvStatus,
1343
+ pinned_execution: {
1344
+ command: rollbackCmd,
1345
+ exact_version: matchingRelease.version,
1346
+ tarball_sha512: matchingRelease.tarball_sha512,
1347
+ caveat: rollbackCmd
1348
+ ? "Stock npx pins top-level version only; verify dist.integrity SHA-512 and lock transitive dependencies before execution."
1349
+ : "Execution command suppressed due to unsafe package/version/bin identifier.",
1350
+ },
1351
+ residual_advisories: residualAdvisories,
1352
+ },
1353
+ alternatives: params.alternatives ?? [],
1354
+ inspected_commits,
1355
+ evidence,
1356
+ unknowns,
1357
+ };
1358
+ } finally {
1359
+ if (tempCloneDir) {
1360
+ ACTIVE_GIT_TEMP_DIRS.delete(tempCloneDir);
1361
+ try {
1362
+ rmSync(tempCloneDir, { recursive: true, force: true });
1363
+ } catch {
1364
+ // Best-effort temp cleanup
1365
+ }
1366
+ }
1367
+ }
1368
+ }
1369
+
1370
+
1371
+ //# sourceURL=analysis/parity-and-bisect.ts