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.
Files changed (102) hide show
  1. package/ACCESSIBILITY.md +17 -0
  2. package/CHANGELOG.md +97 -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 +36 -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,357 @@
1
+ import { createHash } from "node:crypto";
2
+ import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, statSync, unlinkSync } from "node:fs";
3
+ import { appendFile, mkdir, open, stat, unlink } from "node:fs/promises";
4
+ import { userInfo } from "node:os";
5
+ import { dirname } from "node:path";
6
+ import { openReadCappedFile, readCappedRegularFileSync } from "../core/path-confinement.mjs";
7
+
8
+
9
+ const GENESIS_HASH = "0".repeat(64);
10
+ const LOCK_STALE_MS = 30_000;
11
+ const LOCK_WAIT_MS = 25;
12
+ const LOCK_MAX_ATTEMPTS = 80;
13
+ export const MAX_AUDIT_LOG_BYTES = 20 * 1024 * 1024;
14
+
15
+ const SLEEP_ARRAY = new Int32Array(new SharedArrayBuffer(4));
16
+
17
+ function sleepSync(ms ) {
18
+ Atomics.wait(SLEEP_ARRAY, 0, 0, ms);
19
+ }
20
+
21
+ function sleepAsync(ms ) {
22
+ return new Promise((r) => setTimeout(r, ms));
23
+ }
24
+
25
+ function withAuditFileLock (auditLogPath , fn ) {
26
+ const lockPath = `${auditLogPath}.lock`;
27
+ mkdirSync(dirname(auditLogPath), { recursive: true });
28
+
29
+ let fd = null;
30
+ for (let attempt = 0; attempt < LOCK_MAX_ATTEMPTS; attempt++) {
31
+ try {
32
+ fd = openSync(lockPath, "wx");
33
+ break;
34
+ } catch (err) {
35
+ const code = (err ).code;
36
+ if (code !== "EEXIST") throw err;
37
+ try {
38
+ const st = statSync(lockPath);
39
+ if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
40
+ unlinkSync(lockPath);
41
+ continue;
42
+ }
43
+ } catch {
44
+ continue;
45
+ }
46
+ sleepSync(LOCK_WAIT_MS);
47
+ }
48
+ }
49
+
50
+ if (fd === null) {
51
+ throw new Error(`Timed out acquiring audit log lock at ${lockPath}`);
52
+ }
53
+
54
+ try {
55
+ return fn();
56
+ } finally {
57
+ try {
58
+ closeSync(fd);
59
+ } catch {
60
+ // Ignore close error on cleanup
61
+ }
62
+ try {
63
+ unlinkSync(lockPath);
64
+ } catch {
65
+ // Ignore unlink error on cleanup
66
+ }
67
+ }
68
+ }
69
+
70
+ async function withAuditFileLockAsync (auditLogPath , fn ) {
71
+ const lockPath = `${auditLogPath}.lock`;
72
+ await mkdir(dirname(auditLogPath), { recursive: true });
73
+
74
+ let fh = null;
75
+ for (let attempt = 0; attempt < LOCK_MAX_ATTEMPTS; attempt++) {
76
+ try {
77
+ fh = await open(lockPath, "wx");
78
+ break;
79
+ } catch (err) {
80
+ const code = (err ).code;
81
+ if (code !== "EEXIST") throw err;
82
+ try {
83
+ const st = await stat(lockPath);
84
+ if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
85
+ await unlink(lockPath);
86
+ continue;
87
+ }
88
+ } catch {
89
+ continue;
90
+ }
91
+ const jitter = Math.floor(Math.random() * 15);
92
+ await sleepAsync(LOCK_WAIT_MS + jitter);
93
+ }
94
+ }
95
+
96
+ if (fh === null) {
97
+ throw new Error(`Timed out acquiring audit log lock at ${lockPath}`);
98
+ }
99
+
100
+ try {
101
+ return await fn();
102
+ } finally {
103
+ try {
104
+ await fh.close();
105
+ } catch {
106
+ // Ignore close error on cleanup
107
+ }
108
+ try {
109
+ await unlink(lockPath);
110
+ } catch {
111
+ // Ignore unlink error on cleanup
112
+ }
113
+ }
114
+ }
115
+
116
+ /**
117
+ * Structured operational JSON telemetry formatter — strictly separate from the
118
+ * hash-chained audit trail (`audit.jsonl`). Never logs secrets, tokens, or PII.
119
+ * Pure-core invariant: never writes directly to `process.stdout` or `process.stderr`;
120
+ * callers inject a `writer` (CLI/MCP pass stderr).
121
+ */
122
+ export function logOperationalEvent(
123
+ verbose ,
124
+ event ,
125
+ writer ,
126
+ ) {
127
+ if (!verbose) return null;
128
+ const line = `${JSON.stringify({
129
+ ts_utc: new Date().toISOString(),
130
+ stream: "operational",
131
+ ...event,
132
+ })}\n`;
133
+ if (writer) writer(line);
134
+ return line;
135
+ }
136
+
137
+ const ALLOWED_AUDIT_KEYS = new Set([
138
+ "seq",
139
+ "ts_utc",
140
+ "request_id",
141
+ "invoker_surface",
142
+ "mcp_client_name",
143
+ "tool_name",
144
+ "actor_id_hash",
145
+ "action",
146
+ "target",
147
+ "version",
148
+ "commit_sha",
149
+ "tarball_sha512",
150
+ "verdict",
151
+ "policy_sha256",
152
+ "evidence_ids",
153
+ "override_ticket_id",
154
+ "prev_hash",
155
+ "entry_hash",
156
+ ]);
157
+
158
+ function canonicalAuditPayload(ev ) {
159
+ const ordered = {
160
+ seq: ev.seq,
161
+ ts_utc: ev.ts_utc,
162
+ ...(ev.request_id !== undefined ? { request_id: ev.request_id } : {}),
163
+ ...(ev.invoker_surface !== undefined ? { invoker_surface: ev.invoker_surface } : {}),
164
+ ...(ev.mcp_client_name !== undefined ? { mcp_client_name: ev.mcp_client_name } : {}),
165
+ ...(ev.tool_name !== undefined ? { tool_name: ev.tool_name } : {}),
166
+ actor_id_hash: ev.actor_id_hash,
167
+ action: ev.action,
168
+ target: ev.target,
169
+ version: ev.version ?? null,
170
+ commit_sha: ev.commit_sha ?? null,
171
+ tarball_sha512: ev.tarball_sha512 ?? null,
172
+ verdict: ev.verdict,
173
+ policy_sha256: ev.policy_sha256,
174
+ evidence_ids: [...ev.evidence_ids].sort(),
175
+ ...(ev.override_ticket_id !== undefined ? { override_ticket_id: ev.override_ticket_id } : {}),
176
+ prev_hash: ev.prev_hash,
177
+ };
178
+ return JSON.stringify(ordered);
179
+ }
180
+
181
+ export function computePseudonymousActorId(salt = "coldpin-local-v1") {
182
+ let username = "unknown";
183
+ try {
184
+ username = userInfo().username;
185
+ } catch {
186
+ username = process.env["USER"] ?? process.env["USERNAME"] ?? "unknown";
187
+ }
188
+ return `actor_${createHash("sha256").update(`${salt}:${username}`).digest("hex").slice(0, 16)}`;
189
+ }
190
+
191
+ function buildChainedAuditEntry(
192
+ rawExisting ,
193
+ auditLogPath ,
194
+ params ,
195
+ ) {
196
+ let prevHash = GENESIS_HASH;
197
+ let nextSeq = 1;
198
+
199
+ if (rawExisting !== null) {
200
+ const lines = rawExisting
201
+ .split(/\r?\n/)
202
+ .filter((l) => l.trim().length > 0);
203
+ if (lines.length > 0) {
204
+ let last ;
205
+ try {
206
+ last = JSON.parse(lines[lines.length - 1] ) ;
207
+ } catch {
208
+ throw new Error(`Corrupted final JSONL line in audit log ${auditLogPath}; refusing to chain.`);
209
+ }
210
+ if (typeof last.seq !== "number" || typeof last.entry_hash !== "string" || !/^[0-9a-f]{64}$/.test(last.entry_hash)) {
211
+ throw new Error(`Invalid final audit entry fields in ${auditLogPath}; refusing to chain.`);
212
+ }
213
+ prevHash = last.entry_hash;
214
+ nextSeq = last.seq + 1;
215
+ }
216
+ }
217
+
218
+ const base = {
219
+ seq: nextSeq,
220
+ ts_utc: new Date().toISOString(),
221
+ actor_id_hash: computePseudonymousActorId(),
222
+ ...params,
223
+ prev_hash: prevHash,
224
+ };
225
+ const entry_hash = createHash("sha256")
226
+ .update(`${prevHash}|${canonicalAuditPayload(base)}`)
227
+ .digest("hex");
228
+
229
+ return { ...base, entry_hash };
230
+ }
231
+
232
+ /**
233
+ * Local append-only hash-chained audit trail (`audit.jsonl`) with atomic lockfile
234
+ * serialization so concurrent invocations cannot fork or corrupt the chain.
235
+ */
236
+ export function appendAuditEvent(
237
+ auditLogPath ,
238
+ params ,
239
+ ) {
240
+ return withAuditFileLock(auditLogPath, () => {
241
+ const rawExisting = existsSync(auditLogPath)
242
+ ? readCappedRegularFileSync(auditLogPath, MAX_AUDIT_LOG_BYTES).toString("utf8")
243
+ : null;
244
+ const full = buildChainedAuditEntry(rawExisting, auditLogPath, params);
245
+ appendFileSync(auditLogPath, `${JSON.stringify(full)}\n`, "utf8");
246
+ return full;
247
+ });
248
+ }
249
+
250
+ export async function appendAuditEventAsync(
251
+ auditLogPath ,
252
+ params ,
253
+ ) {
254
+ return withAuditFileLockAsync(auditLogPath, async () => {
255
+ let rawExisting = null;
256
+ if (existsSync(auditLogPath)) {
257
+ const buf = await openReadCappedFile(auditLogPath, MAX_AUDIT_LOG_BYTES);
258
+ rawExisting = buf.toString("utf8");
259
+ }
260
+ const full = buildChainedAuditEntry(rawExisting, auditLogPath, params);
261
+ await appendFile(auditLogPath, `${JSON.stringify(full)}\n`, "utf8");
262
+ return full;
263
+ });
264
+ }
265
+
266
+ export function verifyAuditLogContent(rawContent )
267
+
268
+
269
+
270
+
271
+ {
272
+ const lines = rawContent
273
+ .split(/\r?\n/)
274
+ .filter((l) => l.trim().length > 0);
275
+
276
+ let expectedPrev = GENESIS_HASH;
277
+ for (let i = 0; i < lines.length; i++) {
278
+ let ev ;
279
+ try {
280
+ ev = JSON.parse(lines[i] ) ;
281
+ } catch {
282
+ return { valid: false, total_events: lines.length, broken_at_seq: i + 1, reason: `Malformed JSON at line ${i + 1}` };
283
+ }
284
+ if (ev === null || typeof ev !== "object" || Array.isArray(ev)) {
285
+ return { valid: false, total_events: lines.length, broken_at_seq: i + 1, reason: `Non-object JSON entry at line ${i + 1}` };
286
+ }
287
+ const expectedSeq = i + 1;
288
+ if (ev.seq !== expectedSeq) {
289
+ return {
290
+ valid: false,
291
+ total_events: lines.length,
292
+ broken_at_seq: expectedSeq,
293
+ reason: `Sequence gap/mismatch: expected ${expectedSeq}, found ${String(ev.seq)}`,
294
+ };
295
+ }
296
+ if (ev.prev_hash !== expectedPrev) {
297
+ return {
298
+ valid: false,
299
+ total_events: lines.length,
300
+ broken_at_seq: ev.seq,
301
+ reason: `Hash chain break at seq ${ev.seq}: prev_hash mismatch.`,
302
+ };
303
+ }
304
+ const unexpectedKeys = Object.keys(ev ).filter((k) => !ALLOWED_AUDIT_KEYS.has(k));
305
+ if (unexpectedKeys.length > 0) {
306
+ return {
307
+ valid: false,
308
+ total_events: lines.length,
309
+ broken_at_seq: ev.seq,
310
+ reason: `Unexpected unhashed field(s) injected at seq ${ev.seq} (${unexpectedKeys.length} disallowed key(s); redacted).`,
311
+ };
312
+ }
313
+ const { entry_hash, ...rest } = ev;
314
+ const recomputed = createHash("sha256")
315
+ .update(`${expectedPrev}|${canonicalAuditPayload(rest)}`)
316
+ .digest("hex");
317
+ if (recomputed !== entry_hash) {
318
+ return {
319
+ valid: false,
320
+ total_events: lines.length,
321
+ broken_at_seq: ev.seq,
322
+ reason: `Tampered payload detected at seq ${ev.seq}: entry_hash mismatch.`,
323
+ };
324
+ }
325
+ expectedPrev = entry_hash;
326
+ }
327
+
328
+ return { valid: true, total_events: lines.length };
329
+ }
330
+
331
+ export function verifyAuditLog(
332
+ auditLogPath ,
333
+ maxBytes = MAX_AUDIT_LOG_BYTES,
334
+ )
335
+
336
+
337
+
338
+
339
+ {
340
+ if (!existsSync(auditLogPath)) {
341
+ return { valid: false, total_events: 0, reason: `Audit log not found at ${auditLogPath}` };
342
+ }
343
+ let rawContent ;
344
+ try {
345
+ rawContent = readCappedRegularFileSync(auditLogPath, maxBytes).toString("utf8");
346
+ } catch (err) {
347
+ return {
348
+ valid: false,
349
+ total_events: 0,
350
+ reason: `Audit log unreadable or exceeds size cap: ${err instanceof Error ? err.message : String(err)}`,
351
+ };
352
+ }
353
+ return verifyAuditLogContent(rawContent);
354
+ }
355
+
356
+
357
+ //# sourceURL=compliance/audit-log.ts