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.
- package/ACCESSIBILITY.md +17 -0
- package/CHANGELOG.md +89 -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 +35 -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,286 @@
|
|
|
1
|
+
import type { Readable, Writable } from "node:stream";
|
|
2
|
+
import { JSONRPC_ERRORS, type JsonRpcId, type JsonRpcRequest, type JsonRpcResponse } from "./types.ts";
|
|
3
|
+
|
|
4
|
+
export const MAX_STDIO_FRAME_BYTES = 1_048_576; // 1 MiB hard line limit
|
|
5
|
+
|
|
6
|
+
export interface StdioTransportOptions {
|
|
7
|
+
input?: Readable;
|
|
8
|
+
output?: Writable;
|
|
9
|
+
errorOutput?: Writable;
|
|
10
|
+
hijackProcessStdio?: boolean;
|
|
11
|
+
maxFrameBytes?: number;
|
|
12
|
+
onMessage: (rawMessage: unknown) => Promise<void> | void;
|
|
13
|
+
onParseError?: (message: string) => void;
|
|
14
|
+
onClose?: () => void;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Zero-dependency byte-buffered JSON-RPC 2.0 stdio transport:
|
|
19
|
+
* - Scans raw Buffer bytes for `0x0a` (`\n`) before UTF-8 decoding (multi-byte safe).
|
|
20
|
+
* - Trims trailing `0x0d` (`\r`) for Windows CRLF clients.
|
|
21
|
+
* - Caps frames at 1 MiB and recovers cleanly with `-32700` Parse Error without crashing.
|
|
22
|
+
* - Guards `process.stdout` and `console.*` so stray logs can never corrupt JSON-RPC framing.
|
|
23
|
+
* - Honors Writable stream backpressure (`write() === false` -> awaits `drain`).
|
|
24
|
+
*/
|
|
25
|
+
export class StdioJsonRpcTransport {
|
|
26
|
+
private readonly input: Readable;
|
|
27
|
+
private readonly output: Writable;
|
|
28
|
+
private readonly errorOutput: Writable;
|
|
29
|
+
private readonly maxFrameBytes: number;
|
|
30
|
+
private readonly rawWrite: (chunk: string) => boolean;
|
|
31
|
+
private readonly onMessage: (rawMessage: unknown) => Promise<void> | void;
|
|
32
|
+
private readonly onParseError?: (message: string) => void;
|
|
33
|
+
private readonly onClose?: () => void;
|
|
34
|
+
|
|
35
|
+
private buffer: Buffer = Buffer.alloc(0);
|
|
36
|
+
private discardingOversizedLine = false;
|
|
37
|
+
private writeChain: Promise<void> = Promise.resolve();
|
|
38
|
+
private closed = false;
|
|
39
|
+
private nextClientReqId = 1;
|
|
40
|
+
private readonly pendingClientRequests = new Map<
|
|
41
|
+
string,
|
|
42
|
+
{
|
|
43
|
+
resolve: (val: unknown) => void;
|
|
44
|
+
reject: (err: Error) => void;
|
|
45
|
+
timer: ReturnType<typeof setTimeout>;
|
|
46
|
+
}
|
|
47
|
+
>();
|
|
48
|
+
|
|
49
|
+
constructor(opts: StdioTransportOptions) {
|
|
50
|
+
this.input = opts.input ?? process.stdin;
|
|
51
|
+
this.output = opts.output ?? process.stdout;
|
|
52
|
+
this.errorOutput = opts.errorOutput ?? process.stderr;
|
|
53
|
+
this.maxFrameBytes = opts.maxFrameBytes ?? MAX_STDIO_FRAME_BYTES;
|
|
54
|
+
this.onMessage = opts.onMessage;
|
|
55
|
+
this.onParseError = opts.onParseError;
|
|
56
|
+
this.onClose = opts.onClose;
|
|
57
|
+
|
|
58
|
+
// Bind original write method BEFORE installing any stdout hijack guard
|
|
59
|
+
const boundOut = this.output.write.bind(this.output);
|
|
60
|
+
this.rawWrite = (chunk: string) => boundOut(chunk, "utf8");
|
|
61
|
+
|
|
62
|
+
if (opts.hijackProcessStdio && this.output === process.stdout) {
|
|
63
|
+
this.installStdoutHijackGuard();
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
private installStdoutHijackGuard(): void {
|
|
68
|
+
const errOut = this.errorOutput;
|
|
69
|
+
const redirectToStderr = (...args: unknown[]): void => {
|
|
70
|
+
const text = args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ");
|
|
71
|
+
errOut.write(`${text}\n`);
|
|
72
|
+
};
|
|
73
|
+
console.log = redirectToStderr;
|
|
74
|
+
console.info = redirectToStderr;
|
|
75
|
+
console.debug = redirectToStderr;
|
|
76
|
+
console.warn = redirectToStderr;
|
|
77
|
+
console.error = redirectToStderr;
|
|
78
|
+
|
|
79
|
+
// Redirect any accidental direct process.stdout.write() from third-party/stray paths to stderr
|
|
80
|
+
process.stdout.write = ((chunk: string | Uint8Array, ...rest: unknown[]): boolean => {
|
|
81
|
+
const cb = typeof rest[rest.length - 1] === "function" ? (rest[rest.length - 1] as () => void) : undefined;
|
|
82
|
+
const ok = errOut.write(chunk);
|
|
83
|
+
if (cb) cb();
|
|
84
|
+
return ok;
|
|
85
|
+
}) as typeof process.stdout.write;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
start(): void {
|
|
89
|
+
this.input.on("data", (chunk: Buffer | string) => {
|
|
90
|
+
const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf8");
|
|
91
|
+
this.handleChunk(buf);
|
|
92
|
+
});
|
|
93
|
+
this.input.on("end", () => {
|
|
94
|
+
this.flushTrailingAndClose();
|
|
95
|
+
});
|
|
96
|
+
this.input.on("close", () => {
|
|
97
|
+
this.flushTrailingAndClose();
|
|
98
|
+
});
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
private flushTrailingAndClose(): void {
|
|
102
|
+
if (this.closed) return;
|
|
103
|
+
if (!this.discardingOversizedLine && this.buffer.byteLength > 0) {
|
|
104
|
+
const lineBuf =
|
|
105
|
+
this.buffer[this.buffer.byteLength - 1] === 0x0d
|
|
106
|
+
? this.buffer.subarray(0, this.buffer.byteLength - 1)
|
|
107
|
+
: this.buffer;
|
|
108
|
+
this.buffer = Buffer.alloc(0);
|
|
109
|
+
if (lineBuf.byteLength > 0) {
|
|
110
|
+
this.dispatchLine(lineBuf);
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
this.closed = true;
|
|
114
|
+
for (const [id, pending] of this.pendingClientRequests) {
|
|
115
|
+
clearTimeout(pending.timer);
|
|
116
|
+
pending.reject(new Error("Transport closed"));
|
|
117
|
+
this.pendingClientRequests.delete(id);
|
|
118
|
+
}
|
|
119
|
+
if (this.onClose) this.onClose();
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
private handleChunk(chunk: Buffer): void {
|
|
123
|
+
if (this.closed || chunk.byteLength === 0) return;
|
|
124
|
+
|
|
125
|
+
let offset = 0;
|
|
126
|
+
while (offset < chunk.byteLength) {
|
|
127
|
+
if (this.discardingOversizedLine) {
|
|
128
|
+
const nlIdx = chunk.indexOf(0x0a, offset);
|
|
129
|
+
if (nlIdx === -1) {
|
|
130
|
+
return;
|
|
131
|
+
}
|
|
132
|
+
this.discardingOversizedLine = false;
|
|
133
|
+
offset = nlIdx + 1;
|
|
134
|
+
continue;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
const nlIdx = chunk.indexOf(0x0a, offset);
|
|
138
|
+
if (nlIdx === -1) {
|
|
139
|
+
const remaining = chunk.subarray(offset);
|
|
140
|
+
if (this.buffer.byteLength + remaining.byteLength > this.maxFrameBytes) {
|
|
141
|
+
this.buffer = Buffer.alloc(0);
|
|
142
|
+
this.discardingOversizedLine = true;
|
|
143
|
+
this.emitFrameParseError(`Message frame exceeded maximum size (${this.maxFrameBytes} bytes).`);
|
|
144
|
+
return;
|
|
145
|
+
}
|
|
146
|
+
this.buffer = this.buffer.byteLength === 0 ? Buffer.from(remaining) : Buffer.concat([this.buffer, remaining]);
|
|
147
|
+
return;
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
const piece = chunk.subarray(offset, nlIdx);
|
|
151
|
+
offset = nlIdx + 1;
|
|
152
|
+
|
|
153
|
+
if (this.buffer.byteLength + piece.byteLength > this.maxFrameBytes) {
|
|
154
|
+
this.buffer = Buffer.alloc(0);
|
|
155
|
+
this.emitFrameParseError(`Message frame exceeded maximum size (${this.maxFrameBytes} bytes).`);
|
|
156
|
+
continue;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
const fullLine = this.buffer.byteLength === 0 ? piece : Buffer.concat([this.buffer, piece]);
|
|
160
|
+
this.buffer = Buffer.alloc(0);
|
|
161
|
+
|
|
162
|
+
const trimmed =
|
|
163
|
+
fullLine.byteLength > 0 && fullLine[fullLine.byteLength - 1] === 0x0d
|
|
164
|
+
? fullLine.subarray(0, fullLine.byteLength - 1)
|
|
165
|
+
: fullLine;
|
|
166
|
+
if (trimmed.byteLength === 0) continue;
|
|
167
|
+
|
|
168
|
+
this.dispatchLine(trimmed);
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
private emitFrameParseError(message: string): void {
|
|
173
|
+
if (this.onParseError) this.onParseError(message);
|
|
174
|
+
void this.sendError(null, JSONRPC_ERRORS.PARSE_ERROR, message);
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
private dispatchLine(lineBuf: Buffer): void {
|
|
178
|
+
const lineStr = lineBuf.toString("utf8").trim();
|
|
179
|
+
if (!lineStr) return;
|
|
180
|
+
let parsed: unknown;
|
|
181
|
+
try {
|
|
182
|
+
parsed = JSON.parse(lineStr);
|
|
183
|
+
} catch {
|
|
184
|
+
this.emitFrameParseError("Malformed JSON-RPC message.");
|
|
185
|
+
return;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
// Intercept responses to server-initiated requests (such as `roots/list`)
|
|
189
|
+
if (
|
|
190
|
+
parsed !== null &&
|
|
191
|
+
typeof parsed === "object" &&
|
|
192
|
+
!Array.isArray(parsed) &&
|
|
193
|
+
!("method" in parsed) &&
|
|
194
|
+
"id" in parsed
|
|
195
|
+
) {
|
|
196
|
+
const resp = parsed as JsonRpcResponse;
|
|
197
|
+
const key = String(resp.id);
|
|
198
|
+
const pending = this.pendingClientRequests.get(key);
|
|
199
|
+
if (pending) {
|
|
200
|
+
clearTimeout(pending.timer);
|
|
201
|
+
this.pendingClientRequests.delete(key);
|
|
202
|
+
if (resp.error) {
|
|
203
|
+
pending.reject(new Error(resp.error.message || "Client request failed"));
|
|
204
|
+
} else {
|
|
205
|
+
pending.resolve(resp.result);
|
|
206
|
+
}
|
|
207
|
+
return;
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
Promise.resolve(this.onMessage(parsed)).catch((err) => {
|
|
212
|
+
this.writeStderrLog({
|
|
213
|
+
stage: "transport_dispatch_error",
|
|
214
|
+
error: err instanceof Error ? err.message : String(err),
|
|
215
|
+
});
|
|
216
|
+
});
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
send(payload: JsonRpcResponse | JsonRpcRequest): Promise<void> {
|
|
220
|
+
if (this.closed) return Promise.resolve();
|
|
221
|
+
const serialized = `${JSON.stringify(payload)}\n`;
|
|
222
|
+
this.writeChain = this.writeChain.then(
|
|
223
|
+
() =>
|
|
224
|
+
new Promise<void>((resolveWrite) => {
|
|
225
|
+
if (this.closed) {
|
|
226
|
+
resolveWrite();
|
|
227
|
+
return;
|
|
228
|
+
}
|
|
229
|
+
const ok = this.rawWrite(serialized);
|
|
230
|
+
if (ok) {
|
|
231
|
+
resolveWrite();
|
|
232
|
+
} else {
|
|
233
|
+
this.output.once("drain", () => resolveWrite());
|
|
234
|
+
}
|
|
235
|
+
}),
|
|
236
|
+
);
|
|
237
|
+
return this.writeChain;
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
sendResult(id: JsonRpcId, result: unknown): Promise<void> {
|
|
241
|
+
return this.send({ jsonrpc: "2.0", id, result });
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
sendError(id: JsonRpcId, code: number, message: string, data?: unknown): Promise<void> {
|
|
245
|
+
return this.send({
|
|
246
|
+
jsonrpc: "2.0",
|
|
247
|
+
id,
|
|
248
|
+
error: {
|
|
249
|
+
code,
|
|
250
|
+
message,
|
|
251
|
+
...(data !== undefined ? { data } : {}),
|
|
252
|
+
},
|
|
253
|
+
});
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
sendClientRequest(method: string, params?: Record<string, unknown>, timeoutMs = 3000): Promise<unknown> {
|
|
257
|
+
if (this.closed) return Promise.reject(new Error("Transport closed"));
|
|
258
|
+
const id = `coldpin_srv_${this.nextClientReqId++}`;
|
|
259
|
+
return new Promise<unknown>((resolveReq, rejectReq) => {
|
|
260
|
+
const timer = setTimeout(() => {
|
|
261
|
+
this.pendingClientRequests.delete(id);
|
|
262
|
+
rejectReq(new Error(`Client request '${method}' timed out after ${timeoutMs}ms`));
|
|
263
|
+
}, timeoutMs);
|
|
264
|
+
this.pendingClientRequests.set(id, { resolve: resolveReq, reject: rejectReq, timer });
|
|
265
|
+
void this.send({
|
|
266
|
+
jsonrpc: "2.0",
|
|
267
|
+
id,
|
|
268
|
+
method,
|
|
269
|
+
...(params ? { params } : {}),
|
|
270
|
+
});
|
|
271
|
+
});
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
writeStderrLog(event: Record<string, unknown>): void {
|
|
275
|
+
const line = `${JSON.stringify({
|
|
276
|
+
ts_utc: new Date().toISOString(),
|
|
277
|
+
stream: "operational",
|
|
278
|
+
...event,
|
|
279
|
+
})}\n`;
|
|
280
|
+
this.errorOutput.write(line);
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
async flush(): Promise<void> {
|
|
284
|
+
await this.writeChain;
|
|
285
|
+
}
|
|
286
|
+
}
|
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { ENGINE_VERSION } from "../types.ts";
|
|
3
|
+
import type {
|
|
4
|
+
McpPromptDefinition,
|
|
5
|
+
McpResourceDefinition,
|
|
6
|
+
McpResourceTemplateDefinition,
|
|
7
|
+
McpToolDefinition,
|
|
8
|
+
} from "./types.ts";
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Static, plain-English MCP tool catalog (`ADR-003`, `[MCP-07]`):
|
|
12
|
+
* - Zero dynamic description generation, zero hidden directives, zero execution tools.
|
|
13
|
+
* - Control-plane parameters (`policy_path`, writable `audit_log_path`, `override_ticket_id`)
|
|
14
|
+
* are permanently omitted from all tool schemas.
|
|
15
|
+
* - Total serialized `tools/list` footprint is kept strictly <= 1,800 estimated tokens (~7,200 chars).
|
|
16
|
+
*/
|
|
17
|
+
export const MCP_TOOLS: readonly McpToolDefinition[] = [
|
|
18
|
+
{
|
|
19
|
+
name: "discover_packages",
|
|
20
|
+
description:
|
|
21
|
+
"Search npm packages by query, org, creator, or category with slopsquat, cooldown, policy, and OSV preview verdicts.",
|
|
22
|
+
annotations: {
|
|
23
|
+
title: "Discover npm Packages",
|
|
24
|
+
readOnlyHint: true,
|
|
25
|
+
destructiveHint: false,
|
|
26
|
+
idempotentHint: true,
|
|
27
|
+
openWorldHint: true,
|
|
28
|
+
},
|
|
29
|
+
inputSchema: {
|
|
30
|
+
type: "object",
|
|
31
|
+
additionalProperties: false,
|
|
32
|
+
required: ["query"],
|
|
33
|
+
properties: {
|
|
34
|
+
query: { type: "string", minLength: 1, maxLength: 128, description: "Search query text." },
|
|
35
|
+
org: { type: "string", maxLength: 64, description: "Optional npm scope or org filter." },
|
|
36
|
+
creator: { type: "string", maxLength: 64, description: "Optional maintainer handle filter." },
|
|
37
|
+
category: { type: "string", maxLength: 64, description: "Optional keyword or capability filter." },
|
|
38
|
+
limit: { type: "integer", minimum: 1, maximum: 25, default: 10, description: "Max results (1-25)." },
|
|
39
|
+
detail: { type: "string", enum: ["summary", "full"], default: "summary", description: "Output detail level." },
|
|
40
|
+
},
|
|
41
|
+
},
|
|
42
|
+
},
|
|
43
|
+
{
|
|
44
|
+
name: "inspect_package_artifact",
|
|
45
|
+
description:
|
|
46
|
+
"Inspect an npm package or local .tgz cold in memory for taint, lifecycle hooks, Git parity, provenance, and OSV/KEV.",
|
|
47
|
+
annotations: {
|
|
48
|
+
title: "Inspect Package Artifact",
|
|
49
|
+
readOnlyHint: true,
|
|
50
|
+
destructiveHint: false,
|
|
51
|
+
idempotentHint: true,
|
|
52
|
+
openWorldHint: true,
|
|
53
|
+
},
|
|
54
|
+
inputSchema: {
|
|
55
|
+
type: "object",
|
|
56
|
+
additionalProperties: false,
|
|
57
|
+
properties: {
|
|
58
|
+
package_spec: { type: "string", minLength: 1, maxLength: 256, description: "npm spec <pkg>[@<ver>]; XOR tarball_path." },
|
|
59
|
+
tarball_path: { type: "string", minLength: 1, maxLength: 1024, description: "Root-confined local .tgz path; XOR package_spec." },
|
|
60
|
+
git_dir: { type: "string", minLength: 1, maxLength: 1024, description: "Optional root-confined local Git dir for parity." },
|
|
61
|
+
subdir: { type: "string", maxLength: 256, description: "Optional monorepo subdirectory inside Git repo." },
|
|
62
|
+
offline: { type: "boolean", default: false, description: "Tighten-only flag to disable outbound network." },
|
|
63
|
+
detail: { type: "string", enum: ["summary", "card", "full"], default: "summary", description: "Output detail level." },
|
|
64
|
+
format: { type: "string", enum: ["json", "card", "sarif", "sbom"], default: "json", description: "Output format." },
|
|
65
|
+
},
|
|
66
|
+
},
|
|
67
|
+
},
|
|
68
|
+
{
|
|
69
|
+
name: "resolve_safe_anchor",
|
|
70
|
+
description:
|
|
71
|
+
"Walk Git history to locate patient-zero compromise commit and recommend a clean pre-compromise release or alternative.",
|
|
72
|
+
annotations: {
|
|
73
|
+
title: "Resolve Safe Git Anchor",
|
|
74
|
+
readOnlyHint: true,
|
|
75
|
+
destructiveHint: false,
|
|
76
|
+
idempotentHint: true,
|
|
77
|
+
openWorldHint: true,
|
|
78
|
+
},
|
|
79
|
+
inputSchema: {
|
|
80
|
+
type: "object",
|
|
81
|
+
additionalProperties: false,
|
|
82
|
+
required: ["package_name"],
|
|
83
|
+
properties: {
|
|
84
|
+
package_name: { type: "string", minLength: 1, maxLength: 214, description: "Target npm package name." },
|
|
85
|
+
git_dir: { type: "string", minLength: 1, maxLength: 1024, description: "Root-confined local Git directory." },
|
|
86
|
+
repo_url: { type: "string", minLength: 1, maxLength: 256, description: "HTTPS remote Git URL (no query/userinfo)." },
|
|
87
|
+
subdir: { type: "string", maxLength: 256, description: "Optional monorepo subdirectory." },
|
|
88
|
+
window: { type: "integer", minimum: 1, maximum: 200, description: "Max commits to inspect (clamped to policy)." },
|
|
89
|
+
detail: { type: "string", enum: ["summary", "full"], default: "summary", description: "Output detail level." },
|
|
90
|
+
},
|
|
91
|
+
},
|
|
92
|
+
},
|
|
93
|
+
{
|
|
94
|
+
name: "verify_confusion",
|
|
95
|
+
description:
|
|
96
|
+
"Audit a root-confined package.json and .npmrc for unpinned private scopes or dependency confusion risks (T1195.001).",
|
|
97
|
+
annotations: {
|
|
98
|
+
title: "Verify Dependency Confusion",
|
|
99
|
+
readOnlyHint: true,
|
|
100
|
+
destructiveHint: false,
|
|
101
|
+
idempotentHint: true,
|
|
102
|
+
openWorldHint: false,
|
|
103
|
+
},
|
|
104
|
+
inputSchema: {
|
|
105
|
+
type: "object",
|
|
106
|
+
additionalProperties: false,
|
|
107
|
+
properties: {
|
|
108
|
+
manifest_path: { type: "string", minLength: 1, maxLength: 1024, description: "Optional root-confined package.json path." },
|
|
109
|
+
check_public: { type: "boolean", default: false, description: "Requires operator COLDPIN_ALLOW_PUBLIC_CONFUSION_PROBE=1." },
|
|
110
|
+
},
|
|
111
|
+
},
|
|
112
|
+
},
|
|
113
|
+
{
|
|
114
|
+
name: "audit_verify",
|
|
115
|
+
description:
|
|
116
|
+
"Read-only verification of a root-confined hash-chained Coldpin audit.jsonl log for sequence gaps or tampering.",
|
|
117
|
+
annotations: {
|
|
118
|
+
title: "Verify Audit Log Integrity",
|
|
119
|
+
readOnlyHint: true,
|
|
120
|
+
destructiveHint: false,
|
|
121
|
+
idempotentHint: true,
|
|
122
|
+
openWorldHint: false,
|
|
123
|
+
},
|
|
124
|
+
inputSchema: {
|
|
125
|
+
type: "object",
|
|
126
|
+
additionalProperties: false,
|
|
127
|
+
required: ["audit_log_path"],
|
|
128
|
+
properties: {
|
|
129
|
+
audit_log_path: { type: "string", minLength: 1, maxLength: 1024, description: "Root-confined audit.jsonl path (read-only)." },
|
|
130
|
+
},
|
|
131
|
+
},
|
|
132
|
+
},
|
|
133
|
+
{
|
|
134
|
+
name: "audit_manifest_batch",
|
|
135
|
+
description:
|
|
136
|
+
"Batch-screen up to 50 direct dependencies from a root-confined package.json for squats, policy, private scopes, and OSV/KEV.",
|
|
137
|
+
annotations: {
|
|
138
|
+
title: "Batch Audit Manifest Dependencies",
|
|
139
|
+
readOnlyHint: true,
|
|
140
|
+
destructiveHint: false,
|
|
141
|
+
idempotentHint: true,
|
|
142
|
+
openWorldHint: true,
|
|
143
|
+
},
|
|
144
|
+
inputSchema: {
|
|
145
|
+
type: "object",
|
|
146
|
+
additionalProperties: false,
|
|
147
|
+
properties: {
|
|
148
|
+
manifest_path: { type: "string", minLength: 1, maxLength: 1024, description: "Optional root-confined package.json path." },
|
|
149
|
+
include_dev: { type: "boolean", default: false, description: "Include devDependencies." },
|
|
150
|
+
max_deps: { type: "integer", minimum: 1, maximum: 50, default: 50, description: "Max direct dependencies (1-50)." },
|
|
151
|
+
offline: { type: "boolean", default: false, description: "Tighten-only offline flag." },
|
|
152
|
+
detail: { type: "string", enum: ["summary", "full"], default: "summary", description: "Output detail level." },
|
|
153
|
+
},
|
|
154
|
+
},
|
|
155
|
+
},
|
|
156
|
+
{
|
|
157
|
+
name: "get_artifact_report",
|
|
158
|
+
description:
|
|
159
|
+
"Page through a session-scoped Coldpin report section (observations, iocs, unknowns, commits, card, sarif, sbom) by report_id.",
|
|
160
|
+
annotations: {
|
|
161
|
+
title: "Get Paginated Artifact Report",
|
|
162
|
+
readOnlyHint: true,
|
|
163
|
+
destructiveHint: false,
|
|
164
|
+
idempotentHint: true,
|
|
165
|
+
openWorldHint: false,
|
|
166
|
+
},
|
|
167
|
+
inputSchema: {
|
|
168
|
+
type: "object",
|
|
169
|
+
additionalProperties: false,
|
|
170
|
+
required: ["report_id", "section"],
|
|
171
|
+
properties: {
|
|
172
|
+
report_id: { type: "string", minLength: 4, maxLength: 64, description: "Session report_id from a prior Coldpin tool call." },
|
|
173
|
+
section: {
|
|
174
|
+
type: "string",
|
|
175
|
+
enum: ["observations", "iocs", "unknowns", "commits", "card", "sarif", "sbom"],
|
|
176
|
+
description: "Report section to slice.",
|
|
177
|
+
},
|
|
178
|
+
offset: { type: "integer", minimum: 0, maximum: 10_000_000, default: 0, description: "Item index or UTF-8 byte offset." },
|
|
179
|
+
limit: { type: "integer", minimum: 1, maximum: 50, default: 20, description: "Max items for list sections (1-50)." },
|
|
180
|
+
},
|
|
181
|
+
},
|
|
182
|
+
},
|
|
183
|
+
];
|
|
184
|
+
|
|
185
|
+
export const MCP_RESOURCES: readonly McpResourceDefinition[] = [
|
|
186
|
+
{
|
|
187
|
+
uri: "coldpin://policy/active",
|
|
188
|
+
name: "Active Coldpin Policy",
|
|
189
|
+
description: "Sanitized active operator policy, SHA-256 hash, authorized root count, and host capabilities (zero secrets).",
|
|
190
|
+
mimeType: "application/json",
|
|
191
|
+
},
|
|
192
|
+
];
|
|
193
|
+
|
|
194
|
+
export const MCP_RESOURCE_TEMPLATES: readonly McpResourceTemplateDefinition[] = [
|
|
195
|
+
{
|
|
196
|
+
uriTemplate: "coldpin://reports/{report_id}",
|
|
197
|
+
name: "Coldpin Session Report Summary",
|
|
198
|
+
description: "Read-only summary of a session-scoped Coldpin report stored in ephemeral memory.",
|
|
199
|
+
mimeType: "application/json",
|
|
200
|
+
},
|
|
201
|
+
];
|
|
202
|
+
|
|
203
|
+
export const MCP_PROMPTS: readonly McpPromptDefinition[] = [
|
|
204
|
+
{
|
|
205
|
+
name: "vet_before_npx",
|
|
206
|
+
description: "Vet an npm package cold with Coldpin before approving any pinned npx command.",
|
|
207
|
+
arguments: [
|
|
208
|
+
{ name: "package_spec", description: "Target package specification (<pkg> or <pkg>@<ver>).", required: true },
|
|
209
|
+
{ name: "git_dir", description: "Optional local Git repository directory for parity verification.", required: false },
|
|
210
|
+
],
|
|
211
|
+
},
|
|
212
|
+
{
|
|
213
|
+
name: "investigate_compromised_org",
|
|
214
|
+
description: "Identify patient-zero compromise commit and safe rollback anchor or vetted alternative for an npm package.",
|
|
215
|
+
arguments: [
|
|
216
|
+
{ name: "package_name", description: "Target npm package name.", required: true },
|
|
217
|
+
{ name: "repo_url", description: "Optional HTTPS repository URL.", required: false },
|
|
218
|
+
],
|
|
219
|
+
},
|
|
220
|
+
];
|
|
221
|
+
|
|
222
|
+
export function canonicalJson(value: unknown): string {
|
|
223
|
+
if (value === null || typeof value !== "object") return JSON.stringify(value);
|
|
224
|
+
if (Array.isArray(value)) return `[${value.map((v) => canonicalJson(v)).join(",")}]`;
|
|
225
|
+
const obj = value as Record<string, unknown>;
|
|
226
|
+
const keys = Object.keys(obj).sort();
|
|
227
|
+
return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
export interface McpSchemaPin {
|
|
231
|
+
schema_version: "1";
|
|
232
|
+
engine_version: string;
|
|
233
|
+
tools_count: number;
|
|
234
|
+
resources_count: number;
|
|
235
|
+
resource_templates_count: number;
|
|
236
|
+
prompts_count: number;
|
|
237
|
+
tools_list_chars: number;
|
|
238
|
+
estimated_tokens: number;
|
|
239
|
+
tools_sha256: string;
|
|
240
|
+
resources_sha256: string;
|
|
241
|
+
prompts_sha256: string;
|
|
242
|
+
catalog_sha256: string;
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
export function computeMcpSchemaPin(): McpSchemaPin {
|
|
246
|
+
const toolsJson = canonicalJson(MCP_TOOLS);
|
|
247
|
+
const resourcesJson = canonicalJson({ resources: MCP_RESOURCES, resourceTemplates: MCP_RESOURCE_TEMPLATES });
|
|
248
|
+
const promptsJson = canonicalJson(MCP_PROMPTS);
|
|
249
|
+
const catalogJson = canonicalJson({
|
|
250
|
+
tools: MCP_TOOLS,
|
|
251
|
+
resources: MCP_RESOURCES,
|
|
252
|
+
resourceTemplates: MCP_RESOURCE_TEMPLATES,
|
|
253
|
+
prompts: MCP_PROMPTS,
|
|
254
|
+
});
|
|
255
|
+
const toolsListChars = JSON.stringify({ tools: MCP_TOOLS }).length;
|
|
256
|
+
return {
|
|
257
|
+
schema_version: "1",
|
|
258
|
+
engine_version: ENGINE_VERSION,
|
|
259
|
+
tools_count: MCP_TOOLS.length,
|
|
260
|
+
resources_count: MCP_RESOURCES.length,
|
|
261
|
+
resource_templates_count: MCP_RESOURCE_TEMPLATES.length,
|
|
262
|
+
prompts_count: MCP_PROMPTS.length,
|
|
263
|
+
tools_list_chars: toolsListChars,
|
|
264
|
+
estimated_tokens: Math.ceil(toolsListChars / 4),
|
|
265
|
+
tools_sha256: createHash("sha256").update(toolsJson).digest("hex"),
|
|
266
|
+
resources_sha256: createHash("sha256").update(resourcesJson).digest("hex"),
|
|
267
|
+
prompts_sha256: createHash("sha256").update(promptsJson).digest("hex"),
|
|
268
|
+
catalog_sha256: createHash("sha256").update(catalogJson).digest("hex"),
|
|
269
|
+
};
|
|
270
|
+
}
|
package/src/mcp/types.ts
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
export const SUPPORTED_PROTOCOL_VERSIONS = [
|
|
2
|
+
"2025-11-25",
|
|
3
|
+
"2025-06-18",
|
|
4
|
+
"2025-03-26",
|
|
5
|
+
] as const;
|
|
6
|
+
|
|
7
|
+
export type SupportedProtocolVersion = (typeof SUPPORTED_PROTOCOL_VERSIONS)[number];
|
|
8
|
+
|
|
9
|
+
export const JSONRPC_ERRORS = {
|
|
10
|
+
PARSE_ERROR: -32700,
|
|
11
|
+
INVALID_REQUEST: -32600,
|
|
12
|
+
METHOD_NOT_FOUND: -32601,
|
|
13
|
+
INVALID_PARAMS: -32602,
|
|
14
|
+
INTERNAL_ERROR: -32603,
|
|
15
|
+
SERVER_BUSY: -32001,
|
|
16
|
+
NOT_INITIALIZED: -32002,
|
|
17
|
+
} as const;
|
|
18
|
+
|
|
19
|
+
export type McpLifecycleState =
|
|
20
|
+
| "UNINITIALIZED"
|
|
21
|
+
| "INITIALIZING"
|
|
22
|
+
| "ROOTS_SYNCING"
|
|
23
|
+
| "ACTIVE"
|
|
24
|
+
| "SHUTTING_DOWN";
|
|
25
|
+
|
|
26
|
+
export type JsonRpcId = string | number | null;
|
|
27
|
+
|
|
28
|
+
export interface JsonRpcRequest {
|
|
29
|
+
jsonrpc: "2.0";
|
|
30
|
+
id?: JsonRpcId;
|
|
31
|
+
method: string;
|
|
32
|
+
params?: Record<string, unknown>;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export interface JsonRpcResponse {
|
|
36
|
+
jsonrpc: "2.0";
|
|
37
|
+
id: JsonRpcId;
|
|
38
|
+
result?: unknown;
|
|
39
|
+
error?: {
|
|
40
|
+
code: number;
|
|
41
|
+
message: string;
|
|
42
|
+
data?: unknown;
|
|
43
|
+
};
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
export interface McpToolAnnotations {
|
|
47
|
+
title?: string;
|
|
48
|
+
readOnlyHint: boolean;
|
|
49
|
+
destructiveHint: boolean;
|
|
50
|
+
idempotentHint: boolean;
|
|
51
|
+
openWorldHint: boolean;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
export interface McpToolDefinition {
|
|
55
|
+
name: string;
|
|
56
|
+
description: string;
|
|
57
|
+
annotations: McpToolAnnotations;
|
|
58
|
+
inputSchema: Record<string, unknown>;
|
|
59
|
+
outputSchema?: Record<string, unknown>;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export interface McpResourceDefinition {
|
|
63
|
+
uri: string;
|
|
64
|
+
name: string;
|
|
65
|
+
description: string;
|
|
66
|
+
mimeType: string;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export interface McpResourceTemplateDefinition {
|
|
70
|
+
uriTemplate: string;
|
|
71
|
+
name: string;
|
|
72
|
+
description: string;
|
|
73
|
+
mimeType: string;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
export interface McpPromptArgument {
|
|
77
|
+
name: string;
|
|
78
|
+
description: string;
|
|
79
|
+
required: boolean;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
export interface McpPromptDefinition {
|
|
83
|
+
name: string;
|
|
84
|
+
description: string;
|
|
85
|
+
arguments: McpPromptArgument[];
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
export interface McpToolCallResult {
|
|
89
|
+
content: Array<{ type: "text"; text: string }>;
|
|
90
|
+
structuredContent?: Record<string, unknown>;
|
|
91
|
+
isError: boolean;
|
|
92
|
+
}
|
package/src/mcp.ts
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
function checkNodeVersionFloor(): void {
|
|
4
|
+
const major = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
|
|
5
|
+
if (!Number.isFinite(major) || major < 24) {
|
|
6
|
+
process.stderr.write(
|
|
7
|
+
`Coldpin requires Node.js >= 24.0.0; detected ${process.version}. Upgrade to Node 24+ LTS.\n`,
|
|
8
|
+
);
|
|
9
|
+
process.exit(1);
|
|
10
|
+
}
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
checkNodeVersionFloor();
|
|
14
|
+
|
|
15
|
+
const { startMcpServerFromEnv } = await import("./mcp/server.ts");
|
|
16
|
+
process.exitCode = await startMcpServerFromEnv();
|