@vaultcompass/conductor 0.16.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 +18 -18
- package/dist/gate-runner.js +13 -6
- 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 +44 -3
- package/dist/policy.d.ts +21 -1
- package/dist/policy.js +58 -2
- package/dist/resolve.d.ts +23 -4
- package/dist/resolve.js +64 -43
- package/dist/trust-base.d.ts +35 -4
- package/dist/trust-base.js +255 -24
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -76,7 +76,7 @@ jobs:
|
|
|
76
76
|
echo "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108 $bin/osv-scanner" | sha256sum -c -
|
|
77
77
|
chmod +x "$bin/osv-scanner"
|
|
78
78
|
echo "$bin" >> "$GITHUB_PATH"
|
|
79
|
-
- uses: vaultcompasshq/conductor@
|
|
79
|
+
- uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
|
|
80
80
|
- uses: github/codeql-action/upload-sarif@v4
|
|
81
81
|
if: always()
|
|
82
82
|
with:
|
|
@@ -229,7 +229,7 @@ required.
|
|
|
229
229
|
|
|
230
230
|
Your terminal also shows one status line per gate, written to stderr so a
|
|
231
231
|
CI job log has a per-gate record even when the report goes to a file,
|
|
232
|
-
such as `conductor: gate dependencies (dep-guard 0.18.
|
|
232
|
+
such as `conductor: gate dependencies (dep-guard 0.18.1): ok, exit 0` or
|
|
233
233
|
a `skipped (deferred to stage ci)` line for a deferred gate. They carry
|
|
234
234
|
nothing the summary does not; to see only the summary, redirect stderr
|
|
235
235
|
(`conductor run --staged --stage commit 2>/dev/null` in the hook).
|
|
@@ -237,15 +237,15 @@ required.
|
|
|
237
237
|
A commit with a staged credential in it prints the full report and exits 1:
|
|
238
238
|
|
|
239
239
|
```
|
|
240
|
-
conductor 0.
|
|
240
|
+
conductor 0.17.0
|
|
241
241
|
verdict-token: blocked (1)
|
|
242
242
|
conductor run: 2 gate(s), 1 finding(s)
|
|
243
243
|
|
|
244
|
-
dependencies dep-guard 0.18.
|
|
244
|
+
dependencies dep-guard 0.18.1 exit 0 153ms via dep-guard on path
|
|
245
245
|
threshold medium suppressed 0 ignored 0
|
|
246
246
|
mode staged corpusBuiltAt 2026-09-20T06:16:40.340Z lockfileFormat npm online false lookups 0 skipped-by-deadline 0
|
|
247
247
|
|
|
248
|
-
secrets vault-guard 1.13.
|
|
248
|
+
secrets vault-guard 1.13.1 exit 1 105ms via vault-guard on path
|
|
249
249
|
BLOCKING critical vault-guard/anthropic jest.config.mjs:14:12
|
|
250
250
|
Possible secret of type 'anthropic'
|
|
251
251
|
threshold medium suppressed 0 ignored not reported
|
|
@@ -532,8 +532,8 @@ request being judged, and the version-pin protection described above
|
|
|
532
532
|
"protects nothing" against a tree that controls its own judge (the
|
|
533
533
|
validate step's own comment in `action.yml` says so in those words). A tag
|
|
534
534
|
moves when someone pushes it. Name this action by owner and the full commit
|
|
535
|
-
SHA instead. The recipes in this README name v0.
|
|
536
|
-
`vaultcompasshq/conductor@
|
|
535
|
+
SHA instead. The recipes in this README name v0.16.0 that way, as
|
|
536
|
+
`vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0`.
|
|
537
537
|
|
|
538
538
|
```yaml
|
|
539
539
|
name: guardrails
|
|
@@ -555,10 +555,10 @@ jobs:
|
|
|
555
555
|
with:
|
|
556
556
|
node-version: '22.23.4'
|
|
557
557
|
- id: conductor
|
|
558
|
-
uses: vaultcompasshq/conductor@
|
|
558
|
+
uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
|
|
559
559
|
with:
|
|
560
560
|
output: conductor.sarif
|
|
561
|
-
- uses: github/codeql-action/upload-sarif@
|
|
561
|
+
- uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
|
|
562
562
|
if: always()
|
|
563
563
|
continue-on-error: true
|
|
564
564
|
with:
|
|
@@ -654,7 +654,7 @@ jobs:
|
|
|
654
654
|
# installs those itself, globally. Leave conductor-version unset so the
|
|
655
655
|
# umbrella is the default in the pinned action.yml.
|
|
656
656
|
- id: conductor
|
|
657
|
-
uses: vaultcompasshq/conductor@
|
|
657
|
+
uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
|
|
658
658
|
with:
|
|
659
659
|
output: conductor.sarif
|
|
660
660
|
# Exact versions, never a range and never "latest". These three
|
|
@@ -665,10 +665,10 @@ jobs:
|
|
|
665
665
|
# request of their own. On a pull request the action refuses a pin
|
|
666
666
|
# below what the pinned action.yml ships, and the three lines can
|
|
667
667
|
# be left out entirely to take that action's own versions.
|
|
668
|
-
dep-guard-version: 0.18.
|
|
669
|
-
vault-guard-version: 1.13.
|
|
670
|
-
intent-guard-version: 1.10.
|
|
671
|
-
- uses: github/codeql-action/upload-sarif@
|
|
668
|
+
dep-guard-version: 0.18.1
|
|
669
|
+
vault-guard-version: 1.13.1
|
|
670
|
+
intent-guard-version: 1.10.4
|
|
671
|
+
- uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
|
|
672
672
|
# Always: the log is most worth having on the run that failed.
|
|
673
673
|
if: always()
|
|
674
674
|
# The sarif path is published BEFORE the gates run, so on the exit 2
|
|
@@ -876,7 +876,7 @@ jobs:
|
|
|
876
876
|
# seconds) plus 300 seconds for the preview, rounded up. A step
|
|
877
877
|
# timeout below that can kill a full gitleaks scan and leave no verdict.
|
|
878
878
|
timeout-minutes: 30
|
|
879
|
-
uses: vaultcompasshq/conductor@
|
|
879
|
+
uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
|
|
880
880
|
with:
|
|
881
881
|
pr-comment: true
|
|
882
882
|
advisory: true
|
|
@@ -1012,7 +1012,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1012
1012
|
# the pull request runs before the action in this job: no install, build
|
|
1013
1013
|
# or test step here; those belong in a separate job. ...
|
|
1014
1014
|
- id: conductor
|
|
1015
|
-
uses: vaultcompasshq/conductor@
|
|
1015
|
+
uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
|
|
1016
1016
|
with:
|
|
1017
1017
|
output: conductor.sarif
|
|
1018
1018
|
pr-comment: true
|
|
@@ -1091,12 +1091,12 @@ per pull request.
|
|
|
1091
1091
|
|
|
1092
1092
|
```yaml
|
|
1093
1093
|
- id: conductor-package-a
|
|
1094
|
-
uses: vaultcompasshq/conductor@
|
|
1094
|
+
uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
|
|
1095
1095
|
with:
|
|
1096
1096
|
pr-comment: true
|
|
1097
1097
|
pr-comment-marker: 'package-a'
|
|
1098
1098
|
- id: conductor-package-b
|
|
1099
|
-
uses: vaultcompasshq/conductor@
|
|
1099
|
+
uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
|
|
1100
1100
|
with:
|
|
1101
1101
|
pr-comment: true
|
|
1102
1102
|
pr-comment-marker: 'package-b'
|
package/dist/gate-runner.js
CHANGED
|
@@ -31,7 +31,7 @@ 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, refuseHeadControlledData, refuseHeadControlledProgram, } from './trust-base.js';
|
|
34
|
+
import { atLeastVersion, refuseHeadControlledArgument, refuseHeadControlledData, refuseHeadControlledProgram, writtenInsideWorkingTree, } from './trust-base.js';
|
|
35
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;
|
|
@@ -675,8 +675,9 @@ 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:");
|
|
680
681
|
if (refusal !== null) {
|
|
681
682
|
return refusal;
|
|
682
683
|
}
|
|
@@ -770,7 +771,7 @@ changeBase,
|
|
|
770
771
|
* after its enables, so the appended flag wins.
|
|
771
772
|
*/
|
|
772
773
|
preview = false) {
|
|
773
|
-
const passthrough = renderOptionFlags(gate.options);
|
|
774
|
+
const passthrough = renderOptionFlags(gate.options, gate.product);
|
|
774
775
|
const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
|
|
775
776
|
const config = external.configPath === undefined ? [] : ['--config', external.configPath];
|
|
776
777
|
switch (gate.product) {
|
|
@@ -946,7 +947,7 @@ preview = false) {
|
|
|
946
947
|
...lockfiles,
|
|
947
948
|
...(noResolve ? ['--no-resolve'] : []),
|
|
948
949
|
...callAnalysis,
|
|
949
|
-
...renderOptionFlags(options),
|
|
950
|
+
...renderOptionFlags(options, gate.product),
|
|
950
951
|
...(preview ? ['--no-call-analysis=all'] : []),
|
|
951
952
|
];
|
|
952
953
|
}
|
|
@@ -1304,7 +1305,11 @@ function previewRefusal(gate, repoRoot) {
|
|
|
1304
1305
|
detail: "the preview does not run call analysis, because it would build the head's code",
|
|
1305
1306
|
};
|
|
1306
1307
|
}
|
|
1307
|
-
|
|
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))) {
|
|
1308
1313
|
return {
|
|
1309
1314
|
reason: 'gate-program-refused',
|
|
1310
1315
|
detail: `preview under the proposed rules: the base command ${gate.command} is inside the working tree, so this gate was not run`,
|
|
@@ -1327,7 +1332,9 @@ function previewRefusal(gate, repoRoot) {
|
|
|
1327
1332
|
// on every preview spawn, an option-value directory included (review B1).
|
|
1328
1333
|
for (const arg of codeArguments(gate)) {
|
|
1329
1334
|
const candidates = argumentCandidates(arg, repoRoot);
|
|
1330
|
-
if (candidates.some((named) => realPathInside(repoRoot, named) ||
|
|
1335
|
+
if (candidates.some((named) => realPathInside(repoRoot, named) ||
|
|
1336
|
+
realPathInside(repoRoot, path.dirname(named)) ||
|
|
1337
|
+
writtenInsideWorkingTree(repoRoot, named))) {
|
|
1331
1338
|
return {
|
|
1332
1339
|
reason: 'gate-program-refused',
|
|
1333
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
|
@@ -404,14 +404,23 @@ function gateSection(gate, verbose, refusedOnTerminal = false) {
|
|
|
404
404
|
const facts = Object.entries(gate.run.details)
|
|
405
405
|
.filter(([key, value]) =>
|
|
406
406
|
// ignoredReported drives the line above rather than being a fact
|
|
407
|
-
// 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.
|
|
408
409
|
key !== 'ignoredReported' &&
|
|
410
|
+
key !== 'skipReason' &&
|
|
409
411
|
(typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') &&
|
|
410
412
|
value !== '')
|
|
411
413
|
.map(([key, value]) => `${key} ${String(value)}`);
|
|
412
414
|
if (facts.length > 0) {
|
|
413
415
|
lines.push(` ${facts.join(' ')}`);
|
|
414
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
|
+
}
|
|
415
424
|
for (const diagnostic of gate.run.diagnostics) {
|
|
416
425
|
lines.push(` note ${diagnostic.code}: ${diagnostic.message}`);
|
|
417
426
|
}
|
|
@@ -1030,7 +1039,30 @@ function gateCheckedNothing(gate) {
|
|
|
1030
1039
|
}
|
|
1031
1040
|
return (gate.diagnostics.some((d) => d.code === 'conductor/nothing-to-scan') ||
|
|
1032
1041
|
readNoPackages(gate) ||
|
|
1033
|
-
(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));
|
|
1034
1066
|
}
|
|
1035
1067
|
/** How the verdict sentence names a gate that ran and checked nothing. */
|
|
1036
1068
|
function checkedNothingWording(gate) {
|
|
@@ -1364,7 +1396,16 @@ function summaryLine(result) {
|
|
|
1364
1396
|
// decided there is none exactly where most readers stop reading. Grouped in
|
|
1365
1397
|
// first-seen order so the sentence does not reorder itself between runs.
|
|
1366
1398
|
const skippedByWording = new Map();
|
|
1367
|
-
|
|
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) {
|
|
1368
1409
|
const lead = skipWording(gate.reason).summary;
|
|
1369
1410
|
skippedByWording.set(lead, [
|
|
1370
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
|
@@ -26,6 +26,8 @@ export interface DataArgument {
|
|
|
26
26
|
positional: boolean;
|
|
27
27
|
/** The args entry as written, for the refusal message. */
|
|
28
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';
|
|
29
31
|
}
|
|
30
32
|
export interface ResolvedBinary {
|
|
31
33
|
/** What to spawn. */
|
|
@@ -59,14 +61,23 @@ export interface ResolvedBinary {
|
|
|
59
61
|
* When `command:` is the gate itself (commandIsGateProgram) only the args
|
|
60
62
|
* entries with a code extension are listed here (`codeArguments`); the
|
|
61
63
|
* rest of its args are its own argv, read as data, and land in
|
|
62
|
-
* `dataArguments` instead.
|
|
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).
|
|
63
67
|
*/
|
|
64
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[];
|
|
65
75
|
/**
|
|
66
76
|
* Every args entry that could name a path, when `command:` is the gate
|
|
67
77
|
* itself (`dataArgumentPaths`), in args order, by POSITION and never by
|
|
68
|
-
* what the head's disk holds
|
|
69
|
-
* resolution found
|
|
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).
|
|
70
81
|
*
|
|
71
82
|
* The pull-request check (refuseHeadControlledData) decides from the BASE
|
|
72
83
|
* tree what each one is: a file must be the base's blob, a directory given
|
|
@@ -195,7 +206,8 @@ export declare function argumentCandidates(arg: string, repoRoot: string): strin
|
|
|
195
206
|
/**
|
|
196
207
|
* The args entries vetted as CODE: every entry when the command is not the
|
|
197
208
|
* gate itself, and only the code-extension values (`hasCodeExtension`) when
|
|
198
|
-
* it is
|
|
209
|
+
* it is, then the code-extension `options:` values (optionCodeArguments).
|
|
210
|
+
* Each goes through `argumentCandidates`, here and in the preview.
|
|
199
211
|
*/
|
|
200
212
|
export declare function codeArguments(gate: GatePolicy): string[];
|
|
201
213
|
/**
|
|
@@ -218,5 +230,12 @@ export declare function codeArguments(gate: GatePolicy): string[];
|
|
|
218
230
|
* wrapper given a gate's name that hands an extension-less entry to an
|
|
219
231
|
* interpreter is a wrapper, vetted no further than this (README,
|
|
220
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.
|
|
221
240
|
*/
|
|
222
241
|
export declare function dataArgumentPaths(gate: GatePolicy, repoRoot: string): DataArgument[];
|
package/dist/resolve.js
CHANGED
|
@@ -61,6 +61,7 @@
|
|
|
61
61
|
// reported missing.
|
|
62
62
|
import { accessSync, constants, lstatSync, statSync } from 'node:fs';
|
|
63
63
|
import path from 'node:path';
|
|
64
|
+
import { NO_VALUE_FLAGS, renderOptionFlags } from './policy.js';
|
|
64
65
|
import { profileFor } from './products.js';
|
|
65
66
|
export const CANDIDATES = {
|
|
66
67
|
'dep-guard': [{ name: 'dep-guard', prefix: ['scan'], versionSafe: true }],
|
|
@@ -221,6 +222,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
221
222
|
const candidateName = inferred?.name ?? baseName(gate.command);
|
|
222
223
|
const candidate = inferred ?? table[0];
|
|
223
224
|
const argumentPaths = argumentPathsOf(gate, repoRoot);
|
|
225
|
+
const optionArgumentPaths = optionArgumentPathsOf(gate, repoRoot);
|
|
224
226
|
const dataArguments = dataArgumentPaths(gate, repoRoot);
|
|
225
227
|
// A build directory holds plain .js files with a shebang but no
|
|
226
228
|
// executable bit surprisingly often (a fresh tsc output, a file copied
|
|
@@ -234,6 +236,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
234
236
|
program: gate.command,
|
|
235
237
|
argvPrefix: [gate.command, ...prefix],
|
|
236
238
|
argumentPaths,
|
|
239
|
+
optionArgumentPaths,
|
|
237
240
|
dataArguments,
|
|
238
241
|
source: 'policy',
|
|
239
242
|
candidate: candidateName,
|
|
@@ -255,6 +258,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
255
258
|
program: gate.command,
|
|
256
259
|
argvPrefix: prefix,
|
|
257
260
|
argumentPaths,
|
|
261
|
+
optionArgumentPaths,
|
|
258
262
|
dataArguments,
|
|
259
263
|
source: 'policy',
|
|
260
264
|
candidate: candidateName,
|
|
@@ -271,8 +275,11 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
271
275
|
command: found.command,
|
|
272
276
|
program: found.command,
|
|
273
277
|
argvPrefix: [...candidate.prefix],
|
|
274
|
-
|
|
275
|
-
|
|
278
|
+
// No args: here (they go with a command:), but the options: are handed
|
|
279
|
+
// to this gate all the same (audit 2026-11-01, MB1).
|
|
280
|
+
argumentPaths: optionArgumentPathsOf(gate, repoRoot),
|
|
281
|
+
optionArgumentPaths: optionArgumentPathsOf(gate, repoRoot),
|
|
282
|
+
dataArguments: dataArgumentPaths(gate, repoRoot),
|
|
276
283
|
source: found.source,
|
|
277
284
|
candidate: candidate.name,
|
|
278
285
|
versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue, skipNodeModules),
|
|
@@ -412,35 +419,10 @@ function hasCodeExtension(value) {
|
|
|
412
419
|
* - a bare word that is one of the product's subcommands: nothing;
|
|
413
420
|
* - any other word: a positional.
|
|
414
421
|
*/
|
|
415
|
-
|
|
416
|
-
* Flags that take NO value, per product, read from each gate's own `--help`
|
|
417
|
-
* (osv-scanner 2.4.0 `scan source`, gitleaks 8.30.1 `git`, dep-guard 0.17.0
|
|
418
|
-
* and vault-guard 1.12.1 `scan`, intent-guard 1.10.2 `check`). The word after
|
|
419
|
-
* one of these is NOT its value, so `osv-scanner scan source -r .` keeps `.`
|
|
420
|
-
* as a positional scan target (re-review 2026-10-28, R1). Any flag not listed
|
|
421
|
-
* stays fail-closed: the word after it is read as its value. A wrong entry
|
|
422
|
-
* would let a value be read as a positional, which leaves a directory
|
|
423
|
-
* unvetted, so entries come only from a gate's own help text.
|
|
424
|
-
*/
|
|
425
|
-
const NO_VALUE_FLAGS = {
|
|
426
|
-
'osv-scanner': [
|
|
427
|
-
'-r', '--recursive', '--no-ignore', '--include-git-root', '--serve', '--offline',
|
|
428
|
-
'--offline-vulnerabilities', '--download-offline-databases', '--no-resolve',
|
|
429
|
-
'--allow-no-lockfiles', '--all-packages', '--all-vulns',
|
|
430
|
-
'--experimental-flag-deprecated-packages', '--experimental-no-default-plugins', '-h', '--help',
|
|
431
|
-
],
|
|
432
|
-
gitleaks: [
|
|
433
|
-
'-v', '--verbose', '--pre-commit', '--staged', '--ignore-gitleaks-allow', '--no-banner',
|
|
434
|
-
'--no-color', '--redact', '-h', '--help',
|
|
435
|
-
],
|
|
436
|
-
'dep-guard': ['--staged', '--online', '--no-online', '-h', '--help'],
|
|
437
|
-
'vault-guard': ['--staged', '-h', '--help'],
|
|
438
|
-
'intent-guard': ['--staged', '--no-require-frozen', '--log', '--json', '-h', '--help', '-v', '--version'],
|
|
439
|
-
};
|
|
440
|
-
function gateArgEntries(gate) {
|
|
422
|
+
function gateArgEntries(product, words) {
|
|
441
423
|
const entries = [];
|
|
442
424
|
let pendingOption = false;
|
|
443
|
-
for (const arg of
|
|
425
|
+
for (const arg of words) {
|
|
444
426
|
if (arg.startsWith('-') && arg !== '-') {
|
|
445
427
|
pendingOption = false;
|
|
446
428
|
const equals = arg.indexOf('=');
|
|
@@ -453,7 +435,7 @@ function gateArgEntries(gate) {
|
|
|
453
435
|
else {
|
|
454
436
|
// A flag the gate's own help says takes no value leaves the next word
|
|
455
437
|
// a positional (NO_VALUE_FLAGS); any other flag claims it.
|
|
456
|
-
pendingOption = !NO_VALUE_FLAGS[
|
|
438
|
+
pendingOption = !NO_VALUE_FLAGS[product].includes(arg);
|
|
457
439
|
}
|
|
458
440
|
continue;
|
|
459
441
|
}
|
|
@@ -462,30 +444,54 @@ function gateArgEntries(gate) {
|
|
|
462
444
|
entries.push({ value: arg, positional: false, entry: arg });
|
|
463
445
|
continue;
|
|
464
446
|
}
|
|
465
|
-
if (CANDIDATES[
|
|
447
|
+
if (CANDIDATES[product].some((candidate) => candidate.prefix.includes(arg))) {
|
|
466
448
|
continue;
|
|
467
449
|
}
|
|
468
450
|
entries.push({ value: arg, positional: true, entry: arg });
|
|
469
451
|
}
|
|
470
452
|
return entries.filter((each) => each.value !== '');
|
|
471
453
|
}
|
|
454
|
+
/**
|
|
455
|
+
* The policy's `options:` as the gate receives them: rendered to flags
|
|
456
|
+
* (renderOptionFlags, the same rendering gateArgs appends to every spawn) and
|
|
457
|
+
* read by position like a gate-named command's args (audit 2026-11-01, MB1).
|
|
458
|
+
*
|
|
459
|
+
* Whatever the command is: the rendered flags always come after the args, so
|
|
460
|
+
* they are the gate's own argv, or a script's argv when the command is an
|
|
461
|
+
* interpreter, and never an interpreter's. Option keys cannot hold `=` (the
|
|
462
|
+
* schema's key pattern), so `--name value` is the only rendering there is.
|
|
463
|
+
*/
|
|
464
|
+
function optionEntries(gate) {
|
|
465
|
+
return gateArgEntries(gate.product, renderOptionFlags(gate.options, gate.product));
|
|
466
|
+
}
|
|
467
|
+
/** The `options:` values vetted as CODE: those with a code extension, as for a gate-named command's args. */
|
|
468
|
+
function optionCodeArguments(gate) {
|
|
469
|
+
return optionEntries(gate)
|
|
470
|
+
.filter((each) => hasCodeExtension(each.value))
|
|
471
|
+
.map((each) => each.value);
|
|
472
|
+
}
|
|
472
473
|
/**
|
|
473
474
|
* The args entries vetted as CODE: every entry when the command is not the
|
|
474
475
|
* gate itself, and only the code-extension values (`hasCodeExtension`) when
|
|
475
|
-
* it is
|
|
476
|
+
* it is, then the code-extension `options:` values (optionCodeArguments).
|
|
477
|
+
* Each goes through `argumentCandidates`, here and in the preview.
|
|
476
478
|
*/
|
|
477
479
|
export function codeArguments(gate) {
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
480
|
+
const fromArgs = !commandIsGateProgram(gate)
|
|
481
|
+
? gate.args ?? []
|
|
482
|
+
: gateArgEntries(gate.product, gate.args ?? [])
|
|
483
|
+
.filter((each) => hasCodeExtension(each.value))
|
|
484
|
+
.map((each) => each.value);
|
|
485
|
+
return [...fromArgs, ...optionCodeArguments(gate)];
|
|
484
486
|
}
|
|
485
487
|
/** `argumentCandidates` for every code argument (`codeArguments`), flattened. */
|
|
486
488
|
function argumentPathsOf(gate, repoRoot) {
|
|
487
489
|
return codeArguments(gate).flatMap((arg) => argumentCandidates(arg, repoRoot));
|
|
488
490
|
}
|
|
491
|
+
/** `argumentCandidates` for the code-extension `options:` values alone (optionCodeArguments). */
|
|
492
|
+
function optionArgumentPathsOf(gate, repoRoot) {
|
|
493
|
+
return optionCodeArguments(gate).flatMap((arg) => argumentCandidates(arg, repoRoot));
|
|
494
|
+
}
|
|
489
495
|
/**
|
|
490
496
|
* The args entries of a gate-named command that are its own DATA, when
|
|
491
497
|
* `command:` is the gate itself (commandIsGateProgram), in args order; empty
|
|
@@ -506,14 +512,29 @@ function argumentPathsOf(gate, repoRoot) {
|
|
|
506
512
|
* wrapper given a gate's name that hands an extension-less entry to an
|
|
507
513
|
* interpreter is a wrapper, vetted no further than this (README,
|
|
508
514
|
* pull-request trust boundary).
|
|
515
|
+
*
|
|
516
|
+
* Then every non-code `options:` value (optionEntries), WHATEVER the command
|
|
517
|
+
* is and with no command at all: they are rendered into the argv of every
|
|
518
|
+
* spawn, after the args, so they are the gate's own data (or a script's)
|
|
519
|
+
* whoever runs them, and a rules directory written there is as much the
|
|
520
|
+
* rules as one written in args (audit 2026-11-01, MB1). Marked `from:
|
|
521
|
+
* 'options'` only so a refusal names the list the value came from.
|
|
509
522
|
*/
|
|
510
523
|
export function dataArgumentPaths(gate, repoRoot) {
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
524
|
+
const fromArgs = gate.command === undefined || !commandIsGateProgram(gate)
|
|
525
|
+
? []
|
|
526
|
+
: gateArgEntries(gate.product, gate.args ?? [])
|
|
527
|
+
.filter((each) => !hasCodeExtension(each.value))
|
|
528
|
+
.map((each) => ({ path: path.resolve(repoRoot, each.value), positional: each.positional, entry: each.entry }));
|
|
529
|
+
const fromOptions = optionEntries(gate)
|
|
515
530
|
.filter((each) => !hasCodeExtension(each.value))
|
|
516
|
-
.map((each) => ({
|
|
531
|
+
.map((each) => ({
|
|
532
|
+
path: path.resolve(repoRoot, each.value),
|
|
533
|
+
positional: each.positional,
|
|
534
|
+
entry: each.entry,
|
|
535
|
+
from: 'options',
|
|
536
|
+
}));
|
|
537
|
+
return [...fromArgs, ...fromOptions];
|
|
517
538
|
}
|
|
518
539
|
/**
|
|
519
540
|
* The version probe for a policy `command:` that is not itself a gate name,
|
package/dist/trust-base.d.ts
CHANGED
|
@@ -253,6 +253,12 @@ export type TreeEntry = {
|
|
|
253
253
|
* decided outside the tree, so it is an error, never absent.
|
|
254
254
|
*/
|
|
255
255
|
export declare function treeEntryAt(repoRoot: string, ref: string, relativePath: string): TreeEntry;
|
|
256
|
+
/**
|
|
257
|
+
* Whether `candidate`, as written, names the working tree or something in it
|
|
258
|
+
* (writtenRelative). For the preview's outright refusals, so a base path
|
|
259
|
+
* written inside the tree is refused there even when a link on it points out.
|
|
260
|
+
*/
|
|
261
|
+
export declare function writtenInsideWorkingTree(repoRoot: string, candidate: string): boolean;
|
|
256
262
|
/**
|
|
257
263
|
* Why this gate's PROGRAM cannot be trusted on a pull-request run, or null.
|
|
258
264
|
*
|
|
@@ -322,10 +328,23 @@ export declare function treeEntryAt(repoRoot: string, ref: string, relativePath:
|
|
|
322
328
|
* or its tree entry is a link rather than a regular file, and either refuses.
|
|
323
329
|
* Vetting the target is what catches a link whose own path is outside the
|
|
324
330
|
* tree pointing into it; it never decides the in-repo case.
|
|
331
|
+
*
|
|
332
|
+
* AND THE PATH AS WRITTEN, for this rule and for both args rules below
|
|
333
|
+
* (audit 2026-11-01, MB2). Both spellings above resolve the directories on
|
|
334
|
+
* the path through the head's disk, so a head that replaced `tools/` with a
|
|
335
|
+
* link to a base-tracked `stub/` had `tools/vault-guard` judged as
|
|
336
|
+
* `stub/vault-guard`, which the base approved. So the path is also judged
|
|
337
|
+
* exactly as written inside the tree (writtenRelative): refused when HEAD's
|
|
338
|
+
* tree holds any directory on it as a link (linkOnWrittenPathAtHead), and
|
|
339
|
+
* the written path is one more candidate, judged by its own entries at both
|
|
340
|
+
* refs like the others. A link the base already had there is refused too:
|
|
341
|
+
* what the gate is handed through it is still decided by the head tree.
|
|
325
342
|
*/
|
|
326
343
|
export declare function refuseHeadControlledProgram(repoRoot: string, trustBase: string, programPath: string,
|
|
327
344
|
/** True when asked for an interpreter's `args:` entry, which words the root refusal for an argument. */
|
|
328
|
-
fromArgs?: boolean
|
|
345
|
+
fromArgs?: boolean,
|
|
346
|
+
/** Which policy list an argument came from, for its refusals: `args:`, or `options:` for a code-extension option value. */
|
|
347
|
+
list?: string): string | null;
|
|
329
348
|
/**
|
|
330
349
|
* Whether a gate's reported version is at least `minimum`.
|
|
331
350
|
*
|
|
@@ -371,13 +390,16 @@ export declare function atLeastVersion(version: string | null, minimum: string):
|
|
|
371
390
|
* read from disk, and a link is never followed for that, so a link is always
|
|
372
391
|
* vetted as a link.
|
|
373
392
|
*/
|
|
374
|
-
export declare function refuseHeadControlledArgument(repoRoot: string, trustBase: string, argumentPath: string
|
|
393
|
+
export declare function refuseHeadControlledArgument(repoRoot: string, trustBase: string, argumentPath: string,
|
|
394
|
+
/** Which policy list the path came from, for the refusals: `args:`, or `options:` for a code-extension option value. */
|
|
395
|
+
list?: string): string | null;
|
|
375
396
|
/**
|
|
376
397
|
* Why a path a gate's own `args:` name cannot be trusted on a pull-request
|
|
377
398
|
* run, or null (audit 2026-10-28, N1, and its review, B1 and N-a).
|
|
378
399
|
*
|
|
379
|
-
* Asked
|
|
380
|
-
* src/resolve.ts),
|
|
400
|
+
* Asked for the args of a `command:` that is the gate itself, and for the
|
|
401
|
+
* `options:` values of every gate (dataArgumentPaths in src/resolve.ts),
|
|
402
|
+
* since both are the gate's own argv: a rules file such as
|
|
381
403
|
* `--config=.gitleaks.toml`, or a rules directory such as dep-guard's
|
|
382
404
|
* `--corpus-dir`, is read as data, not loaded as code. Its contents still
|
|
383
405
|
* decide what the gate reports, so a pull request that rewrote them would
|
|
@@ -406,6 +428,14 @@ export declare function refuseHeadControlledArgument(repoRoot: string, trustBase
|
|
|
406
428
|
* - Absent at the base: accepted only if the head has nothing there either,
|
|
407
429
|
* tracked or on disk (a word that is not a path, `--format=json`);
|
|
408
430
|
* otherwise it is a path this pull request chose, and refused.
|
|
431
|
+
* - AS WRITTEN as well as resolved (audit 2026-11-01, MB2): a directory on
|
|
432
|
+
* the written path that HEAD's tree holds as a link is refused, the
|
|
433
|
+
* written path is judged by the rules above like the resolved ones, and a
|
|
434
|
+
* positional scan target the base tracks as a directory is refused when
|
|
435
|
+
* HEAD holds it as a link, since that one is otherwise not compared.
|
|
436
|
+
* - The same for an `options:` value (audit 2026-11-01, MB1): it is
|
|
437
|
+
* rendered into the gate's argv and read the same way (dataArgumentPaths),
|
|
438
|
+
* and `from: 'options'` only changes which list the refusal names.
|
|
409
439
|
*
|
|
410
440
|
* Only whether something exists on disk at a path the base does not track is
|
|
411
441
|
* read from the working tree; every other answer is a `git ls-tree` listing.
|
|
@@ -414,4 +444,5 @@ export declare function refuseHeadControlledData(repoRoot: string, trustBase: st
|
|
|
414
444
|
path: string;
|
|
415
445
|
positional: boolean;
|
|
416
446
|
entry?: string;
|
|
447
|
+
from?: 'options';
|
|
417
448
|
}): string | null;
|
package/dist/trust-base.js
CHANGED
|
@@ -708,6 +708,132 @@ function withResolvedParent(candidate) {
|
|
|
708
708
|
const parent = path.dirname(candidate);
|
|
709
709
|
return path.join(realOrNull(parent) ?? parent, path.basename(candidate));
|
|
710
710
|
}
|
|
711
|
+
/**
|
|
712
|
+
* A vetted path AS WRITTEN, relative to the repository root with `/`
|
|
713
|
+
* separators: '' for the root itself, null when the path is not in the
|
|
714
|
+
* working tree (audit 2026-11-01, MB2).
|
|
715
|
+
*
|
|
716
|
+
* The resolved spellings above follow every link on the path, and a link
|
|
717
|
+
* inside the tree is the head's to choose: a head that replaces `data/` with
|
|
718
|
+
* a link to a base-approved `alt/` makes `data/corpus` resolve to
|
|
719
|
+
* `alt/corpus`, whose tree is the base's, while the policy named
|
|
720
|
+
* `data/corpus`. So the components INSIDE the tree are kept exactly as
|
|
721
|
+
* written. Only the leading components that reach the tree are resolved: the
|
|
722
|
+
* shortest prefix whose real path is the root or under it, which is how a
|
|
723
|
+
* root spelled through a symlinked mount (a macOS temporary directory) or an
|
|
724
|
+
* outside link into the tree still lands inside. Components above the tree
|
|
725
|
+
* are the machine's, which a pull request cannot write.
|
|
726
|
+
*/
|
|
727
|
+
function writtenRelative(repoReal, candidate) {
|
|
728
|
+
const absolute = path.resolve(candidate);
|
|
729
|
+
const root = path.parse(absolute).root;
|
|
730
|
+
const segments = absolute.slice(root.length).split(path.sep).filter((segment) => segment !== '');
|
|
731
|
+
for (let depth = 0; depth <= segments.length; depth += 1) {
|
|
732
|
+
const real = realOrNull(path.join(root, ...segments.slice(0, depth)));
|
|
733
|
+
if (real === null) {
|
|
734
|
+
// Nothing below a missing component exists either.
|
|
735
|
+
return null;
|
|
736
|
+
}
|
|
737
|
+
if (real === repoReal || insideWorkingTree(repoReal, real)) {
|
|
738
|
+
const reached = path.relative(repoReal, real).split(path.sep).filter((segment) => segment !== '');
|
|
739
|
+
return [...reached, ...segments.slice(depth)].join('/');
|
|
740
|
+
}
|
|
741
|
+
}
|
|
742
|
+
return null;
|
|
743
|
+
}
|
|
744
|
+
/**
|
|
745
|
+
* Whether `candidate`, as written, names the working tree or something in it
|
|
746
|
+
* (writtenRelative). For the preview's outright refusals, so a base path
|
|
747
|
+
* written inside the tree is refused there even when a link on it points out.
|
|
748
|
+
*/
|
|
749
|
+
export function writtenInsideWorkingTree(repoRoot, candidate) {
|
|
750
|
+
const repoReal = realOrNull(repoRoot);
|
|
751
|
+
return repoReal !== null && writtenRelative(repoReal, candidate) !== null;
|
|
752
|
+
}
|
|
753
|
+
/**
|
|
754
|
+
* The first DIRECTORY component above the last one of `relative` that HEAD's
|
|
755
|
+
* tree holds as a symbolic link, or null (audit 2026-11-01, MB2). Read from
|
|
756
|
+
* `git ls-tree`, one component at a time, never from the disk. Stops,
|
|
757
|
+
* answering null, at a component HEAD does not have, cannot list, or holds as
|
|
758
|
+
* a file: what is below it is then absent or unreadable, which the rule
|
|
759
|
+
* asking decides. The last component is each rule's own entry, which every
|
|
760
|
+
* rule already refuses as a link in its own words (a positional scan target
|
|
761
|
+
* included, in refuseHeadControlledData).
|
|
762
|
+
*/
|
|
763
|
+
function linkOnWrittenPathAtHead(repoRoot, relative) {
|
|
764
|
+
const segments = relative.split('/').filter((segment) => segment !== '' && segment !== '.');
|
|
765
|
+
for (let depth = 1; depth < segments.length; depth += 1) {
|
|
766
|
+
const prefix = segments.slice(0, depth).join('/');
|
|
767
|
+
const listed = listOne(repoRoot, 'HEAD', prefix);
|
|
768
|
+
if (listed.kind !== 'entry') {
|
|
769
|
+
return null;
|
|
770
|
+
}
|
|
771
|
+
if (listed.mode === '120000') {
|
|
772
|
+
return prefix;
|
|
773
|
+
}
|
|
774
|
+
if (listed.type !== 'tree') {
|
|
775
|
+
return null;
|
|
776
|
+
}
|
|
777
|
+
}
|
|
778
|
+
return null;
|
|
779
|
+
}
|
|
780
|
+
/**
|
|
781
|
+
* The refusal for a vetted path a link at HEAD redirects, naming the link.
|
|
782
|
+
* `subject` is how the rule asking names the path: "the gate program at X",
|
|
783
|
+
* "in the gate's args:, the path X", "the path X named in the gate's args:".
|
|
784
|
+
*/
|
|
785
|
+
function linkOnWrittenPathRefusal(subject, link, baseName) {
|
|
786
|
+
return (`${subject} goes through ${link}, which is a symbolic link at the head commit, so this pull ` +
|
|
787
|
+
'request changed the path it is judged by: the gate would be handed whatever that link points ' +
|
|
788
|
+
`at, not the path ${baseName} approved. conductor judges every path as written and follows no ` +
|
|
789
|
+
'link inside the repository. Name the directory the link points at, or commit a real directory ' +
|
|
790
|
+
'there on the base branch. Nothing was checked by this gate.');
|
|
791
|
+
}
|
|
792
|
+
/**
|
|
793
|
+
* The first component of `relative`, the last one included, that is a
|
|
794
|
+
* symbolic link ON DISK while HEAD's tree holds no link at that exact
|
|
795
|
+
* spelling, or null (review of the 2026-11-01 fix, item 1).
|
|
796
|
+
*
|
|
797
|
+
* `git ls-tree` matches names exactly, and a case-insensitive disk does not:
|
|
798
|
+
* a head that adds a link entry `data` beside the base's tree `Data` leaves
|
|
799
|
+
* only `data -> alt` on disk after a checkout, so `Data/corpus` reads the
|
|
800
|
+
* link's target while the tree still says `Data` is the base's directory.
|
|
801
|
+
* The disk is therefore asked too, and a link there that the tree does not
|
|
802
|
+
* declare at that spelling refuses: what the gate is handed is decided by
|
|
803
|
+
* something other than the tree conductor judged. A link the tree DOES
|
|
804
|
+
* declare is left to the checks that already refuse it. Stops at the first
|
|
805
|
+
* component that is missing or not a directory. Each rule asks this LAST, so
|
|
806
|
+
* a path its own checks refuse keeps its wording; the exception is the data
|
|
807
|
+
* rule's positional root, which returns early and asks this first (R1).
|
|
808
|
+
*/
|
|
809
|
+
function undeclaredLinkOnDisk(repoRoot, repoReal, relative) {
|
|
810
|
+
const segments = relative.split('/').filter((segment) => segment !== '' && segment !== '.');
|
|
811
|
+
for (let depth = 1; depth <= segments.length; depth += 1) {
|
|
812
|
+
const prefix = segments.slice(0, depth).join('/');
|
|
813
|
+
let stats;
|
|
814
|
+
try {
|
|
815
|
+
stats = lstatSync(path.join(repoReal, prefix));
|
|
816
|
+
}
|
|
817
|
+
catch {
|
|
818
|
+
return null;
|
|
819
|
+
}
|
|
820
|
+
if (stats.isSymbolicLink()) {
|
|
821
|
+
const listed = listOne(repoRoot, 'HEAD', prefix);
|
|
822
|
+
return listed.kind === 'entry' && listed.mode === '120000' ? null : prefix;
|
|
823
|
+
}
|
|
824
|
+
if (!stats.isDirectory()) {
|
|
825
|
+
return null;
|
|
826
|
+
}
|
|
827
|
+
}
|
|
828
|
+
return null;
|
|
829
|
+
}
|
|
830
|
+
/** The refusal for a link on disk the head tree does not declare, naming it. */
|
|
831
|
+
function undeclaredLinkRefusal(subject, link) {
|
|
832
|
+
return (`${subject} goes through ${link}, which is a symbolic link on disk that the pull request's tree does not declare ` +
|
|
833
|
+
'there, so what the gate would be handed is decided by something other than the tree conductor ' +
|
|
834
|
+
'judged. On a case-insensitive filesystem a tree entry spelled with different case is the same ' +
|
|
835
|
+
'path. Nothing was checked by this gate.');
|
|
836
|
+
}
|
|
711
837
|
/**
|
|
712
838
|
* The tree object id of one directory at a ref, or null.
|
|
713
839
|
*
|
|
@@ -792,16 +918,44 @@ function treeShaAt(repoRoot, ref, relativeDir) {
|
|
|
792
918
|
* or its tree entry is a link rather than a regular file, and either refuses.
|
|
793
919
|
* Vetting the target is what catches a link whose own path is outside the
|
|
794
920
|
* tree pointing into it; it never decides the in-repo case.
|
|
921
|
+
*
|
|
922
|
+
* AND THE PATH AS WRITTEN, for this rule and for both args rules below
|
|
923
|
+
* (audit 2026-11-01, MB2). Both spellings above resolve the directories on
|
|
924
|
+
* the path through the head's disk, so a head that replaced `tools/` with a
|
|
925
|
+
* link to a base-tracked `stub/` had `tools/vault-guard` judged as
|
|
926
|
+
* `stub/vault-guard`, which the base approved. So the path is also judged
|
|
927
|
+
* exactly as written inside the tree (writtenRelative): refused when HEAD's
|
|
928
|
+
* tree holds any directory on it as a link (linkOnWrittenPathAtHead), and
|
|
929
|
+
* the written path is one more candidate, judged by its own entries at both
|
|
930
|
+
* refs like the others. A link the base already had there is refused too:
|
|
931
|
+
* what the gate is handed through it is still decided by the head tree.
|
|
795
932
|
*/
|
|
796
933
|
export function refuseHeadControlledProgram(repoRoot, trustBase, programPath,
|
|
797
934
|
/** True when asked for an interpreter's `args:` entry, which words the root refusal for an argument. */
|
|
798
|
-
fromArgs = false
|
|
935
|
+
fromArgs = false,
|
|
936
|
+
/** Which policy list an argument came from, for its refusals: `args:`, or `options:` for a code-extension option value. */
|
|
937
|
+
list = "the gate's args:") {
|
|
799
938
|
const repoReal = realOrNull(repoRoot);
|
|
800
939
|
if (repoReal === null) {
|
|
801
940
|
return `the repository root ${repoRoot} could not be resolved, so the gate program could not be checked against "${trustBase}". Nothing was checked by this gate.`;
|
|
802
941
|
}
|
|
942
|
+
// AS WRITTEN, before either resolved spelling (audit 2026-11-01, MB2): a
|
|
943
|
+
// directory on the written path that HEAD holds as a link redirects the
|
|
944
|
+
// program to wherever the head points it, and the written path is also a
|
|
945
|
+
// candidate below, judged by its own entries at both refs.
|
|
946
|
+
const written = writtenRelative(repoReal, programPath);
|
|
947
|
+
if (written !== null && written !== '') {
|
|
948
|
+
const link = linkOnWrittenPathAtHead(repoRoot, written);
|
|
949
|
+
if (link !== null) {
|
|
950
|
+
return linkOnWrittenPathRefusal(fromArgs ? `in ${list}, the path ${written}` : `the gate program at ${written}`, link, trustBase === '' ? 'the base' : `"${trustBase}"`);
|
|
951
|
+
}
|
|
952
|
+
}
|
|
803
953
|
const candidates = new Set();
|
|
804
|
-
for (const candidate of [
|
|
954
|
+
for (const candidate of [
|
|
955
|
+
withResolvedParent(programPath),
|
|
956
|
+
realOrNull(programPath),
|
|
957
|
+
written === null ? null : path.join(repoReal, written),
|
|
958
|
+
]) {
|
|
805
959
|
if (candidate !== null && insideWorkingTree(repoReal, candidate)) {
|
|
806
960
|
candidates.add(candidate);
|
|
807
961
|
}
|
|
@@ -827,18 +981,18 @@ fromArgs = false) {
|
|
|
827
981
|
// gate program": it may be a script or a file a script reads (review
|
|
828
982
|
// 2026-10-28, N-f, which the first N1 round fixed for the root only).
|
|
829
983
|
if (fromArgs && (base === null || head === null)) {
|
|
830
|
-
return (`in
|
|
984
|
+
return (`in ${list}, the ${trustBase === '' ? 'base' : `"${trustBase}"`} ref does not ` +
|
|
831
985
|
`track ${relative}, a file named there or one an interpreter could load for it, so it is ` +
|
|
832
986
|
'a file this pull request controls, vetted as code. Land it on the base branch first, or ' +
|
|
833
987
|
'name a script outside the repository. Nothing was checked by this gate.');
|
|
834
988
|
}
|
|
835
989
|
if (fromArgs && (!isRegularFileMode(base.mode) || !isRegularFileMode(head.mode))) {
|
|
836
|
-
return (`in
|
|
990
|
+
return (`in ${list}, the file ${relative} is not a regular file at both "${trustBase}" ` +
|
|
837
991
|
'and the head commit, so what an interpreter would load is decided by something other ' +
|
|
838
992
|
'than the approved bytes. Nothing was checked by this gate.');
|
|
839
993
|
}
|
|
840
994
|
if (fromArgs && base.sha !== head.sha) {
|
|
841
|
-
return (`in
|
|
995
|
+
return (`in ${list}, the file ${relative} is not the one "${trustBase}" approved: this ` +
|
|
842
996
|
'pull request changes it, and it is vetted as code an interpreter could load. Land the ' +
|
|
843
997
|
'change on the base branch first. Nothing was checked by this gate.');
|
|
844
998
|
}
|
|
@@ -882,7 +1036,7 @@ fromArgs = false) {
|
|
|
882
1036
|
// the file may be a script or something the script reads, so it is
|
|
883
1037
|
// not called "the gate program", and the remedy is about the
|
|
884
1038
|
// command, not about vendoring (audit 2026-10-28, N1).
|
|
885
|
-
return (`the file ${relative} named in
|
|
1039
|
+
return (`the file ${relative} named in ${list} is at the repository root, and it is ` +
|
|
886
1040
|
'vetted as code an interpreter could load (the command is not the gate itself, or ' +
|
|
887
1041
|
'the entry has a code extension): ' +
|
|
888
1042
|
'the directory that would have to be unchanged is the whole repository, and this pull ' +
|
|
@@ -897,7 +1051,7 @@ fromArgs = false) {
|
|
|
897
1051
|
'its own directory, or install it on PATH. Nothing was checked by this gate.');
|
|
898
1052
|
}
|
|
899
1053
|
if (fromArgs) {
|
|
900
|
-
return (`in
|
|
1054
|
+
return (`in ${list}, a file beside ${relative} in ${directory} is not what ` +
|
|
901
1055
|
`"${trustBase}" approved: ${relative} is unchanged, but the directory around it is not, ` +
|
|
902
1056
|
'and code an interpreter loads can load its neighbours. Land the change on the base ' +
|
|
903
1057
|
'branch first, or name a script outside the repository. Nothing was checked by this gate.');
|
|
@@ -909,6 +1063,13 @@ fromArgs = false) {
|
|
|
909
1063
|
'PATH. Nothing was checked by this gate.');
|
|
910
1064
|
}
|
|
911
1065
|
}
|
|
1066
|
+
// LAST, the disk against the tree (review of the 2026-11-01 fix, item 1).
|
|
1067
|
+
if (written !== null && written !== '') {
|
|
1068
|
+
const undeclared = undeclaredLinkOnDisk(repoRoot, repoReal, written);
|
|
1069
|
+
if (undeclared !== null) {
|
|
1070
|
+
return undeclaredLinkRefusal(fromArgs ? `in ${list}, the path ${written}` : `the gate program at ${written}`, undeclared);
|
|
1071
|
+
}
|
|
1072
|
+
}
|
|
912
1073
|
return null;
|
|
913
1074
|
}
|
|
914
1075
|
/**
|
|
@@ -975,18 +1136,32 @@ export function atLeastVersion(version, minimum) {
|
|
|
975
1136
|
* read from disk, and a link is never followed for that, so a link is always
|
|
976
1137
|
* vetted as a link.
|
|
977
1138
|
*/
|
|
978
|
-
export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath
|
|
1139
|
+
export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath,
|
|
1140
|
+
/** Which policy list the path came from, for the refusals: `args:`, or `options:` for a code-extension option value. */
|
|
1141
|
+
list = "the gate's args:") {
|
|
979
1142
|
const repoReal = realOrNull(repoRoot);
|
|
980
1143
|
if (repoReal === null) {
|
|
981
1144
|
return `the repository root ${repoRoot} could not be resolved, so the gate arguments could not be checked against "${trustBase}". Nothing was checked by this gate.`;
|
|
982
1145
|
}
|
|
983
|
-
|
|
1146
|
+
// The written spelling beside the resolved ones (audit 2026-11-01, MB2).
|
|
1147
|
+
const written = writtenRelative(repoReal, argumentPath);
|
|
1148
|
+
const spellings = [
|
|
1149
|
+
withResolvedParent(argumentPath),
|
|
1150
|
+
realOrNull(argumentPath),
|
|
1151
|
+
written === null ? null : path.join(repoReal, written),
|
|
1152
|
+
].filter((spelling) => spelling !== null);
|
|
984
1153
|
if (spellings.some((spelling) => path.relative(repoReal, spelling) === '')) {
|
|
985
|
-
return (
|
|
1154
|
+
return (`${list} name the repository root (${argumentPath}), so what would run is decided by ` +
|
|
986
1155
|
`the whole working tree, and this pull request differs from "${trustBase}" somewhere in it. ` +
|
|
987
1156
|
'conductor already hands each gate the repository it scans; name a script in its own ' +
|
|
988
1157
|
'directory instead. Nothing was checked by this gate.');
|
|
989
1158
|
}
|
|
1159
|
+
if (written !== null) {
|
|
1160
|
+
const link = linkOnWrittenPathAtHead(repoRoot, written);
|
|
1161
|
+
if (link !== null) {
|
|
1162
|
+
return linkOnWrittenPathRefusal(`in ${list}, the path ${written}`, link, trustBase === '' ? 'the base' : `"${trustBase}"`);
|
|
1163
|
+
}
|
|
1164
|
+
}
|
|
990
1165
|
let isDirectory;
|
|
991
1166
|
try {
|
|
992
1167
|
isDirectory = lstatSync(argumentPath).isDirectory();
|
|
@@ -998,7 +1173,7 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
|
|
|
998
1173
|
isDirectory = false;
|
|
999
1174
|
}
|
|
1000
1175
|
if (!isDirectory) {
|
|
1001
|
-
return refuseHeadControlledProgram(repoRoot, trustBase, argumentPath, true);
|
|
1176
|
+
return refuseHeadControlledProgram(repoRoot, trustBase, argumentPath, true, list);
|
|
1002
1177
|
}
|
|
1003
1178
|
for (const spelling of new Set(spellings)) {
|
|
1004
1179
|
if (!insideWorkingTree(repoReal, spelling)) {
|
|
@@ -1009,27 +1184,35 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
|
|
|
1009
1184
|
const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
|
|
1010
1185
|
for (const listed of [baseEntry, headEntry]) {
|
|
1011
1186
|
if (listed.kind === 'error') {
|
|
1012
|
-
return (`the directory ${relative} named in
|
|
1187
|
+
return (`the directory ${relative} named in ${list} could not be checked against ` +
|
|
1013
1188
|
`"${trustBase}": ${listed.detail}. Nothing was checked by this gate.`);
|
|
1014
1189
|
}
|
|
1015
1190
|
}
|
|
1016
1191
|
const base = baseEntry.kind === 'entry' ? baseEntry : null;
|
|
1017
1192
|
const head = headEntry.kind === 'entry' ? headEntry : null;
|
|
1018
1193
|
if (base === null || head === null || base.type !== 'tree' || head.type !== 'tree' || base.sha !== head.sha) {
|
|
1019
|
-
return (`the directory ${relative} named in
|
|
1194
|
+
return (`the directory ${relative} named in ${list} is not what "${trustBase}" approved: ` +
|
|
1020
1195
|
'this pull request adds, removes or changes something in it, and an interpreter handed a ' +
|
|
1021
1196
|
'directory runs what is inside. Land the change on the base branch first, or name a ' +
|
|
1022
1197
|
'script outside the repository. Nothing was checked by this gate.');
|
|
1023
1198
|
}
|
|
1024
1199
|
}
|
|
1200
|
+
// LAST, the disk against the tree (review of the 2026-11-01 fix, item 1).
|
|
1201
|
+
if (written !== null) {
|
|
1202
|
+
const undeclared = undeclaredLinkOnDisk(repoRoot, repoReal, written);
|
|
1203
|
+
if (undeclared !== null) {
|
|
1204
|
+
return undeclaredLinkRefusal(`in ${list}, the path ${written}`, undeclared);
|
|
1205
|
+
}
|
|
1206
|
+
}
|
|
1025
1207
|
return null;
|
|
1026
1208
|
}
|
|
1027
1209
|
/**
|
|
1028
1210
|
* Why a path a gate's own `args:` name cannot be trusted on a pull-request
|
|
1029
1211
|
* run, or null (audit 2026-10-28, N1, and its review, B1 and N-a).
|
|
1030
1212
|
*
|
|
1031
|
-
* Asked
|
|
1032
|
-
* src/resolve.ts),
|
|
1213
|
+
* Asked for the args of a `command:` that is the gate itself, and for the
|
|
1214
|
+
* `options:` values of every gate (dataArgumentPaths in src/resolve.ts),
|
|
1215
|
+
* since both are the gate's own argv: a rules file such as
|
|
1033
1216
|
* `--config=.gitleaks.toml`, or a rules directory such as dep-guard's
|
|
1034
1217
|
* `--corpus-dir`, is read as data, not loaded as code. Its contents still
|
|
1035
1218
|
* decide what the gate reports, so a pull request that rewrote them would
|
|
@@ -1058,26 +1241,67 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
|
|
|
1058
1241
|
* - Absent at the base: accepted only if the head has nothing there either,
|
|
1059
1242
|
* tracked or on disk (a word that is not a path, `--format=json`);
|
|
1060
1243
|
* otherwise it is a path this pull request chose, and refused.
|
|
1244
|
+
* - AS WRITTEN as well as resolved (audit 2026-11-01, MB2): a directory on
|
|
1245
|
+
* the written path that HEAD's tree holds as a link is refused, the
|
|
1246
|
+
* written path is judged by the rules above like the resolved ones, and a
|
|
1247
|
+
* positional scan target the base tracks as a directory is refused when
|
|
1248
|
+
* HEAD holds it as a link, since that one is otherwise not compared.
|
|
1249
|
+
* - The same for an `options:` value (audit 2026-11-01, MB1): it is
|
|
1250
|
+
* rendered into the gate's argv and read the same way (dataArgumentPaths),
|
|
1251
|
+
* and `from: 'options'` only changes which list the refusal names.
|
|
1061
1252
|
*
|
|
1062
1253
|
* Only whether something exists on disk at a path the base does not track is
|
|
1063
1254
|
* read from the working tree; every other answer is a `git ls-tree` listing.
|
|
1064
1255
|
*/
|
|
1065
1256
|
export function refuseHeadControlledData(repoRoot, trustBase, data) {
|
|
1257
|
+
// Which list of the policy the value came from, for every message below:
|
|
1258
|
+
// an `options:` value is rendered into the same argv and vetted the same
|
|
1259
|
+
// way (audit 2026-11-01, MB1).
|
|
1260
|
+
const list = data.from === 'options' ? "the gate's options:" : "the gate's args:";
|
|
1066
1261
|
const repoReal = realOrNull(repoRoot);
|
|
1067
1262
|
if (repoReal === null) {
|
|
1068
|
-
return `the repository root ${repoRoot} could not be resolved, so the files named in
|
|
1263
|
+
return `the repository root ${repoRoot} could not be resolved, so the files named in ${list} could not be checked against "${trustBase}". Nothing was checked by this gate.`;
|
|
1069
1264
|
}
|
|
1070
1265
|
const dataPath = data.path;
|
|
1071
|
-
|
|
1266
|
+
// The written spelling beside the resolved ones (audit 2026-11-01, MB2).
|
|
1267
|
+
const written = writtenRelative(repoReal, dataPath);
|
|
1268
|
+
const spellings = [
|
|
1269
|
+
withResolvedParent(dataPath),
|
|
1270
|
+
realOrNull(dataPath),
|
|
1271
|
+
written === null ? null : path.join(repoReal, written),
|
|
1272
|
+
].filter((spelling) => spelling !== null);
|
|
1072
1273
|
const baseName = trustBase === '' ? 'the base' : `"${trustBase}"`;
|
|
1274
|
+
if (written !== null && written !== '') {
|
|
1275
|
+
const subject = `the path ${written} named in ${list}`;
|
|
1276
|
+
const link = linkOnWrittenPathAtHead(repoRoot, written);
|
|
1277
|
+
if (link !== null) {
|
|
1278
|
+
return linkOnWrittenPathRefusal(subject, link, baseName);
|
|
1279
|
+
}
|
|
1280
|
+
// A positional directory the base tracks is a scan target and is not
|
|
1281
|
+
// compared below, so its own entry is asked here: a link there hands the
|
|
1282
|
+
// gate wherever the head points it, possibly the root, instead of the
|
|
1283
|
+
// target the base named. Every other own-entry link (a file, an option
|
|
1284
|
+
// value) is refused below, in the words of its kind.
|
|
1285
|
+
if (data.positional) {
|
|
1286
|
+
const own = listOne(repoRoot, 'HEAD', written);
|
|
1287
|
+
const approved = treeEntryAt(repoRoot, trustBase, written);
|
|
1288
|
+
if (own.kind === 'entry' && own.mode === '120000' && approved.kind === 'entry' && approved.type === 'tree') {
|
|
1289
|
+
return linkOnWrittenPathRefusal(subject, written, baseName);
|
|
1290
|
+
}
|
|
1291
|
+
}
|
|
1292
|
+
}
|
|
1073
1293
|
if (spellings.some((spelling) => path.relative(repoReal, spelling) === '')) {
|
|
1074
1294
|
if (data.positional) {
|
|
1075
|
-
|
|
1295
|
+
// A scan target that IS the root is accepted, so the disk check that
|
|
1296
|
+
// otherwise runs last runs here first: a link on disk the head tree
|
|
1297
|
+
// does not declare can fold a positional onto the root (review R1).
|
|
1298
|
+
const undeclared = written === null || written === '' ? null : undeclaredLinkOnDisk(repoRoot, repoReal, written);
|
|
1299
|
+
return undeclared === null ? null : undeclaredLinkRefusal(`the path ${written} named in ${list}`, undeclared);
|
|
1076
1300
|
}
|
|
1077
1301
|
// The entry as written, never the absolute checkout path, which would
|
|
1078
1302
|
// reach the pull-request comment and SARIF; and the remedy for the common
|
|
1079
1303
|
// case, a scan target written after a flag, first (re-review R1).
|
|
1080
|
-
return (
|
|
1304
|
+
return (`${list} give the repository root (${data.entry ?? '.'}) as an option's value, so ` +
|
|
1081
1305
|
`the whole working tree would be data the gate reads, and this pull request differs from ` +
|
|
1082
1306
|
`${baseName} somewhere in it. If it is the scan target written after a flag, move it before ` +
|
|
1083
1307
|
'the flags, where it reads as a positional; otherwise give that option a directory of its ' +
|
|
@@ -1095,7 +1319,7 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
|
|
|
1095
1319
|
const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
|
|
1096
1320
|
for (const listed of [baseEntry, headEntry]) {
|
|
1097
1321
|
if (listed.kind === 'error') {
|
|
1098
|
-
return (`the file ${relative} named in
|
|
1322
|
+
return (`the file ${relative} named in ${list} could not be checked against ${baseName}: ` +
|
|
1099
1323
|
`${listed.detail}. Nothing was checked by this gate.`);
|
|
1100
1324
|
}
|
|
1101
1325
|
}
|
|
@@ -1106,7 +1330,7 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
|
|
|
1106
1330
|
// Names nothing at either side: a word, not a path.
|
|
1107
1331
|
continue;
|
|
1108
1332
|
}
|
|
1109
|
-
return (`the file ${relative} named in
|
|
1333
|
+
return (`the file ${relative} named in ${list} is not tracked at ${baseName} and the head ` +
|
|
1110
1334
|
'commit both, so the gate would read a path this pull request chose. Commit it on the base ' +
|
|
1111
1335
|
'branch first, or name a file outside the repository. Nothing was checked by this gate.');
|
|
1112
1336
|
}
|
|
@@ -1116,7 +1340,7 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
|
|
|
1116
1340
|
continue;
|
|
1117
1341
|
}
|
|
1118
1342
|
if (head === null || head.type !== 'tree' || head.sha !== base.sha) {
|
|
1119
|
-
return (`the directory ${relative} named in
|
|
1343
|
+
return (`the directory ${relative} named in ${list} is not what ${baseName} approved: ` +
|
|
1120
1344
|
'this pull request adds, removes or changes something in it, and it is given as an ' +
|
|
1121
1345
|
"option's value, so the gate reads it as data, such as a rules directory " +
|
|
1122
1346
|
'(dep-guard --corpus-dir). Land the change on the base branch first. If it is a scan ' +
|
|
@@ -1126,16 +1350,23 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
|
|
|
1126
1350
|
continue;
|
|
1127
1351
|
}
|
|
1128
1352
|
if (head === null || !isRegularFileMode(base.mode) || !isRegularFileMode(head.mode)) {
|
|
1129
|
-
return (`the file ${relative} named in
|
|
1353
|
+
return (`the file ${relative} named in ${list} is not a regular file at both ${baseName} ` +
|
|
1130
1354
|
'and the head commit, so what the gate would read is decided by something other than the ' +
|
|
1131
1355
|
'approved bytes. Name the file itself. Nothing was checked by this gate.');
|
|
1132
1356
|
}
|
|
1133
1357
|
if (base.sha !== head.sha) {
|
|
1134
|
-
return (`the file ${relative} named in
|
|
1358
|
+
return (`the file ${relative} named in ${list} is not the one ${baseName} approved: this ` +
|
|
1135
1359
|
'pull request changes it, and the gate reads it, so running the gate would let the pull ' +
|
|
1136
1360
|
'request choose the rules that judge it. Land the change on the base branch first. ' +
|
|
1137
1361
|
'Nothing was checked by this gate.');
|
|
1138
1362
|
}
|
|
1139
1363
|
}
|
|
1364
|
+
// LAST, the disk against the tree (review of the 2026-11-01 fix, item 1).
|
|
1365
|
+
if (written !== null && written !== '') {
|
|
1366
|
+
const undeclared = undeclaredLinkOnDisk(repoRoot, repoReal, written);
|
|
1367
|
+
if (undeclared !== null) {
|
|
1368
|
+
return undeclaredLinkRefusal(`the path ${written} named in ${list}`, undeclared);
|
|
1369
|
+
}
|
|
1370
|
+
}
|
|
1140
1371
|
return null;
|
|
1141
1372
|
}
|