@vaultcompass/conductor 0.8.1 → 0.10.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 +261 -46
- package/dist/cli.d.ts +6 -0
- package/dist/cli.js +20 -5
- package/dist/envelope.d.ts +8 -0
- package/dist/exit-codes.d.ts +52 -2
- package/dist/exit-codes.js +64 -14
- package/dist/gate-runner.d.ts +124 -11
- package/dist/gate-runner.js +491 -60
- package/dist/git.d.ts +15 -0
- package/dist/git.js +20 -0
- package/dist/init-hook-detect.d.ts +1 -0
- package/dist/init-hook-detect.js +45 -0
- package/dist/init-policy.js +51 -2
- package/dist/init.d.ts +8 -0
- package/dist/init.js +166 -20
- package/dist/intent-prepare.d.ts +18 -1
- package/dist/intent-prepare.js +23 -2
- package/dist/normalize.d.ts +43 -2
- package/dist/normalize.js +168 -10
- package/dist/osv-baseline.d.ts +84 -0
- package/dist/osv-baseline.js +325 -0
- package/dist/osv-coverage.d.ts +80 -0
- package/dist/osv-coverage.js +223 -0
- package/dist/output-sarif.js +61 -2
- package/dist/output-text.d.ts +31 -3
- package/dist/output-text.js +354 -26
- package/dist/policy.d.ts +18 -0
- package/dist/policy.js +45 -6
- package/dist/products.d.ts +40 -11
- package/dist/products.js +87 -9
- package/dist/requirements-pin.d.ts +47 -0
- package/dist/requirements-pin.js +256 -0
- package/dist/run.d.ts +17 -0
- package/dist/run.js +29 -4
- package/dist/trust-base.d.ts +19 -0
- package/dist/trust-base.js +30 -1
- package/dist/unread-manifests.d.ts +14 -0
- package/dist/unread-manifests.js +69 -0
- package/package.json +1 -1
- package/schema/guardrails.schema.json +10 -0
package/dist/exit-codes.js
CHANGED
|
@@ -30,20 +30,70 @@
|
|
|
30
30
|
// maximum of the children's, and that is deliberate.
|
|
31
31
|
//
|
|
32
32
|
// The umbrella never overrules a gate's own blocking decision. A gate that
|
|
33
|
-
// exited non-zero produces a non-zero composed code,
|
|
34
|
-
// per-finding `blocking` flag can only ADD to that,
|
|
35
|
-
// exists so a gate whose exit code somehow said clean
|
|
36
|
-
// carried a blocking finding still fails the run.
|
|
33
|
+
// exited non-zero produces a non-zero composed code, with exactly one
|
|
34
|
+
// exception, below. The per-finding `blocking` flag can only ADD to that,
|
|
35
|
+
// never subtract: it exists so a gate whose exit code somehow said clean
|
|
36
|
+
// while its own report carried a blocking finding still fails the run.
|
|
37
37
|
//
|
|
38
|
-
//
|
|
39
|
-
//
|
|
40
|
-
//
|
|
41
|
-
//
|
|
42
|
-
//
|
|
43
|
-
//
|
|
44
|
-
//
|
|
45
|
-
//
|
|
46
|
-
//
|
|
38
|
+
// Two written decisions change what reaches this composition, and both are
|
|
39
|
+
// the repository's own lines in its policy file rather than a judgment made
|
|
40
|
+
// here.
|
|
41
|
+
//
|
|
42
|
+
// First, a gate carrying `enforce: false` is left out of this composition
|
|
43
|
+
// entirely. That is the adoption ramp, so a gate can be switched on and read
|
|
44
|
+
// for a few weeks before it is allowed to refuse anybody's commit. It is not
|
|
45
|
+
// a downgrade: the gate still runs, its findings keep their own levels, its
|
|
46
|
+
// blocking flags are untouched, and both output formats say plainly that it
|
|
47
|
+
// blocked and was not enforced. Nothing here reads a gate's output and
|
|
48
|
+
// decides on its own judgment to ignore it.
|
|
49
|
+
//
|
|
50
|
+
// Second, the vulnerabilities gate under `present-on-base: report` (osv
|
|
51
|
+
// design, section 4.3): a non-zero osv-scanner exit does not block when ALL
|
|
52
|
+
// of (a) to (f) in `gateExitBlocks` hold, which is a compared pull-request
|
|
53
|
+
// run whose every parsed finding is also on the base branch, under a key the
|
|
54
|
+
// BASE policy wrote, with no non-advisory verdict in the output. That is a
|
|
55
|
+
// set difference of two runs of the same tool, not a judgment about any one
|
|
56
|
+
// finding, and the findings still print with their labels.
|
|
57
|
+
/**
|
|
58
|
+
* Whether this gate's own child exit blocks the run.
|
|
59
|
+
*
|
|
60
|
+
* Every "the child exited non-zero" decision goes through here: the composed
|
|
61
|
+
* exit code, the verdict token's count, the verdict sentence, the
|
|
62
|
+
* not-enforced note and the SARIF gate-not-enforced notification. A reader
|
|
63
|
+
* that compares the raw exit with 0 instead would say "blocked" on a run
|
|
64
|
+
* that exits 0 (tests/osv-exit.test.ts holds every reader to this).
|
|
65
|
+
*
|
|
66
|
+
* False for an exit of 0 (or no child). For a non-zero exit, true unless ALL
|
|
67
|
+
* of these hold:
|
|
68
|
+
* (a) the gate is the vulnerabilities gate, osv-scanner in that role;
|
|
69
|
+
* (b) its base policy said present-on-base: report;
|
|
70
|
+
* (c) a base comparison ran (it is carried on the outcome only then);
|
|
71
|
+
* (d) at least one finding was parsed, since exit 1 with nothing parsed
|
|
72
|
+
* is a verdict this umbrella cannot read;
|
|
73
|
+
* (e) every finding is labelled present-on-base. Redundant by
|
|
74
|
+
* construction: under report an introduced finding stays blocking,
|
|
75
|
+
* which blocks the run through `hasBlockingFinding` whatever this
|
|
76
|
+
* returns. Kept so the predicate states the whole rule;
|
|
77
|
+
* (f) the head output carried no verdict that is not an advisory: no
|
|
78
|
+
* license_violations, no deprecated package, no other unmapped
|
|
79
|
+
* package-level field. osv-scanner exits 1 for those too, and none of
|
|
80
|
+
* them is a finding here.
|
|
81
|
+
*/
|
|
82
|
+
export function gateExitBlocks(gate) {
|
|
83
|
+
if ((gate.exitCode ?? 0) === 0) {
|
|
84
|
+
return false;
|
|
85
|
+
}
|
|
86
|
+
const comparison = gate.baseComparison;
|
|
87
|
+
const reportedNotBlocking = gate.role === 'vulnerabilities' &&
|
|
88
|
+
gate.product === 'osv-scanner' &&
|
|
89
|
+
comparison !== undefined &&
|
|
90
|
+
comparison.policy === 'report' &&
|
|
91
|
+
gate.couldNotRun === null &&
|
|
92
|
+
gate.findings.length > 0 &&
|
|
93
|
+
gate.findings.every((finding) => finding.details.baseline === 'present-on-base') &&
|
|
94
|
+
comparison.otherVerdicts.length === 0;
|
|
95
|
+
return !reportedNotBlocking;
|
|
96
|
+
}
|
|
47
97
|
export const EXIT_OK = 0;
|
|
48
98
|
export const EXIT_BLOCKED = 1;
|
|
49
99
|
export const EXIT_COULD_NOT_RUN = 2;
|
|
@@ -52,7 +102,7 @@ export function composeExitCode(gates) {
|
|
|
52
102
|
if (enforced.some((gate) => gate.couldNotRun !== null)) {
|
|
53
103
|
return EXIT_COULD_NOT_RUN;
|
|
54
104
|
}
|
|
55
|
-
if (enforced.some((gate) =>
|
|
105
|
+
if (enforced.some((gate) => gate.exitBlocks || gate.hasBlockingFinding)) {
|
|
56
106
|
return EXIT_BLOCKED;
|
|
57
107
|
}
|
|
58
108
|
return EXIT_OK;
|
package/dist/gate-runner.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { Diagnostic, Finding, RunSummary } from './envelope.js';
|
|
2
2
|
import type { ContractSource, IntentPreparation } from './intent-prepare.js';
|
|
3
3
|
import type { GatePolicy, GateRole, GateStage, Product } from './policy.js';
|
|
4
|
+
import { type BaseComparison } from './osv-baseline.js';
|
|
4
5
|
import type { ResolvedBinary } from './resolve.js';
|
|
5
6
|
export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing' | 'spawn-failed' | 'gate-error' | 'unparseable-output'
|
|
6
7
|
/**
|
|
@@ -48,10 +49,37 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
|
|
|
48
49
|
* inside the pull request is never seen). Never unshallowed automatically:
|
|
49
50
|
* the remedy is a checkout setting, fetch-depth: 0.
|
|
50
51
|
*/
|
|
51
|
-
| 'history-shallow'
|
|
52
|
+
| 'history-shallow'
|
|
53
|
+
/**
|
|
54
|
+
* conductor stopped the gate at its time limit (`timeout-seconds` in the
|
|
55
|
+
* policy, else the product's default). Decided by the spawn error code
|
|
56
|
+
* ETIMEDOUT alone, never by the signal or the status: a child that handled
|
|
57
|
+
* SIGTERM can return status 0, or its blocked code, with a clean report.
|
|
58
|
+
* Raised for the version probe, the scan, and the intent gate's
|
|
59
|
+
* preparation steps; `timedOut.step` says which spawn was stopped.
|
|
60
|
+
*/
|
|
61
|
+
| 'timed-out';
|
|
62
|
+
/** Where a gate's time limit came from: the test hook, the policy, or the product default. */
|
|
63
|
+
export type TimeLimitSource = 'override' | 'policy' | 'default';
|
|
64
|
+
export interface TimeLimit {
|
|
65
|
+
ms: number;
|
|
66
|
+
source: TimeLimitSource;
|
|
67
|
+
}
|
|
68
|
+
/** Which of a gate's spawns was stopped at the limit. The intent gate's check is `scan`. */
|
|
69
|
+
export type TimedOutStep = 'version-probe' | 'scan' | 'import-spec' | 'freeze';
|
|
70
|
+
export interface TimedOut {
|
|
71
|
+
step: TimedOutStep;
|
|
72
|
+
limitSeconds: number;
|
|
73
|
+
elapsedSeconds: number;
|
|
74
|
+
limitSource: TimeLimitSource;
|
|
75
|
+
/** What spawnSync reported; null when the child handled SIGTERM and exited itself. Never used to classify. */
|
|
76
|
+
signal: string | null;
|
|
77
|
+
}
|
|
52
78
|
export interface CouldNotRun {
|
|
53
79
|
reason: CouldNotRunReason;
|
|
54
80
|
detail: string;
|
|
81
|
+
/** Present only for `timed-out`. */
|
|
82
|
+
timedOut?: TimedOut;
|
|
55
83
|
/**
|
|
56
84
|
* What the gate itself said about why it could not run: a short, bounded,
|
|
57
85
|
* sanitised excerpt of its own stderr (first line) or, failing that, of a
|
|
@@ -73,10 +101,41 @@ export declare const GATE_SAID_MAX_CHARS = 160;
|
|
|
73
101
|
export declare function breakWorkflowMarkers(text: string): string;
|
|
74
102
|
/**
|
|
75
103
|
* The could-not-run reasons that are conductor's OWN decision, made before
|
|
76
|
-
* the gate was spawned (or instead of spawning it),
|
|
77
|
-
* the gate itself said or did.
|
|
104
|
+
* the gate was spawned (or instead of spawning it), or the umbrella stopping
|
|
105
|
+
* it, as opposed to something the gate itself said or did.
|
|
78
106
|
*/
|
|
79
107
|
export declare const CONDUCTOR_OWN_REASONS: ReadonlySet<CouldNotRunReason>;
|
|
108
|
+
/**
|
|
109
|
+
* A gate's time limit, and where it came from. THE ONE PLACE the precedence
|
|
110
|
+
* is written: the test hook (`RunGateOptions.timeoutMs`, which no CLI path
|
|
111
|
+
* sets), then the policy's `timeout-seconds`, then the product's default.
|
|
112
|
+
* runGate and the intent gate's preparation in run.ts both call this, so the
|
|
113
|
+
* two cannot disagree about a gate's limit.
|
|
114
|
+
*/
|
|
115
|
+
export declare function resolveTimeLimit(gate: GatePolicy, override: number | undefined): TimeLimit;
|
|
116
|
+
/** What a spawn error was: the umbrella's deadline, or anything else. */
|
|
117
|
+
export type SpawnFailure = {
|
|
118
|
+
reason: 'timed-out';
|
|
119
|
+
signal: string | null;
|
|
120
|
+
} | {
|
|
121
|
+
reason: 'spawn-failed';
|
|
122
|
+
message: string;
|
|
123
|
+
};
|
|
124
|
+
/**
|
|
125
|
+
* Classifies a spawnSync result that carries an error. PURE, so it is tested
|
|
126
|
+
* on hand-built results.
|
|
127
|
+
*
|
|
128
|
+
* THE ERROR CODE ALONE decides it. ETIMEDOUT is timed-out and nothing else
|
|
129
|
+
* is. No status or signal condition belongs here: a child that traps SIGTERM,
|
|
130
|
+
* or ignores it and exits on its own, comes back with status 0 (or its
|
|
131
|
+
* blocked code) and signal null, and ENOBUFS arrives with the same SIGTERM a
|
|
132
|
+
* timeout does. The signal is recorded for the report and never classifies.
|
|
133
|
+
*/
|
|
134
|
+
export declare function spawnFailure(child: {
|
|
135
|
+
error?: Error | undefined;
|
|
136
|
+
status?: number | null;
|
|
137
|
+
signal?: NodeJS.Signals | string | null;
|
|
138
|
+
}): SpawnFailure | null;
|
|
80
139
|
/**
|
|
81
140
|
* conductor's own reason for a could-not-run, as a job-log excerpt: cleaned,
|
|
82
141
|
* one line, capped and with double quotes replaced, exactly like a gate's
|
|
@@ -93,12 +152,15 @@ export declare function cleanOutputLine(raw: string): string;
|
|
|
93
152
|
* What a gate that exited with a non-verdict code said about why.
|
|
94
153
|
*
|
|
95
154
|
* TOTAL, and never a decision: the caller has already settled that this is a
|
|
96
|
-
* could-not-run, and nothing here can change that.
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
-
*
|
|
100
|
-
*
|
|
101
|
-
*
|
|
155
|
+
* could-not-run, and nothing here can change that. stderr is preferred, since
|
|
156
|
+
* that is where every gate in the family prints its reason on exit 2
|
|
157
|
+
* (dep-guard, intent-guard and vault-guard all do), read by the rule in
|
|
158
|
+
* `statedReasonFromStderr`: the line the gate marks as the failure, never an
|
|
159
|
+
* informational line. Failing that, stdout is parsed only for a gate whose
|
|
160
|
+
* output is JSON on stdout, and only a string `reason` field (top level, or
|
|
161
|
+
* on `run`) is read; anything else, including output that does not parse, is
|
|
162
|
+
* simply no excerpt. An absent excerpt is better than quoting a warning as
|
|
163
|
+
* the cause; the full stderr is still printed in the text report.
|
|
102
164
|
*/
|
|
103
165
|
export declare function gateStatedReason(stderr: string, stdout: string | null | undefined, stdoutIsJson: boolean): string | null;
|
|
104
166
|
/**
|
|
@@ -257,6 +319,30 @@ export interface GateOutcome {
|
|
|
257
319
|
found: string;
|
|
258
320
|
path: string;
|
|
259
321
|
};
|
|
322
|
+
/**
|
|
323
|
+
* The vulnerabilities gate only, and only when a base comparison ran (a
|
|
324
|
+
* pull-request run whose head scan blocked with at least one finding): the
|
|
325
|
+
* ref, the base policy's present-on-base value, the counts, the lockfiles
|
|
326
|
+
* the comparison was unavailable for, and any non-advisory verdict in the
|
|
327
|
+
* head output. Carried here, like `enforce`, so a report and the exit
|
|
328
|
+
* decision (gateExitBlocks) never need the policy file.
|
|
329
|
+
*/
|
|
330
|
+
baseComparison?: BaseComparison;
|
|
331
|
+
/**
|
|
332
|
+
* The time limit this gate ran under and where it came from, carried like
|
|
333
|
+
* `enforce` so the report and the timed-out message never need the policy
|
|
334
|
+
* file. Set on every outcome runGate builds once the limit is resolved.
|
|
335
|
+
*/
|
|
336
|
+
timeLimit?: TimeLimit;
|
|
337
|
+
/**
|
|
338
|
+
* The `conductor/option-is-gate-own` note: set when the secrets-history
|
|
339
|
+
* gate's options carry `timeout`, which is gitleaks' own --timeout and not
|
|
340
|
+
* conductor's limit. On the OUTCOME rather than in `run.diagnostics`,
|
|
341
|
+
* because every could-not-run outcome carries an empty run, and the
|
|
342
|
+
* gate-error that gitleaks' own deadline produces is exactly the outcome
|
|
343
|
+
* that needs the note. Information only; nothing decides on it.
|
|
344
|
+
*/
|
|
345
|
+
gateOwnOption?: string;
|
|
260
346
|
}
|
|
261
347
|
export interface RunGateOptions {
|
|
262
348
|
/**
|
|
@@ -269,7 +355,10 @@ export interface RunGateOptions {
|
|
|
269
355
|
staged: boolean;
|
|
270
356
|
/** PATH to search. Injected so tests never depend on the machine. */
|
|
271
357
|
pathValue: string;
|
|
272
|
-
/**
|
|
358
|
+
/**
|
|
359
|
+
* A test hook: the time limit for every spawn of this gate, outranking the
|
|
360
|
+
* policy's timeout-seconds. No CLI path sets it. See `resolveTimeLimit`.
|
|
361
|
+
*/
|
|
273
362
|
timeoutMs?: number;
|
|
274
363
|
/** The contract and change set prepared for the intent gate, when there is one. */
|
|
275
364
|
intent?: IntentPreparation;
|
|
@@ -307,6 +396,19 @@ export interface RunGateOptions {
|
|
|
307
396
|
* would have to learn about.
|
|
308
397
|
*/
|
|
309
398
|
export declare function preparationFailed(gate: GatePolicy, detail: string): GateOutcome;
|
|
399
|
+
/**
|
|
400
|
+
* The intent gate whose preparation step (import-spec or freeze) was stopped
|
|
401
|
+
* at the gate's time limit. Shaped like `preparationFailed`, with the
|
|
402
|
+
* timed-out reason, so it composes the same way; the caller decides
|
|
403
|
+
* `enforce` under the same rule it applies to a failed preparation.
|
|
404
|
+
*/
|
|
405
|
+
export declare function preparationTimedOut(gate: GatePolicy, stopped: {
|
|
406
|
+
step: 'import-spec' | 'freeze';
|
|
407
|
+
elapsedMs: number;
|
|
408
|
+
signal: string | null;
|
|
409
|
+
limit: TimeLimit;
|
|
410
|
+
trustBase?: string;
|
|
411
|
+
}): GateOutcome;
|
|
310
412
|
/**
|
|
311
413
|
* EVERY program this binary would spawn, vetted against the trust base.
|
|
312
414
|
*
|
|
@@ -354,8 +456,19 @@ export interface ExternalArgs {
|
|
|
354
456
|
* .gitleaksignore at its root for gitleaks to load on its own.
|
|
355
457
|
*/
|
|
356
458
|
scanRoot?: string;
|
|
357
|
-
/**
|
|
459
|
+
/**
|
|
460
|
+
* The files osv-scanner is handed: repository-relative on the head run,
|
|
461
|
+
* absolute copies under the work directory on the base run.
|
|
462
|
+
*/
|
|
358
463
|
lockfiles?: readonly string[];
|
|
464
|
+
/**
|
|
465
|
+
* Whether this invocation gets --no-resolve. Decided once, from the HEAD
|
|
466
|
+
* run's list (any requirements file), and handed to the base run as is, so
|
|
467
|
+
* the two command lines cannot differ in resolution mode because the base
|
|
468
|
+
* run scans a different subset (osv design, section 2.4). Absent means
|
|
469
|
+
* "decide from `lockfiles`".
|
|
470
|
+
*/
|
|
471
|
+
noResolve?: boolean;
|
|
359
472
|
}
|
|
360
473
|
/**
|
|
361
474
|
* The arguments the umbrella adds, per product.
|