@vaultcompass/conductor 0.4.6 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +526 -169
- package/dist/cli.js +47 -9
- package/dist/envelope.js +1 -1
- package/dist/exit-codes.js +5 -1
- package/dist/external-config.d.ts +54 -0
- package/dist/external-config.js +171 -0
- package/dist/gate-runner.d.ts +43 -3
- package/dist/gate-runner.js +463 -37
- package/dist/init-policy.d.ts +19 -1
- package/dist/init-policy.js +42 -8
- package/dist/init.d.ts +30 -1
- package/dist/init.js +108 -19
- package/dist/normalize.d.ts +7 -1
- package/dist/normalize.js +309 -5
- package/dist/output-sarif.js +3 -2
- package/dist/output-text.d.ts +41 -0
- package/dist/output-text.js +68 -9
- package/dist/policy.d.ts +10 -4
- package/dist/policy.js +100 -14
- package/dist/products.d.ts +91 -0
- package/dist/products.js +123 -0
- package/dist/resolve.js +18 -4
- package/dist/run.js +3 -0
- package/package.json +1 -1
- package/schema/guardrails.schema.json +7 -5
package/dist/policy.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
// The one policy file.
|
|
2
2
|
//
|
|
3
|
-
// Gates are keyed by the ROLE they fill (dependencies, secrets, intent
|
|
3
|
+
// Gates are keyed by the ROLE they fill (dependencies, secrets, intent,
|
|
4
|
+
// secrets-history, vulnerabilities) and
|
|
4
5
|
// name the product filling it in a `product` field. That indirection is
|
|
5
6
|
// worth the extra line: a product rename, or swapping one gate for another,
|
|
6
7
|
// becomes a one-line edit instead of a rename of the key a repository wrote
|
|
@@ -9,18 +10,19 @@
|
|
|
9
10
|
// Two rules this file exists to enforce, both of them decisions rather than
|
|
10
11
|
// mechanics:
|
|
11
12
|
//
|
|
12
|
-
// 1. THERE IS NO SHARED SEVERITY THRESHOLD.
|
|
13
|
-
//
|
|
14
|
-
// rubric from 0 to 100
|
|
15
|
-
//
|
|
16
|
-
//
|
|
13
|
+
// 1. THERE IS NO SHARED SEVERITY THRESHOLD. Five products, two of them
|
|
14
|
+
// external tools. Two of the family's three share a four-level scale; the
|
|
15
|
+
// third scores a weighted rubric from 0 to 100, gitleaks reports match
|
|
16
|
+
// or no match, and osv-scanner carries CVSS scores. A single `failOn` at
|
|
17
|
+
// the top of the file would read as one decision and mean five
|
|
18
|
+
// different things, so a top-level `failOn` is rejected outright
|
|
17
19
|
// rather than silently ignored. Each gate keeps its own threshold in
|
|
18
20
|
// its own passthrough block, spelled the way that gate spells it.
|
|
19
21
|
//
|
|
20
22
|
// 2. THE PASSTHROUGH IS ACTUALLY A PASSTHROUGH. `options` keys are the
|
|
21
23
|
// gate's own long-flag names with the dashes stripped, and this file
|
|
22
24
|
// never maps, renames, or interprets one. That is what keeps the
|
|
23
|
-
// umbrella from growing a second, drifting copy of
|
|
25
|
+
// umbrella from growing a second, drifting copy of five CLIs, and it
|
|
24
26
|
// is why a gate gains a flag without this package needing a release.
|
|
25
27
|
// The only keys rejected are the handful the umbrella itself passes,
|
|
26
28
|
// because two writers of the same flag is a fight the user would have
|
|
@@ -34,8 +36,20 @@ import path from 'node:path';
|
|
|
34
36
|
import { fileURLToPath } from 'node:url';
|
|
35
37
|
import { parse as parseYaml } from 'yaml';
|
|
36
38
|
export const POLICY_FILE_NAME = '.guardrails.yaml';
|
|
37
|
-
export const GATE_ROLES = [
|
|
38
|
-
|
|
39
|
+
export const GATE_ROLES = [
|
|
40
|
+
'dependencies',
|
|
41
|
+
'secrets',
|
|
42
|
+
'intent',
|
|
43
|
+
'secrets-history',
|
|
44
|
+
'vulnerabilities',
|
|
45
|
+
];
|
|
46
|
+
/**
|
|
47
|
+
* Five products. The first three are this family's own npm packages, which
|
|
48
|
+
* the Action installs. The last two are external tools the adopter installs
|
|
49
|
+
* on their own machine or runner; conductor finds them on PATH and downloads
|
|
50
|
+
* nothing (src/products.ts, `managed: false`).
|
|
51
|
+
*/
|
|
52
|
+
export const PRODUCTS = ['dep-guard', 'vault-guard', 'intent-guard', 'gitleaks', 'osv-scanner'];
|
|
39
53
|
/**
|
|
40
54
|
* When a gate runs, in order, earliest first.
|
|
41
55
|
*
|
|
@@ -49,8 +63,8 @@ export const GATE_STAGES = ['commit', 'push', 'ci'];
|
|
|
49
63
|
/**
|
|
50
64
|
* Where each gate sits when the policy file does not say.
|
|
51
65
|
*
|
|
52
|
-
* Runtime is not what decides this
|
|
53
|
-
* second on a staged commit; the cost is CEREMONY, and only the intent gate
|
|
66
|
+
* Runtime is not what decides this for the three family gates: together they
|
|
67
|
+
* take under a second on a staged commit; the cost is CEREMONY, and only the intent gate
|
|
54
68
|
* has any, because it wants a contract approved before the work starts.
|
|
55
69
|
* The other two are silent until they find something, and a secret that
|
|
56
70
|
* reaches a pull request is already on a remote, so the earliest stage is
|
|
@@ -60,6 +74,11 @@ export const DEFAULT_STAGE_FOR_ROLE = {
|
|
|
60
74
|
dependencies: 'commit',
|
|
61
75
|
secrets: 'commit',
|
|
62
76
|
intent: 'ci',
|
|
77
|
+
// A history scan and a registry lookup are pull-request work, not
|
|
78
|
+
// commit-time work: one reads every commit, the other asks a network
|
|
79
|
+
// service, and neither says anything about the files being staged.
|
|
80
|
+
'secrets-history': 'ci',
|
|
81
|
+
vulnerabilities: 'ci',
|
|
63
82
|
};
|
|
64
83
|
/** Whether a gate at `gateStage` runs during a run asked for at `requested`. */
|
|
65
84
|
export function runsAtStage(gateStage, requested) {
|
|
@@ -79,6 +98,8 @@ export const PRODUCT_FOR_ROLE = {
|
|
|
79
98
|
dependencies: 'dep-guard',
|
|
80
99
|
secrets: 'vault-guard',
|
|
81
100
|
intent: 'intent-guard',
|
|
101
|
+
'secrets-history': 'gitleaks',
|
|
102
|
+
vulnerabilities: 'osv-scanner',
|
|
82
103
|
};
|
|
83
104
|
/**
|
|
84
105
|
* Flags the umbrella supplies itself, per product. A policy that also sets
|
|
@@ -112,6 +133,27 @@ export const RESERVED_OPTIONS = {
|
|
|
112
133
|
// problem rather than a confusion, since the loser decides where the gate
|
|
113
134
|
// reads its rules from.
|
|
114
135
|
'intent-guard': ['json', 'staged', 'project', 'paths', 'base', 'trust-base'],
|
|
136
|
+
// The umbrella writes every one of these for gitleaks: the report goes to a
|
|
137
|
+
// file it owns, the exit code for a leak is moved off 1 so an error and a
|
|
138
|
+
// leak stop sharing a number, history is scoped by --log-opts so one
|
|
139
|
+
// branch's secret cannot redden every other pull request, and the config
|
|
140
|
+
// is read from the base ref on a pull request, as is the ignore file.
|
|
141
|
+
gitleaks: [
|
|
142
|
+
'report-format',
|
|
143
|
+
'report-path',
|
|
144
|
+
'exit-code',
|
|
145
|
+
'log-opts',
|
|
146
|
+
'config',
|
|
147
|
+
'gitleaks-ignore-path',
|
|
148
|
+
'ignore-gitleaks-allow',
|
|
149
|
+
'redact',
|
|
150
|
+
'no-banner',
|
|
151
|
+
'log-level',
|
|
152
|
+
],
|
|
153
|
+
// osv-scanner: the umbrella owns the format (json to stdout), the config on
|
|
154
|
+
// a pull-request run, and which lockfiles are scanned (every tracked one,
|
|
155
|
+
// by name; there is no directory walk and so no --recursive).
|
|
156
|
+
'osv-scanner': ['format', 'config', 'lockfile'],
|
|
115
157
|
};
|
|
116
158
|
export class PolicyError extends Error {
|
|
117
159
|
constructor(message) {
|
|
@@ -175,18 +217,62 @@ function reservedReason(product, key) {
|
|
|
175
217
|
"Use the umbrella's own --base instead.");
|
|
176
218
|
}
|
|
177
219
|
if (product === 'dep-guard' && key === 'base') {
|
|
178
|
-
return ('
|
|
179
|
-
'
|
|
180
|
-
'
|
|
220
|
+
return ('On a pull-request run the umbrella writes --base to this gate itself, pointing at the ' +
|
|
221
|
+
'same ref as --trust-base, so a value here would be a second writer of the flag that ' +
|
|
222
|
+
'decides what changed. Otherwise the umbrella passes --staged on a staged run, and a ' +
|
|
223
|
+
"base here would fight it: dep-guard's own CLI refuses --staged and --base together. On " +
|
|
224
|
+
'a plain run the umbrella passes neither flag, and a base here would silently decide ' +
|
|
225
|
+
'what that run compares dependencies against, without going through the trust base the ' +
|
|
226
|
+
'umbrella itself decided. Leave it off; the umbrella decides it either way.');
|
|
181
227
|
}
|
|
182
228
|
if (product === 'vault-guard' && key === 'format') {
|
|
183
229
|
return ('The umbrella writes this option itself under its short name, -f json. A --format here ' +
|
|
184
230
|
'is a second writer of the same option, and which one wins depends on that CLI argument ' +
|
|
185
231
|
'parser. The report format is chosen with the umbrella own --format.');
|
|
186
232
|
}
|
|
233
|
+
const external = EXTERNAL_RESERVED_REASONS[product]?.[key];
|
|
234
|
+
if (external !== undefined) {
|
|
235
|
+
return `The umbrella passes --${key} to ${product} itself. ${external}`;
|
|
236
|
+
}
|
|
187
237
|
return (`The umbrella passes that flag to ${product} itself, and two writers of one flag ` +
|
|
188
238
|
'would resolve differently depending on that CLI argument parser.');
|
|
189
239
|
}
|
|
240
|
+
/**
|
|
241
|
+
* Why each flag the umbrella writes for an external tool is the umbrella's.
|
|
242
|
+
* Every one of them is written; the sentence says what a second writer would
|
|
243
|
+
* break, which for these tools is a verdict rather than a formatting detail.
|
|
244
|
+
*/
|
|
245
|
+
const EXTERNAL_RESERVED_REASONS = {
|
|
246
|
+
gitleaks: {
|
|
247
|
+
'report-format': 'The report is parsed as JSON; another format would make every run unparseable.',
|
|
248
|
+
'report-path': 'The report goes to a file the umbrella owns and reads back; pointing it elsewhere would ' +
|
|
249
|
+
'leave the umbrella nothing to read.',
|
|
250
|
+
'exit-code': 'The umbrella moves the leak exit code to 3 because gitleaks also exits 1 on an error; ' +
|
|
251
|
+
'another value would make a crash read as a leak, or a leak read as clean.',
|
|
252
|
+
'log-opts': 'The umbrella scopes history to HEAD, or to base..HEAD on a pull request, so a secret on ' +
|
|
253
|
+
'another branch cannot redden this one. Narrow the scan in .gitleaks.toml instead.',
|
|
254
|
+
config: 'On a pull request the config is read from the base ref, so the pull request cannot ' +
|
|
255
|
+
'allowlist what it adds. Commit .gitleaks.toml instead.',
|
|
256
|
+
'gitleaks-ignore-path': 'On a pull request the ignore file is read from the base ref, so the pull request cannot ' +
|
|
257
|
+
'ignore the fingerprint of the leak it adds. Commit .gitleaksignore instead.',
|
|
258
|
+
'ignore-gitleaks-allow': 'On a pull request inline gitleaks:allow comments are ignored, because an inline allow ' +
|
|
259
|
+
'lives in the tree being judged and the pull request controls it. A legitimate allow ' +
|
|
260
|
+
'belongs in the base ref .gitleaks.toml allowlist or .gitleaksignore.',
|
|
261
|
+
redact: 'Findings reach a pull-request comment and a SARIF upload; the umbrella keeps secrets ' +
|
|
262
|
+
'redacted in the report it reads.',
|
|
263
|
+
'no-banner': 'The banner is noise on stderr, which the report shows when a gate fails.',
|
|
264
|
+
'log-level': 'The umbrella depends on gitleaks ERR lines to tell a failed scan from a clean one: gitleaks ' +
|
|
265
|
+
'reports a git failure as exit 0 with an empty report. A lower level would silence them and ' +
|
|
266
|
+
'turn a scan that never happened into a pass, so the umbrella pins it at info.',
|
|
267
|
+
},
|
|
268
|
+
'osv-scanner': {
|
|
269
|
+
format: 'The output is parsed as JSON from stdout; another format would make every run unparseable.',
|
|
270
|
+
config: 'On a pull request the config is read from the base ref, so the pull request cannot ' +
|
|
271
|
+
'ignore the advisory it introduces. Commit osv-scanner.toml instead.',
|
|
272
|
+
lockfile: 'The umbrella hands osv-scanner every tracked lockfile by name, so no lockfile is left ' +
|
|
273
|
+
'out by a policy line or by a .gitignore entry.',
|
|
274
|
+
},
|
|
275
|
+
};
|
|
190
276
|
/**
|
|
191
277
|
* Parses and validates policy YAML.
|
|
192
278
|
*
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import type { Product } from './policy.js';
|
|
2
|
+
export type OutputSource = {
|
|
3
|
+
kind: 'stdout';
|
|
4
|
+
} | {
|
|
5
|
+
kind: 'report-file';
|
|
6
|
+
flag: string;
|
|
7
|
+
extension: string;
|
|
8
|
+
};
|
|
9
|
+
export interface ExitSemantics {
|
|
10
|
+
clean: readonly number[];
|
|
11
|
+
blocked: readonly number[];
|
|
12
|
+
/** Exits that mean "there was nothing here to scan": clean, with a diagnostic. */
|
|
13
|
+
nothingToScan: readonly number[];
|
|
14
|
+
}
|
|
15
|
+
export interface VersionProbeSpec {
|
|
16
|
+
argv: readonly string[];
|
|
17
|
+
/**
|
|
18
|
+
* Applied to the trimmed first line of the probe's stdout. Capture group 1
|
|
19
|
+
* is the version when the pattern has one; otherwise the whole match is.
|
|
20
|
+
*/
|
|
21
|
+
pattern: RegExp;
|
|
22
|
+
}
|
|
23
|
+
export interface ProductProfile {
|
|
24
|
+
product: Product;
|
|
25
|
+
/** Installed by the Action from npm and covered by npm audit signatures. */
|
|
26
|
+
managed: boolean;
|
|
27
|
+
versionProbe: VersionProbeSpec | null;
|
|
28
|
+
output: OutputSource;
|
|
29
|
+
exit: ExitSemantics;
|
|
30
|
+
timeoutMs: number;
|
|
31
|
+
/** Oldest version whose command line this runner speaks; null means any. */
|
|
32
|
+
minVersion: string | null;
|
|
33
|
+
/** Config file the tool auto-loads from the scanned tree; read from the base ref on a pull request. */
|
|
34
|
+
configFile: string | null;
|
|
35
|
+
/** What to pass as the config when the base ref has none, so the head's cannot be auto-loaded. */
|
|
36
|
+
neutralConfig: string | null;
|
|
37
|
+
/**
|
|
38
|
+
* A second file the tool auto-loads from the scanned tree that suppresses
|
|
39
|
+
* findings, and the flag that points it elsewhere. Read from the base ref
|
|
40
|
+
* on a pull request, like the config.
|
|
41
|
+
*/
|
|
42
|
+
ignoreFile: {
|
|
43
|
+
name: string;
|
|
44
|
+
flag: string;
|
|
45
|
+
/**
|
|
46
|
+
* The tool ALSO loads `<scan root>/<name>` whatever the flag says, so on
|
|
47
|
+
* a pull request the scan root must be somewhere the head cannot write.
|
|
48
|
+
*/
|
|
49
|
+
alsoLoadedFromScanRoot: boolean;
|
|
50
|
+
} | null;
|
|
51
|
+
/** How to install the tool, for a missing-binary finding. */
|
|
52
|
+
remedy: (skipNodeModules: boolean) => string;
|
|
53
|
+
/**
|
|
54
|
+
* A stderr line (ANSI colour stripped) that turns a clean exit into an
|
|
55
|
+
* error. Null for a tool whose exit code can be taken at its word.
|
|
56
|
+
*/
|
|
57
|
+
stderrError: RegExp | null;
|
|
58
|
+
/**
|
|
59
|
+
* File names the tool is handed one by one, from the repository's tracked
|
|
60
|
+
* files, instead of being pointed at a directory to walk. Null for a tool
|
|
61
|
+
* that is not handed files.
|
|
62
|
+
*/
|
|
63
|
+
lockfileNames: readonly string[] | null;
|
|
64
|
+
/**
|
|
65
|
+
* The config can name another file (`[extend] path`) that the tool reads
|
|
66
|
+
* relative to its working directory. On a pull request every such file is
|
|
67
|
+
* materialised from the base ref and the tool is run from that directory.
|
|
68
|
+
*/
|
|
69
|
+
followsConfigExtend: boolean;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* The lockfiles osv-scanner is handed, matched by base name at any depth
|
|
73
|
+
* among the repository's TRACKED files (`git ls-files`).
|
|
74
|
+
*
|
|
75
|
+
* By name, not by walking the tree, for three reasons: osv-scanner's own walk
|
|
76
|
+
* skips anything .gitignore matches, tracked or not, so a pull request could
|
|
77
|
+
* hide a committed lockfile from it with one ignore line; the walk can reach
|
|
78
|
+
* into node_modules; and an untracked lockfile is not part of what is being
|
|
79
|
+
* judged. Only the npm family is listed, because that is the ecosystem this
|
|
80
|
+
* family's own dependency gate knows (npm, pnpm, yarn, bun); osv-scanner
|
|
81
|
+
* supports more, and a repository whose only lockfile is another ecosystem's
|
|
82
|
+
* gets nothing-to-scan until a name is added here.
|
|
83
|
+
*/
|
|
84
|
+
export declare const OSV_LOCKFILE_NAMES: readonly string[];
|
|
85
|
+
/**
|
|
86
|
+
* The npm gates print a bare version. No capture group on purpose: the runner
|
|
87
|
+
* has always reported the whole first line minus a leading v, prerelease
|
|
88
|
+
* suffix included, and the trust-base floor compares that value.
|
|
89
|
+
*/
|
|
90
|
+
export declare const NPM_VERSION_PATTERN: RegExp;
|
|
91
|
+
export declare function profileFor(product: Product): ProductProfile;
|
package/dist/products.js
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
// What the runner needs to know about each product, as data.
|
|
2
|
+
//
|
|
3
|
+
// The runner used to hardcode one behaviour for every gate: ask --version,
|
|
4
|
+
// read JSON from stdout, read exit 0 as clean and 1 as blocked, give up after
|
|
5
|
+
// two minutes. That was true of the three npm gates and it is not true of the
|
|
6
|
+
// external tools, so the behaviour lives here per product and the runner
|
|
7
|
+
// consults it. The three npm profiles below restate exactly what the runner
|
|
8
|
+
// did before profiles existed; changing one of them changes a gate that
|
|
9
|
+
// adopters already run.
|
|
10
|
+
/**
|
|
11
|
+
* The lockfiles osv-scanner is handed, matched by base name at any depth
|
|
12
|
+
* among the repository's TRACKED files (`git ls-files`).
|
|
13
|
+
*
|
|
14
|
+
* By name, not by walking the tree, for three reasons: osv-scanner's own walk
|
|
15
|
+
* skips anything .gitignore matches, tracked or not, so a pull request could
|
|
16
|
+
* hide a committed lockfile from it with one ignore line; the walk can reach
|
|
17
|
+
* into node_modules; and an untracked lockfile is not part of what is being
|
|
18
|
+
* judged. Only the npm family is listed, because that is the ecosystem this
|
|
19
|
+
* family's own dependency gate knows (npm, pnpm, yarn, bun); osv-scanner
|
|
20
|
+
* supports more, and a repository whose only lockfile is another ecosystem's
|
|
21
|
+
* gets nothing-to-scan until a name is added here.
|
|
22
|
+
*/
|
|
23
|
+
export const OSV_LOCKFILE_NAMES = [
|
|
24
|
+
'package-lock.json',
|
|
25
|
+
'npm-shrinkwrap.json',
|
|
26
|
+
'pnpm-lock.yaml',
|
|
27
|
+
'yarn.lock',
|
|
28
|
+
'bun.lock',
|
|
29
|
+
];
|
|
30
|
+
/**
|
|
31
|
+
* The npm gates print a bare version. No capture group on purpose: the runner
|
|
32
|
+
* has always reported the whole first line minus a leading v, prerelease
|
|
33
|
+
* suffix included, and the trust-base floor compares that value.
|
|
34
|
+
*/
|
|
35
|
+
export const NPM_VERSION_PATTERN = /^v?\d+\.\d+\.\d+.*/;
|
|
36
|
+
const NPM_EXIT = { clean: [0], blocked: [1], nothingToScan: [] };
|
|
37
|
+
function managedRemedy(product) {
|
|
38
|
+
return (skipNodeModules) => skipNodeModules
|
|
39
|
+
? `Install the gate outside the tree with npm install -g @vaultcompass/${product}. The ` +
|
|
40
|
+
`conductor Action does exactly that, at the version its ${product}-version input pins, and ` +
|
|
41
|
+
'that pin lives in the workflow file on the base branch.'
|
|
42
|
+
: `Install it with npm install -g @vaultcompass/${product}, or add it to the repository's devDependencies.`;
|
|
43
|
+
}
|
|
44
|
+
function managedProfile(product) {
|
|
45
|
+
return {
|
|
46
|
+
product,
|
|
47
|
+
managed: true,
|
|
48
|
+
versionProbe: { argv: ['--version'], pattern: NPM_VERSION_PATTERN },
|
|
49
|
+
output: { kind: 'stdout' },
|
|
50
|
+
exit: NPM_EXIT,
|
|
51
|
+
timeoutMs: 120_000,
|
|
52
|
+
minVersion: null,
|
|
53
|
+
configFile: null,
|
|
54
|
+
neutralConfig: null,
|
|
55
|
+
ignoreFile: null,
|
|
56
|
+
remedy: managedRemedy(product),
|
|
57
|
+
stderrError: null,
|
|
58
|
+
lockfileNames: null,
|
|
59
|
+
followsConfigExtend: false,
|
|
60
|
+
};
|
|
61
|
+
}
|
|
62
|
+
const PROFILES = {
|
|
63
|
+
'dep-guard': managedProfile('dep-guard'),
|
|
64
|
+
'vault-guard': managedProfile('vault-guard'),
|
|
65
|
+
'intent-guard': managedProfile('intent-guard'),
|
|
66
|
+
gitleaks: {
|
|
67
|
+
product: 'gitleaks',
|
|
68
|
+
managed: false,
|
|
69
|
+
versionProbe: { argv: ['version'], pattern: /(\d+\.\d+\.\d+)/ },
|
|
70
|
+
// gitleaks writes its JSON report to a file, never to stdout.
|
|
71
|
+
output: { kind: 'report-file', flag: '--report-path', extension: '.json' },
|
|
72
|
+
// gitleaks exits 1 for a leak AND for an error by default. The umbrella
|
|
73
|
+
// passes --exit-code 3 (src/gate-runner.ts, gateArgs), so 3 is a leak and
|
|
74
|
+
// 1 is left meaning an error.
|
|
75
|
+
exit: { clean: [0], blocked: [3], nothingToScan: [] },
|
|
76
|
+
// A full-history scan on a large repository outlives the npm gates' two
|
|
77
|
+
// minutes; could-not-run on every pull request is the failure to avoid.
|
|
78
|
+
timeoutMs: 600_000,
|
|
79
|
+
minVersion: '8.19.0',
|
|
80
|
+
configFile: '.gitleaks.toml',
|
|
81
|
+
neutralConfig: '[extend]\nuseDefault = true\n',
|
|
82
|
+
// .gitleaksignore lists fingerprints the scan skips: a pull request
|
|
83
|
+
// adding its own leak's fingerprint there is the config hole through a
|
|
84
|
+
// second file. gitleaks 8.30.1 loads the one at --gitleaks-ignore-path
|
|
85
|
+
// AND the one at the root of the scanned source, whatever the flag says
|
|
86
|
+
// (observed against the real binary, tests/fixtures/README.md), so the
|
|
87
|
+
// flag alone does not close it.
|
|
88
|
+
ignoreFile: { name: '.gitleaksignore', flag: '--gitleaks-ignore-path', alsoLoadedFromScanRoot: true },
|
|
89
|
+
remedy: () => 'Install gitleaks 8.19 or later on the machine or runner before conductor runs (a pinned ' +
|
|
90
|
+
'release download with a checksum is the usual step), or disable the secrets-history gate ' +
|
|
91
|
+
'in .guardrails.yaml. conductor does not download it.',
|
|
92
|
+
// gitleaks 8.30.1 swallows a git failure: it logs "<time> ERR [git]
|
|
93
|
+
// fatal: ..." and exits 0 with an empty report (tests/fixtures/README.md).
|
|
94
|
+
stderrError: /^\S+\s+ERR\s/,
|
|
95
|
+
lockfileNames: null,
|
|
96
|
+
followsConfigExtend: true,
|
|
97
|
+
},
|
|
98
|
+
'osv-scanner': {
|
|
99
|
+
product: 'osv-scanner',
|
|
100
|
+
managed: false,
|
|
101
|
+
versionProbe: { argv: ['--version'], pattern: /(\d+\.\d+\.\d+)/ },
|
|
102
|
+
// JSON goes to stdout and everything else to stderr.
|
|
103
|
+
output: { kind: 'stdout' },
|
|
104
|
+
// 128 is osv-scanner's "no package sources found": a repository with no
|
|
105
|
+
// lockfile has nothing to scan, which is clean, not an error.
|
|
106
|
+
exit: { clean: [0], blocked: [1], nothingToScan: [128] },
|
|
107
|
+
timeoutMs: 300_000,
|
|
108
|
+
minVersion: '2.0.0',
|
|
109
|
+
configFile: 'osv-scanner.toml',
|
|
110
|
+
neutralConfig: '',
|
|
111
|
+
ignoreFile: null,
|
|
112
|
+
remedy: () => 'Install osv-scanner 2.x on the machine or runner before conductor runs, or disable the ' +
|
|
113
|
+
'vulnerabilities gate in .guardrails.yaml. conductor does not download it.',
|
|
114
|
+
// osv-scanner's exit codes separate an error (127) from a verdict, and
|
|
115
|
+
// its stderr is progress chatter, so the exit is taken at its word.
|
|
116
|
+
stderrError: null,
|
|
117
|
+
lockfileNames: OSV_LOCKFILE_NAMES,
|
|
118
|
+
followsConfigExtend: false,
|
|
119
|
+
},
|
|
120
|
+
};
|
|
121
|
+
export function profileFor(product) {
|
|
122
|
+
return PROFILES[product];
|
|
123
|
+
}
|
package/dist/resolve.js
CHANGED
|
@@ -61,6 +61,7 @@
|
|
|
61
61
|
// reported missing.
|
|
62
62
|
import { accessSync, constants, statSync } from 'node:fs';
|
|
63
63
|
import path from 'node:path';
|
|
64
|
+
import { profileFor } from './products.js';
|
|
64
65
|
export const CANDIDATES = {
|
|
65
66
|
'dep-guard': [{ name: 'dep-guard', prefix: ['scan'], versionSafe: true }],
|
|
66
67
|
'vault-guard': [{ name: 'vault-guard', prefix: ['scan'], versionSafe: true }],
|
|
@@ -74,6 +75,10 @@ export const CANDIDATES = {
|
|
|
74
75
|
{ name: 'intent-guard', prefix: ['check'], versionSafe: true },
|
|
75
76
|
{ name: 'intent-guard-check', prefix: [], versionSafe: false },
|
|
76
77
|
],
|
|
78
|
+
// The two external tools. Each has one name, and both version probes
|
|
79
|
+
// (gitleaks version, osv-scanner --version) print and exit without scanning.
|
|
80
|
+
gitleaks: [{ name: 'gitleaks', prefix: ['git'], versionSafe: true }],
|
|
81
|
+
'osv-scanner': [{ name: 'osv-scanner', prefix: ['scan', 'source'], versionSafe: true }],
|
|
77
82
|
};
|
|
78
83
|
export class ResolveError extends Error {
|
|
79
84
|
constructor(message) {
|
|
@@ -162,8 +167,14 @@ export function nodeModulesCandidate(gate, repoRoot) {
|
|
|
162
167
|
}
|
|
163
168
|
/** The candidate whose --version can be asked without running anything. */
|
|
164
169
|
function versionProbeFor(product, resolvedCandidate, resolvedCommand, repoRoot, pathValue, skipNodeModules) {
|
|
170
|
+
// How to ask is the product's (src/products.ts); whether this particular
|
|
171
|
+
// binary can be asked safely is the candidate's, per rule 2 above.
|
|
172
|
+
const spec = profileFor(product).versionProbe;
|
|
173
|
+
if (spec === null) {
|
|
174
|
+
return null;
|
|
175
|
+
}
|
|
165
176
|
if (resolvedCandidate.versionSafe) {
|
|
166
|
-
return { command: resolvedCommand, argv: [
|
|
177
|
+
return { command: resolvedCommand, argv: [...spec.argv] };
|
|
167
178
|
}
|
|
168
179
|
for (const candidate of CANDIDATES[product]) {
|
|
169
180
|
if (!candidate.versionSafe) {
|
|
@@ -174,7 +185,7 @@ function versionProbeFor(product, resolvedCandidate, resolvedCommand, repoRoot,
|
|
|
174
185
|
// head-chosen program in order to answer a question about it.
|
|
175
186
|
const found = locate(candidate.name, repoRoot, pathValue, skipNodeModules);
|
|
176
187
|
if (found !== null) {
|
|
177
|
-
return { command: found.command, argv: [
|
|
188
|
+
return { command: found.command, argv: [...spec.argv] };
|
|
178
189
|
}
|
|
179
190
|
}
|
|
180
191
|
return null;
|
|
@@ -222,8 +233,11 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
222
233
|
argvPrefix: [gate.command, ...prefix],
|
|
223
234
|
source: 'policy',
|
|
224
235
|
candidate: candidateName,
|
|
225
|
-
versionProbe: candidate.versionSafe
|
|
226
|
-
? {
|
|
236
|
+
versionProbe: candidate.versionSafe && profileFor(gate.product).versionProbe !== null
|
|
237
|
+
? {
|
|
238
|
+
command: process.execPath,
|
|
239
|
+
argv: [gate.command, ...(profileFor(gate.product).versionProbe?.argv ?? [])],
|
|
240
|
+
}
|
|
227
241
|
: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
|
|
228
242
|
};
|
|
229
243
|
}
|
package/dist/run.js
CHANGED
|
@@ -248,6 +248,9 @@ export function runAll(policy, options) {
|
|
|
248
248
|
// so a gate with no pull-request mode yet is not handed a flag it
|
|
249
249
|
// would reject, and the reason it was withheld is on the outcome.
|
|
250
250
|
...(options.trustBase === undefined ? {} : { trustBase: options.trustBase.ref }),
|
|
251
|
+
// Where an external gate's working directory goes (its report file,
|
|
252
|
+
// its config from the base ref). The runner removes what it makes.
|
|
253
|
+
...(options.tempRoot === undefined ? {} : { tempRoot: options.tempRoot }),
|
|
251
254
|
}));
|
|
252
255
|
}
|
|
253
256
|
}
|
package/package.json
CHANGED
|
@@ -18,7 +18,9 @@
|
|
|
18
18
|
"properties": {
|
|
19
19
|
"dependencies": { "$ref": "#/$defs/gate" },
|
|
20
20
|
"secrets": { "$ref": "#/$defs/gate" },
|
|
21
|
-
"intent": { "$ref": "#/$defs/gate" }
|
|
21
|
+
"intent": { "$ref": "#/$defs/gate" },
|
|
22
|
+
"secrets-history": { "$ref": "#/$defs/gate" },
|
|
23
|
+
"vulnerabilities": { "$ref": "#/$defs/gate" }
|
|
22
24
|
}
|
|
23
25
|
},
|
|
24
26
|
"report": {
|
|
@@ -39,8 +41,8 @@
|
|
|
39
41
|
"required": ["product"],
|
|
40
42
|
"properties": {
|
|
41
43
|
"product": {
|
|
42
|
-
"description": "Which product currently fills this role.",
|
|
43
|
-
"enum": ["dep-guard", "vault-guard", "intent-guard"]
|
|
44
|
+
"description": "Which product currently fills this role. gitleaks and osv-scanner are installed by the adopter, never by conductor.",
|
|
45
|
+
"enum": ["dep-guard", "vault-guard", "intent-guard", "gitleaks", "osv-scanner"]
|
|
44
46
|
},
|
|
45
47
|
"enabled": {
|
|
46
48
|
"description": "Whether this gate runs. Defaults to true. A gate that is enabled but whose binary cannot be found is a blocking finding, never a silent skip.",
|
|
@@ -53,7 +55,7 @@
|
|
|
53
55
|
"default": true
|
|
54
56
|
},
|
|
55
57
|
"stage": {
|
|
56
|
-
"description": "When this gate runs. Stages are cumulative in the order commit, push, ci: a gate runs at its own stage and at every later one, so a run at ci runs everything enabled. Defaults to commit for dependencies and secrets, and to ci for intent,
|
|
58
|
+
"description": "When this gate runs. Stages are cumulative in the order commit, push, ci: a gate runs at its own stage and at every later one, so a run at ci runs everything enabled. Defaults to commit for dependencies and secrets, and to ci for intent, secrets-history and vulnerabilities: the intent gate carries per-task ceremony, and a history scan or a registry lookup is pull-request work. A run with no --stage runs every enabled gate whatever its stage.",
|
|
57
59
|
"enum": ["commit", "push", "ci"]
|
|
58
60
|
},
|
|
59
61
|
"command": {
|
|
@@ -67,7 +69,7 @@
|
|
|
67
69
|
"items": { "type": "string" }
|
|
68
70
|
},
|
|
69
71
|
"options": {
|
|
70
|
-
"description": "Handed to this gate unchanged. Each key is one of that gate's own long-flag spellings without the leading dashes; true renders as --key, false as --no-key, a scalar as --key value, and an array as one --key value pair per entry. The umbrella does not interpret any of them. Per-gate thresholds live here; there is deliberately no shared threshold, because the
|
|
72
|
+
"description": "Handed to this gate unchanged. Each key is one of that gate's own long-flag spellings without the leading dashes; true renders as --key, false as --no-key, a scalar as --key value, and an array as one --key value pair per entry. The umbrella does not interpret any of them. Per-gate thresholds live here; there is deliberately no shared threshold, because the five products do not share one severity scale.",
|
|
71
73
|
"type": "object",
|
|
72
74
|
"propertyNames": { "pattern": "^[a-z0-9][a-z0-9-]*$" },
|
|
73
75
|
"additionalProperties": {
|