@aisac/cli 0.4.0-beta.2 → 0.4.0-beta.21

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 (47) hide show
  1. package/README.md +115 -10
  2. package/dist/assets/claude/hooks/context-compaction.ts +17 -5
  3. package/dist/assets/claude/hooks/native-host-contract-runtime.ts +1 -1
  4. package/dist/assets/claude/hooks/native-host-contract.test.ts +8 -4
  5. package/dist/assets/claude/hooks/provider-window.d.ts +83 -0
  6. package/dist/assets/codex-context-compaction.mjs +243 -5
  7. package/dist/assets/jev-paid-pilot-terminal.mjs +6 -0
  8. package/dist/claude-compatibility.mjs +26 -25
  9. package/dist/claude-observation.mjs +2 -1
  10. package/dist/cli.mjs +584 -35
  11. package/dist/codex-compatibility.mjs +48 -2
  12. package/dist/codex-engineering.mjs +165 -0
  13. package/dist/codex-hooks.mjs +411 -0
  14. package/dist/codex-permissions.mjs +67 -34
  15. package/dist/codex-protocol-fingerprint.json +11 -11
  16. package/dist/engineering-init.mjs +615 -0
  17. package/dist/engineering-pack.mjs +259 -23
  18. package/dist/engineering-scan-pins.json +42 -0
  19. package/dist/engineering-scan-report.mjs +1274 -0
  20. package/dist/engineering-scan-tools.mjs +1418 -0
  21. package/dist/engineering-scan.mjs +1265 -0
  22. package/dist/extensions-catalog.mjs +373 -0
  23. package/dist/extensions-cli.mjs +492 -0
  24. package/dist/extensions-preferences.mjs +151 -0
  25. package/dist/guardrails/continuity.mjs +239 -0
  26. package/dist/guardrails/format.mjs +111 -0
  27. package/dist/guardrails/guards.mjs +449 -0
  28. package/dist/guardrails/patch.mjs +33 -0
  29. package/dist/guardrails/run.mjs +286 -0
  30. package/dist/guardrails/shell-words.mjs +206 -0
  31. package/dist/guardrails-plugin.mjs +207 -0
  32. package/dist/launch.mjs +278 -34
  33. package/dist/managed-host.mjs +977 -0
  34. package/dist/mcp-servers.mjs +192 -0
  35. package/dist/mcp.mjs +10 -2
  36. package/dist/monitor.mjs +76 -1
  37. package/dist/package.json +1 -1
  38. package/dist/platform.mjs +78 -29
  39. package/dist/release-manifest-public-keys.json +10 -0
  40. package/dist/release-manifest.json +328 -0
  41. package/dist/release-manifest.mjs +817 -0
  42. package/dist/release-settings.mjs +210 -0
  43. package/dist/self-update.mjs +1036 -0
  44. package/dist/state.mjs +25 -1
  45. package/dist/token-guide.mjs +132 -0
  46. package/dist/update-actions.mjs +442 -0
  47. package/package.json +1 -1
@@ -0,0 +1,1418 @@
1
+ // @ts-check
2
+
3
+ /**
4
+ * `aisac scan` tool layer (spec aisac-engineering-scan D2, D3, D9, FR3, FR4;
5
+ * ADR-0055): the pinned scanners, how each one is found (an image by digest,
6
+ * else an allowlisted binary, else a recorded skip), the argv each one runs
7
+ * with, bounded reads of what it wrote, the Semgrep registry rulesets and the
8
+ * AISAC rules from the pack's `scan/` files.
9
+ *
10
+ * Nothing here builds a shell string: every process gets an argv array and
11
+ * goes through an injectable `spawn`, so the deterministic suite runs no
12
+ * scanner and no Docker. Tool output is data, read with size bounds and never
13
+ * executed; the AISAC rules are checked against a key allowlist before they
14
+ * reach Semgrep.
15
+ */
16
+
17
+ import { createHash, randomBytes } from 'node:crypto';
18
+ import { constants } from 'node:fs';
19
+ import { open, writeFile } from 'node:fs/promises';
20
+ import { join, posix } from 'node:path';
21
+ import { StringDecoder } from 'node:string_decoder';
22
+ import { SCAN_PREFIX, splitFrontMatter } from './engineering-pack.mjs';
23
+ import { isRecord, isTimeout, readBoundedText } from './engineering.mjs';
24
+ import { resolveNative } from './platform.mjs';
25
+
26
+ export const SCAN_KINDS = /** @type {const} */ (['secrets', 'sast', 'sca', 'iac', 'container']);
27
+ export const SCAN_TOOLS = /** @type {const} */ (['gitleaks', 'semgrep', 'osv-scanner', 'trivy']);
28
+
29
+ /** @typedef {(typeof SCAN_KINDS)[number]} ScanKind */
30
+ /** @typedef {(typeof SCAN_TOOLS)[number]} ScanTool */
31
+ /**
32
+ * @typedef {(command: string, args: readonly string[],
33
+ * options: import('node:child_process').SpawnOptions) => import('node:child_process').ChildProcess} SpawnFunction
34
+ */
35
+ /**
36
+ * @typedef {{
37
+ * kinds: ScanKind[],
38
+ * image: string,
39
+ * tag: string,
40
+ * digest: string,
41
+ * binary: string,
42
+ * versions: string[],
43
+ * user: string | null
44
+ * }} ToolPin
45
+ */
46
+ /** @typedef {{ schemaVersion: 1, capturedAt: string, tools: Record<ScanTool, ToolPin> }} ScanPins */
47
+ /**
48
+ * @typedef {{ mode: 'image', tool: ScanTool, pin: ToolPin, reference: string, version: string, docker: string }
49
+ * | { mode: 'binary', tool: ScanTool, pin: ToolPin, reference: string, version: string }} Runner
50
+ */
51
+
52
+ /** The kinds each pinned tool serves (spec D2); the pins file must say the same. */
53
+ /** @type {Readonly<Record<ScanTool, readonly ScanKind[]>>} */
54
+ export const TOOL_KINDS = Object.freeze({
55
+ gitleaks: ['secrets'],
56
+ semgrep: ['sast'],
57
+ 'osv-scanner': ['sca'],
58
+ trivy: ['iac', 'container'],
59
+ });
60
+ /** @type {Readonly<Record<ScanKind, ScanTool>>} */
61
+ export const TOOL_OF_KIND = Object.freeze({
62
+ secrets: 'gitleaks',
63
+ sast: 'semgrep',
64
+ sca: 'osv-scanner',
65
+ iac: 'trivy',
66
+ container: 'trivy',
67
+ });
68
+ /** The file each tool writes into the output directory; the client names it, not the tool. */
69
+ /** @type {Readonly<Record<ScanTool, string>>} */
70
+ export const OUTPUT_FILE = Object.freeze({
71
+ gitleaks: 'gitleaks.json',
72
+ semgrep: 'semgrep.json',
73
+ 'osv-scanner': 'osv-scanner.json',
74
+ trivy: 'trivy-misconfig.json',
75
+ });
76
+
77
+ /** The `--history` pass of gitleaks writes here, next to `gitleaks.json` (scan review F1). */
78
+ export const HISTORY_OUTPUT_FILE = 'gitleaks-history.json';
79
+
80
+ /**
81
+ * Scanner configs the client owns (scan review F2), written into the private
82
+ * rules directory and passed by flag, so a config file planted in the target
83
+ * cannot silence a scanner. gitleaks keeps its default rules; the others get
84
+ * empty files, which mean "no ignores, no overrides".
85
+ */
86
+ /** The gitleaks fields the report template copies; never Secret, Match, Line or the author's. */
87
+ export const GITLEAKS_REPORT_FIELDS = Object.freeze([
88
+ 'RuleID',
89
+ 'Description',
90
+ 'StartLine',
91
+ 'EndLine',
92
+ 'StartColumn',
93
+ 'EndColumn',
94
+ 'File',
95
+ 'SymlinkFile',
96
+ 'Commit',
97
+ 'Entropy',
98
+ 'Tags',
99
+ 'Fingerprint',
100
+ ]);
101
+ /** The report field holding the sha256 of the matched value (scan review F1). */
102
+ export const GITLEAKS_VALUE_DIGEST = 'ValueSha256';
103
+ /**
104
+ * The gitleaks report as a Go template (Sprig's `toJson` and `sha256sum`,
105
+ * verified on the pinned image): the same JSON array, with the matched value
106
+ * replaced by its sha256 before anything is written. A secret found in the
107
+ * tree and in history is then the same secret without the value ever on
108
+ * disk, which `--redact` could not give (it masks the value before the
109
+ * template sees it).
110
+ */
111
+ const GITLEAKS_REPORT_TEMPLATE = `[{{ range $i, $f := . }}{{ if $i }},{{ end }}{${GITLEAKS_REPORT_FIELDS.map(
112
+ (field) => `"${field}":{{ toJson $f.${field} }}`,
113
+ ).join(',')},"${GITLEAKS_VALUE_DIGEST}":{{ sha256sum $f.Secret | toJson }}}{{ end }}]\n`;
114
+ export const CLIENT_CONFIGS = Object.freeze({
115
+ gitleaks: { file: 'client-gitleaks.toml', content: '[extend]\nuseDefault = true\n' },
116
+ gitleaksIgnore: { file: 'client-gitleaksignore', content: '' },
117
+ gitleaksReport: { file: 'client-gitleaks-report.tmpl', content: GITLEAKS_REPORT_TEMPLATE },
118
+ osvScanner: { file: 'client-osv-scanner.toml', content: '' },
119
+ trivy: { file: 'client-trivy.yaml', content: '' },
120
+ trivyIgnore: { file: 'client-trivyignore', content: '' },
121
+ });
122
+ /** @typedef {Record<keyof typeof CLIENT_CONFIGS, string>} ClientConfigPaths */
123
+
124
+ /**
125
+ * Where each client-owned config is, under `directory` (the container's
126
+ * `/rules` with `posix.join`, or the host's rules directory with `join`).
127
+ * @param {string} directory
128
+ * @param {(...parts: string[]) => string} joinPath
129
+ * @returns {ClientConfigPaths}
130
+ */
131
+ export function clientConfigPaths(directory, joinPath) {
132
+ return {
133
+ gitleaks: joinPath(directory, CLIENT_CONFIGS.gitleaks.file),
134
+ gitleaksIgnore: joinPath(directory, CLIENT_CONFIGS.gitleaksIgnore.file),
135
+ gitleaksReport: joinPath(directory, CLIENT_CONFIGS.gitleaksReport.file),
136
+ osvScanner: joinPath(directory, CLIENT_CONFIGS.osvScanner.file),
137
+ trivy: joinPath(directory, CLIENT_CONFIGS.trivy.file),
138
+ trivyIgnore: joinPath(directory, CLIENT_CONFIGS.trivyIgnore.file),
139
+ };
140
+ }
141
+
142
+ export const PINS_FILE = 'engineering-scan-pins.json';
143
+ const PINS_SCHEMA_VERSION = 1;
144
+ const MAX_PINS_BYTES = 64 * 1024;
145
+ const PINS_KEYS = ['schemaVersion', 'capturedAt', 'tools'];
146
+ const PIN_KEYS = ['kinds', 'image', 'tag', 'digest', 'binary', 'versions', 'user'];
147
+ const IMAGE_NAME = /^[a-z0-9]+(?:[._-][a-z0-9]+)*(?:\/[a-z0-9]+(?:[._-][a-z0-9]+)*)*$/u;
148
+ const MAX_IMAGE_NAME_LENGTH = 255;
149
+ const IMAGE_TAG = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$/u;
150
+ const IMAGE_DIGEST = /^sha256:[0-9a-f]{64}$/u;
151
+ const BINARY_NAME = /^[a-z][a-z0-9-]{0,63}$/u;
152
+ const TOOL_VERSION = /^\d{1,4}\.\d{1,4}\.\d{1,6}$/u;
153
+ const MAX_PINNED_VERSIONS = 16;
154
+ const IMAGE_USER = /^[A-Za-z0-9_][A-Za-z0-9_.:-]{0,63}$/u;
155
+ const ISO_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/u;
156
+ /** The first `x.y.z` of a `--version` answer; `v` prefixes and suffixes like `-dev` are tolerated. */
157
+ const VERSION_TOKEN = /(?<![\w.])v?(\d{1,4}\.\d{1,4}\.\d{1,6})(?!\.?\d)/u;
158
+
159
+ export const MAX_TOOL_OUTPUT_BYTES = 16 * 1024 * 1024;
160
+ const MAX_PROCESS_OUTPUT_BYTES = 256 * 1024;
161
+ const DOCKER_PROBE_TIMEOUT_MS = 15_000;
162
+ const VERSION_PROBE_TIMEOUT_MS = 15_000;
163
+ const DOCKER_KILL_TIMEOUT_MS = 15_000;
164
+ const CONTAINER_NAME_BYTES = 6;
165
+ const PRIVATE_FILE_MODE = 0o600;
166
+
167
+ const CONTAINER_SOURCE = '/src';
168
+ const CONTAINER_OUT = '/out';
169
+ const CONTAINER_RULES = '/rules';
170
+ const CONTAINER_HOME = '/tmp';
171
+ /** Semgrep and Trivy stop without a writable temporary directory (fixture README). */
172
+ const CONTAINER_TMPFS = '/tmp:rw,noexec,nosuid,nodev,size=512m';
173
+ const CONTAINER_TRIVY_CACHE = '/tmp/trivy-cache';
174
+ /**
175
+ * gitleaks 8.30.1 always reads `<source>/.gitleaksignore`, whatever
176
+ * `--gitleaks-ignore-path` says (verified on the pinned image), so in an image
177
+ * an empty client file is mounted over it (scan review F2).
178
+ */
179
+ const CONTAINER_GITLEAKS_IGNORE = posix.join(CONTAINER_SOURCE, '.gitleaksignore');
180
+ const CANNOT_SCAN_EXIT_CODE = 3;
181
+ /**
182
+ * Only osv-scanner needs the network (OSV.dev, spec D9). Trivy's IaC checks
183
+ * run offline on the checks embedded in the pinned image (S2 note on D9).
184
+ */
185
+ const NETWORKED_TOOLS = new Set(['osv-scanner']);
186
+ /** What comes between the image reference and the tool's arguments (the image's entrypoint). */
187
+ /** @type {Readonly<Record<ScanTool, readonly string[]>>} */
188
+ const IMAGE_COMMAND = Object.freeze({
189
+ gitleaks: [],
190
+ semgrep: ['semgrep'],
191
+ 'osv-scanner': [],
192
+ trivy: [],
193
+ });
194
+ /** Exit codes that mean the tool ran; osv-scanner says 1 for findings and 128 for no package. */
195
+ /** @type {Readonly<Record<ScanTool, readonly number[]>>} */
196
+ const ACCEPTED_EXIT_CODES = Object.freeze({
197
+ gitleaks: [0],
198
+ semgrep: [0],
199
+ 'osv-scanner': [0, 1, 128],
200
+ trivy: [0],
201
+ });
202
+ /** Exit codes after which a missing output file means "nothing to report". */
203
+ /** @type {Readonly<Record<ScanTool, readonly number[]>>} */
204
+ const EMPTY_OUTPUT_EXIT_CODES = Object.freeze({
205
+ gitleaks: [],
206
+ semgrep: [],
207
+ 'osv-scanner': [128],
208
+ trivy: [],
209
+ });
210
+ const OSV_NO_PACKAGES_EXIT_CODE = 128;
211
+ /**
212
+ * The stderr line osv-scanner 2.7.1 prints when a lockfile fails to parse
213
+ * (`Error during extraction: ... could not extract: ...`); it still exits 0, 1
214
+ * or 128, so the line, not the exit code, says the result is partial (F6).
215
+ */
216
+ const OSV_EXTRACTION_ERROR = /Error during extraction|could not extract/u;
217
+ /** How much of an unfinished stderr line is kept while waiting for its end. */
218
+ const MAX_STDERR_LINE_CARRY = 64 * 1024;
219
+ /**
220
+ * The file names osv-scanner 2.7.1 extracts packages from (scan review F6). A
221
+ * tree holding one of them, where osv-scanner still found no package, failed
222
+ * to parse it.
223
+ */
224
+ export const OSV_LOCKFILE_NAMES = Object.freeze(
225
+ new Set([
226
+ 'package-lock.json',
227
+ 'npm-shrinkwrap.json',
228
+ 'yarn.lock',
229
+ 'pnpm-lock.yaml',
230
+ 'bun.lock',
231
+ 'requirements.txt',
232
+ 'poetry.lock',
233
+ 'Pipfile.lock',
234
+ 'pdm.lock',
235
+ 'uv.lock',
236
+ 'go.mod',
237
+ 'Cargo.lock',
238
+ 'Gemfile.lock',
239
+ 'composer.lock',
240
+ 'pom.xml',
241
+ 'build.gradle',
242
+ 'build.gradle.kts',
243
+ 'gradle.lockfile',
244
+ 'buildscript-gradle.lockfile',
245
+ 'verification-metadata.xml',
246
+ 'pubspec.lock',
247
+ 'mix.lock',
248
+ 'renv.lock',
249
+ 'conan.lock',
250
+ 'packages.lock.json',
251
+ 'packages.config',
252
+ 'deps.json',
253
+ 'Package.resolved',
254
+ 'Podfile.lock',
255
+ ]),
256
+ );
257
+ /**
258
+ * Files a repository can use to silence a scanner (scan review F2). The client
259
+ * passes its own config instead wherever the tool has a flag, and reports each
260
+ * one it finds as a warning either way.
261
+ */
262
+ export const SCANNER_CONFIG_NAMES = Object.freeze(
263
+ new Set([
264
+ '.gitleaks.toml',
265
+ '.gitleaksignore',
266
+ '.semgrepignore',
267
+ 'osv-scanner.toml',
268
+ 'trivy.yaml',
269
+ '.trivyignore',
270
+ '.trivyignore.yaml',
271
+ ]),
272
+ );
273
+ /**
274
+ * Trivy runs only from its image, offline (scan review F5): a host binary
275
+ * downloads the remote Terraform modules a target names (git and registry
276
+ * sources) with the host's network and credentials.
277
+ */
278
+ const CONTAINER_ONLY_TOOLS = new Set(['trivy']);
279
+ const DOCKER_ERROR_EXIT_CODE = 125;
280
+ /** Excluded from SAST (spec D4); gitleaks applies its own default allowlist. */
281
+ export const EXCLUDED_DIRECTORIES = Object.freeze([
282
+ '.git',
283
+ 'node_modules',
284
+ '.venv',
285
+ 'vendor',
286
+ '.security-reports',
287
+ ]);
288
+ const DOCKER_ENV_KEYS = [
289
+ 'PATH',
290
+ 'HOME',
291
+ 'DOCKER_HOST',
292
+ 'DOCKER_CONTEXT',
293
+ 'DOCKER_CONFIG',
294
+ 'DOCKER_CERT_PATH',
295
+ 'DOCKER_TLS_VERIFY',
296
+ 'XDG_RUNTIME_DIR',
297
+ ];
298
+ const BINARY_ENV_KEYS = ['PATH', 'LANG', 'LC_ALL', 'LC_CTYPE'];
299
+
300
+ const REGISTRY_BASE_URL = 'https://semgrep.dev/c/';
301
+ /** The public Semgrep packs of FR4, resolved before the scan step (S2 note on FR4/D9). */
302
+ export const REGISTRY_RULESETS = Object.freeze(['p/owasp-top-ten', 'p/secrets']);
303
+ const REGISTRY_TIMEOUT_MS = 60_000;
304
+ const RULESET_START = /^(?:#[^\n]*\n|[ \t]*\n)*rules:[ \t]*\n/u;
305
+ /**
306
+ * The JSON form semgrep.dev serves to a fetch client (whatever `Accept` says). JSON is
307
+ * YAML: Semgrep reads it as a config, so it is written as it came.
308
+ */
309
+ const RULESET_JSON_START = /^\s*\{\s*"rules"\s*:\s*\[/u;
310
+
311
+ const RULE_FILE_PATH = /^scan\/([A-Za-z0-9][A-Za-z0-9._-]{0,127})\.md$/u;
312
+ const RULE_FILE_KEYS = new Set(['name', 'description', 'aisac_watermark']);
313
+ const MAX_RULE_DESCRIPTION_LENGTH = 1024;
314
+ const WATERMARK_KEY = 'aisac_watermark';
315
+ const OPENING_FENCE = /^(`{3,})([^`]*)$/u;
316
+ const CLOSING_FENCE = /^(`{3,})[ \t]*$/u;
317
+ const YAML_INFO = new Set(['yaml', 'yml']);
318
+ /** The `rules[]` keys a pack rule may use (spec D3); `fix`, `paths`, `options` and anything else refuse the set. */
319
+ export const RULE_KEYS = Object.freeze(
320
+ new Set([
321
+ 'id',
322
+ 'message',
323
+ 'severity',
324
+ 'languages',
325
+ 'metadata',
326
+ 'pattern',
327
+ 'patterns',
328
+ 'pattern-either',
329
+ 'pattern-not',
330
+ 'pattern-inside',
331
+ 'pattern-not-inside',
332
+ 'pattern-regex',
333
+ 'pattern-not-regex',
334
+ 'metavariable-regex',
335
+ 'metavariable-pattern',
336
+ 'focus-metavariable',
337
+ ]),
338
+ );
339
+ const REQUIRED_RULE_KEYS = ['id', 'message', 'severity', 'languages'];
340
+ const TOP_PATTERN_KEYS = ['pattern', 'patterns', 'pattern-either', 'pattern-regex'];
341
+ const RULE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
342
+ const MAX_AISAC_RULES = 200;
343
+ const MAX_RULE_LINE_LENGTH = 4096;
344
+ const YAML_KEY = /^([a-z][a-z-]*):(?:[ ]+(.*))?$/u;
345
+ const YAML_ENTRY = /^- ([a-z][a-z-]*):(?:[ ]+(.*))?$/u;
346
+ const NESTED_KEY = /^(?:- )?([^\s:#'"][^:#]*?)[ ]*:(?:[ ]+(.*))?$/u;
347
+ const BLOCK_SCALAR = /^[|>][-+0-9]*[ ]*(?:#.*)?$/u;
348
+ const YAML_NODE_PROPERTY = /^[&*!]/u;
349
+ /** Tabs, carriage returns, other controls and the YAML 1.1 line breaks (NEL, LS, PS) could hide a key from a line-based check. */
350
+ const YAML_FORBIDDEN_CHARACTERS = /[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u2028\u2029\ufeff]/u;
351
+ const LEADING_SPACES = /^ */u;
352
+
353
+ /** @param {string} text */
354
+ export function sha256Hex(text) {
355
+ return createHash('sha256').update(text, 'utf8').digest('hex');
356
+ }
357
+
358
+ /** @param {unknown} error */
359
+ function errorCodeOf(error) {
360
+ return isRecord(error) && typeof error.code === 'string' ? error.code : 'unknown';
361
+ }
362
+
363
+ /** A bad pins file means the client cannot scan as asked: exit 3 (scan review F3). */
364
+ function pinsInvalid() {
365
+ const error = new Error('scan_pins_invalid');
366
+ Object.defineProperty(error, 'exitCode', { value: CANNOT_SCAN_EXIT_CODE });
367
+ return error;
368
+ }
369
+
370
+ /** @param {ScanTool} tool */
371
+ export function needsContainer(tool) {
372
+ return CONTAINER_ONLY_TOOLS.has(tool);
373
+ }
374
+
375
+ /**
376
+ * @param {unknown} value
377
+ * @param {readonly string[]} keys
378
+ * @returns {value is Record<string, unknown>}
379
+ */
380
+ function hasExactKeys(value, keys) {
381
+ return (
382
+ isRecord(value) &&
383
+ Object.keys(value).length === keys.length &&
384
+ keys.every((key) => Object.hasOwn(value, key))
385
+ );
386
+ }
387
+
388
+ /** @param {unknown} versions @returns {versions is string[]} */
389
+ function isVersionList(versions) {
390
+ return (
391
+ Array.isArray(versions) &&
392
+ versions.length > 0 &&
393
+ versions.length <= MAX_PINNED_VERSIONS &&
394
+ versions.every((version) => typeof version === 'string' && TOOL_VERSION.test(version)) &&
395
+ new Set(versions).size === versions.length
396
+ );
397
+ }
398
+
399
+ /**
400
+ * One tool's pin. `user` null means the image needs its own default user; a
401
+ * non-null value means it runs as any non-root user, so the client runs it as
402
+ * the invoking user (the private run directory stays writable).
403
+ * @param {unknown} value
404
+ * @param {ScanTool} tool
405
+ * @returns {ToolPin}
406
+ */
407
+ function validatePin(value, tool) {
408
+ if (!hasExactKeys(value, PIN_KEYS)) throw pinsInvalid();
409
+ const { kinds, image, tag, digest, binary, versions, user } = value;
410
+ const expected = TOOL_KINDS[tool];
411
+ if (
412
+ !Array.isArray(kinds) ||
413
+ kinds.length !== expected.length ||
414
+ !expected.every((kind, index) => kinds[index] === kind)
415
+ )
416
+ throw pinsInvalid();
417
+ if (typeof image !== 'string' || image.length > MAX_IMAGE_NAME_LENGTH || !IMAGE_NAME.test(image))
418
+ throw pinsInvalid();
419
+ if (typeof tag !== 'string' || !IMAGE_TAG.test(tag)) throw pinsInvalid();
420
+ if (typeof digest !== 'string' || !IMAGE_DIGEST.test(digest)) throw pinsInvalid();
421
+ if (typeof binary !== 'string' || !BINARY_NAME.test(binary)) throw pinsInvalid();
422
+ if (!isVersionList(versions)) throw pinsInvalid();
423
+ if (user !== null && (typeof user !== 'string' || !IMAGE_USER.test(user))) throw pinsInvalid();
424
+ return { kinds: [...expected], image, tag, digest, binary, versions: [...versions], user };
425
+ }
426
+
427
+ /**
428
+ * The pins file (S2 note on D2): every tool, its image digest and its
429
+ * binary version allowlist. A malformed file is a client bug.
430
+ * @param {unknown} value
431
+ * @returns {ScanPins}
432
+ */
433
+ export function validateScanPins(value) {
434
+ if (!hasExactKeys(value, PINS_KEYS)) throw pinsInvalid();
435
+ if (value.schemaVersion !== PINS_SCHEMA_VERSION) throw pinsInvalid();
436
+ if (typeof value.capturedAt !== 'string' || !ISO_INSTANT.test(value.capturedAt))
437
+ throw pinsInvalid();
438
+ if (!hasExactKeys(value.tools, SCAN_TOOLS)) throw pinsInvalid();
439
+ const tools = value.tools;
440
+ /** @type {Record<ScanTool, ToolPin>} */
441
+ const pins = /** @type {Record<ScanTool, ToolPin>} */ ({});
442
+ for (const tool of SCAN_TOOLS) pins[tool] = validatePin(tools[tool], tool);
443
+ return { schemaVersion: PINS_SCHEMA_VERSION, capturedAt: value.capturedAt, tools: pins };
444
+ }
445
+
446
+ /**
447
+ * Read a regular file without following a link and without blocking on a
448
+ * FIFO, refusing more than `limit` bytes.
449
+ * @param {string} path
450
+ * @param {number} limit
451
+ * @returns {Promise<{ ok: true, text: string } | { ok: false, reason: 'missing' | 'not_file' | 'too_large' }>}
452
+ */
453
+ export async function readBoundedFile(path, limit) {
454
+ let handle;
455
+ try {
456
+ handle = await open(
457
+ path,
458
+ constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0),
459
+ );
460
+ } catch (error) {
461
+ return { ok: false, reason: errorCodeOf(error) === 'ENOENT' ? 'missing' : 'not_file' };
462
+ }
463
+ try {
464
+ const info = await handle.stat();
465
+ if (!info.isFile()) return { ok: false, reason: 'not_file' };
466
+ if (info.size > limit) return { ok: false, reason: 'too_large' };
467
+ const buffer = await handle.readFile();
468
+ if (buffer.byteLength > limit) return { ok: false, reason: 'too_large' };
469
+ return { ok: true, text: buffer.toString('utf8') };
470
+ } finally {
471
+ await handle.close().catch(() => undefined);
472
+ }
473
+ }
474
+
475
+ /**
476
+ * The pins shipped next to this module (`packageRoot`, like the pack's public key).
477
+ * @param {string} packageRoot
478
+ * @returns {Promise<ScanPins>}
479
+ */
480
+ export async function loadScanPins(packageRoot) {
481
+ const read = await readBoundedFile(join(packageRoot, PINS_FILE), MAX_PINS_BYTES);
482
+ if (!read.ok) throw pinsInvalid();
483
+ let value;
484
+ try {
485
+ value = JSON.parse(read.text);
486
+ } catch {
487
+ throw pinsInvalid();
488
+ }
489
+ return validateScanPins(value);
490
+ }
491
+
492
+ /** @param {NodeJS.ProcessEnv} env @param {readonly string[]} keys @returns {NodeJS.ProcessEnv} */
493
+ function pickEnvironment(env, keys) {
494
+ /** @type {NodeJS.ProcessEnv} */
495
+ const picked = {};
496
+ for (const key of keys) {
497
+ const value = env[key];
498
+ if (typeof value === 'string') picked[key] = value;
499
+ }
500
+ return picked;
501
+ }
502
+
503
+ /** The docker CLI gets only what it needs to reach the daemon. @param {NodeJS.ProcessEnv} env */
504
+ export function dockerEnvironment(env) {
505
+ return pickEnvironment(env, DOCKER_ENV_KEYS);
506
+ }
507
+
508
+ /**
509
+ * A binary scanner gets the PATH, the locale and a private home, so it reads
510
+ * no user configuration and sends no metrics.
511
+ * @param {NodeJS.ProcessEnv} env
512
+ * @param {string} home
513
+ */
514
+ export function binaryEnvironment(env, home) {
515
+ return {
516
+ ...pickEnvironment(env, BINARY_ENV_KEYS),
517
+ HOME: home,
518
+ TMPDIR: home,
519
+ SEMGREP_SEND_METRICS: 'off',
520
+ SEMGREP_ENABLE_VERSION_CHECK: '0',
521
+ };
522
+ }
523
+
524
+ /** @param {NodeJS.ProcessEnv} env */
525
+ function probeEnvironment(env) {
526
+ return pickEnvironment(env, [...BINARY_ENV_KEYS, 'HOME']);
527
+ }
528
+
529
+ /** @param {AbortSignal | undefined} signal */
530
+ function isAborted(signal) {
531
+ return signal?.aborted === true;
532
+ }
533
+
534
+ /** @param {import('node:child_process').ChildProcess} child */
535
+ function killProcessTree(child) {
536
+ if (process.platform !== 'win32' && typeof child.pid === 'number') {
537
+ try {
538
+ process.kill(-child.pid, 'SIGKILL');
539
+ return;
540
+ } catch {
541
+ // The group is gone or was never created; kill the direct child.
542
+ }
543
+ }
544
+ child.kill('SIGKILL');
545
+ }
546
+
547
+ /**
548
+ * @typedef {{
549
+ * code: number | null,
550
+ * stdout: string,
551
+ * stderr: string,
552
+ * timedOut: boolean,
553
+ * interrupted: boolean,
554
+ * spawnFailed: boolean,
555
+ * stderrMatched: boolean
556
+ * }} ProcessResult
557
+ */
558
+ /**
559
+ * `stderrPattern` (not global) is tested on every stderr line as it streams,
560
+ * so a line past the capture bound still counts (`stderrMatched`).
561
+ * @typedef {{
562
+ * timeoutMs: number,
563
+ * env: NodeJS.ProcessEnv,
564
+ * cwd?: string,
565
+ * maxOutputBytes?: number,
566
+ * signal?: AbortSignal,
567
+ * onStop?: () => Promise<unknown>,
568
+ * stderrPattern?: RegExp
569
+ * }} ProcessOptions
570
+ */
571
+
572
+ /**
573
+ * A line watcher over a byte stream: `write` each chunk, then `end`.
574
+ * @param {RegExp | undefined} pattern
575
+ */
576
+ function lineWatcher(pattern) {
577
+ const decoder = new StringDecoder('utf8');
578
+ let carry = '';
579
+ let matched = false;
580
+ /** @param {string} text */
581
+ const feed = (text) => {
582
+ if (pattern === undefined || matched) return;
583
+ const lines = `${carry}${text}`.split('\n');
584
+ carry = (lines.pop() ?? '').slice(-MAX_STDERR_LINE_CARRY);
585
+ matched = lines.some((line) => pattern.test(line));
586
+ };
587
+ return {
588
+ /** @param {Buffer} chunk */
589
+ write: (chunk) => feed(decoder.write(chunk)),
590
+ end: () => {
591
+ feed(decoder.end());
592
+ if (pattern !== undefined && !matched) matched = pattern.test(carry);
593
+ return matched;
594
+ },
595
+ };
596
+ }
597
+
598
+ /**
599
+ * Run one process from an argv array, never through a shell. On timeout or
600
+ * abort, `onStop` runs first (a `docker kill`), then the whole process group
601
+ * is killed. Captured output is bounded and only used for probes.
602
+ * @param {SpawnFunction} spawnImpl
603
+ * @param {string} command
604
+ * @param {readonly string[]} args
605
+ * @param {ProcessOptions} options
606
+ * @returns {Promise<ProcessResult>}
607
+ */
608
+ export function runProcess(spawnImpl, command, args, options) {
609
+ const limit = options.maxOutputBytes ?? MAX_PROCESS_OUTPUT_BYTES;
610
+ return new Promise((resolvePromise) => {
611
+ /** @type {import('node:child_process').SpawnOptions} */
612
+ const spawnOptions = {
613
+ env: options.env,
614
+ stdio: ['ignore', 'pipe', 'pipe'],
615
+ shell: false,
616
+ windowsHide: true,
617
+ detached: process.platform !== 'win32',
618
+ };
619
+ if (options.cwd !== undefined) spawnOptions.cwd = options.cwd;
620
+ /** @type {ProcessResult} */
621
+ const result = {
622
+ code: null,
623
+ stdout: '',
624
+ stderr: '',
625
+ timedOut: false,
626
+ interrupted: false,
627
+ spawnFailed: false,
628
+ stderrMatched: false,
629
+ };
630
+ if (options.signal?.aborted === true) {
631
+ resolvePromise({ ...result, interrupted: true });
632
+ return;
633
+ }
634
+ let child;
635
+ try {
636
+ child = spawnImpl(command, args, spawnOptions);
637
+ } catch {
638
+ resolvePromise({ ...result, spawnFailed: true });
639
+ return;
640
+ }
641
+ const running = child;
642
+ let bytes = 0;
643
+ let settled = false;
644
+ let stopping = false;
645
+ const stop = () => {
646
+ if (stopping) return;
647
+ stopping = true;
648
+ Promise.resolve()
649
+ .then(() => options.onStop?.())
650
+ .catch(() => undefined)
651
+ .finally(() => killProcessTree(running));
652
+ };
653
+ const timer = setTimeout(() => {
654
+ result.timedOut = true;
655
+ stop();
656
+ }, options.timeoutMs);
657
+ const onAbort = () => {
658
+ result.interrupted = true;
659
+ stop();
660
+ };
661
+ options.signal?.addEventListener('abort', onAbort, { once: true });
662
+ // An abort that arrived while the child was being spawned.
663
+ if (isAborted(options.signal)) onAbort();
664
+ /** @param {'stdout' | 'stderr'} stream @param {Buffer} chunk */
665
+ const append = (stream, chunk) => {
666
+ bytes += chunk.byteLength;
667
+ if (bytes <= limit) result[stream] += chunk.toString('utf8');
668
+ };
669
+ const watcher = lineWatcher(options.stderrPattern);
670
+ running.stdout?.on('data', (chunk) => append('stdout', chunk));
671
+ running.stderr?.on('data', (chunk) => {
672
+ watcher.write(chunk);
673
+ append('stderr', chunk);
674
+ });
675
+ /** @param {number | null} code */
676
+ const finish = (code) => {
677
+ if (settled) return;
678
+ settled = true;
679
+ clearTimeout(timer);
680
+ options.signal?.removeEventListener('abort', onAbort);
681
+ resolvePromise({ ...result, code, stderrMatched: watcher.end() });
682
+ };
683
+ running.once('error', () => {
684
+ result.spawnFailed = true;
685
+ finish(null);
686
+ });
687
+ running.once('close', (code) => finish(typeof code === 'number' ? code : null));
688
+ });
689
+ }
690
+
691
+ /**
692
+ * The docker CLI when its daemon answers, else null (spec FR3 step 1).
693
+ * @param {SpawnFunction} spawnImpl
694
+ * @param {NodeJS.ProcessEnv} env
695
+ */
696
+ export async function probeDocker(spawnImpl, env) {
697
+ const docker = resolveNative('docker', env);
698
+ if (docker === null) return null;
699
+ const answer = await runProcess(
700
+ spawnImpl,
701
+ docker,
702
+ ['version', '--format', '{{.Server.Version}}'],
703
+ { timeoutMs: DOCKER_PROBE_TIMEOUT_MS, env: dockerEnvironment(env) },
704
+ );
705
+ return answer.code === 0 ? docker : null;
706
+ }
707
+
708
+ /** @param {ToolPin} pin */
709
+ export function imageReference(pin) {
710
+ return `${pin.image}@${pin.digest}`;
711
+ }
712
+
713
+ /**
714
+ * Whether the pinned image is already local, and optionally pull it. An
715
+ * abort stops the inspect or the pull at once (scan review F8).
716
+ * @param {{ spawn: SpawnFunction, env: NodeJS.ProcessEnv, docker: string, signal?: AbortSignal }} context
717
+ * @param {ToolPin} pin
718
+ * @param {{ pull: boolean, timeoutMs: number }} options
719
+ * @returns {Promise<'local' | 'pulled' | 'absent' | 'pull_failed' | 'interrupted'>}
720
+ */
721
+ export async function ensureImage(context, pin, options) {
722
+ const reference = imageReference(pin);
723
+ const env = dockerEnvironment(context.env);
724
+ /** @param {number} timeoutMs @returns {ProcessOptions} */
725
+ const processOptions = (timeoutMs) =>
726
+ context.signal === undefined ? { timeoutMs, env } : { timeoutMs, env, signal: context.signal };
727
+ const inspected = await runProcess(
728
+ context.spawn,
729
+ context.docker,
730
+ ['image', 'inspect', '--format', '{{.Id}}', reference],
731
+ processOptions(DOCKER_PROBE_TIMEOUT_MS),
732
+ );
733
+ if (inspected.interrupted) return 'interrupted';
734
+ if (inspected.code === 0) return 'local';
735
+ if (!options.pull) return 'absent';
736
+ const pulled = await runProcess(
737
+ context.spawn,
738
+ context.docker,
739
+ ['pull', '--quiet', reference],
740
+ processOptions(options.timeoutMs),
741
+ );
742
+ if (pulled.interrupted) return 'interrupted';
743
+ return pulled.code === 0 ? 'pulled' : 'pull_failed';
744
+ }
745
+
746
+ /**
747
+ * The tool's binary on PATH and whether its `--version` is allowlisted
748
+ * (spec FR3 step 2). PATH is read from the injected environment, never a shell.
749
+ * @param {SpawnFunction} spawnImpl
750
+ * @param {NodeJS.ProcessEnv} env
751
+ * @param {ToolPin} pin
752
+ * @returns {Promise<{ status: 'missing' } | { status: 'qualified' | 'unqualified', path: string, version: string | null }>}
753
+ */
754
+ export async function probeBinary(spawnImpl, env, pin) {
755
+ const path = resolveNative(pin.binary, env);
756
+ if (path === null) return { status: 'missing' };
757
+ const answer = await runProcess(spawnImpl, path, ['--version'], {
758
+ timeoutMs: VERSION_PROBE_TIMEOUT_MS,
759
+ env: probeEnvironment(env),
760
+ });
761
+ const version =
762
+ answer.code === 0
763
+ ? (VERSION_TOKEN.exec(`${answer.stdout}\n${answer.stderr}`)?.[1] ?? null)
764
+ : null;
765
+ return {
766
+ status: version !== null && pin.versions.includes(version) ? 'qualified' : 'unqualified',
767
+ path,
768
+ version,
769
+ };
770
+ }
771
+
772
+ /**
773
+ * @typedef {{
774
+ * source: string,
775
+ * output: string,
776
+ * configs: readonly string[],
777
+ * cache: string,
778
+ * history: boolean,
779
+ * clientConfigs: ClientConfigPaths
780
+ * }} ToolPaths
781
+ */
782
+
783
+ /**
784
+ * The scanner's own arguments, the same in both modes but for the paths.
785
+ * Semgrep's configs are names relative to its working directory (the rules
786
+ * directory), so its rule ids are reported as written. Every tool reads the
787
+ * client's config, never the target's (scan review F2; each flag verified on
788
+ * the pinned image): gitleaks `--config` and `--gitleaks-ignore-path`, Semgrep
789
+ * `--x-ignore-semgrepignore-files`, osv-scanner `--config` and Trivy
790
+ * `--config` and `--ignorefile`. osv-scanner never resolves transitive
791
+ * dependencies from a registry (`--no-resolve`, scan review F4). `history`
792
+ * selects gitleaks' `git` pass; nothing else changes (F1).
793
+ * @param {ScanTool} tool
794
+ * @param {ToolPaths} paths
795
+ * @returns {string[]}
796
+ */
797
+ export function toolArguments(tool, paths) {
798
+ switch (tool) {
799
+ case 'gitleaks':
800
+ return [
801
+ paths.history ? 'git' : 'dir',
802
+ paths.source,
803
+ '--no-banner',
804
+ '--no-color',
805
+ '--report-format',
806
+ 'template',
807
+ '--report-template',
808
+ paths.clientConfigs.gitleaksReport,
809
+ '--report-path',
810
+ paths.output,
811
+ '--exit-code',
812
+ '0',
813
+ '--config',
814
+ paths.clientConfigs.gitleaks,
815
+ '--gitleaks-ignore-path',
816
+ paths.clientConfigs.gitleaksIgnore,
817
+ ];
818
+ case 'semgrep':
819
+ return [
820
+ 'scan',
821
+ '--oss-only',
822
+ '--metrics=off',
823
+ '--disable-version-check',
824
+ '--x-ignore-semgrepignore-files',
825
+ '--json',
826
+ '--output',
827
+ paths.output,
828
+ ...paths.configs.flatMap((config) => ['--config', config]),
829
+ ...EXCLUDED_DIRECTORIES.flatMap((directory) => ['--exclude', directory]),
830
+ paths.source,
831
+ ];
832
+ case 'osv-scanner':
833
+ return [
834
+ 'scan',
835
+ 'source',
836
+ '--recursive',
837
+ '--no-resolve',
838
+ '--config',
839
+ paths.clientConfigs.osvScanner,
840
+ '--format',
841
+ 'json',
842
+ '--output-file',
843
+ paths.output,
844
+ paths.source,
845
+ ];
846
+ default:
847
+ return [
848
+ 'fs',
849
+ '--scanners',
850
+ 'misconfig',
851
+ '--skip-check-update',
852
+ '--skip-version-check',
853
+ '--disable-telemetry',
854
+ '--config',
855
+ paths.clientConfigs.trivy,
856
+ '--ignorefile',
857
+ paths.clientConfigs.trivyIgnore,
858
+ '--format',
859
+ 'json',
860
+ '--output',
861
+ paths.output,
862
+ '--cache-dir',
863
+ paths.cache,
864
+ paths.source,
865
+ ];
866
+ }
867
+ }
868
+
869
+ /**
870
+ * One `--mount` value, CSV-quoted when the path needs it (Docker parses
871
+ * `--mount` as CSV). Unlike `-v`, a missing source is an error, never a new
872
+ * root-owned directory.
873
+ * @param {string} source
874
+ * @param {string} target
875
+ * @param {boolean} readOnly
876
+ */
877
+ export function bindMount(source, target, readOnly) {
878
+ const field = `source=${source}`;
879
+ const quoted = /[",\r\n]/u.test(field) ? `"${field.replaceAll('"', '""')}"` : field;
880
+ return `type=bind,${quoted},target=${target}${readOnly ? ',readonly' : ''}`;
881
+ }
882
+
883
+ /** The invoking user, so a container writes its output as that user; null where unknown. */
884
+ export function hostUser() {
885
+ return typeof process.getuid === 'function' && typeof process.getgid === 'function'
886
+ ? `${process.getuid()}:${process.getgid()}`
887
+ : null;
888
+ }
889
+
890
+ /**
891
+ * The `docker run` argv for one tool (spec FR3 step 1): removed after the
892
+ * run, never pulled implicitly, no capabilities, no new privileges, a
893
+ * read-only root with a private `/tmp`, the source read-only, no network
894
+ * unless the tool needs it, and a non-root user when the image allows one.
895
+ * The private rules directory is the working directory, so a tool's default
896
+ * config lookup finds the client's files; `ignoreOverlay` masks the target's
897
+ * `.gitleaksignore` with an empty file (scan review F2).
898
+ * @param {{ tool: ScanTool, pin: ToolPin, name: string, source: string, out: string,
899
+ * rules: string | null, user: string | null, args: readonly string[],
900
+ * ignoreOverlay?: string }} input
901
+ */
902
+ export function dockerRunArguments(input) {
903
+ return [
904
+ 'run',
905
+ '--rm',
906
+ '--pull',
907
+ 'never',
908
+ '--name',
909
+ input.name,
910
+ '--cap-drop',
911
+ 'ALL',
912
+ '--security-opt',
913
+ 'no-new-privileges',
914
+ '--read-only',
915
+ '--tmpfs',
916
+ CONTAINER_TMPFS,
917
+ '--env',
918
+ `HOME=${CONTAINER_HOME}`,
919
+ ...(NETWORKED_TOOLS.has(input.tool) ? [] : ['--network', 'none']),
920
+ ...(input.pin.user === null || input.user === null ? [] : ['--user', input.user]),
921
+ '--mount',
922
+ bindMount(input.source, CONTAINER_SOURCE, true),
923
+ ...(input.ignoreOverlay === undefined
924
+ ? []
925
+ : ['--mount', bindMount(input.ignoreOverlay, CONTAINER_GITLEAKS_IGNORE, true)]),
926
+ '--mount',
927
+ bindMount(input.out, CONTAINER_OUT, false),
928
+ ...(input.rules === null
929
+ ? []
930
+ : ['--mount', bindMount(input.rules, CONTAINER_RULES, true), '--workdir', CONTAINER_RULES]),
931
+ imageReference(input.pin),
932
+ ...IMAGE_COMMAND[input.tool],
933
+ ...input.args,
934
+ ];
935
+ }
936
+
937
+ /** @param {ScanTool} tool */
938
+ export function usesNetwork(tool) {
939
+ return NETWORKED_TOOLS.has(tool);
940
+ }
941
+
942
+ /**
943
+ * @typedef {{
944
+ * status: 'ran' | 'failed' | 'timed_out' | 'interrupted',
945
+ * reason: string | null,
946
+ * exitCode: number | null,
947
+ * output: unknown
948
+ * }} ToolRun
949
+ */
950
+
951
+ /**
952
+ * Classify a finished process and read its output file. osv-scanner fails
953
+ * with `no_packages_parsed` when it printed an extraction error, or when it
954
+ * found no package in a tree that holds a lockfile (scan review F6).
955
+ * @param {ScanTool} tool
956
+ * @param {ProcessResult} result
957
+ * @param {'image' | 'binary'} mode
958
+ * @param {string} outputPath
959
+ * @param {boolean} lockfiles
960
+ * @returns {Promise<ToolRun>}
961
+ */
962
+ async function outcomeOf(tool, result, mode, outputPath, lockfiles) {
963
+ if (result.interrupted)
964
+ return { status: 'interrupted', reason: 'interrupted', exitCode: null, output: null };
965
+ if (result.timedOut) return { status: 'timed_out', reason: null, exitCode: null, output: null };
966
+ if (result.spawnFailed || result.code === null)
967
+ return { status: 'failed', reason: 'spawn_failed', exitCode: null, output: null };
968
+ const code = result.code;
969
+ if (!ACCEPTED_EXIT_CODES[tool].includes(code))
970
+ return {
971
+ status: 'failed',
972
+ reason: mode === 'image' && code === DOCKER_ERROR_EXIT_CODE ? 'docker_error' : `exit_${code}`,
973
+ exitCode: code,
974
+ output: null,
975
+ };
976
+ if (
977
+ tool === 'osv-scanner' &&
978
+ (result.stderrMatched || (code === OSV_NO_PACKAGES_EXIT_CODE && lockfiles))
979
+ )
980
+ return { status: 'failed', reason: 'no_packages_parsed', exitCode: code, output: null };
981
+ const read = await readBoundedFile(outputPath, MAX_TOOL_OUTPUT_BYTES);
982
+ if (!read.ok) {
983
+ if (read.reason === 'missing' && EMPTY_OUTPUT_EXIT_CODES[tool].includes(code))
984
+ return { status: 'ran', reason: null, exitCode: code, output: null };
985
+ return { status: 'failed', reason: `output_${read.reason}`, exitCode: code, output: null };
986
+ }
987
+ try {
988
+ return { status: 'ran', reason: null, exitCode: code, output: JSON.parse(read.text) };
989
+ } catch {
990
+ return { status: 'failed', reason: 'output_invalid', exitCode: code, output: null };
991
+ }
992
+ }
993
+
994
+ /**
995
+ * Run one tool with its resolved runner. The output lands in the private
996
+ * `outDir` (never in the project), and is returned parsed, not interpreted.
997
+ * Every tool runs in the private rules directory, which holds the client's
998
+ * scanner configs. `history` is gitleaks' second pass (scan review F1);
999
+ * `ignoreOverlay` says the target has a `.gitleaksignore` to mask; `lockfiles`
1000
+ * says the target may hold a lockfile osv-scanner reads.
1001
+ * @param {{ spawn: SpawnFunction, env: NodeJS.ProcessEnv, signal?: AbortSignal }} context
1002
+ * @param {{ runner: Runner, target: string, outDir: string, rulesDir: string,
1003
+ * configs: readonly string[], history: boolean, timeoutMs: number, home: string,
1004
+ * ignoreOverlay: boolean, lockfiles: boolean }} input
1005
+ * @returns {Promise<ToolRun>}
1006
+ */
1007
+ export async function executeTool(context, input) {
1008
+ const { runner } = input;
1009
+ const tool = runner.tool;
1010
+ const file = input.history ? HISTORY_OUTPUT_FILE : OUTPUT_FILE[tool];
1011
+ const outputPath = join(input.outDir, file);
1012
+ /** @type {ProcessOptions} */
1013
+ const options = { timeoutMs: input.timeoutMs, env: {} };
1014
+ if (context.signal !== undefined) options.signal = context.signal;
1015
+ if (tool === 'osv-scanner') options.stderrPattern = OSV_EXTRACTION_ERROR;
1016
+ let command;
1017
+ let args;
1018
+ if (runner.mode === 'image') {
1019
+ const docker = runner.docker;
1020
+ const name = `aisac-scan-${tool}-${randomBytes(CONTAINER_NAME_BYTES).toString('hex')}`;
1021
+ command = docker;
1022
+ args = dockerRunArguments({
1023
+ tool,
1024
+ pin: runner.pin,
1025
+ name,
1026
+ source: input.target,
1027
+ out: input.outDir,
1028
+ rules: input.rulesDir,
1029
+ user: hostUser(),
1030
+ ...(tool === 'gitleaks' && input.ignoreOverlay
1031
+ ? { ignoreOverlay: join(input.rulesDir, CLIENT_CONFIGS.gitleaksIgnore.file) }
1032
+ : {}),
1033
+ args: toolArguments(tool, {
1034
+ source: CONTAINER_SOURCE,
1035
+ output: posix.join(CONTAINER_OUT, file),
1036
+ configs: input.configs,
1037
+ cache: CONTAINER_TRIVY_CACHE,
1038
+ history: input.history,
1039
+ clientConfigs: clientConfigPaths(CONTAINER_RULES, posix.join),
1040
+ }),
1041
+ });
1042
+ options.env = dockerEnvironment(context.env);
1043
+ options.onStop = () =>
1044
+ runProcess(context.spawn, docker, ['kill', name], {
1045
+ timeoutMs: DOCKER_KILL_TIMEOUT_MS,
1046
+ env: dockerEnvironment(context.env),
1047
+ });
1048
+ } else {
1049
+ command = runner.reference;
1050
+ args = toolArguments(tool, {
1051
+ source: input.target,
1052
+ output: outputPath,
1053
+ configs: input.configs,
1054
+ cache: join(input.home, 'trivy-cache'),
1055
+ history: input.history,
1056
+ clientConfigs: clientConfigPaths(input.rulesDir, join),
1057
+ });
1058
+ options.env = binaryEnvironment(context.env, input.home);
1059
+ options.cwd = input.rulesDir;
1060
+ }
1061
+ const result = await runProcess(context.spawn, command, args, options);
1062
+ return outcomeOf(tool, result, runner.mode, outputPath, input.lockfiles);
1063
+ }
1064
+
1065
+ /** @param {string} name */
1066
+ export function registryRulesetUrl(name) {
1067
+ return `${REGISTRY_BASE_URL}${name}`;
1068
+ }
1069
+
1070
+ /**
1071
+ * One public Semgrep pack as YAML, fetched without the source tree in reach
1072
+ * (Semgrep step 1, S2 note on FR4/D9). Bounded, redirect-free, and recorded
1073
+ * by its sha256; it is passed to Semgrep untouched. The caller's `signal`
1074
+ * stops the request at once (`interrupted`, scan review F8).
1075
+ * @param {string} name
1076
+ * @param {typeof fetch} fetchImpl
1077
+ * @param {AbortSignal} [signal]
1078
+ * @returns {Promise<{ ok: true, text: string, sha256: string } | { ok: false, reason: string }>}
1079
+ */
1080
+ export async function fetchRegistryRuleset(name, fetchImpl, signal) {
1081
+ if (isAborted(signal)) return { ok: false, reason: 'interrupted' };
1082
+ const timeout = AbortSignal.timeout(REGISTRY_TIMEOUT_MS);
1083
+ let response;
1084
+ try {
1085
+ response = await fetchImpl(registryRulesetUrl(name), {
1086
+ method: 'GET',
1087
+ redirect: 'error',
1088
+ signal: signal === undefined ? timeout : AbortSignal.any([timeout, signal]),
1089
+ headers: { Accept: 'text/yaml, application/x-yaml;q=0.9' },
1090
+ });
1091
+ } catch (error) {
1092
+ if (isAborted(signal)) return { ok: false, reason: 'interrupted' };
1093
+ return { ok: false, reason: isTimeout(error) ? 'timeout' : 'unreachable' };
1094
+ }
1095
+ if (response.status !== 200) {
1096
+ await response.body?.cancel().catch(() => undefined);
1097
+ return { ok: false, reason: `http_${response.status}` };
1098
+ }
1099
+ let text;
1100
+ try {
1101
+ text = await readBoundedText(response, MAX_TOOL_OUTPUT_BYTES);
1102
+ } catch (error) {
1103
+ if (isAborted(signal)) return { ok: false, reason: 'interrupted' };
1104
+ if (isTimeout(error)) return { ok: false, reason: 'timeout' };
1105
+ return {
1106
+ ok: false,
1107
+ reason:
1108
+ error instanceof Error && error.message === 'body_too_large' ? 'too_large' : 'invalid',
1109
+ };
1110
+ }
1111
+ if (!isRulesetText(text)) return { ok: false, reason: 'invalid_ruleset' };
1112
+ return { ok: true, text, sha256: sha256Hex(text) };
1113
+ }
1114
+
1115
+ /**
1116
+ * A registry answer is a ruleset: YAML that opens with `rules:`, or a JSON object whose
1117
+ * `rules` is an array. Anything else (an error page, a JSON error) is `invalid_ruleset`.
1118
+ * @param {string} text
1119
+ */
1120
+ function isRulesetText(text) {
1121
+ if (RULESET_START.test(text)) return true;
1122
+ if (!RULESET_JSON_START.test(text)) return false;
1123
+ try {
1124
+ return Array.isArray(JSON.parse(text)?.rules);
1125
+ } catch {
1126
+ return false;
1127
+ }
1128
+ }
1129
+
1130
+ /** @param {string} path @param {string} content */
1131
+ export async function writePrivateFile(path, content) {
1132
+ await writeFile(path, content, { mode: PRIVATE_FILE_MODE, flag: 'wx' });
1133
+ }
1134
+
1135
+ /** The client-owned scanner configs, written once per run (scan review F2). @param {string} rulesDir */
1136
+ export async function writeClientConfigs(rulesDir) {
1137
+ for (const config of Object.values(CLIENT_CONFIGS))
1138
+ await writePrivateFile(join(rulesDir, config.file), config.content);
1139
+ }
1140
+
1141
+ /**
1142
+ * @typedef {{ name: string, source: 'registry', status: 'loaded', sha256: string, bytes: number }
1143
+ * | { name: string, source: 'registry', status: 'unavailable', reason: string }} RulesetRecord
1144
+ */
1145
+ /**
1146
+ * @typedef {{ status: 'none' }
1147
+ * | { status: 'loaded', count: number, files: { name: string, yaml: string }[] }
1148
+ * | { status: 'refused', reason: string }} AisacRules
1149
+ */
1150
+
1151
+ /**
1152
+ * Semgrep step 1: the registry packs and the accepted AISAC rules written as
1153
+ * YAML files into the private rules directory. Returns the config names (relative
1154
+ * to that directory) and what was resolved; no config at all means `no_rules`.
1155
+ * After an abort, the remaining packs are `unavailable` (`interrupted`) unfetched.
1156
+ * @param {{ rulesDir: string, fetchImpl: typeof fetch, aisacRules: AisacRules,
1157
+ * signal?: AbortSignal }} input
1158
+ * @returns {Promise<{ configs: string[], rulesets: RulesetRecord[] }>}
1159
+ */
1160
+ export async function prepareSemgrepRules(input) {
1161
+ /** @type {string[]} */
1162
+ const configs = [];
1163
+ /** @type {RulesetRecord[]} */
1164
+ const rulesets = [];
1165
+ for (const name of REGISTRY_RULESETS) {
1166
+ const fetched = await fetchRegistryRuleset(name, input.fetchImpl, input.signal);
1167
+ if (!fetched.ok) {
1168
+ rulesets.push({ name, source: 'registry', status: 'unavailable', reason: fetched.reason });
1169
+ continue;
1170
+ }
1171
+ const file = `registry-${name.replace(/^p\//u, '')}.yaml`;
1172
+ await writePrivateFile(join(input.rulesDir, file), fetched.text);
1173
+ configs.push(file);
1174
+ rulesets.push({
1175
+ name,
1176
+ source: 'registry',
1177
+ status: 'loaded',
1178
+ sha256: fetched.sha256,
1179
+ bytes: Buffer.byteLength(fetched.text, 'utf8'),
1180
+ });
1181
+ }
1182
+ if (input.aisacRules.status === 'loaded') {
1183
+ for (const rule of input.aisacRules.files) {
1184
+ const file = `aisac-${rule.name}.yaml`;
1185
+ await writePrivateFile(join(input.rulesDir, file), rule.yaml);
1186
+ configs.push(file);
1187
+ }
1188
+ }
1189
+ return { configs, rulesets };
1190
+ }
1191
+
1192
+ /**
1193
+ * The one fenced `yaml` block of a `scan/` file, as file content; null when
1194
+ * there is not exactly one, it is not YAML, or it carries the watermark.
1195
+ * Same grammar as the `init/` templates (ADR-0053).
1196
+ * @param {string} markdown
1197
+ * @returns {string | null}
1198
+ */
1199
+ export function fencedYaml(markdown) {
1200
+ /** @type {number | null} */
1201
+ let fence = null;
1202
+ /** @type {string[] | null} */
1203
+ let content = null;
1204
+ let closed = false;
1205
+ for (const line of markdown.split('\n')) {
1206
+ if (fence === null) {
1207
+ const opening = OPENING_FENCE.exec(line);
1208
+ if (opening === null) continue;
1209
+ if (closed || !YAML_INFO.has((opening[2] ?? '').trim().toLowerCase())) return null;
1210
+ fence = opening[1]?.length ?? 0;
1211
+ content = [];
1212
+ continue;
1213
+ }
1214
+ const closing = CLOSING_FENCE.exec(line);
1215
+ if (closing !== null && (closing[1]?.length ?? 0) >= fence) {
1216
+ fence = null;
1217
+ closed = true;
1218
+ continue;
1219
+ }
1220
+ content?.push(line);
1221
+ }
1222
+ if (fence !== null || !closed || content === null || content.length === 0) return null;
1223
+ if (content.some((line) => line.includes(WATERMARK_KEY))) return null;
1224
+ return `${content.join('\n')}\n`;
1225
+ }
1226
+
1227
+ /** @param {string} value */
1228
+ function plainScalar(value) {
1229
+ const trimmed = value.trim();
1230
+ if (
1231
+ trimmed.length >= 2 &&
1232
+ (trimmed[0] === '"' || trimmed[0] === "'") &&
1233
+ trimmed.at(-1) === trimmed[0]
1234
+ )
1235
+ return trimmed.slice(1, -1);
1236
+ return trimmed;
1237
+ }
1238
+
1239
+ /** Only ASCII spaces indent YAML. @param {string} line */
1240
+ function indentOf(line) {
1241
+ return LEADING_SPACES.exec(line)?.[0].length ?? 0;
1242
+ }
1243
+
1244
+ /** @param {string | undefined} value */
1245
+ function isNodeProperty(value) {
1246
+ return value !== undefined && YAML_NODE_PROPERTY.test(value.trim());
1247
+ }
1248
+
1249
+ /** A key with nothing after its colon opens a nested node. @param {string | undefined} value */
1250
+ function isOpenValue(value) {
1251
+ return value === undefined || value.trim() === '';
1252
+ }
1253
+
1254
+ /** @param {string | undefined} value */
1255
+ function opensBlockScalar(value) {
1256
+ return value !== undefined && BLOCK_SCALAR.test(value.trim());
1257
+ }
1258
+
1259
+ /**
1260
+ * @typedef {{ ok: true, ids: string[] } | { ok: false, reason: string }} RuleCheck
1261
+ */
1262
+
1263
+ /**
1264
+ * Check one rule key line of an entry and record the key.
1265
+ * @param {Map<string, string>} entry
1266
+ * @param {string} key
1267
+ * @param {string | undefined} value
1268
+ * @returns {string | null} the refusal reason, or null
1269
+ */
1270
+ function addRuleKey(entry, key, value) {
1271
+ if (!RULE_KEYS.has(key)) return `rule_key:${key}`;
1272
+ if (entry.has(key)) return 'yaml_grammar';
1273
+ if (isNodeProperty(value)) return 'yaml_grammar';
1274
+ entry.set(key, value ?? '');
1275
+ return null;
1276
+ }
1277
+
1278
+ /** @param {Map<string, string>} entry @returns {string | null} */
1279
+ function checkEntry(entry) {
1280
+ if (!REQUIRED_RULE_KEYS.every((key) => entry.has(key))) return 'rule_incomplete';
1281
+ if (!TOP_PATTERN_KEYS.some((key) => entry.has(key))) return 'rule_incomplete';
1282
+ if (!RULE_ID.test(plainScalar(entry.get('id') ?? ''))) return 'rule_id';
1283
+ return null;
1284
+ }
1285
+
1286
+ /**
1287
+ * Validate a Semgrep rule file without a YAML parser (spec D3, S2 note): a
1288
+ * strict, line-based grammar for the flat `rules:` shape. The only top-level
1289
+ * key is `rules`; each entry is a block mapping whose keys are in the
1290
+ * allowlist; anchors, aliases, tags, merge keys, complex keys, flow entries,
1291
+ * tabs and documents markers are refused. Nested values and block scalars
1292
+ * are passed through to Semgrep untouched.
1293
+ * @param {string} text
1294
+ * @returns {RuleCheck}
1295
+ */
1296
+ export function validateRuleYaml(text) {
1297
+ if (YAML_FORBIDDEN_CHARACTERS.test(text)) return { ok: false, reason: 'yaml_grammar' };
1298
+ /** @type {Map<string, string>[]} */
1299
+ const entries = [];
1300
+ let seenRules = false;
1301
+ /** @type {number | null} */
1302
+ let entryIndent = null;
1303
+ /** @type {number | null} */
1304
+ let blockParent = null;
1305
+ // Whether the last rule key has no inline value, so a `- ` item at its column is its sequence.
1306
+ let lastKeyOpen = false;
1307
+ for (const line of text.split('\n')) {
1308
+ if (line.length > MAX_RULE_LINE_LENGTH) return { ok: false, reason: 'yaml_grammar' };
1309
+ if (line.trim() === '') continue;
1310
+ const indent = indentOf(line);
1311
+ if (blockParent !== null && indent > blockParent) continue;
1312
+ blockParent = null;
1313
+ const trimmed = line.slice(indent);
1314
+ if (/^\s/u.test(trimmed)) return { ok: false, reason: 'yaml_grammar' };
1315
+ if (trimmed.startsWith('#')) continue;
1316
+ if (!seenRules) {
1317
+ if (line !== 'rules:') return { ok: false, reason: 'top_level_key' };
1318
+ seenRules = true;
1319
+ continue;
1320
+ }
1321
+ const isEntry = trimmed === '-' || trimmed.startsWith('- ');
1322
+ if (isEntry && (entryIndent === null || indent === entryIndent)) {
1323
+ const match = YAML_ENTRY.exec(trimmed);
1324
+ if (match === null) return { ok: false, reason: 'yaml_grammar' };
1325
+ entryIndent = indent;
1326
+ /** @type {Map<string, string>} */
1327
+ const entry = new Map();
1328
+ entries.push(entry);
1329
+ const refusal = addRuleKey(entry, match[1] ?? '', match[2]);
1330
+ if (refusal !== null) return { ok: false, reason: refusal };
1331
+ lastKeyOpen = isOpenValue(match[2]);
1332
+ // A block scalar ends at its key's column, which is two past the dash.
1333
+ if (opensBlockScalar(match[2])) blockParent = indent + 2;
1334
+ continue;
1335
+ }
1336
+ if (indent === 0 || entryIndent === null) return { ok: false, reason: 'top_level_key' };
1337
+ const entry = entries.at(-1);
1338
+ if (entry === undefined || indent < entryIndent + 2)
1339
+ return { ok: false, reason: 'yaml_grammar' };
1340
+ if (indent === entryIndent + 2 && !isEntry) {
1341
+ const match = YAML_KEY.exec(trimmed);
1342
+ if (match === null) return { ok: false, reason: 'yaml_grammar' };
1343
+ const refusal = addRuleKey(entry, match[1] ?? '', match[2]);
1344
+ if (refusal !== null) return { ok: false, reason: refusal };
1345
+ lastKeyOpen = isOpenValue(match[2]);
1346
+ if (opensBlockScalar(match[2])) blockParent = indent;
1347
+ continue;
1348
+ }
1349
+ if (indent === entryIndent + 2 && !lastKeyOpen) return { ok: false, reason: 'yaml_grammar' };
1350
+ if (trimmed.startsWith('? ') || trimmed === '?') return { ok: false, reason: 'yaml_grammar' };
1351
+ const nested = NESTED_KEY.exec(trimmed);
1352
+ const nestedKey = nested?.[1];
1353
+ const value = nested !== null ? nested[2] : isEntry ? trimmed.slice(2) : undefined;
1354
+ if (
1355
+ (nestedKey !== undefined && (nestedKey.trim() === '<<' || isNodeProperty(nestedKey))) ||
1356
+ isNodeProperty(value)
1357
+ )
1358
+ return { ok: false, reason: 'yaml_grammar' };
1359
+ if (opensBlockScalar(value)) blockParent = isEntry && nested !== null ? indent + 2 : indent;
1360
+ }
1361
+ if (!seenRules || entries.length === 0) return { ok: false, reason: 'rule_incomplete' };
1362
+ for (const entry of entries) {
1363
+ const refusal = checkEntry(entry);
1364
+ if (refusal !== null) return { ok: false, reason: refusal };
1365
+ }
1366
+ return { ok: true, ids: entries.map((entry) => plainScalar(entry.get('id') ?? '')) };
1367
+ }
1368
+
1369
+ /** @param {string} reason @param {string} path @returns {AisacRules} */
1370
+ function refusedRules(reason, path) {
1371
+ return { status: 'refused', reason: `${reason}:${path}` };
1372
+ }
1373
+
1374
+ /** @param {{ path: string }} left @param {{ path: string }} right */
1375
+ function byPath(left, right) {
1376
+ return left.path < right.path ? -1 : left.path > right.path ? 1 : 0;
1377
+ }
1378
+
1379
+ /**
1380
+ * The AISAC rules of a verified pack (spec D3): every `scan/<name>.md` with
1381
+ * front matter and one fenced `yaml` block whose rules pass the allowlist.
1382
+ * The first invalid file refuses the whole set; the registry packs still run.
1383
+ * @param {readonly { path: string, content: string }[]} files
1384
+ * @returns {AisacRules}
1385
+ */
1386
+ export function loadAisacRules(files) {
1387
+ const ruleFiles = files.filter((file) => file.path.startsWith(SCAN_PREFIX)).sort(byPath);
1388
+ if (ruleFiles.length === 0) return { status: 'none' };
1389
+ /** @type {{ name: string, yaml: string }[]} */
1390
+ const accepted = [];
1391
+ const ids = new Set();
1392
+ for (const file of ruleFiles) {
1393
+ const stem = RULE_FILE_PATH.exec(file.path)?.[1];
1394
+ if (stem === undefined) return refusedRules('path', file.path);
1395
+ const parsed = splitFrontMatter(file.content);
1396
+ if (parsed === null) return refusedRules('front_matter', file.path);
1397
+ const description = parsed.values.get('description');
1398
+ if (
1399
+ [...parsed.values.keys()].some((key) => !RULE_FILE_KEYS.has(key)) ||
1400
+ parsed.values.get('name') !== stem ||
1401
+ description === undefined ||
1402
+ description.length === 0 ||
1403
+ description.length > MAX_RULE_DESCRIPTION_LENGTH
1404
+ )
1405
+ return refusedRules('front_matter', file.path);
1406
+ const yaml = fencedYaml(parsed.body);
1407
+ if (yaml === null) return refusedRules('body', file.path);
1408
+ const check = validateRuleYaml(yaml);
1409
+ if (!check.ok) return refusedRules(check.reason, file.path);
1410
+ for (const id of check.ids) {
1411
+ if (ids.has(id)) return refusedRules('duplicate_id', file.path);
1412
+ ids.add(id);
1413
+ }
1414
+ if (ids.size > MAX_AISAC_RULES) return refusedRules('too_many_rules', file.path);
1415
+ accepted.push({ name: stem, yaml });
1416
+ }
1417
+ return { status: 'loaded', count: ids.size, files: accepted };
1418
+ }