@vaultcompass/conductor 0.4.7 → 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.
@@ -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;
@@ -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: ['--version'] };
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: ['--version'] };
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
- ? { command: process.execPath, argv: [gate.command, '--version'] }
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.4.7",
3
+ "version": "0.5.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [
@@ -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, because only the intent gate carries per-task ceremony. A run with no --stage runs every enabled gate whatever its stage.",
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 three products do not share one severity scale.",
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": {