@vaultcompass/conductor 0.15.0 → 0.17.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 +154 -1186
- package/dist/gate-runner.js +31 -11
- package/dist/normalize.js +42 -2
- package/dist/output-sarif.js +22 -1
- package/dist/output-text.d.ts +15 -0
- package/dist/output-text.js +52 -3
- package/dist/policy.d.ts +21 -1
- package/dist/policy.js +58 -2
- package/dist/resolve.d.ts +96 -14
- package/dist/resolve.js +177 -25
- package/dist/trust-base.d.ts +78 -2
- package/dist/trust-base.js +413 -11
- package/package.json +1 -1
package/dist/gate-runner.js
CHANGED
|
@@ -31,8 +31,8 @@ import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals,
|
|
|
31
31
|
import { osvLockfileKind, profileFor } from './products.js';
|
|
32
32
|
import { unreadManifestsNote } from './unread-manifests.js';
|
|
33
33
|
import { escapeNonAscii } from './policy-diff.js';
|
|
34
|
-
import { atLeastVersion, refuseHeadControlledArgument, refuseHeadControlledProgram } from './trust-base.js';
|
|
35
|
-
import { ResolveError, argumentCandidates, candidateNames,
|
|
34
|
+
import { atLeastVersion, refuseHeadControlledArgument, refuseHeadControlledData, refuseHeadControlledProgram, writtenInsideWorkingTree, } from './trust-base.js';
|
|
35
|
+
import { ResolveError, argumentCandidates, candidateNames, codeArguments, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
|
|
36
36
|
/** The longest excerpt of a gate's own reason that is carried. */
|
|
37
37
|
export const GATE_SAID_MAX_CHARS = 160;
|
|
38
38
|
/**
|
|
@@ -675,8 +675,18 @@ export function refuseHeadControlledBinary(repoRoot, trustBase, binary) {
|
|
|
675
675
|
return refusal;
|
|
676
676
|
}
|
|
677
677
|
}
|
|
678
|
+
const fromOptions = new Set(binary.optionArgumentPaths ?? []);
|
|
678
679
|
for (const argument of binary.argumentPaths) {
|
|
679
|
-
const refusal = refuseHeadControlledArgument(repoRoot, trustBase, argument);
|
|
680
|
+
const refusal = refuseHeadControlledArgument(repoRoot, trustBase, argument, fromOptions.has(argument) ? "the gate's options:" : "the gate's args:");
|
|
681
|
+
if (refusal !== null) {
|
|
682
|
+
return refusal;
|
|
683
|
+
}
|
|
684
|
+
}
|
|
685
|
+
// A command that is the gate itself reads the rest of its args as data
|
|
686
|
+
// (audit 2026-10-28, N1, and its review): what each path is comes from the
|
|
687
|
+
// base tree, and a file or an option-value directory must be the base's.
|
|
688
|
+
for (const data of binary.dataArguments) {
|
|
689
|
+
const refusal = refuseHeadControlledData(repoRoot, trustBase, data);
|
|
680
690
|
if (refusal !== null) {
|
|
681
691
|
return refusal;
|
|
682
692
|
}
|
|
@@ -761,7 +771,7 @@ changeBase,
|
|
|
761
771
|
* after its enables, so the appended flag wins.
|
|
762
772
|
*/
|
|
763
773
|
preview = false) {
|
|
764
|
-
const passthrough = renderOptionFlags(gate.options);
|
|
774
|
+
const passthrough = renderOptionFlags(gate.options, gate.product);
|
|
765
775
|
const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
|
|
766
776
|
const config = external.configPath === undefined ? [] : ['--config', external.configPath];
|
|
767
777
|
switch (gate.product) {
|
|
@@ -937,7 +947,7 @@ preview = false) {
|
|
|
937
947
|
...lockfiles,
|
|
938
948
|
...(noResolve ? ['--no-resolve'] : []),
|
|
939
949
|
...callAnalysis,
|
|
940
|
-
...renderOptionFlags(options),
|
|
950
|
+
...renderOptionFlags(options, gate.product),
|
|
941
951
|
...(preview ? ['--no-call-analysis=all'] : []),
|
|
942
952
|
];
|
|
943
953
|
}
|
|
@@ -1295,7 +1305,11 @@ function previewRefusal(gate, repoRoot) {
|
|
|
1295
1305
|
detail: "the preview does not run call analysis, because it would build the head's code",
|
|
1296
1306
|
};
|
|
1297
1307
|
}
|
|
1298
|
-
|
|
1308
|
+
// Inside by its real path OR as written: a directory on the written path
|
|
1309
|
+
// that is a link out of the tree is the head's choice too (audit
|
|
1310
|
+
// 2026-11-01, MB2), and the primary rule judges every path as written.
|
|
1311
|
+
if (gate.command !== undefined &&
|
|
1312
|
+
(realPathInside(repoRoot, gate.command) || writtenInsideWorkingTree(repoRoot, gate.command))) {
|
|
1299
1313
|
return {
|
|
1300
1314
|
reason: 'gate-program-refused',
|
|
1301
1315
|
detail: `preview under the proposed rules: the base command ${gate.command} is inside the working tree, so this gate was not run`,
|
|
@@ -1310,11 +1324,17 @@ function previewRefusal(gate, repoRoot) {
|
|
|
1310
1324
|
// own entry is in the tree, wherever it points (its directory is checked).
|
|
1311
1325
|
// The candidate set is the primary run's (argumentCandidates): the entry and
|
|
1312
1326
|
// every loadable sibling of it, so a head-added tools/gate.js beside a base
|
|
1313
|
-
// tools/gate/ is refused here too.
|
|
1314
|
-
|
|
1315
|
-
for
|
|
1316
|
-
|
|
1317
|
-
|
|
1327
|
+
// tools/gate/ is refused here too. The entries are the primary run's code
|
|
1328
|
+
// arguments (codeArguments): every entry for a command that is not the gate
|
|
1329
|
+
// itself, and only the code-extension ones for one that is. The gate's
|
|
1330
|
+
// other args are data it reads (audit 2026-10-28, N1), and runGate's data
|
|
1331
|
+
// check (refuseHeadControlledData, through refuseHeadControlledBinary) runs
|
|
1332
|
+
// on every preview spawn, an option-value directory included (review B1).
|
|
1333
|
+
for (const arg of codeArguments(gate)) {
|
|
1334
|
+
const candidates = argumentCandidates(arg, repoRoot);
|
|
1335
|
+
if (candidates.some((named) => realPathInside(repoRoot, named) ||
|
|
1336
|
+
realPathInside(repoRoot, path.dirname(named)) ||
|
|
1337
|
+
writtenInsideWorkingTree(repoRoot, named))) {
|
|
1318
1338
|
return {
|
|
1319
1339
|
reason: 'gate-program-refused',
|
|
1320
1340
|
detail: `preview under the proposed rules: the base args entry ${arg} names a path inside the working tree, so this gate was not run`,
|
package/dist/normalize.js
CHANGED
|
@@ -533,8 +533,15 @@ function readTrustBase(raw, product) {
|
|
|
533
533
|
export function normalizeIntentGuard(raw, version) {
|
|
534
534
|
const product = 'intent-guard';
|
|
535
535
|
const root = needRecord(raw, product, 'the output');
|
|
536
|
-
|
|
537
|
-
|
|
536
|
+
// "skipped" is accepted ahead of the gate using it (issue 103): intent-guard
|
|
537
|
+
// 1.10.4 says "nothing was checked" as status ok plus skipReason, because
|
|
538
|
+
// anything else would have been unparseable to every conductor up to this
|
|
539
|
+
// one, and a later release can move to a status of its own once its pin
|
|
540
|
+
// floor is above this version. It is the one value added; every other
|
|
541
|
+
// status is still refused, and readSkipReason refuses a skipped status
|
|
542
|
+
// that names no reason or that carries a finding.
|
|
543
|
+
if (root.status !== 'blocked' && root.status !== 'ok' && root.status !== 'skipped') {
|
|
544
|
+
fail(product, 'status', 'one of "ok", "blocked" or "skipped"');
|
|
538
545
|
}
|
|
539
546
|
const trustBase = readTrustBase(root.trustBase, product);
|
|
540
547
|
const warnings = readIntentWarnings(root.warnings);
|
|
@@ -678,6 +685,7 @@ export function normalizeIntentGuard(raw, version) {
|
|
|
678
685
|
: 'The intent gate blocked without stating a reason.', 'unattributed'));
|
|
679
686
|
}
|
|
680
687
|
}
|
|
688
|
+
const skipReason = readSkipReason(root, findings, product);
|
|
681
689
|
return {
|
|
682
690
|
findings,
|
|
683
691
|
...(trustBase === undefined ? {} : { trustBase }),
|
|
@@ -700,11 +708,43 @@ export function normalizeIntentGuard(raw, version) {
|
|
|
700
708
|
driftCategories: drift?.categories ?? null,
|
|
701
709
|
budgetAction: budget?.action ?? null,
|
|
702
710
|
reasons,
|
|
711
|
+
// Present only when the gate said it checked nothing. The report
|
|
712
|
+
// surfaces read it through intentCheckedNothing in output-text.ts.
|
|
713
|
+
...(skipReason === null ? {} : { skipReason }),
|
|
703
714
|
},
|
|
704
715
|
},
|
|
705
716
|
diagnostics: [],
|
|
706
717
|
};
|
|
707
718
|
}
|
|
719
|
+
/**
|
|
720
|
+
* The gate's own statement that it checked nothing, or null (issue 103).
|
|
721
|
+
*
|
|
722
|
+
* intent-guard 1.10.4 puts a top-level `skipReason` string on a result whose
|
|
723
|
+
* status is still "ok" when require-frozen is off and there is no contract;
|
|
724
|
+
* a future status "skipped" means the same. Read only on those two
|
|
725
|
+
* statuses: a blocked result stays blocked whatever else it says, which is
|
|
726
|
+
* the fail-closed reading of a contradiction. An empty string is no reason.
|
|
727
|
+
*
|
|
728
|
+
* Refused as unparseable, never guessed at: a skipReason that is not a
|
|
729
|
+
* string, a status "skipped" that names no reason, and a skip that carries
|
|
730
|
+
* any finding. "Nothing was checked" beside a finding is a contradiction,
|
|
731
|
+
* and reading it as a skip would hide the finding, so the gate is reported
|
|
732
|
+
* as one whose output could not be read.
|
|
733
|
+
*/
|
|
734
|
+
function readSkipReason(root, findings, product) {
|
|
735
|
+
if (root.status === 'blocked') {
|
|
736
|
+
return null;
|
|
737
|
+
}
|
|
738
|
+
const said = optionalString(root.skipReason ?? undefined, product, 'skipReason');
|
|
739
|
+
const reason = said === undefined || said === '' ? null : said;
|
|
740
|
+
if (root.status === 'skipped' && reason === null) {
|
|
741
|
+
fail(product, 'skipReason', 'a non-empty string when status is "skipped"');
|
|
742
|
+
}
|
|
743
|
+
if (reason !== null && findings.length > 0) {
|
|
744
|
+
fail(product, 'findings', 'empty when the gate says it checked nothing (skipReason)');
|
|
745
|
+
}
|
|
746
|
+
return reason;
|
|
747
|
+
}
|
|
708
748
|
// -- gitleaks (external, git history mode) -------------------------------
|
|
709
749
|
//
|
|
710
750
|
// The report is a JSON array written to a file, one entry per leak, with
|
package/dist/output-sarif.js
CHANGED
|
@@ -121,7 +121,7 @@ import { gateExitBlocks } from './exit-codes.js';
|
|
|
121
121
|
import { cleanPreviewLine } from './gate-runner.js';
|
|
122
122
|
import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
|
|
123
123
|
import { INTENT_WARNING } from './normalize.js';
|
|
124
|
-
import { gateOutcomeWords, skewFound, skewPlace } from './output-text.js';
|
|
124
|
+
import { gateOutcomeWords, intentCheckedNothing, intentSkipReason, skewFound, skewPlace, } from './output-text.js';
|
|
125
125
|
import { POLICY_FILE_NAME } from './policy.js';
|
|
126
126
|
import { policyChangeLine } from './policy-diff.js';
|
|
127
127
|
import { guardPreview } from './run.js';
|
|
@@ -587,6 +587,27 @@ function treeUnchangedNotifications(result) {
|
|
|
587
587
|
* keep answering it the same way.
|
|
588
588
|
*/
|
|
589
589
|
function skippedNotifications(result) {
|
|
590
|
+
return [...preparedSkipNotifications(result), ...ranAndCheckedNothingNotifications(result)];
|
|
591
|
+
}
|
|
592
|
+
/**
|
|
593
|
+
* An intent gate that RAN and checked nothing (issue 103): intent-guard
|
|
594
|
+
* 1.10.4's skipReason on a directly spawned run, or, before it, no contract
|
|
595
|
+
* found with require-frozen off. Filed under the same id as the
|
|
596
|
+
* pull-request path's no-contract skip, with the same message shape and the
|
|
597
|
+
* gate's own sentence as the detail, because it is the same state and a
|
|
598
|
+
* consumer filtering on intent-guard/no-contract should see both. The same
|
|
599
|
+
* predicate the text report reads (intentCheckedNothing), so the two agree.
|
|
600
|
+
* The gate's own run is still in the log, since it did run.
|
|
601
|
+
*/
|
|
602
|
+
function ranAndCheckedNothingNotifications(result) {
|
|
603
|
+
return result.gates.filter(intentCheckedNothing).map((gate) => ({
|
|
604
|
+
id: `${gate.product}/no-contract`,
|
|
605
|
+
message: `The ${gate.role} gate (${gate.product}) checked nothing on this branch. ` +
|
|
606
|
+
(intentSkipReason(gate) ?? 'It found no contract to check against.'),
|
|
607
|
+
details: { role: gate.role, product: gate.product, reason: 'no-contract' },
|
|
608
|
+
}));
|
|
609
|
+
}
|
|
610
|
+
function preparedSkipNotifications(result) {
|
|
590
611
|
return result.skipped.map((gate) => ({
|
|
591
612
|
// The reason IS the second half of the id, which keeps
|
|
592
613
|
// intent-guard/no-contract exactly where consumers already have it and
|
package/dist/output-text.d.ts
CHANGED
|
@@ -177,6 +177,21 @@ export declare function versionSkewSummaryLines(result: RunResult): string[];
|
|
|
177
177
|
* not a pass.
|
|
178
178
|
*/
|
|
179
179
|
export declare function verdictToken(result: RunResult, advisory: boolean): string;
|
|
180
|
+
/**
|
|
181
|
+
* The gate's own skipReason (intent-guard 1.10.4, issue 103), or null. Put
|
|
182
|
+
* in the run details by normalizeIntentGuard only when non-empty.
|
|
183
|
+
*/
|
|
184
|
+
export declare function intentSkipReason(gate: GateOutcome): string | null;
|
|
185
|
+
/**
|
|
186
|
+
* An intent gate that RAN and checked nothing: it said so with skipReason,
|
|
187
|
+
* or (before 1.10.4) it reported no contract found. The one predicate the
|
|
188
|
+
* text report, its one-line summary and the SARIF notification all read, so
|
|
189
|
+
* a directly spawned run reports this state on the same surfaces as the
|
|
190
|
+
* pull-request path's no-contract skip (issue 103). Never for a gate that
|
|
191
|
+
* could not run or that blocked: a missing contract under require-frozen is
|
|
192
|
+
* a block, not a skip.
|
|
193
|
+
*/
|
|
194
|
+
export declare function intentCheckedNothing(gate: GateOutcome): boolean;
|
|
180
195
|
export interface TextOptions {
|
|
181
196
|
/**
|
|
182
197
|
* Print the full report even when the run is fully clean.
|
package/dist/output-text.js
CHANGED
|
@@ -235,6 +235,14 @@ function enforcementNote(gate) {
|
|
|
235
235
|
`${gate.exitCode ?? '?'}, and enforce is false for it in .guardrails.yaml, so the commit ` +
|
|
236
236
|
'proceeds. Set enforce: true there to make it block.');
|
|
237
237
|
}
|
|
238
|
+
// A gate that ran and checked nothing (an intent gate with no contract, a
|
|
239
|
+
// scanner with nothing to scan) found nothing because it looked at nothing,
|
|
240
|
+
// and "found nothing to block on" reads as a clean result (audit
|
|
241
|
+
// 2026-10-28, N5). The same predicate and words as the verdict's list.
|
|
242
|
+
if (gateCheckedNothing(gate)) {
|
|
243
|
+
return (' not enforced: enforce is false for this gate in .guardrails.yaml, and it checked ' +
|
|
244
|
+
`nothing here: ${checkedNothingWording(gate)}. This is not a clean result.`);
|
|
245
|
+
}
|
|
238
246
|
return ' not enforced: enforce is false for this gate in .guardrails.yaml. It found nothing to block on here.';
|
|
239
247
|
}
|
|
240
248
|
/**
|
|
@@ -396,14 +404,23 @@ function gateSection(gate, verbose, refusedOnTerminal = false) {
|
|
|
396
404
|
const facts = Object.entries(gate.run.details)
|
|
397
405
|
.filter(([key, value]) =>
|
|
398
406
|
// ignoredReported drives the line above rather than being a fact
|
|
399
|
-
// about the run, so it is not printed twice.
|
|
407
|
+
// about the run, so it is not printed twice. skipReason gets its
|
|
408
|
+
// own line, below.
|
|
400
409
|
key !== 'ignoredReported' &&
|
|
410
|
+
key !== 'skipReason' &&
|
|
401
411
|
(typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') &&
|
|
402
412
|
value !== '')
|
|
403
413
|
.map(([key, value]) => `${key} ${String(value)}`);
|
|
404
414
|
if (facts.length > 0) {
|
|
405
415
|
lines.push(` ${facts.join(' ')}`);
|
|
406
416
|
}
|
|
417
|
+
// The gate's own sentence for having checked nothing (issue 103), in the
|
|
418
|
+
// words the pull-request path's skipped line uses for the same state.
|
|
419
|
+
// The gate wrote it, so it is cleaned like any other gate text.
|
|
420
|
+
const skipReason = intentSkipReason(gate);
|
|
421
|
+
if (skipReason !== null && intentCheckedNothing(gate)) {
|
|
422
|
+
lines.push(` ${skipWording('no-contract').line}: ${cleanOutputLine(skipReason)}`);
|
|
423
|
+
}
|
|
407
424
|
for (const diagnostic of gate.run.diagnostics) {
|
|
408
425
|
lines.push(` note ${diagnostic.code}: ${diagnostic.message}`);
|
|
409
426
|
}
|
|
@@ -1022,7 +1039,30 @@ function gateCheckedNothing(gate) {
|
|
|
1022
1039
|
}
|
|
1023
1040
|
return (gate.diagnostics.some((d) => d.code === 'conductor/nothing-to-scan') ||
|
|
1024
1041
|
readNoPackages(gate) ||
|
|
1025
|
-
(gate
|
|
1042
|
+
intentCheckedNothing(gate));
|
|
1043
|
+
}
|
|
1044
|
+
/**
|
|
1045
|
+
* The gate's own skipReason (intent-guard 1.10.4, issue 103), or null. Put
|
|
1046
|
+
* in the run details by normalizeIntentGuard only when non-empty.
|
|
1047
|
+
*/
|
|
1048
|
+
export function intentSkipReason(gate) {
|
|
1049
|
+
const said = gate.run.details.skipReason;
|
|
1050
|
+
return typeof said === 'string' && said !== '' ? said : null;
|
|
1051
|
+
}
|
|
1052
|
+
/**
|
|
1053
|
+
* An intent gate that RAN and checked nothing: it said so with skipReason,
|
|
1054
|
+
* or (before 1.10.4) it reported no contract found. The one predicate the
|
|
1055
|
+
* text report, its one-line summary and the SARIF notification all read, so
|
|
1056
|
+
* a directly spawned run reports this state on the same surfaces as the
|
|
1057
|
+
* pull-request path's no-contract skip (issue 103). Never for a gate that
|
|
1058
|
+
* could not run or that blocked: a missing contract under require-frozen is
|
|
1059
|
+
* a block, not a skip.
|
|
1060
|
+
*/
|
|
1061
|
+
export function intentCheckedNothing(gate) {
|
|
1062
|
+
return (gate.role === 'intent' &&
|
|
1063
|
+
gate.couldNotRun === null &&
|
|
1064
|
+
!gate.findings.some((finding) => finding.blocking) &&
|
|
1065
|
+
(intentSkipReason(gate) !== null || gate.run.details.contractFound === false));
|
|
1026
1066
|
}
|
|
1027
1067
|
/** How the verdict sentence names a gate that ran and checked nothing. */
|
|
1028
1068
|
function checkedNothingWording(gate) {
|
|
@@ -1356,7 +1396,16 @@ function summaryLine(result) {
|
|
|
1356
1396
|
// decided there is none exactly where most readers stop reading. Grouped in
|
|
1357
1397
|
// first-seen order so the sentence does not reorder itself between runs.
|
|
1358
1398
|
const skippedByWording = new Map();
|
|
1359
|
-
|
|
1399
|
+
// An intent gate that ran and checked nothing (issue 103) is named in the
|
|
1400
|
+
// same clause as the pull-request path's no-contract skip: it is the same
|
|
1401
|
+
// state, and this line is all a hook or a pull request comment prints.
|
|
1402
|
+
const checkedNothing = [
|
|
1403
|
+
...result.skipped,
|
|
1404
|
+
...result.gates
|
|
1405
|
+
.filter(intentCheckedNothing)
|
|
1406
|
+
.map((gate) => ({ role: gate.role, product: gate.product, reason: 'no-contract' })),
|
|
1407
|
+
];
|
|
1408
|
+
for (const gate of checkedNothing) {
|
|
1360
1409
|
const lead = skipWording(gate.reason).summary;
|
|
1361
1410
|
skippedByWording.set(lead, [
|
|
1362
1411
|
...(skippedByWording.get(lead) ?? []),
|
package/dist/policy.d.ts
CHANGED
|
@@ -140,11 +140,31 @@ export interface CliOverrides {
|
|
|
140
140
|
export declare function applyCliOverrides(policy: Policy, overrides: CliOverrides): Policy;
|
|
141
141
|
/** Enabled gates in role order, so a report's section order never depends on file order. */
|
|
142
142
|
export declare function enabledGates(policy: Policy): GatePolicy[];
|
|
143
|
+
/**
|
|
144
|
+
* Flags that take NO value, per product, read from each gate's own `--help`
|
|
145
|
+
* (osv-scanner 2.4.0 `scan source`, gitleaks 8.30.1 `git`, dep-guard 0.17.0
|
|
146
|
+
* and vault-guard 1.12.1 `scan`, intent-guard 1.10.2 `check`, and 1.10.3
|
|
147
|
+
* `check` again for issue 161, which lists the same flags). Two readers:
|
|
148
|
+
*
|
|
149
|
+
* - gateArgEntries in resolve.ts: the word after one of these is NOT its
|
|
150
|
+
* value, so `osv-scanner scan source -r .` keeps `.` as a positional scan
|
|
151
|
+
* target (re-review 2026-10-28, R1). Any flag not listed stays
|
|
152
|
+
* fail-closed there: the word after it is read as its value. A wrong
|
|
153
|
+
* entry would let a value be read as a positional, which leaves a
|
|
154
|
+
* directory unvetted, so entries come only from a gate's own help text.
|
|
155
|
+
* - renderOptionFlags below: a `true` option whose gate lists `--no-<key>`
|
|
156
|
+
* and not `--<key>` is not rendered (issue 161).
|
|
157
|
+
*/
|
|
158
|
+
export declare const NO_VALUE_FLAGS: Record<Product, readonly string[]>;
|
|
143
159
|
/**
|
|
144
160
|
* Renders a passthrough option bag as child-process arguments.
|
|
145
161
|
*
|
|
146
162
|
* Keys are sorted so two policy files that differ only in key order produce
|
|
147
163
|
* the same command line, which is what makes a run reproducible and a
|
|
148
164
|
* report diffable.
|
|
165
|
+
*
|
|
166
|
+
* `product` is required so every caller renders what that gate accepts:
|
|
167
|
+
* `true` is `--key`, except where the gate's own help has only `--no-key`
|
|
168
|
+
* (onlyNegatedSpelling), where it is nothing.
|
|
149
169
|
*/
|
|
150
|
-
export declare function renderOptionFlags(options: Record<string, OptionValue
|
|
170
|
+
export declare function renderOptionFlags(options: Record<string, OptionValue>, product: Product): string[];
|
package/dist/policy.js
CHANGED
|
@@ -443,19 +443,75 @@ export function applyCliOverrides(policy, overrides) {
|
|
|
443
443
|
export function enabledGates(policy) {
|
|
444
444
|
return GATE_ROLES.map((role) => policy.gates[role]).filter((gate) => gate !== undefined && gate.enabled);
|
|
445
445
|
}
|
|
446
|
+
/**
|
|
447
|
+
* Flags that take NO value, per product, read from each gate's own `--help`
|
|
448
|
+
* (osv-scanner 2.4.0 `scan source`, gitleaks 8.30.1 `git`, dep-guard 0.17.0
|
|
449
|
+
* and vault-guard 1.12.1 `scan`, intent-guard 1.10.2 `check`, and 1.10.3
|
|
450
|
+
* `check` again for issue 161, which lists the same flags). Two readers:
|
|
451
|
+
*
|
|
452
|
+
* - gateArgEntries in resolve.ts: the word after one of these is NOT its
|
|
453
|
+
* value, so `osv-scanner scan source -r .` keeps `.` as a positional scan
|
|
454
|
+
* target (re-review 2026-10-28, R1). Any flag not listed stays
|
|
455
|
+
* fail-closed there: the word after it is read as its value. A wrong
|
|
456
|
+
* entry would let a value be read as a positional, which leaves a
|
|
457
|
+
* directory unvetted, so entries come only from a gate's own help text.
|
|
458
|
+
* - renderOptionFlags below: a `true` option whose gate lists `--no-<key>`
|
|
459
|
+
* and not `--<key>` is not rendered (issue 161).
|
|
460
|
+
*/
|
|
461
|
+
export const NO_VALUE_FLAGS = {
|
|
462
|
+
'osv-scanner': [
|
|
463
|
+
'-r', '--recursive', '--no-ignore', '--include-git-root', '--serve', '--offline',
|
|
464
|
+
'--offline-vulnerabilities', '--download-offline-databases', '--no-resolve',
|
|
465
|
+
'--allow-no-lockfiles', '--all-packages', '--all-vulns',
|
|
466
|
+
'--experimental-flag-deprecated-packages', '--experimental-no-default-plugins', '-h', '--help',
|
|
467
|
+
],
|
|
468
|
+
gitleaks: [
|
|
469
|
+
'-v', '--verbose', '--pre-commit', '--staged', '--ignore-gitleaks-allow', '--no-banner',
|
|
470
|
+
'--no-color', '--redact', '-h', '--help',
|
|
471
|
+
],
|
|
472
|
+
'dep-guard': ['--staged', '--online', '--no-online', '-h', '--help'],
|
|
473
|
+
'vault-guard': ['--staged', '-h', '--help'],
|
|
474
|
+
'intent-guard': ['--staged', '--no-require-frozen', '--log', '--json', '-h', '--help', '-v', '--version'],
|
|
475
|
+
};
|
|
476
|
+
/**
|
|
477
|
+
* Whether `--<key>` is a spelling the gate does not have while `--no-<key>`
|
|
478
|
+
* is: its own help lists only the negation. The gate's default for such a
|
|
479
|
+
* flag is then on (a `--no-` flag exists to turn a default off), so a policy
|
|
480
|
+
* value `true` asks for exactly the default, and rendering it would hand the
|
|
481
|
+
* gate an option it refuses (issue 161: intent-guard 1.10.3 `check
|
|
482
|
+
* --require-frozen` exits 1 with "unknown option", which every directly
|
|
483
|
+
* spawned run reported as unparseable output).
|
|
484
|
+
*
|
|
485
|
+
* General across gates, not an intent-guard case: gitleaks `banner` and
|
|
486
|
+
* `color` and osv-scanner `ignore` and `resolve` take the same path. The
|
|
487
|
+
* premise is the table's: NO_VALUE_FLAGS lists only value-less flags, so
|
|
488
|
+
* this reads "the gate has a value-less --no-<key> and no value-less
|
|
489
|
+
* --<key>". A gate with a VALUED --<key> beside a value-less --no-<key>
|
|
490
|
+
* would wrongly lose `true`; no gate has that shape today.
|
|
491
|
+
*/
|
|
492
|
+
function onlyNegatedSpelling(key, product) {
|
|
493
|
+
const known = NO_VALUE_FLAGS[product];
|
|
494
|
+
return known.includes(`--no-${key}`) && !known.includes(`--${key}`);
|
|
495
|
+
}
|
|
446
496
|
/**
|
|
447
497
|
* Renders a passthrough option bag as child-process arguments.
|
|
448
498
|
*
|
|
449
499
|
* Keys are sorted so two policy files that differ only in key order produce
|
|
450
500
|
* the same command line, which is what makes a run reproducible and a
|
|
451
501
|
* report diffable.
|
|
502
|
+
*
|
|
503
|
+
* `product` is required so every caller renders what that gate accepts:
|
|
504
|
+
* `true` is `--key`, except where the gate's own help has only `--no-key`
|
|
505
|
+
* (onlyNegatedSpelling), where it is nothing.
|
|
452
506
|
*/
|
|
453
|
-
export function renderOptionFlags(options) {
|
|
507
|
+
export function renderOptionFlags(options, product) {
|
|
454
508
|
const args = [];
|
|
455
509
|
for (const key of Object.keys(options).sort()) {
|
|
456
510
|
const value = options[key];
|
|
457
511
|
if (value === true) {
|
|
458
|
-
|
|
512
|
+
if (!onlyNegatedSpelling(key, product)) {
|
|
513
|
+
args.push(`--${key}`);
|
|
514
|
+
}
|
|
459
515
|
}
|
|
460
516
|
else if (value === false) {
|
|
461
517
|
// Both dep-guard and intent-guard spell a negated boolean this way,
|
package/dist/resolve.d.ts
CHANGED
|
@@ -18,6 +18,17 @@ export interface VersionProbe {
|
|
|
18
18
|
command: string;
|
|
19
19
|
argv: string[];
|
|
20
20
|
}
|
|
21
|
+
/** One args entry of a gate-named command that could name a path (`dataArgumentPaths`). */
|
|
22
|
+
export interface DataArgument {
|
|
23
|
+
/** Absolute, resolved against the repository root. */
|
|
24
|
+
path: string;
|
|
25
|
+
/** False for an option's value (`--x=v`, the word after `--x`, `-xv`): data the gate reads. */
|
|
26
|
+
positional: boolean;
|
|
27
|
+
/** The args entry as written, for the refusal message. */
|
|
28
|
+
entry: string;
|
|
29
|
+
/** 'options' when the value came from the policy's `options:`, so the refusal names that list; absent for `args:`. */
|
|
30
|
+
from?: 'options';
|
|
31
|
+
}
|
|
21
32
|
export interface ResolvedBinary {
|
|
22
33
|
/** What to spawn. */
|
|
23
34
|
command: string;
|
|
@@ -46,8 +57,35 @@ export interface ResolvedBinary {
|
|
|
46
57
|
* policy's args, never a candidate's built-in prefix (`scan`, `source`):
|
|
47
58
|
* those are subcommands this package wrote, and a directory of the same
|
|
48
59
|
* name in somebody's repository is not a program.
|
|
60
|
+
*
|
|
61
|
+
* When `command:` is the gate itself (commandIsGateProgram) only the args
|
|
62
|
+
* entries with a code extension are listed here (`codeArguments`); the
|
|
63
|
+
* rest of its args are its own argv, read as data, and land in
|
|
64
|
+
* `dataArguments` instead. The code-extension `options:` values are listed
|
|
65
|
+
* here too, for every command and for a gate resolution found (audit
|
|
66
|
+
* 2026-11-01, MB1).
|
|
49
67
|
*/
|
|
50
68
|
argumentPaths: string[];
|
|
69
|
+
/**
|
|
70
|
+
* The entries of `argumentPaths` that came from `options:`, so a refusal
|
|
71
|
+
* names the list the value was written in (review of the 2026-11-01 fix,
|
|
72
|
+
* item 3). Absent is the same as empty: every entry came from `args:`.
|
|
73
|
+
*/
|
|
74
|
+
optionArgumentPaths?: string[];
|
|
75
|
+
/**
|
|
76
|
+
* Every args entry that could name a path, when `command:` is the gate
|
|
77
|
+
* itself (`dataArgumentPaths`), in args order, by POSITION and never by
|
|
78
|
+
* what the head's disk holds; then every non-code `options:` value as
|
|
79
|
+
* rendered, for every command and for a gate resolution found (audit
|
|
80
|
+
* 2026-11-01, MB1).
|
|
81
|
+
*
|
|
82
|
+
* The pull-request check (refuseHeadControlledData) decides from the BASE
|
|
83
|
+
* tree what each one is: a file must be the base's blob, a directory given
|
|
84
|
+
* as an option's value must be the base's tree, and a positional directory
|
|
85
|
+
* is a scan target and is not compared (audit 2026-10-28, N1, and its
|
|
86
|
+
* review, B1 and N-a).
|
|
87
|
+
*/
|
|
88
|
+
dataArguments: DataArgument[];
|
|
51
89
|
source: ResolutionSource;
|
|
52
90
|
/** The candidate name this matched, for the report's gate header. */
|
|
53
91
|
candidate: string;
|
|
@@ -107,14 +145,22 @@ export declare function candidateNames(product: Product): string[];
|
|
|
107
145
|
* Whether the policy's `command:` is itself the gate program, so its `args:`
|
|
108
146
|
* are that gate's own argv rather than something an interpreter will load.
|
|
109
147
|
*
|
|
110
|
-
* True when the command's
|
|
111
|
-
* `intent-guard.js
|
|
112
|
-
*
|
|
113
|
-
*
|
|
114
|
-
* Only
|
|
115
|
-
* from being read as paths
|
|
116
|
-
*
|
|
117
|
-
*
|
|
148
|
+
* True only when the command's NAME is a candidate name (`vault-guard`,
|
|
149
|
+
* `intent-guard.js`, executable or not). False for anything else: an
|
|
150
|
+
* interpreter such as `node` or `python3`, a renamed gate binary, and any
|
|
151
|
+
* wrapper or dispatcher whose name is not a gate name, a non-executable
|
|
152
|
+
* `my-build.js` included. Only when true are the product's subcommand words
|
|
153
|
+
* (`scan`, `source`) exempt from being read as paths, and the args read as
|
|
154
|
+
* the gate's own data rather than as code (`dataArgumentPaths`): an
|
|
155
|
+
* interpreter handed `scan` runs `scan.js` or `scan/index.js`, so for it the
|
|
156
|
+
* word is a path like any other (audit 2026-10-27 fix round, MB3).
|
|
157
|
+
*
|
|
158
|
+
* The name is the only test. An earlier version also counted every
|
|
159
|
+
* non-executable `.js` command, because this package runs one through its own
|
|
160
|
+
* Node with the script as the program; but how a file is RUN says nothing
|
|
161
|
+
* about what it LOADS, and a dispatcher that requires the script its first
|
|
162
|
+
* argument names let a pull request rewrite `scan.js` and pass (audit
|
|
163
|
+
* 2026-10-28, MB1).
|
|
118
164
|
*/
|
|
119
165
|
export declare function commandIsGateProgram(gate: GatePolicy): boolean;
|
|
120
166
|
/**
|
|
@@ -134,11 +180,11 @@ export declare function commandIsGateProgram(gate: GatePolicy): boolean;
|
|
|
134
180
|
* (`--config=tools/cfg.json`, `--import=./hook.mjs`) is read for the value
|
|
135
181
|
* after the first `=`, since that is where an interpreter takes a file to
|
|
136
182
|
* load and a gate takes a file to read its rules from.
|
|
137
|
-
* -
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
*
|
|
141
|
-
*
|
|
183
|
+
* - Nothing else is exempt, the product's own subcommand words (`scan`,
|
|
184
|
+
* `source`) included: this is only ever asked for a command that is not
|
|
185
|
+
* the gate itself (commandIsGateProgram), and an interpreter handed `scan`
|
|
186
|
+
* runs `scan.js` or `scan/index.js`. The gate itself has no code args;
|
|
187
|
+
* its args are data (dataArgumentPaths).
|
|
142
188
|
* - The entry as written, when it exists as a file, a directory or a
|
|
143
189
|
* symlink, without following the symlink, so the caller can refuse an
|
|
144
190
|
* in-tree link on its own entry.
|
|
@@ -156,4 +202,40 @@ export declare function commandIsGateProgram(gate: GatePolicy): boolean;
|
|
|
156
202
|
* string (`node -e`, `bash -c`), is not recognised as a path. The README says
|
|
157
203
|
* so.
|
|
158
204
|
*/
|
|
159
|
-
export declare function argumentCandidates(arg: string, repoRoot: string
|
|
205
|
+
export declare function argumentCandidates(arg: string, repoRoot: string): string[];
|
|
206
|
+
/**
|
|
207
|
+
* The args entries vetted as CODE: every entry when the command is not the
|
|
208
|
+
* gate itself, and only the code-extension values (`hasCodeExtension`) when
|
|
209
|
+
* it is, then the code-extension `options:` values (optionCodeArguments).
|
|
210
|
+
* Each goes through `argumentCandidates`, here and in the preview.
|
|
211
|
+
*/
|
|
212
|
+
export declare function codeArguments(gate: GatePolicy): string[];
|
|
213
|
+
/**
|
|
214
|
+
* The args entries of a gate-named command that are its own DATA, when
|
|
215
|
+
* `command:` is the gate itself (commandIsGateProgram), in args order; empty
|
|
216
|
+
* for every other command (audit 2026-10-28, N1, and its review, B1, N-a,
|
|
217
|
+
* N-b, N-e).
|
|
218
|
+
*
|
|
219
|
+
* Every non-code entry (`gateArgEntries`, less the code-extension ones in
|
|
220
|
+
* `codeArguments`) is listed with its position, resolved against the
|
|
221
|
+
* repository root, WHETHER OR NOT the head's disk has it and whatever kind of
|
|
222
|
+
* thing the disk holds there: a head must not be able to delete a path or
|
|
223
|
+
* change it from a file to a directory to move it out of vetting. What each
|
|
224
|
+
* one is, and so which rule applies, is decided from the base tree by
|
|
225
|
+
* refuseHeadControlledData. No `<entry>.js` sibling is tried: that is how an
|
|
226
|
+
* interpreter resolves a name, and this command is not one.
|
|
227
|
+
*
|
|
228
|
+
* What this trusts is the NAME: a program named like a gate is taken to be
|
|
229
|
+
* that gate, except that a code-extension entry keeps the code rule. A
|
|
230
|
+
* wrapper given a gate's name that hands an extension-less entry to an
|
|
231
|
+
* interpreter is a wrapper, vetted no further than this (README,
|
|
232
|
+
* pull-request trust boundary).
|
|
233
|
+
*
|
|
234
|
+
* Then every non-code `options:` value (optionEntries), WHATEVER the command
|
|
235
|
+
* is and with no command at all: they are rendered into the argv of every
|
|
236
|
+
* spawn, after the args, so they are the gate's own data (or a script's)
|
|
237
|
+
* whoever runs them, and a rules directory written there is as much the
|
|
238
|
+
* rules as one written in args (audit 2026-11-01, MB1). Marked `from:
|
|
239
|
+
* 'options'` only so a refusal names the list the value came from.
|
|
240
|
+
*/
|
|
241
|
+
export declare function dataArgumentPaths(gate: GatePolicy, repoRoot: string): DataArgument[];
|