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,289 @@
|
|
|
1
|
+
import { closeSync, fstatSync, lstatSync, openSync, readSync, realpathSync, statSync } from "node:fs";
|
|
2
|
+
import { open } from "node:fs/promises";
|
|
3
|
+
import { homedir } from "node:os";
|
|
4
|
+
import { isAbsolute, parse as parsePath, resolve, sep } from "node:path";
|
|
5
|
+
|
|
6
|
+
export const MAX_AUTHORIZED_ROOTS = 10;
|
|
7
|
+
|
|
8
|
+
export function hasUnsafePathChars(rawPath ) {
|
|
9
|
+
if (!rawPath || rawPath.length > 4096) return true;
|
|
10
|
+
if (/[\x00-\x1f\x7f]/.test(rawPath)) return true;
|
|
11
|
+
// Reject NTFS Alternate Data Stream colons while preserving Windows drive prefixes (e.g. C:\)
|
|
12
|
+
const withoutDrive = /^[A-Za-z]:[\\/]/.test(rawPath) ? rawPath.slice(2) : rawPath;
|
|
13
|
+
if (withoutDrive.includes(":")) return true;
|
|
14
|
+
return false;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
export function isDangerousRootPath(rawPath ) {
|
|
18
|
+
const normalized = resolve(rawPath);
|
|
19
|
+
const parsed = parsePath(normalized);
|
|
20
|
+
if (normalized === parsed.root) return true;
|
|
21
|
+
// Also guard Windows UNC roots (\\server\share) and bare drive specs
|
|
22
|
+
if (/^[A-Za-z]:[\\/]?$/.test(normalized)) return true;
|
|
23
|
+
if (/^\\\\[^\\]+\\[^\\]+[\\/]?$/.test(normalized)) return true;
|
|
24
|
+
return false;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function normalizeForCompare(p ) {
|
|
28
|
+
const trimmed = p.endsWith(sep) && p.length > 1 ? p.slice(0, -1) : p;
|
|
29
|
+
return process.platform === "win32" ? trimmed.toLowerCase() : trimmed;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export function isPathWithinRoot(canonicalTarget , canonicalRoot ) {
|
|
33
|
+
const targetCmp = normalizeForCompare(canonicalTarget);
|
|
34
|
+
const rootCmp = normalizeForCompare(canonicalRoot);
|
|
35
|
+
return targetCmp === rootCmp || targetCmp.startsWith(`${rootCmp}${sep}`);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export function canonicalizeAuthorizedRoots(rawRoots ) {
|
|
39
|
+
const out = [];
|
|
40
|
+
const seen = new Set ();
|
|
41
|
+
for (const raw of rawRoots) {
|
|
42
|
+
if (out.length >= MAX_AUTHORIZED_ROOTS) break;
|
|
43
|
+
const trimmed = raw.trim();
|
|
44
|
+
if (!trimmed || hasUnsafePathChars(trimmed)) continue;
|
|
45
|
+
try {
|
|
46
|
+
const resolved = resolve(trimmed);
|
|
47
|
+
if (isDangerousRootPath(resolved)) continue;
|
|
48
|
+
const canonical = realpathSync(resolved);
|
|
49
|
+
if (isDangerousRootPath(canonical)) continue;
|
|
50
|
+
if (!statSync(canonical).isDirectory()) continue;
|
|
51
|
+
const key = normalizeForCompare(canonical);
|
|
52
|
+
if (!seen.has(key)) {
|
|
53
|
+
seen.add(key);
|
|
54
|
+
out.push(canonical);
|
|
55
|
+
}
|
|
56
|
+
} catch {
|
|
57
|
+
// Ignore nonexistent or inaccessible root entries
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
return out;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
export function intersectAuthorizedRoots(
|
|
64
|
+
clientRoots ,
|
|
65
|
+
operatorRoots ,
|
|
66
|
+
) {
|
|
67
|
+
const canonOp = canonicalizeAuthorizedRoots(operatorRoots);
|
|
68
|
+
const canonClient = canonicalizeAuthorizedRoots(clientRoots);
|
|
69
|
+
if (canonOp.length === 0) return canonClient;
|
|
70
|
+
if (canonClient.length === 0) return canonOp;
|
|
71
|
+
const out = [];
|
|
72
|
+
for (const c of canonClient) {
|
|
73
|
+
if (canonOp.some((op) => isPathWithinRoot(c, op))) {
|
|
74
|
+
out.push(c);
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
// If client roots are broader than operator roots, keep operator roots inside client roots
|
|
78
|
+
for (const op of canonOp) {
|
|
79
|
+
if (canonClient.some((c) => isPathWithinRoot(op, c)) && !out.includes(op)) {
|
|
80
|
+
out.push(op);
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
return out.slice(0, MAX_AUTHORIZED_ROOTS);
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
export function parseFileUriToPath(uri ) {
|
|
87
|
+
try {
|
|
88
|
+
const parsed = new URL(uri);
|
|
89
|
+
if (parsed.protocol !== "file:") return null;
|
|
90
|
+
let pathname = decodeURIComponent(parsed.pathname);
|
|
91
|
+
if (process.platform === "win32") {
|
|
92
|
+
if (/^\/[A-Za-z]:/.test(pathname)) pathname = pathname.slice(1);
|
|
93
|
+
pathname = pathname.replace(/\//g, "\\");
|
|
94
|
+
}
|
|
95
|
+
return pathname;
|
|
96
|
+
} catch {
|
|
97
|
+
return null;
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
export function resolveConfinedPath(
|
|
109
|
+
rawPath ,
|
|
110
|
+
authorizedRoots ,
|
|
111
|
+
opts = {},
|
|
112
|
+
) {
|
|
113
|
+
const label = opts.label ?? "path";
|
|
114
|
+
if (authorizedRoots.length === 0) {
|
|
115
|
+
return {
|
|
116
|
+
ok: false,
|
|
117
|
+
error: `Local ${label} access denied: no authorized workspace roots configured (set COLDPIN_ALLOWED_ROOTS or provide MCP client roots).`,
|
|
118
|
+
};
|
|
119
|
+
}
|
|
120
|
+
if (hasUnsafePathChars(rawPath)) {
|
|
121
|
+
return { ok: false, error: `Invalid ${label}: contains NUL, control characters, or disallowed NTFS ADS colon.` };
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
const candidate = isAbsolute(rawPath) ? resolve(rawPath) : resolve(authorizedRoots[0] , rawPath);
|
|
125
|
+
|
|
126
|
+
if (opts.rejectSymlink) {
|
|
127
|
+
try {
|
|
128
|
+
const lst = lstatSync(candidate);
|
|
129
|
+
if (lst.isSymbolicLink()) {
|
|
130
|
+
return { ok: false, error: `Rejected ${label}: symbolic link targets are not permitted.` };
|
|
131
|
+
}
|
|
132
|
+
} catch {
|
|
133
|
+
return { ok: false, error: `Path not found or unreadable for ${label}.` };
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
let canonical ;
|
|
138
|
+
try {
|
|
139
|
+
canonical = realpathSync(candidate);
|
|
140
|
+
} catch {
|
|
141
|
+
return { ok: false, error: `Path not found or unreadable for ${label}.` };
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
if (isDangerousRootPath(canonical)) {
|
|
145
|
+
return { ok: false, error: `Rejected ${label}: filesystem root paths are not permitted.` };
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
const allowed = authorizedRoots.some((root) => isPathWithinRoot(canonical, root));
|
|
149
|
+
if (!allowed) {
|
|
150
|
+
return { ok: false, error: `Access denied for ${label}: resolved path escapes authorized workspace roots.` };
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
try {
|
|
154
|
+
const st = lstatSync(canonical);
|
|
155
|
+
if (opts.rejectSymlink && st.isSymbolicLink()) {
|
|
156
|
+
return { ok: false, error: `Rejected ${label}: symbolic link targets are not permitted.` };
|
|
157
|
+
}
|
|
158
|
+
if (opts.requireRegularFile && !st.isFile()) {
|
|
159
|
+
return { ok: false, error: `Rejected ${label}: target is not a regular file.` };
|
|
160
|
+
}
|
|
161
|
+
if (opts.requireDirectory && !st.isDirectory()) {
|
|
162
|
+
return { ok: false, error: `Rejected ${label}: target is not a directory.` };
|
|
163
|
+
}
|
|
164
|
+
} catch {
|
|
165
|
+
return { ok: false, error: `Failed to stat ${label}.` };
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
return { ok: true, canonicalPath: canonical };
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* TOCTOU-free single-FD capped reader (async).
|
|
173
|
+
* Opens the target file descriptor once, verifies `isFile()` and `size <= maxBytes`,
|
|
174
|
+
* and reads at most `maxBytes + 1` bytes before failing closed.
|
|
175
|
+
*/
|
|
176
|
+
export async function openReadCappedFile(
|
|
177
|
+
filePath ,
|
|
178
|
+
maxBytes ,
|
|
179
|
+
rejectSymlink = false,
|
|
180
|
+
) {
|
|
181
|
+
if (hasUnsafePathChars(filePath)) {
|
|
182
|
+
throw new Error("Unsafe file path rejected.");
|
|
183
|
+
}
|
|
184
|
+
if (rejectSymlink) {
|
|
185
|
+
const lst = lstatSync(filePath);
|
|
186
|
+
if (lst.isSymbolicLink()) {
|
|
187
|
+
throw new Error("Symbolic link file rejected.");
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
const fh = await open(filePath, "r");
|
|
191
|
+
try {
|
|
192
|
+
const st = await fh.stat();
|
|
193
|
+
if (!st.isFile()) {
|
|
194
|
+
throw new Error("Target is not a regular file.");
|
|
195
|
+
}
|
|
196
|
+
if (st.size > maxBytes) {
|
|
197
|
+
throw new Error(`File size (${st.size} bytes) exceeds limit (${maxBytes} bytes).`);
|
|
198
|
+
}
|
|
199
|
+
const chunks = [];
|
|
200
|
+
let total = 0;
|
|
201
|
+
const chunkSize = Math.min(64 * 1024, Math.max(1024, maxBytes + 1));
|
|
202
|
+
while (true) {
|
|
203
|
+
const remaining = maxBytes + 1 - total;
|
|
204
|
+
if (remaining <= 0) {
|
|
205
|
+
throw new Error(`File stream exceeded limit (${maxBytes} bytes).`);
|
|
206
|
+
}
|
|
207
|
+
const buf = Buffer.allocUnsafe(Math.min(chunkSize, remaining));
|
|
208
|
+
const { bytesRead } = await fh.read(buf, 0, buf.length, null);
|
|
209
|
+
if (bytesRead === 0) break;
|
|
210
|
+
total += bytesRead;
|
|
211
|
+
if (total > maxBytes) {
|
|
212
|
+
throw new Error(`File stream exceeded limit (${maxBytes} bytes).`);
|
|
213
|
+
}
|
|
214
|
+
chunks.push(bytesRead === buf.length ? buf : buf.subarray(0, bytesRead));
|
|
215
|
+
}
|
|
216
|
+
return Buffer.concat(chunks, total);
|
|
217
|
+
} finally {
|
|
218
|
+
await fh.close();
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* TOCTOU-free single-FD capped reader (sync) for synchronous helpers such as
|
|
224
|
+
* lockfile inspection and CLI `audit-verify`.
|
|
225
|
+
*/
|
|
226
|
+
export function readCappedRegularFileSync(
|
|
227
|
+
filePath ,
|
|
228
|
+
maxBytes ,
|
|
229
|
+
rejectSymlink = false,
|
|
230
|
+
) {
|
|
231
|
+
if (hasUnsafePathChars(filePath)) {
|
|
232
|
+
throw new Error("Unsafe file path rejected.");
|
|
233
|
+
}
|
|
234
|
+
if (rejectSymlink) {
|
|
235
|
+
const lst = lstatSync(filePath);
|
|
236
|
+
if (lst.isSymbolicLink()) {
|
|
237
|
+
throw new Error("Symbolic link file rejected.");
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
const fd = openSync(filePath, "r");
|
|
241
|
+
try {
|
|
242
|
+
const st = fstatSync(fd);
|
|
243
|
+
if (!st.isFile()) {
|
|
244
|
+
throw new Error("Target is not a regular file.");
|
|
245
|
+
}
|
|
246
|
+
if (st.size > maxBytes) {
|
|
247
|
+
throw new Error(`File size (${st.size} bytes) exceeds limit (${maxBytes} bytes).`);
|
|
248
|
+
}
|
|
249
|
+
const chunks = [];
|
|
250
|
+
let total = 0;
|
|
251
|
+
const chunkSize = Math.min(64 * 1024, Math.max(1024, maxBytes + 1));
|
|
252
|
+
while (true) {
|
|
253
|
+
const remaining = maxBytes + 1 - total;
|
|
254
|
+
if (remaining <= 0) {
|
|
255
|
+
throw new Error(`File stream exceeded limit (${maxBytes} bytes).`);
|
|
256
|
+
}
|
|
257
|
+
const buf = Buffer.allocUnsafe(Math.min(chunkSize, remaining));
|
|
258
|
+
const bytesRead = readSync(fd, buf, 0, buf.length, null);
|
|
259
|
+
if (bytesRead === 0) break;
|
|
260
|
+
total += bytesRead;
|
|
261
|
+
if (total > maxBytes) {
|
|
262
|
+
throw new Error(`File stream exceeded limit (${maxBytes} bytes).`);
|
|
263
|
+
}
|
|
264
|
+
chunks.push(bytesRead === buf.length ? buf : buf.subarray(0, bytesRead));
|
|
265
|
+
}
|
|
266
|
+
return Buffer.concat(chunks, total);
|
|
267
|
+
} finally {
|
|
268
|
+
closeSync(fd);
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
export function redactHomePath(rawPath ) {
|
|
273
|
+
try {
|
|
274
|
+
const home = homedir();
|
|
275
|
+
if (!home) return rawPath;
|
|
276
|
+
const normHome = normalizeForCompare(home);
|
|
277
|
+
const normPath = normalizeForCompare(rawPath);
|
|
278
|
+
if (normPath === normHome) return "~";
|
|
279
|
+
if (normPath.startsWith(`${normHome}${sep}`)) {
|
|
280
|
+
return `~${rawPath.slice(home.length).replace(/\\/g, "/")}`;
|
|
281
|
+
}
|
|
282
|
+
} catch {
|
|
283
|
+
// Fall through
|
|
284
|
+
}
|
|
285
|
+
return rawPath;
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
//# sourceURL=core/path-confinement.ts
|