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
package/src/types.ts ADDED
@@ -0,0 +1,380 @@
1
+ export const ENGINE_VERSION = "1.5.1";
2
+ export const CACHE_SCHEMA_VERSION = "3";
3
+
4
+ export type TrustVerdict =
5
+ | "VERIFIED_CLEAN_WITHIN_SCOPE"
6
+ | "QUARANTINE_SUSPICIOUS"
7
+ | "MALICIOUS_INDICATORS_FOUND"
8
+ | "UNVERIFIABLE_UNKNOWN";
9
+
10
+ export type Severity = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO";
11
+
12
+ export type RecommendedAction =
13
+ | "USE_PINNED_LATEST"
14
+ | "ROLLBACK_TO_SAFE_ANCHOR"
15
+ | "FORENSIC_COMMIT_ONLY"
16
+ | "SWITCH_TO_ALTERNATIVE"
17
+ | "BLOCK_NO_SAFE_PATH";
18
+
19
+ export type ProvenanceStatus =
20
+ | "none"
21
+ | "metadata_url_only"
22
+ | "dsse_leaf_verified_unanchored"
23
+ | "sigstore_verified"
24
+ | "verification_failed";
25
+
26
+ export type ParityTier =
27
+ | "PROVENANCE_ATTESTED"
28
+ | "PROVENANCE_UNANCHORED_DSSE"
29
+ | "PROVENANCE_METADATA_UNVERIFIED"
30
+ | "MANIFEST_PARITY_VERIFIED"
31
+ | "COMPILED_DIST_UNATTESTED"
32
+ | "TARBALL_SOURCE_DRIFT"
33
+ | "SOURCE_UNLINKED";
34
+
35
+ export type ExitCode = 0 | 1 | 2 | 3;
36
+
37
+ export interface PolicyConfig {
38
+ private_scopes: string[];
39
+ private_prefixes: string[];
40
+ private_registries: Record<string, string>;
41
+ default_registry: string;
42
+ osv_api_url: string;
43
+ allow_public_fallback: boolean;
44
+ allowed_orgs: string[];
45
+ denied_orgs: string[];
46
+ blocked_licenses: string[];
47
+ cooldown_hours: number;
48
+ max_compressed_bytes: number;
49
+ max_uncompressed_bytes: number;
50
+ max_files: number;
51
+ max_single_file_bytes: number;
52
+ block_on_kev: boolean;
53
+ block_on_critical_cve: boolean;
54
+ block_on_high_cve: boolean;
55
+ require_provenance: boolean;
56
+ require_source_link: boolean;
57
+ bisect_max_commits: number;
58
+ bisect_max_days: number;
59
+ intel_ttl_seconds: number;
60
+ offline_mode: boolean;
61
+ }
62
+
63
+ export interface Observation {
64
+ code: string;
65
+ severity: Severity;
66
+ path: string;
67
+ line?: number;
68
+ digest_sha256?: string;
69
+ attack_id?: string;
70
+ atlas_id?: string;
71
+ detail: string;
72
+ }
73
+
74
+ export interface DefangedIoc {
75
+ kind: "url" | "domain" | "ip" | "sha256" | "sha512";
76
+ value: string;
77
+ tlp: "TLP:CLEAR" | "TLP:AMBER";
78
+ confidence: "high" | "medium" | "low";
79
+ source_path: string;
80
+ }
81
+
82
+ export interface EvidenceRecord {
83
+ evidence_id: string;
84
+ source:
85
+ | "tier0_intel"
86
+ | "tier1_unpack"
87
+ | "tier1_static"
88
+ | "tier1_parity"
89
+ | "tier2_rea"
90
+ | "tier3_bisect";
91
+ artifact_sha512?: string;
92
+ commit_sha?: string;
93
+ observations: Observation[];
94
+ inferences: string[];
95
+ unknowns: string[];
96
+ coverage: {
97
+ files_inspected: number;
98
+ files_skipped: number;
99
+ rea_invoked: boolean;
100
+ transitive_checked: boolean;
101
+ };
102
+ }
103
+
104
+ export interface TarEntry {
105
+ path: string;
106
+ size: number;
107
+ sha256: string;
108
+ content: Buffer;
109
+ }
110
+
111
+ export interface UnpackResult {
112
+ ok: boolean;
113
+ tarball_sha512: string;
114
+ compressed_bytes: number;
115
+ uncompressed_bytes: number;
116
+ entries: TarEntry[];
117
+ observations: Observation[];
118
+ unknowns: string[];
119
+ halted_by_cap: boolean;
120
+ }
121
+
122
+ export interface PackageManifest {
123
+ name?: string;
124
+ version?: string;
125
+ description?: string;
126
+ license?: string | { type?: string };
127
+ author?: string | { name?: string };
128
+ bin?: string | Record<string, string>;
129
+ scripts?: Record<string, string>;
130
+ dependencies?: Record<string, string>;
131
+ optionalDependencies?: Record<string, string>;
132
+ devDependencies?: Record<string, string>;
133
+ keywords?: string[];
134
+ repository?: string | { type?: string; url?: string; directory?: string };
135
+ gitHead?: string;
136
+ }
137
+
138
+ export interface TriageResult {
139
+ ruleset_sha256: string;
140
+ manifest: PackageManifest | null;
141
+ observations: Observation[];
142
+ inferences: string[];
143
+ unknowns: string[];
144
+ iocs: DefangedIoc[];
145
+ has_obfuscation: boolean;
146
+ has_native_or_wasm: boolean;
147
+ rea_recommended: boolean;
148
+ files_inspected: number;
149
+ files_skipped: number;
150
+ }
151
+
152
+ export interface AdvisoryRecord {
153
+ id: string;
154
+ is_malicious: boolean;
155
+ severity: Severity;
156
+ kev: boolean;
157
+ epss?: number;
158
+ summary: string;
159
+ package_name: string;
160
+ affected_version?: string;
161
+ }
162
+
163
+ export interface ParityResult {
164
+ tier: ParityTier;
165
+ git_head?: string;
166
+ repository_url?: string;
167
+ provenance_attested: boolean;
168
+ provenance_status?: ProvenanceStatus;
169
+ provenance_url?: string;
170
+ observations: Observation[];
171
+ unknowns: string[];
172
+ }
173
+
174
+ export interface PinnedExecutionInfo {
175
+ command: string | null;
176
+ exact_version?: string;
177
+ tarball_sha512?: string;
178
+ bin_name?: string;
179
+ caveat: string;
180
+ }
181
+
182
+ export interface ReaEscalationStep {
183
+ path: string;
184
+ signal: string;
185
+ recommended_tool: string;
186
+ rationale: string;
187
+ }
188
+
189
+ export interface ReaEscalationPlan {
190
+ required: boolean;
191
+ rea_available_on_host: boolean;
192
+ bootstrap_prohibition: string;
193
+ steps: ReaEscalationStep[];
194
+ }
195
+
196
+ export interface PackageInspectionReport {
197
+ schema_version: string;
198
+ generated_at_utc: string;
199
+ title: {
200
+ package_name: string;
201
+ version: string;
202
+ org_or_scope: string;
203
+ creator: string;
204
+ category_tags: string[];
205
+ commit_sha?: string;
206
+ };
207
+ info: {
208
+ summary: string;
209
+ license: string;
210
+ published_at?: string;
211
+ weekly_downloads?: number;
212
+ has_bin: boolean;
213
+ bin_names: string[];
214
+ lifecycle_scripts: string[];
215
+ direct_dependency_count: number;
216
+ parity_tier: ParityTier;
217
+ provenance_attested: boolean;
218
+ provenance_status: ProvenanceStatus;
219
+ provenance_url?: string;
220
+ };
221
+ verdict: TrustVerdict;
222
+ recommended_action: RecommendedAction;
223
+ pinned_execution: PinnedExecutionInfo;
224
+ advisories: AdvisoryRecord[];
225
+ evidence: EvidenceRecord[];
226
+ iocs: DefangedIoc[];
227
+ rea_escalation_plan?: ReaEscalationPlan;
228
+ local_workspace_compromised?: {
229
+ lockfile_path: string;
230
+ lockfile_kind?: "package-lock.json" | "pnpm-lock.yaml" | "yarn.lock";
231
+ matched_version: string;
232
+ containment_steps: string[];
233
+ };
234
+ host_capabilities: HostCapabilities;
235
+ }
236
+
237
+ export interface DiscoveryCandidate {
238
+ package_name: string;
239
+ version: string;
240
+ org_or_scope: string;
241
+ creator: string;
242
+ summary: string;
243
+ license: string;
244
+ keywords: string[];
245
+ published_at?: string;
246
+ weekly_downloads?: number;
247
+ squat_warnings: Observation[];
248
+ policy_blocked_reason?: string;
249
+ verdict_preview: TrustVerdict;
250
+ }
251
+
252
+ export interface DiscoveryCardList {
253
+ schema_version: string;
254
+ query: string;
255
+ filters: {
256
+ org?: string;
257
+ creator?: string;
258
+ category?: string;
259
+ };
260
+ registry_route: "private" | "public";
261
+ candidates: DiscoveryCandidate[];
262
+ blocked_candidates: Array<{ package_name: string; reason: string }>;
263
+ unknowns: string[];
264
+ }
265
+
266
+ export interface CommitAuditSummary {
267
+ commit_sha: string;
268
+ committed_at_utc: string;
269
+ subject: string;
270
+ verdict: TrustVerdict;
271
+ changed_blobs: number;
272
+ cache_hits: number;
273
+ observations_count: number;
274
+ }
275
+
276
+ export interface SafeAnchorDecision {
277
+ schema_version: string;
278
+ package_name: string;
279
+ compromised_latest: {
280
+ version?: string;
281
+ commit_sha?: string;
282
+ patient_zero_sha?: string;
283
+ reason: string;
284
+ };
285
+ recommended_action: RecommendedAction;
286
+ safe_anchor?: {
287
+ version?: string;
288
+ commit_sha?: string;
289
+ tarball_sha512?: string;
290
+ provenance_attested: boolean;
291
+ provenance_status?: ProvenanceStatus;
292
+ pinned_execution: PinnedExecutionInfo;
293
+ residual_advisories: AdvisoryRecord[];
294
+ };
295
+ alternatives: Array<{
296
+ package_name: string;
297
+ version: string;
298
+ org_or_scope: string;
299
+ verdict: TrustVerdict;
300
+ pinned_command: string | null;
301
+ reason: string;
302
+ }>;
303
+ inspected_commits: CommitAuditSummary[];
304
+ evidence: EvidenceRecord[];
305
+ unknowns: string[];
306
+ }
307
+
308
+ export interface ConfusionFinding {
309
+ package_name: string;
310
+ declared_range: string;
311
+ issue: "UNPINNED_PRIVATE_SCOPE" | "UNSCOPED_PRIVATE_PREFIX" | "CLAIMABLE_ON_PUBLIC_NPM" | "PUBLIC_SHADOW_EXISTS";
312
+ severity: Severity;
313
+ detail: string;
314
+ remediation: string;
315
+ }
316
+
317
+ export interface ConfusionReport {
318
+ schema_version: string;
319
+ manifest_path: string;
320
+ npmrc_paths: string[];
321
+ findings: ConfusionFinding[];
322
+ passed: boolean;
323
+ unknowns: string[];
324
+ }
325
+
326
+ export interface BatchDependencyFinding {
327
+ package_name: string;
328
+ declared_range: string;
329
+ route: "private" | "public" | "blocked_typo" | "blocked_unconfigured" | "blocked_secret";
330
+ status: "CLEAN_SCREENED" | "FLAGGED_SUSPICIOUS" | "MALICIOUS_OR_BLOCKED" | "UNVERIFIABLE_OFFLINE";
331
+ reasons: string[];
332
+ advisory_ids: string[];
333
+ }
334
+
335
+ export interface ManifestBatchReport {
336
+ schema_version: string;
337
+ manifest_path: string;
338
+ total_declared: number;
339
+ evaluated_count: number;
340
+ truncated_at_cap: boolean;
341
+ offline_mode: boolean;
342
+ summary_counts: {
343
+ clean_screened: number;
344
+ flagged_suspicious: number;
345
+ malicious_or_blocked: number;
346
+ unverifiable_offline: number;
347
+ };
348
+ flagged: BatchDependencyFinding[];
349
+ unknowns: string[];
350
+ }
351
+
352
+ export interface AuditEvent {
353
+ seq: number;
354
+ ts_utc: string;
355
+ request_id?: string;
356
+ invoker_surface?: "cli" | "mcp";
357
+ mcp_client_name?: string;
358
+ tool_name?: string;
359
+ actor_id_hash: string;
360
+ action: "discover" | "inspect" | "resolve-anchor" | "verify-confusion" | "audit-manifest-batch";
361
+ target: string;
362
+ version?: string;
363
+ commit_sha?: string;
364
+ tarball_sha512?: string;
365
+ verdict: string;
366
+ policy_sha256: string;
367
+ evidence_ids: string[];
368
+ override_ticket_id?: string;
369
+ prev_hash: string;
370
+ entry_hash: string;
371
+ }
372
+
373
+ export interface HostCapabilities {
374
+ node_version: string;
375
+ git_available: boolean;
376
+ git_partial_clone_supported: boolean;
377
+ rea_cli_available: boolean;
378
+ rea_cli_command?: string;
379
+ sqlite_available: boolean;
380
+ }