@aisac/cli 0.4.0-beta.14 → 0.4.0-beta.17
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/README.md +45 -3
- package/dist/claude-compatibility.mjs +2 -0
- package/dist/claude-observation.mjs +1 -1
- package/dist/cli.mjs +74 -4
- package/dist/codex-compatibility.mjs +1 -0
- package/dist/codex-protocol-fingerprint.json +11 -11
- package/dist/engineering-pack.mjs +23 -3
- package/dist/engineering-scan-pins.json +42 -0
- package/dist/engineering-scan-report.mjs +1274 -0
- package/dist/engineering-scan-tools.mjs +1418 -0
- package/dist/engineering-scan.mjs +1265 -0
- package/dist/extensions-catalog.mjs +49 -4
- package/dist/extensions-cli.mjs +8 -2
- package/dist/package.json +1 -1
- package/dist/platform.mjs +20 -5
- 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
|
+
}
|