@vaultcompass/conductor 0.9.0 → 0.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +157 -31
- package/dist/cli.d.ts +6 -0
- package/dist/cli.js +19 -4
- package/dist/gate-runner.d.ts +102 -10
- package/dist/gate-runner.js +282 -37
- package/dist/init-hook-detect.d.ts +1 -0
- package/dist/init-hook-detect.js +45 -0
- package/dist/init-policy.js +13 -0
- package/dist/init.d.ts +8 -0
- package/dist/init.js +166 -20
- package/dist/intent-prepare.d.ts +51 -2
- package/dist/intent-prepare.js +160 -35
- package/dist/intent-spec.d.ts +108 -22
- package/dist/intent-spec.js +226 -55
- package/dist/normalize.d.ts +32 -2
- package/dist/normalize.js +117 -11
- package/dist/output-sarif.js +72 -1
- package/dist/output-text.d.ts +37 -1
- package/dist/output-text.js +324 -21
- package/dist/policy.d.ts +8 -0
- package/dist/policy.js +33 -6
- package/dist/products.d.ts +8 -1
- package/dist/products.js +14 -0
- package/dist/run.d.ts +13 -1
- package/dist/run.js +19 -2
- package/package.json +1 -1
- package/schema/guardrails.schema.json +6 -0
package/dist/gate-runner.js
CHANGED
|
@@ -72,8 +72,8 @@ export function breakWorkflowMarkers(text) {
|
|
|
72
72
|
}
|
|
73
73
|
/**
|
|
74
74
|
* The could-not-run reasons that are conductor's OWN decision, made before
|
|
75
|
-
* the gate was spawned (or instead of spawning it),
|
|
76
|
-
* the gate itself said or did.
|
|
75
|
+
* the gate was spawned (or instead of spawning it), or the umbrella stopping
|
|
76
|
+
* it, as opposed to something the gate itself said or did.
|
|
77
77
|
*/
|
|
78
78
|
export const CONDUCTOR_OWN_REASONS = new Set([
|
|
79
79
|
'preparation-failed',
|
|
@@ -81,7 +81,101 @@ export const CONDUCTOR_OWN_REASONS = new Set([
|
|
|
81
81
|
'gate-program-refused',
|
|
82
82
|
'gate-version-unsupported',
|
|
83
83
|
'history-shallow',
|
|
84
|
+
'timed-out',
|
|
84
85
|
]);
|
|
86
|
+
/**
|
|
87
|
+
* A gate's time limit, and where it came from. THE ONE PLACE the precedence
|
|
88
|
+
* is written: the test hook (`RunGateOptions.timeoutMs`, which no CLI path
|
|
89
|
+
* sets), then the policy's `timeout-seconds`, then the product's default.
|
|
90
|
+
* runGate and the intent gate's preparation in run.ts both call this, so the
|
|
91
|
+
* two cannot disagree about a gate's limit.
|
|
92
|
+
*/
|
|
93
|
+
export function resolveTimeLimit(gate, override) {
|
|
94
|
+
if (override !== undefined) {
|
|
95
|
+
return { ms: override, source: 'override' };
|
|
96
|
+
}
|
|
97
|
+
if (gate.timeoutSeconds !== undefined) {
|
|
98
|
+
return { ms: gate.timeoutSeconds * 1000, source: 'policy' };
|
|
99
|
+
}
|
|
100
|
+
return { ms: profileFor(gate.product).timeoutMs, source: 'default' };
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Classifies a spawnSync result that carries an error. PURE, so it is tested
|
|
104
|
+
* on hand-built results.
|
|
105
|
+
*
|
|
106
|
+
* THE ERROR CODE ALONE decides it. ETIMEDOUT is timed-out and nothing else
|
|
107
|
+
* is. No status or signal condition belongs here: a child that traps SIGTERM,
|
|
108
|
+
* or ignores it and exits on its own, comes back with status 0 (or its
|
|
109
|
+
* blocked code) and signal null, and ENOBUFS arrives with the same SIGTERM a
|
|
110
|
+
* timeout does. The signal is recorded for the report and never classifies.
|
|
111
|
+
*/
|
|
112
|
+
export function spawnFailure(child) {
|
|
113
|
+
if (child.error === undefined) {
|
|
114
|
+
return null;
|
|
115
|
+
}
|
|
116
|
+
if (child.error.code === 'ETIMEDOUT') {
|
|
117
|
+
return { reason: 'timed-out', signal: child.signal ?? null };
|
|
118
|
+
}
|
|
119
|
+
return { reason: 'spawn-failed', message: child.error.message };
|
|
120
|
+
}
|
|
121
|
+
/** "(the default for this gate)", or where the policy value came from. */
|
|
122
|
+
function limitSourcePhrase(gate, source, trustBase) {
|
|
123
|
+
if (source === 'policy') {
|
|
124
|
+
return trustBase === undefined
|
|
125
|
+
? `gates.${gate.role}.timeout-seconds`
|
|
126
|
+
: `gates.${gate.role}.timeout-seconds on ${trustBase}`;
|
|
127
|
+
}
|
|
128
|
+
return source === 'default' ? 'the default for this gate' : 'set by the caller';
|
|
129
|
+
}
|
|
130
|
+
/**
|
|
131
|
+
* The note for `options.timeout` on the secrets-history gate, which is
|
|
132
|
+
* gitleaks' own --timeout and not conductor's limit. Null when the key is not
|
|
133
|
+
* set or the gate is not gitleaks.
|
|
134
|
+
*/
|
|
135
|
+
function gateOwnTimeoutNote(gate, limit, trustBase) {
|
|
136
|
+
if (gate.product !== 'gitleaks' || gate.options.timeout === undefined) {
|
|
137
|
+
return null;
|
|
138
|
+
}
|
|
139
|
+
return (`options.timeout is gitleaks' own --timeout (${String(gate.options.timeout)} s); conductor stops the ` +
|
|
140
|
+
`gate at ${Math.round(limit.ms / 1000)} s (${limitSourcePhrase(gate, limit.source, trustBase)}).`);
|
|
141
|
+
}
|
|
142
|
+
/** The could-not-run detail for a gate stopped at its limit, by step. */
|
|
143
|
+
function timedOutDetail(gate, step, limit, elapsedMs, trustBase) {
|
|
144
|
+
const limitSeconds = Math.round(limit.ms / 1000);
|
|
145
|
+
const elapsedSeconds = Math.round(elapsedMs / 1000);
|
|
146
|
+
const where = limitSourcePhrase(gate, limit.source, trustBase);
|
|
147
|
+
const own = gateOwnTimeoutNote(gate, limit, trustBase);
|
|
148
|
+
const remedies = profileFor(gate.product).timeoutRemedies(gate.role);
|
|
149
|
+
if (step === 'version-probe') {
|
|
150
|
+
return (`the version probe of ${gate.product} was stopped at ${limitSeconds} s (${where}), so the gate ` +
|
|
151
|
+
'was not run and nothing was checked by it.');
|
|
152
|
+
}
|
|
153
|
+
const what = step === 'scan'
|
|
154
|
+
? `${gate.product} was stopped after ${elapsedSeconds} s, at its ${limitSeconds} s limit (${where}), ` +
|
|
155
|
+
'so nothing was checked by it.'
|
|
156
|
+
: `the intent gate's ${step} step was stopped after ${elapsedSeconds} s, at its ${limitSeconds} s ` +
|
|
157
|
+
`limit (${where}), so the gate was not run and nothing was checked by it.`;
|
|
158
|
+
return `${what} ${remedies}${own === null ? '' : ` ${own}`}`;
|
|
159
|
+
}
|
|
160
|
+
function timedOutRecord(step, limit, elapsedMs, signal) {
|
|
161
|
+
return {
|
|
162
|
+
step,
|
|
163
|
+
limitSeconds: Math.round(limit.ms / 1000),
|
|
164
|
+
elapsedSeconds: Math.round(elapsedMs / 1000),
|
|
165
|
+
limitSource: limit.source,
|
|
166
|
+
signal,
|
|
167
|
+
};
|
|
168
|
+
}
|
|
169
|
+
/** The `conductor/gate-failed` finding for a timed-out gate, with the timing in its details. */
|
|
170
|
+
function timedOutFinding(gate, detail, timedOut, stderr) {
|
|
171
|
+
return normalizeFailedGate(gate.role, gate.product, detail, stderr, {
|
|
172
|
+
timedOut: {
|
|
173
|
+
limitSeconds: timedOut.limitSeconds,
|
|
174
|
+
elapsedSeconds: timedOut.elapsedSeconds,
|
|
175
|
+
limitSource: timedOut.limitSource,
|
|
176
|
+
},
|
|
177
|
+
});
|
|
178
|
+
}
|
|
85
179
|
/**
|
|
86
180
|
* conductor's own reason for a could-not-run, as a job-log excerpt: cleaned,
|
|
87
181
|
* one line, capped and with double quotes replaced, exactly like a gate's
|
|
@@ -98,25 +192,89 @@ export function conductorStatedReason(detail) {
|
|
|
98
192
|
export function cleanOutputLine(raw) {
|
|
99
193
|
return breakWorkflowMarkers(raw.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' '));
|
|
100
194
|
}
|
|
195
|
+
/** A zerolog line at one level: gitleaks' "<time> ERR ..." shape. */
|
|
196
|
+
const ZEROLOG_ERR = /^\S+\s+ERR\s/;
|
|
197
|
+
const ZEROLOG_WRN = /^\S+\s+WRN\s/;
|
|
198
|
+
function plainLine(raw) {
|
|
199
|
+
return raw.replace(/[^\x20-\x7e]/g, ' ').replace(/\s+/g, ' ').trim();
|
|
200
|
+
}
|
|
201
|
+
/**
|
|
202
|
+
* The stderr half of the stated-reason rule: the line a gate marks as its
|
|
203
|
+
* failure, else the first line that is not informational, else nothing.
|
|
204
|
+
*
|
|
205
|
+
* 1. Lines are split after stripAnsi. Whitespace tests (blank, indented)
|
|
206
|
+
* are made there, before sanitizing, because a colour code can come
|
|
207
|
+
* before the indentation; markers are matched on the sanitized text, so
|
|
208
|
+
* a leading emoji or colour code does not hide one.
|
|
209
|
+
* 2. Informational lines are never chosen: a `note:` line and every
|
|
210
|
+
* following indented line (a BLANK line ends the note block, so an
|
|
211
|
+
* indented reason after it is not swallowed), and gitleaks' two
|
|
212
|
+
* rename-detection warnings.
|
|
213
|
+
* 3. A marker wins: the first remaining INCOMPLETE: or zerolog ERR line,
|
|
214
|
+
* joined with the indented lines after it, skipping blank lines, up to
|
|
215
|
+
* the first non-blank line that is not indented.
|
|
216
|
+
* 4. No marker: the first remaining line.
|
|
217
|
+
*/
|
|
218
|
+
function statedReasonFromStderr(stderr) {
|
|
219
|
+
const lines = stripAnsi(stderr)
|
|
220
|
+
.split('\n')
|
|
221
|
+
.map((raw) => {
|
|
222
|
+
const blank = raw.trim() === '';
|
|
223
|
+
return { blank, indented: !blank && /^\s/.test(raw), text: plainLine(raw), informational: false };
|
|
224
|
+
});
|
|
225
|
+
for (let i = 0; i < lines.length; i++) {
|
|
226
|
+
const line = lines[i];
|
|
227
|
+
if (/^note:/i.test(line.text)) {
|
|
228
|
+
line.informational = true;
|
|
229
|
+
for (let j = i + 1; j < lines.length && lines[j].indented; j++) {
|
|
230
|
+
lines[j].informational = true;
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
else if (ZEROLOG_WRN.test(line.text) &&
|
|
234
|
+
(line.text.includes('rename detection was skipped') || line.text.includes('diff.renameLimit'))) {
|
|
235
|
+
line.informational = true;
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
const candidate = (line) => !line.blank && !line.informational && line.text !== '';
|
|
239
|
+
const markerAt = lines.findIndex((line) => candidate(line) && (line.text.startsWith('INCOMPLETE:') || ZEROLOG_ERR.test(line.text)));
|
|
240
|
+
if (markerAt >= 0) {
|
|
241
|
+
const block = [lines[markerAt].text];
|
|
242
|
+
for (let k = markerAt + 1; k < lines.length; k++) {
|
|
243
|
+
const next = lines[k];
|
|
244
|
+
if (next.blank) {
|
|
245
|
+
continue;
|
|
246
|
+
}
|
|
247
|
+
if (!next.indented) {
|
|
248
|
+
break;
|
|
249
|
+
}
|
|
250
|
+
if (next.text !== '') {
|
|
251
|
+
block.push(next.text);
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
return sanitizeGateSaid(block.join(' '));
|
|
255
|
+
}
|
|
256
|
+
const first = lines.find(candidate);
|
|
257
|
+
return first === undefined ? null : sanitizeGateSaid(first.text);
|
|
258
|
+
}
|
|
101
259
|
/**
|
|
102
260
|
* What a gate that exited with a non-verdict code said about why.
|
|
103
261
|
*
|
|
104
262
|
* TOTAL, and never a decision: the caller has already settled that this is a
|
|
105
|
-
* could-not-run, and nothing here can change that.
|
|
106
|
-
*
|
|
107
|
-
*
|
|
108
|
-
*
|
|
109
|
-
*
|
|
110
|
-
*
|
|
263
|
+
* could-not-run, and nothing here can change that. stderr is preferred, since
|
|
264
|
+
* that is where every gate in the family prints its reason on exit 2
|
|
265
|
+
* (dep-guard, intent-guard and vault-guard all do), read by the rule in
|
|
266
|
+
* `statedReasonFromStderr`: the line the gate marks as the failure, never an
|
|
267
|
+
* informational line. Failing that, stdout is parsed only for a gate whose
|
|
268
|
+
* output is JSON on stdout, and only a string `reason` field (top level, or
|
|
269
|
+
* on `run`) is read; anything else, including output that does not parse, is
|
|
270
|
+
* simply no excerpt. An absent excerpt is better than quoting a warning as
|
|
271
|
+
* the cause; the full stderr is still printed in the text report.
|
|
111
272
|
*/
|
|
112
273
|
export function gateStatedReason(stderr, stdout, stdoutIsJson) {
|
|
113
274
|
try {
|
|
114
|
-
const
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
.find((line) => line !== null);
|
|
118
|
-
if (firstLine !== undefined && firstLine !== null) {
|
|
119
|
-
return firstLine;
|
|
275
|
+
const fromStderr = statedReasonFromStderr(stderr);
|
|
276
|
+
if (fromStderr !== null) {
|
|
277
|
+
return fromStderr;
|
|
120
278
|
}
|
|
121
279
|
if (!stdoutIsJson || typeof stdout !== 'string' || !stdout.trimStart().startsWith('{')) {
|
|
122
280
|
return null;
|
|
@@ -321,6 +479,33 @@ export function preparationFailed(gate, detail) {
|
|
|
321
479
|
diagnostics: [],
|
|
322
480
|
};
|
|
323
481
|
}
|
|
482
|
+
/**
|
|
483
|
+
* The intent gate whose preparation step (import-spec or freeze) was stopped
|
|
484
|
+
* at the gate's time limit. Shaped like `preparationFailed`, with the
|
|
485
|
+
* timed-out reason, so it composes the same way; the caller decides
|
|
486
|
+
* `enforce` under the same rule it applies to a failed preparation.
|
|
487
|
+
*/
|
|
488
|
+
export function preparationTimedOut(gate, stopped) {
|
|
489
|
+
const detail = timedOutDetail(gate, stopped.step, stopped.limit, stopped.elapsedMs, stopped.trustBase);
|
|
490
|
+
const timedOut = timedOutRecord(stopped.step, stopped.limit, stopped.elapsedMs, stopped.signal);
|
|
491
|
+
return {
|
|
492
|
+
role: gate.role,
|
|
493
|
+
product: gate.product,
|
|
494
|
+
stage: gate.stage,
|
|
495
|
+
enforce: gate.enforce,
|
|
496
|
+
productVersion: null,
|
|
497
|
+
argv: [],
|
|
498
|
+
binary: null,
|
|
499
|
+
exitCode: null,
|
|
500
|
+
durationMs: stopped.elapsedMs,
|
|
501
|
+
stderr: '',
|
|
502
|
+
timeLimit: stopped.limit,
|
|
503
|
+
couldNotRun: { reason: 'timed-out', detail, timedOut },
|
|
504
|
+
findings: [timedOutFinding(gate, detail, timedOut)],
|
|
505
|
+
run: EMPTY_RUN,
|
|
506
|
+
diagnostics: [],
|
|
507
|
+
};
|
|
508
|
+
}
|
|
324
509
|
const EMPTY_RUN = {
|
|
325
510
|
failOn: null,
|
|
326
511
|
suppressed: 0,
|
|
@@ -597,25 +782,25 @@ intentBase) {
|
|
|
597
782
|
}
|
|
598
783
|
}
|
|
599
784
|
}
|
|
600
|
-
/**
|
|
601
|
-
* Asks a binary for its version.
|
|
602
|
-
*
|
|
603
|
-
* Never called for a binary the candidate table marks unsafe to ask: the
|
|
604
|
-
* per-command binaries ignore --version and run the gate instead, so a
|
|
605
|
-
* probe there would have side effects on the user's repository.
|
|
606
|
-
*/
|
|
607
785
|
function probeVersion(binary, product, repoRoot, timeoutMs) {
|
|
608
786
|
const spec = profileFor(product).versionProbe;
|
|
609
787
|
if (binary.versionProbe === null || spec === null) {
|
|
610
|
-
return
|
|
788
|
+
return { kind: 'unreadable' };
|
|
611
789
|
}
|
|
790
|
+
const probeStarted = Date.now();
|
|
612
791
|
const probe = spawnSync(binary.versionProbe.command, binary.versionProbe.argv, {
|
|
613
792
|
cwd: repoRoot,
|
|
614
793
|
encoding: 'utf8',
|
|
615
794
|
timeout: timeoutMs,
|
|
616
795
|
});
|
|
796
|
+
// FIRST, before the status: a probe that handled SIGTERM can exit 0 with a
|
|
797
|
+
// version on stdout, and it was still stopped at the limit.
|
|
798
|
+
const failure = spawnFailure(probe);
|
|
799
|
+
if (failure !== null && failure.reason === 'timed-out') {
|
|
800
|
+
return { kind: 'timed-out', elapsedMs: Date.now() - probeStarted, signal: failure.signal };
|
|
801
|
+
}
|
|
617
802
|
if (probe.status !== 0 || typeof probe.stdout !== 'string') {
|
|
618
|
-
return
|
|
803
|
+
return { kind: 'unreadable' };
|
|
619
804
|
}
|
|
620
805
|
// Take the first line and accept it only if the product's pattern matches,
|
|
621
806
|
// so a future help banner does not end up in a SARIF driver's version
|
|
@@ -624,7 +809,7 @@ function probeVersion(binary, product, repoRoot, timeoutMs) {
|
|
|
624
809
|
// a capture group that takes the number alone.
|
|
625
810
|
const first = probe.stdout.trim().split('\n')[0]?.trim() ?? '';
|
|
626
811
|
const match = spec.pattern.exec(first);
|
|
627
|
-
return match === null ?
|
|
812
|
+
return match === null ? { kind: 'unreadable' } : { kind: 'version', value: (match[1] ?? match[0]).replace(/^v/, '') };
|
|
628
813
|
}
|
|
629
814
|
/**
|
|
630
815
|
* `context.blocked` is whether the gate's exit said it blocked. The npm gates
|
|
@@ -648,7 +833,7 @@ function normalizeFor(product, parsed, version, context) {
|
|
|
648
833
|
case 'gitleaks':
|
|
649
834
|
return normalizeGitleaks(parsed, version, context.blocked);
|
|
650
835
|
case 'osv-scanner':
|
|
651
|
-
return normalizeOsvScanner(parsed, version, context.blocked, context.roots, context.lockfiles);
|
|
836
|
+
return normalizeOsvScanner(parsed, version, context.blocked, context.roots, context.lockfiles, context.stderr);
|
|
652
837
|
}
|
|
653
838
|
}
|
|
654
839
|
/**
|
|
@@ -805,7 +990,19 @@ function isShallowRepository(repoRoot) {
|
|
|
805
990
|
return probe.status === 0 && probe.stdout.trim() === 'true';
|
|
806
991
|
}
|
|
807
992
|
function runGateInner(gate, options, started, progress) {
|
|
808
|
-
|
|
993
|
+
// Every spawn of this gate gets the FULL limit, not a share of it: the
|
|
994
|
+
// version probe, the scan and, on a compared pull request, osv-scanner's
|
|
995
|
+
// base run. Onto `progress` so every outcome from here on carries it.
|
|
996
|
+
const timeLimit = resolveTimeLimit(gate, options.timeoutMs);
|
|
997
|
+
const timeoutMs = timeLimit.ms;
|
|
998
|
+
Object.assign(progress, { timeLimit });
|
|
999
|
+
const ownOption = gateOwnTimeoutNote(gate, timeLimit, options.trustBase);
|
|
1000
|
+
if (ownOption !== null) {
|
|
1001
|
+
// Before any spawn, the way nodeModulesSkipped is, so every return path
|
|
1002
|
+
// from here on carries it, the gate-error of gitleaks' own deadline
|
|
1003
|
+
// included.
|
|
1004
|
+
Object.assign(progress, { gateOwnOption: ownOption });
|
|
1005
|
+
}
|
|
809
1006
|
// ONE PLACE DECIDES WHAT PULL-REQUEST MODE IS, and it is the presence of a
|
|
810
1007
|
// trust base. resolve.ts knows nothing about refs, so it is told rather than
|
|
811
1008
|
// asked.
|
|
@@ -938,7 +1135,29 @@ function runGateInner(gate, options, started, progress) {
|
|
|
938
1135
|
diagnostics: [],
|
|
939
1136
|
};
|
|
940
1137
|
}
|
|
941
|
-
const
|
|
1138
|
+
const probed = probeVersion(binary, gate.product, options.repoRoot, timeoutMs);
|
|
1139
|
+
if (probed.kind === 'timed-out') {
|
|
1140
|
+
// Stopped here, before the version floor and before decideTrustBase: a
|
|
1141
|
+
// timed-out probe is not an unreadable version (which on a pull request
|
|
1142
|
+
// would read as trust-base-unverified, a packaging problem that does not
|
|
1143
|
+
// exist), and a local run does not go on to scan with the version
|
|
1144
|
+
// unknown. Enforced under a trust base, like trust-base-unverified: the
|
|
1145
|
+
// gate could not be placed inside the boundary.
|
|
1146
|
+
const detail = timedOutDetail(gate, 'version-probe', timeLimit, probed.elapsedMs, options.trustBase);
|
|
1147
|
+
const timedOut = timedOutRecord('version-probe', timeLimit, probed.elapsedMs, probed.signal);
|
|
1148
|
+
return {
|
|
1149
|
+
...base,
|
|
1150
|
+
binary,
|
|
1151
|
+
enforce: options.trustBase !== undefined ? true : gate.enforce,
|
|
1152
|
+
durationMs: Date.now() - started,
|
|
1153
|
+
exitCode: null,
|
|
1154
|
+
couldNotRun: { reason: 'timed-out', detail, timedOut },
|
|
1155
|
+
findings: [timedOutFinding(gate, detail, timedOut)],
|
|
1156
|
+
run: EMPTY_RUN,
|
|
1157
|
+
diagnostics: [],
|
|
1158
|
+
};
|
|
1159
|
+
}
|
|
1160
|
+
const version = probed.kind === 'version' ? probed.value : null;
|
|
942
1161
|
// A PATH binary at a different version than the run was told to expect: a
|
|
943
1162
|
// fact for a warning and nothing else. It sits on `progress` (which `base`
|
|
944
1163
|
// is) so every outcome from here on carries it, and no branch below reads it.
|
|
@@ -1046,7 +1265,7 @@ function runGateInner(gate, options, started, progress) {
|
|
|
1046
1265
|
version,
|
|
1047
1266
|
trustBase,
|
|
1048
1267
|
profile,
|
|
1049
|
-
|
|
1268
|
+
timeLimit,
|
|
1050
1269
|
workDir,
|
|
1051
1270
|
});
|
|
1052
1271
|
}
|
|
@@ -1062,7 +1281,8 @@ function stripAnsi(text) {
|
|
|
1062
1281
|
}
|
|
1063
1282
|
/** Builds the command line, runs the gate, and reads what it said. */
|
|
1064
1283
|
function spawnAndRead(ctx) {
|
|
1065
|
-
const { gate, options, started, progress, base, binary, version, trustBase, profile,
|
|
1284
|
+
const { gate, options, started, progress, base, binary, version, trustBase, profile, timeLimit, workDir } = ctx;
|
|
1285
|
+
const timeoutMs = timeLimit.ms;
|
|
1066
1286
|
const external = {};
|
|
1067
1287
|
if (profile.output.kind === 'report-file' && workDir !== null) {
|
|
1068
1288
|
external.reportPath = path.join(workDir, `${gate.product}-report${profile.output.extension}`);
|
|
@@ -1263,6 +1483,9 @@ function spawnAndRead(ctx) {
|
|
|
1263
1483
|
...binary.argvPrefix,
|
|
1264
1484
|
...gateArgs(gate, options.staged, options.intent, decidedRef, external, channel.kind === 'base' ? channel.ref : undefined),
|
|
1265
1485
|
];
|
|
1486
|
+
// Taken just before the call, so a timed-out message's elapsed time is the
|
|
1487
|
+
// scan's own and not resolution plus the version probe.
|
|
1488
|
+
const spawnStarted = Date.now();
|
|
1266
1489
|
const child = spawnSync(binary.command, argv, {
|
|
1267
1490
|
cwd: spawnCwd,
|
|
1268
1491
|
encoding: 'utf8',
|
|
@@ -1294,14 +1517,34 @@ function spawnAndRead(ctx) {
|
|
|
1294
1517
|
// Keep the backstop's view current, so an unexpected throw below still
|
|
1295
1518
|
// reports which binary ran and what it printed.
|
|
1296
1519
|
Object.assign(progress, withRun);
|
|
1297
|
-
|
|
1520
|
+
// THE FIRST THING READ after spawnSync returns, ahead of every status,
|
|
1521
|
+
// signal, report and stdout check, and it returns for every error. A child
|
|
1522
|
+
// stopped at the limit that handled SIGTERM can come back with status 0, or
|
|
1523
|
+
// its blocked code, and a complete clean report or clean JSON on stdout;
|
|
1524
|
+
// only this order keeps that from reading as a verdict. The outcome's
|
|
1525
|
+
// exitCode is null whatever child.status says: a status from a child that
|
|
1526
|
+
// was told to stop is not a verdict. Nothing on this path reads the report
|
|
1527
|
+
// file, parses stdout or calls a normalizer.
|
|
1528
|
+
const failure = spawnFailure(child);
|
|
1529
|
+
if (failure !== null) {
|
|
1530
|
+
if (failure.reason === 'timed-out') {
|
|
1531
|
+
const elapsedMs = Date.now() - spawnStarted;
|
|
1532
|
+
const detail = timedOutDetail(gate, 'scan', timeLimit, elapsedMs, options.trustBase);
|
|
1533
|
+
const timedOut = timedOutRecord('scan', timeLimit, elapsedMs, failure.signal);
|
|
1534
|
+
return {
|
|
1535
|
+
...withRun,
|
|
1536
|
+
exitCode: null,
|
|
1537
|
+
couldNotRun: { reason: 'timed-out', detail, timedOut },
|
|
1538
|
+
findings: [timedOutFinding(gate, detail, timedOut, withRun.stderr)],
|
|
1539
|
+
run: EMPTY_RUN,
|
|
1540
|
+
diagnostics: [],
|
|
1541
|
+
};
|
|
1542
|
+
}
|
|
1298
1543
|
return {
|
|
1299
1544
|
...withRun,
|
|
1300
1545
|
exitCode: null,
|
|
1301
|
-
couldNotRun: { reason: 'spawn-failed', detail:
|
|
1302
|
-
findings: [
|
|
1303
|
-
normalizeFailedGate(gate.role, gate.product, child.error.message, withRun.stderr),
|
|
1304
|
-
],
|
|
1546
|
+
couldNotRun: { reason: 'spawn-failed', detail: failure.message },
|
|
1547
|
+
findings: [normalizeFailedGate(gate.role, gate.product, failure.message, withRun.stderr)],
|
|
1305
1548
|
run: EMPTY_RUN,
|
|
1306
1549
|
diagnostics: [],
|
|
1307
1550
|
};
|
|
@@ -1354,12 +1597,13 @@ function spawnAndRead(ctx) {
|
|
|
1354
1597
|
// The profile says which exits are verdicts. For the npm gates that is 0
|
|
1355
1598
|
// and 1, exactly as before profiles existed: dep-guard's 2 means "could not
|
|
1356
1599
|
// run the checks at all" and it prints no JSON. gitleaks is handed
|
|
1357
|
-
// --exit-code 3, so its 1 is left meaning an error. A
|
|
1358
|
-
//
|
|
1600
|
+
// --exit-code 3, so its 1 is left meaning an error. A child killed by
|
|
1601
|
+
// something other than the umbrella lands here too (a timeout returned
|
|
1602
|
+
// above), and none of those are a clean result.
|
|
1359
1603
|
const blocked = exitCode !== null && profile.exit.blocked.includes(exitCode);
|
|
1360
1604
|
if (exitCode === null || (!blocked && !profile.exit.clean.includes(exitCode))) {
|
|
1361
1605
|
const detail = exitCode === null
|
|
1362
|
-
?
|
|
1606
|
+
? `the gate was killed by signal ${child.signal ?? 'unknown'} before it exited.`
|
|
1363
1607
|
: `the gate exited ${exitCode}, which it uses for "could not run".`;
|
|
1364
1608
|
// WHY, in the gate's own words, when it said. Read here and nowhere
|
|
1365
1609
|
// earlier: the exit code has already been judged above, and this only
|
|
@@ -1459,6 +1703,7 @@ function spawnAndRead(ctx) {
|
|
|
1459
1703
|
// not off gate.options: the argv is what dep-guard was actually told.
|
|
1460
1704
|
online: argv.includes('--online'),
|
|
1461
1705
|
lockfiles: external.lockfiles ?? [],
|
|
1706
|
+
stderr: withRun.stderr,
|
|
1462
1707
|
});
|
|
1463
1708
|
// The base comparison (osv design, section 3.1): only on a decided trust
|
|
1464
1709
|
// base, only when the head run exited blocked and produced a finding. A
|
|
@@ -168,6 +168,7 @@ export interface ManagedDeclaration {
|
|
|
168
168
|
detectedIn: ManagedDetection;
|
|
169
169
|
}
|
|
170
170
|
export declare function declaredManagedHooks(root: string): ManagedDeclaration | null;
|
|
171
|
+
export declare function declaredHusky(root: string): string | null;
|
|
171
172
|
/**
|
|
172
173
|
* What init says when it finds one of those two, and why it says nothing
|
|
173
174
|
* else.
|
package/dist/init-hook-detect.js
CHANGED
|
@@ -203,6 +203,51 @@ export function declaredManagedHooks(root) {
|
|
|
203
203
|
}
|
|
204
204
|
return null;
|
|
205
205
|
}
|
|
206
|
+
/**
|
|
207
|
+
* Where this repository's package.json declares husky, or null: a husky
|
|
208
|
+
* dependency or devDependency, or a prepare script that runs husky. The
|
|
209
|
+
* signal that exists on a fresh clone, before husky's own install has set
|
|
210
|
+
* core.hooksPath. Unreadable or unparseable is the same as undeclared, as for
|
|
211
|
+
* declaredManagedHooks above.
|
|
212
|
+
*/
|
|
213
|
+
/**
|
|
214
|
+
* husky as a COMMAND in a script: at the start or after a shell separator
|
|
215
|
+
* (&&, ||, ;, |), optionally behind a package runner, and followed by an
|
|
216
|
+
* argument or the end. So "husky", "husky install", "is-ci || husky" and
|
|
217
|
+
* "npx husky" match, and "no-husky" or "echo skip husky" do not.
|
|
218
|
+
*/
|
|
219
|
+
const HUSKY_COMMAND = /(?:^|&&|\|\||;|\|)\s*(?:(?:npx|pnpx|bunx)\s+|(?:pnpm|yarn|npm)\s+(?:exec\s+)?)?husky(?:\s|$)/;
|
|
220
|
+
export function declaredHusky(root) {
|
|
221
|
+
const raw = readIfExists(path.join(root, 'package.json'));
|
|
222
|
+
if (raw === undefined) {
|
|
223
|
+
return null;
|
|
224
|
+
}
|
|
225
|
+
let parsed;
|
|
226
|
+
try {
|
|
227
|
+
parsed = JSON.parse(raw);
|
|
228
|
+
}
|
|
229
|
+
catch {
|
|
230
|
+
return null;
|
|
231
|
+
}
|
|
232
|
+
if (!isPlainObject(parsed)) {
|
|
233
|
+
return null;
|
|
234
|
+
}
|
|
235
|
+
const manifest = parsed;
|
|
236
|
+
for (const key of ['devDependencies', 'dependencies']) {
|
|
237
|
+
const deps = manifest[key];
|
|
238
|
+
if (isPlainObject(deps) && deps.husky !== undefined) {
|
|
239
|
+
return `package.json (${key})`;
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
const scripts = manifest.scripts;
|
|
243
|
+
if (isPlainObject(scripts)) {
|
|
244
|
+
const prepare = scripts.prepare;
|
|
245
|
+
if (typeof prepare === 'string' && HUSKY_COMMAND.test(prepare)) {
|
|
246
|
+
return 'package.json (the prepare script)';
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
return null;
|
|
250
|
+
}
|
|
206
251
|
function isPlainObject(value) {
|
|
207
252
|
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
208
253
|
}
|
package/dist/init-policy.js
CHANGED
|
@@ -3,6 +3,7 @@ import path from 'node:path';
|
|
|
3
3
|
import { NATIVE_CONTRACT_PATH } from './intent-prepare.js';
|
|
4
4
|
import { DEFAULT_STAGE_FOR_ROLE, GATE_ROLES, POLICY_FILE_NAME, PRODUCT_FOR_ROLE } from './policy.js';
|
|
5
5
|
import { installName } from './normalize.js';
|
|
6
|
+
import { profileFor } from './products.js';
|
|
6
7
|
import { CANDIDATES } from './resolve.js';
|
|
7
8
|
export { POLICY_FILE_NAME };
|
|
8
9
|
/** Names of the gates whose binary resolves right now. */
|
|
@@ -102,6 +103,14 @@ export function renderPolicy(detected, frozenContractPath) {
|
|
|
102
103
|
lines.push(` ${role}:`);
|
|
103
104
|
lines.push(` product: ${product}`);
|
|
104
105
|
lines.push(` enabled: ${enabled ? 'true' : 'false'}`);
|
|
106
|
+
// An external tool is enabled only because THIS machine has it, and
|
|
107
|
+
// nothing installs it anywhere else: say so where the next reader of the
|
|
108
|
+
// file will look, not only in init's own output, which nobody re-reads.
|
|
109
|
+
if (enabled && !profileFor(product).managed) {
|
|
110
|
+
lines.push(` # Enabled because ${product} was found on the machine that ran init. CI must`);
|
|
111
|
+
lines.push(` # install ${product} itself (conductor does not); without it this gate`);
|
|
112
|
+
lines.push(' # reports conductor/gate-missing and the run exits 2.');
|
|
113
|
+
}
|
|
105
114
|
lines.push(` stage: ${DEFAULT_STAGE_FOR_ROLE[role]}`);
|
|
106
115
|
// The intent gate is the one with ceremony, and the ramp is what makes
|
|
107
116
|
// that ceremony adoptable: with no frozen contract yet, it reports for a
|
|
@@ -147,6 +156,10 @@ export function renderPolicy(detected, frozenContractPath) {
|
|
|
147
156
|
if (role === 'secrets-history') {
|
|
148
157
|
lines.push(' # gitleaks has no severity floor. Tune its rules in .gitleaks.toml and');
|
|
149
158
|
lines.push(' # accept an old finding in .gitleaksignore, not here.');
|
|
159
|
+
// No timeout-seconds line: an absent key is the default, and writing
|
|
160
|
+
// 600 would freeze today's default into every new policy.
|
|
161
|
+
lines.push(' # A full-history scan can outlive the 600 s default on a large repository.');
|
|
162
|
+
lines.push(' # Set timeout-seconds beside enforce to change it; see the README.');
|
|
150
163
|
}
|
|
151
164
|
else if (role === 'vulnerabilities') {
|
|
152
165
|
lines.push(' # osv-scanner has no severity floor. Tune what it reports in');
|
package/dist/init.d.ts
CHANGED
|
@@ -91,6 +91,12 @@ export interface InitResult {
|
|
|
91
91
|
content: string;
|
|
92
92
|
kind: 'hook' | 'policy';
|
|
93
93
|
}>;
|
|
94
|
+
/**
|
|
95
|
+
* The .gitignore that GITIGNORE_LINE is appended to on apply, when the
|
|
96
|
+
* manifest is not already ignored and appending is safe. Absent otherwise.
|
|
97
|
+
* Never in the manifest: --revert does not touch .gitignore.
|
|
98
|
+
*/
|
|
99
|
+
gitignoreAppend?: string;
|
|
94
100
|
}
|
|
95
101
|
export interface InitOptions {
|
|
96
102
|
cwd: string;
|
|
@@ -117,6 +123,8 @@ export interface InitOptions {
|
|
|
117
123
|
force?: boolean;
|
|
118
124
|
}
|
|
119
125
|
export declare function planInit(options: InitOptions): InitResult;
|
|
126
|
+
/** The line init adds to .gitignore for the per-machine manifest. */
|
|
127
|
+
export declare const GITIGNORE_LINE = ".guardrails/";
|
|
120
128
|
export declare function applyInit(plan: InitResult, options: InitOptions): InitResult;
|
|
121
129
|
export interface RevertResult {
|
|
122
130
|
ok: boolean;
|