@vaultcompass/conductor 0.9.0 → 0.11.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 +157 -31
- package/dist/cli.d.ts +6 -0
- package/dist/cli.js +19 -4
- package/dist/gate-runner.d.ts +102 -10
- package/dist/gate-runner.js +282 -37
- package/dist/init-hook-detect.d.ts +1 -0
- package/dist/init-hook-detect.js +45 -0
- package/dist/init-policy.js +13 -0
- package/dist/init.d.ts +8 -0
- package/dist/init.js +166 -20
- package/dist/intent-prepare.d.ts +51 -2
- package/dist/intent-prepare.js +160 -35
- package/dist/intent-spec.d.ts +108 -22
- package/dist/intent-spec.js +226 -55
- package/dist/normalize.d.ts +32 -2
- package/dist/normalize.js +117 -11
- package/dist/output-sarif.js +72 -1
- package/dist/output-text.d.ts +37 -1
- package/dist/output-text.js +324 -21
- package/dist/policy.d.ts +8 -0
- package/dist/policy.js +33 -6
- package/dist/products.d.ts +8 -1
- package/dist/products.js +14 -0
- package/dist/run.d.ts +13 -1
- package/dist/run.js +19 -2
- package/package.json +1 -1
- package/schema/guardrails.schema.json +6 -0
package/README.md
CHANGED
|
@@ -142,10 +142,9 @@ required.
|
|
|
142
142
|
|
|
143
143
|
**`.guardrails/manifest.json` records the absolute path on the machine
|
|
144
144
|
that ran `init`**, for the hook, when there is one, and for the policy
|
|
145
|
-
file alike,
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
`.guardrails/manifest.json` to your own `.gitignore` today. The file
|
|
145
|
+
file alike. That path is specific to your checkout, so do not commit the
|
|
146
|
+
file: init appends `.guardrails/` to `.gitignore` when git does not already
|
|
147
|
+
ignore it, and prints the line instead when it cannot append safely. The file
|
|
149
148
|
lives inside your working tree so `--revert` can find it later, and
|
|
150
149
|
recording repo-relative paths there instead of absolute ones is a known
|
|
151
150
|
gap, not a design; it has not been fixed yet.
|
|
@@ -167,7 +166,7 @@ required.
|
|
|
167
166
|
A commit with a staged credential in it prints the full report and exits 1:
|
|
168
167
|
|
|
169
168
|
```
|
|
170
|
-
conductor 0.
|
|
169
|
+
conductor 0.11.0
|
|
171
170
|
verdict-token: blocked (1)
|
|
172
171
|
conductor run: 2 gate(s), 1 finding(s)
|
|
173
172
|
|
|
@@ -435,6 +434,10 @@ that scans a requirements file always gets `--no-resolve`, and a
|
|
|
435
434
|
`no-resolve` key here is dropped from that run with a note; and a
|
|
436
435
|
pull-request run gets `--no-call-analysis=all` unless this block names
|
|
437
436
|
`call-analysis` or `no-call-analysis`, in which case that value is used.
|
|
437
|
+
`timeout-seconds` is refused under `options` on every gate, and `timeout`
|
|
438
|
+
on every gate but gitleaks, where it is gitleaks' own `--timeout` flag and
|
|
439
|
+
is passed through (see `timeout-seconds` below and "What a history scan
|
|
440
|
+
costs").
|
|
438
441
|
|
|
439
442
|
**`present-on-base`** (the `vulnerabilities` gate only, beside `enforce`,
|
|
440
443
|
never under `options`) is `block` or `report`. On a pull-request run whose
|
|
@@ -450,6 +453,27 @@ local run, a push) has no labels, and every finding blocks. The key on any
|
|
|
450
453
|
other gate is an error, and an older conductor rejects it, so move the
|
|
451
454
|
Action first.
|
|
452
455
|
|
|
456
|
+
**`timeout-seconds`** (any gate, beside `enforce`, never under `options`)
|
|
457
|
+
is how long conductor lets that gate run before stopping it: a whole number
|
|
458
|
+
of seconds from 10 to 21600. The floor is there because the same limit
|
|
459
|
+
bounds the gate's version probe, and a limit of a second or two can stop the
|
|
460
|
+
probe of a gate that starts slowly before it ever scans. The ceiling is the
|
|
461
|
+
six hours after which a GitHub-hosted job is cancelled; a larger limit could
|
|
462
|
+
never fire there. Without the key each gate keeps the default for its
|
|
463
|
+
product: 120 seconds for dep-guard, vault-guard and intent-guard, 600 for
|
|
464
|
+
gitleaks, 300 for osv-scanner. There is no policy-wide default, for the same
|
|
465
|
+
reason there is no shared severity threshold: the five gates differ in cost
|
|
466
|
+
by orders of magnitude. Every spawn of the gate gets the full limit (the
|
|
467
|
+
version probe, the scan, the intent gate's preparation steps, osv-scanner's
|
|
468
|
+
base run on a pull request). A gate stopped at its limit could not run, with
|
|
469
|
+
the reason `timed-out` and what to do about it, and an enforced one makes
|
|
470
|
+
the run exit 2. On a pull request the key is read from the base branch's
|
|
471
|
+
policy like every other key, so a pull request cannot raise, lower or
|
|
472
|
+
remove its own limit; an invalid value on the base fails every pull request
|
|
473
|
+
with exit 2 until the base is fixed, and an invalid value only on the head
|
|
474
|
+
is a policy proposal there and fails the push run after merge. An older
|
|
475
|
+
conductor rejects the key, so move the Action first.
|
|
476
|
+
|
|
453
477
|
**There is no shared severity threshold, on purpose.** One top-level
|
|
454
478
|
`failOn` would read as one decision and mean five different things, so
|
|
455
479
|
setting one is an error rather than a knob that half works. Each gate keeps
|
|
@@ -457,7 +481,11 @@ its own threshold in its own `options` block, spelled the way that gate
|
|
|
457
481
|
spells it.
|
|
458
482
|
|
|
459
483
|
**`command`** takes an absolute path and overrides binary resolution for
|
|
460
|
-
that gate, for pointing at a build that is not installed anywhere.
|
|
484
|
+
that gate, for pointing at a build that is not installed anywhere. `args`
|
|
485
|
+
beside it sets the argument prefix. conductor's history gate assumes
|
|
486
|
+
gitleaks' `git` mode; an `args` that switches it to `dir` mode changes what
|
|
487
|
+
gitleaks' own `--timeout` does (in `dir` mode it exits 0 after a partial
|
|
488
|
+
scan, with no warning).
|
|
461
489
|
|
|
462
490
|
**`report.format`** is `text` or `sarif`, and `--format` overrides it.
|
|
463
491
|
|
|
@@ -466,7 +494,14 @@ that gate, for pointing at a build that is not installed anywhere.
|
|
|
466
494
|
`conductor init` writes the policy file and `.guardrails/manifest.json`, the
|
|
467
495
|
record `--revert` reads back later. The manifest currently records absolute
|
|
468
496
|
machine paths rather than repo-relative ones (see "Adopting conductor"
|
|
469
|
-
above); do not commit it.
|
|
497
|
+
above); do not commit it. When git does not already ignore it, init appends
|
|
498
|
+
`.guardrails/` to `.gitignore` (or creates one) and says so; a `.gitignore`
|
|
499
|
+
that is a symbolic link or not a regular file is left alone and the line is
|
|
500
|
+
printed for you to add. On a policy file that already exists, init lists the
|
|
501
|
+
gate roles it has no entry for, with the two lines that add each. An external
|
|
502
|
+
gate (gitleaks, osv-scanner) is written enabled only when its binary is found
|
|
503
|
+
on the machine running init, with a comment under it that CI must install it;
|
|
504
|
+
a CI job without it gets `conductor/gate-missing` and exit 2.
|
|
470
505
|
|
|
471
506
|
- `--hook` also writes one pre-commit hook running every enabled gate whose
|
|
472
507
|
stage is `commit`. Without it, init writes only the policy file and the
|
|
@@ -478,7 +513,9 @@ above); do not commit it.
|
|
|
478
513
|
`--hook` itself.
|
|
479
514
|
- `--dry-run` prints every file it would write or change and writes nothing.
|
|
480
515
|
- `--revert` removes exactly what a previous init wrote, and nothing else.
|
|
481
|
-
A file changed since init is reported and left alone.
|
|
516
|
+
A file changed since init is reported and left alone. The one exception is
|
|
517
|
+
the `.guardrails/` line init appends to `.gitignore`: `--revert` does not
|
|
518
|
+
remove it.
|
|
482
519
|
- `--adopt` replaces one gate's own pre-commit hook with the umbrella hook.
|
|
483
520
|
Without it, init reports the collision and stops rather than stacking a
|
|
484
521
|
second invocation of a gate that is already hooked. A hook the umbrella
|
|
@@ -505,7 +542,14 @@ and none of it can block the policy file from being written, on a plain
|
|
|
505
542
|
|
|
506
543
|
Init recognises the hook manager already wired into the repository. husky is
|
|
507
544
|
redirected to the tracked hook it maintains rather than the generated
|
|
508
|
-
dispatcher git runs.
|
|
545
|
+
dispatcher git runs. On a fresh clone, where husky's install has not set
|
|
546
|
+
`core.hooksPath` yet, husky is recognised from `package.json` (a `husky`
|
|
547
|
+
dependency or devDependency, or a `prepare` script that runs husky) or a
|
|
548
|
+
tracked `.husky/` directory, and init writes `.husky/pre-commit` and says the
|
|
549
|
+
install still has to run, rather than writing `.git/hooks/pre-commit`, which
|
|
550
|
+
husky's install would bypass. This applies only when `core.hooksPath` is not
|
|
551
|
+
set at all: one set by hand, even to `.git/hooks`, is left alone. A prepare
|
|
552
|
+
script counts only when it runs husky as a command. lefthook and the pre-commit framework are refused, with
|
|
509
553
|
the stanza to add to their own config file. simple-git-hooks and yorkie are
|
|
510
554
|
refused too, and recognised from the declaration as well as from the hook
|
|
511
555
|
file, because the declaration is there on a fresh clone where the generated
|
|
@@ -562,7 +606,13 @@ proceeds normally without mentioning them.
|
|
|
562
606
|
copy in a file would only duplicate it. A path that cannot be written is
|
|
563
607
|
exit 2, like `--output`. See "The verdict token" below.
|
|
564
608
|
- `--verbose` prints the full per-gate report even when the run is clean.
|
|
565
|
-
Text output only; the SARIF log never changes shape with it.
|
|
609
|
+
Text output only; the SARIF log never changes shape with it. Without it a
|
|
610
|
+
gate prints its first 20 findings, blocking first, and one line saying how
|
|
611
|
+
many more there are; every count, the verdict and SARIF include all of
|
|
612
|
+
them. `--verbose` also lists the lockfiles behind an osv-scanner line
|
|
613
|
+
that groups one advisory across several ("lodash@4.17.20 2 lockfiles
|
|
614
|
+
fix 4.17.21"). A gitleaks finding shows its short commit and the
|
|
615
|
+
fingerprint `.gitleaksignore` takes.
|
|
566
616
|
- `--compact-on-refusal` shrinks the report to the version, the verdict and
|
|
567
617
|
the refusal reason when the trust base was refused and no gate ran,
|
|
568
618
|
instead of the full per-gate report. Built for the pull-request-comment
|
|
@@ -595,9 +645,10 @@ proceeds normally without mentioning them.
|
|
|
595
645
|
- **0** every enabled gate ran and none blocked.
|
|
596
646
|
- **1** every enabled gate ran and at least one blocked.
|
|
597
647
|
- **2** an enabled gate could not run: its binary is missing, it exited with
|
|
598
|
-
its own could-not-run code,
|
|
648
|
+
its own could-not-run code, it exited 1 with nothing parseable on
|
|
599
649
|
stdout, which is what a rejected config file looks like from two of the
|
|
600
|
-
three family gates
|
|
650
|
+
three family gates, or conductor stopped it at its time limit
|
|
651
|
+
(`timed-out`, see `timeout-seconds` in the policy file).
|
|
601
652
|
|
|
602
653
|
The external gates' exits are read per tool. gitleaks exits 1 for an error
|
|
603
654
|
as well as for a leak, so the umbrella hands it `--exit-code 3`: 3 is a leak
|
|
@@ -670,7 +721,12 @@ code and the `enforce` flags the run already had.
|
|
|
670
721
|
vulnerabilities already on the base branch, reported and not blocking;
|
|
671
722
|
the report's third line then says `present-on-base: N reported, not
|
|
672
723
|
blocking`, the verdict sentence says the same, and the Action copies that
|
|
673
|
-
line to the job summary under the token.
|
|
724
|
+
line to the job summary under the token. When the intent gate's spec was
|
|
725
|
+
chosen weakly, differently than before 0.11.0, or not at all because of a
|
|
726
|
+
tie or a branch 0.10.0 bound, the line after the token (after the
|
|
727
|
+
present-on-base line, when there is one) is one of four fixed
|
|
728
|
+
`intent-spec:` lines naming no branch or file, and the Action copies that
|
|
729
|
+
one too.
|
|
674
730
|
- `nothing-checked`: exit 0, but nothing was checked. Either no gate ran at
|
|
675
731
|
all (none is enabled, or every enabled one was deferred to a later stage,
|
|
676
732
|
had nothing to judge, or was skipped), or every gate that ran examined
|
|
@@ -1129,12 +1185,24 @@ itself and needs an administrator to merge it.
|
|
|
1129
1185
|
token is exact and lowercase, a frozen contract at rule 2 still wins over
|
|
1130
1186
|
it, and `--spec` at rule 1 still overrides it.
|
|
1131
1187
|
4. A markdown file **directly under** `docs/superpowers/specs` whose name
|
|
1132
|
-
|
|
1133
|
-
segment (`feat/`, `fix/`) removed; a filename is reduced by
|
|
1134
|
-
`YYYY-MM-DD-` prefix and a trailing `-design
|
|
1135
|
-
|
|
1136
|
-
|
|
1137
|
-
|
|
1188
|
+
matches the branch on **whole words**. The branch slug is the branch name
|
|
1189
|
+
with its first segment (`feat/`, `fix/`) removed; a filename is reduced by
|
|
1190
|
+
stripping a `YYYY-MM-DD-` prefix and a trailing `-design`. Both have their
|
|
1191
|
+
ASCII letters lower-cased and are split into words on `-`, `_`, `/` and
|
|
1192
|
+
spaces. A spec is a candidate when one name's words appear, in order and
|
|
1193
|
+
together, inside the other's, and at least one shared word is three or
|
|
1194
|
+
more characters, contains a letter, and is not a common branch word
|
|
1195
|
+
(`fix`, `feat`, `wip`, `docs`, and the rest of the list in
|
|
1196
|
+
`src/intent-spec.ts`). Candidates are ranked by an equal name first, then
|
|
1197
|
+
the most shared words, then the longest shared word, then the lexically
|
|
1198
|
+
greatest filename among files with the same name (the newest date when
|
|
1199
|
+
every spec is dated `YYYY-MM-DD-`, so **date every spec** in that form).
|
|
1200
|
+
Two different specs that tie are **not** guessed between: the gate is
|
|
1201
|
+
skipped as `intent-guard/spec-ambiguous`, naming both. A spec chosen on
|
|
1202
|
+
one shared word, or on word length alone, is used and the report says the
|
|
1203
|
+
match is weak. Branch names like `pr` or `fix/wip` choose nothing. When
|
|
1204
|
+
the choice matters, say it: a `Spec:` line in the pull request body, or a
|
|
1205
|
+
branch named after the spec.
|
|
1138
1206
|
|
|
1139
1207
|
**A branch with neither** is a third state beside deferred and could-not-run:
|
|
1140
1208
|
the gate is switched on, it ran, and it had nothing to check. It gets one
|
|
@@ -1146,7 +1214,9 @@ repository. A waived pull request lands in the same state and is reported
|
|
|
1146
1214
|
under its own `intent-guard/contract-waived` id, with its own wording on the
|
|
1147
1215
|
skipped line, in the verdict and on the one-line summary of a clean run, so a
|
|
1148
1216
|
reader can tell "nobody has written one" from "somebody decided against one"
|
|
1149
|
-
wherever they meet it.
|
|
1217
|
+
wherever they meet it. An ambiguous branch, one two specs match equally,
|
|
1218
|
+
lands in the same advisory state under its own `intent-guard/spec-ambiguous`
|
|
1219
|
+
id, and never reaches the exit code either.
|
|
1150
1220
|
|
|
1151
1221
|
**A repository with no contract yet is not a repository this gate can act
|
|
1152
1222
|
on**, and the no-contract skip line names `docs/superpowers/specs`, which is
|
|
@@ -1171,7 +1241,8 @@ gate does not run at all on that pull request, and budget breaches are the
|
|
|
1171
1241
|
thing this gate blocks on. The one thing a waiver cannot override is a frozen
|
|
1172
1242
|
native contract, under either of the two paths above, which is checked first:
|
|
1173
1243
|
a repository that wants the gate to be non-waivable freezes a native contract
|
|
1174
|
-
and keeps it committed.
|
|
1244
|
+
and keeps it committed. The branch-name convention is not a control either:
|
|
1245
|
+
whoever names the branch chooses among the base's specs.
|
|
1175
1246
|
|
|
1176
1247
|
**What blocks is unchanged.** Blocking stays where intent-guard puts it:
|
|
1177
1248
|
budget breaches block, subject to `enforce`. Drift on its own is reported and
|
|
@@ -1307,7 +1378,7 @@ request being judged, and the version-pin protection described above
|
|
|
1307
1378
|
"protects nothing" against a tree that controls its own judge (the
|
|
1308
1379
|
validate step's own comment in `action.yml` says so in those words). A tag
|
|
1309
1380
|
moves when someone pushes it. Name this action by owner and the full commit
|
|
1310
|
-
SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.
|
|
1381
|
+
SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.11.0.
|
|
1311
1382
|
|
|
1312
1383
|
```yaml
|
|
1313
1384
|
name: guardrails
|
|
@@ -1329,7 +1400,7 @@ jobs:
|
|
|
1329
1400
|
with:
|
|
1330
1401
|
node-version: '22.11.0'
|
|
1331
1402
|
- id: conductor
|
|
1332
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1403
|
+
uses: vaultcompasshq/conductor@v0.11.0
|
|
1333
1404
|
with:
|
|
1334
1405
|
output: conductor.sarif
|
|
1335
1406
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -1404,7 +1475,7 @@ jobs:
|
|
|
1404
1475
|
# installs those itself, globally. Leave conductor-version unset so the
|
|
1405
1476
|
# umbrella is the default in the pinned action.yml.
|
|
1406
1477
|
- id: conductor
|
|
1407
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1478
|
+
uses: vaultcompasshq/conductor@v0.11.0
|
|
1408
1479
|
with:
|
|
1409
1480
|
output: conductor.sarif
|
|
1410
1481
|
# Exact versions, never a range and never "latest". These three
|
|
@@ -1415,9 +1486,9 @@ jobs:
|
|
|
1415
1486
|
# request of their own. On a pull request the action refuses a pin
|
|
1416
1487
|
# below what the pinned action.yml ships, and the three lines can
|
|
1417
1488
|
# be left out entirely to take that action's own versions.
|
|
1418
|
-
dep-guard-version: 0.
|
|
1419
|
-
vault-guard-version: 1.
|
|
1420
|
-
intent-guard-version: 1.
|
|
1489
|
+
dep-guard-version: 0.14.0
|
|
1490
|
+
vault-guard-version: 1.11.0
|
|
1491
|
+
intent-guard-version: 1.10.0
|
|
1421
1492
|
- uses: github/codeql-action/upload-sarif@v3
|
|
1422
1493
|
# Always: the log is most worth having on the run that failed.
|
|
1423
1494
|
if: always()
|
|
@@ -1513,6 +1584,61 @@ runs whatever its author pushes to it next. Pin every third-party action by
|
|
|
1513
1584
|
commit digest in a workflow you actually run, the way this repository's own
|
|
1514
1585
|
workflows do.
|
|
1515
1586
|
|
|
1587
|
+
### What a history scan costs
|
|
1588
|
+
|
|
1589
|
+
What the history gate reads depends on the event. On a pull request it is
|
|
1590
|
+
`<base>..HEAD`, with first-parent diffs for merge commits; on a push, a
|
|
1591
|
+
schedule or a local run it is every commit reachable from HEAD. So a pull
|
|
1592
|
+
request's cost follows its own range, and a full run's cost follows the
|
|
1593
|
+
whole history and the size of every blob ever committed. Separately,
|
|
1594
|
+
`fetch-depth: 0` means the checkout fetches the whole history on every run,
|
|
1595
|
+
whatever the scan range.
|
|
1596
|
+
|
|
1597
|
+
The time limit is per gate. The defaults are 120 seconds for the three
|
|
1598
|
+
family gates, 600 for gitleaks and 300 for osv-scanner, and you change one
|
|
1599
|
+
with `timeout-seconds` beside `enforce`; on a pull request it comes from the
|
|
1600
|
+
base branch. Every spawn of a gate gets the full limit (the version probe,
|
|
1601
|
+
the scan, the intent gate's preparation steps, osv-scanner's base run), so
|
|
1602
|
+
a gate's wall time can be a multiple of it. A gate stopped at its limit is
|
|
1603
|
+
could-not-run (`timed-out`), never a pass.
|
|
1604
|
+
|
|
1605
|
+
- The limit is a SIGTERM deadline. A gate that ignores SIGTERM keeps the run
|
|
1606
|
+
waiting until it exits on its own; conductor does not escalate to SIGKILL.
|
|
1607
|
+
- A gate's own child processes are not stopped with it. A gate behind a
|
|
1608
|
+
shell-wrapper `command` can keep running after the report says
|
|
1609
|
+
`timed-out`.
|
|
1610
|
+
- On a hosted runner the six-hour job limit includes checkout, setup and
|
|
1611
|
+
every other gate, so a limit near the 21600 ceiling is cancelled with the
|
|
1612
|
+
job before it can fire. Keep it well under.
|
|
1613
|
+
|
|
1614
|
+
Measure your own full scan once, on the runner it will run on, and set the
|
|
1615
|
+
limit with headroom. The recommended split: every pull request scans its own
|
|
1616
|
+
range, and the full history is scanned on a schedule with a limit sized for
|
|
1617
|
+
it. Two existing ways to make it: by stage, since `secrets-history` defaults
|
|
1618
|
+
to stage `ci` and a push workflow run with the Action's `stage: push` input
|
|
1619
|
+
(or `conductor run --stage push`) leaves ci-stage gates out; or by trigger,
|
|
1620
|
+
running the workflow on pull requests and a schedule and not on push. With
|
|
1621
|
+
the CLI, `--gate secrets-history` on the scheduled job also works.
|
|
1622
|
+
|
|
1623
|
+
`max-target-megabytes`, passed under `options`, skips every file larger
|
|
1624
|
+
than the cap. Measured with gitleaks 8.30.1 in the mode conductor runs, at
|
|
1625
|
+
the log level conductor runs it at: a secret inside a file over the cap was
|
|
1626
|
+
not reported, no line in gitleaks' log named the skipped file, and the scan
|
|
1627
|
+
summary still reported the full byte count. It is a coverage decision, made
|
|
1628
|
+
in the policy file where a reviewer can see it, and conductor never applies
|
|
1629
|
+
it by default.
|
|
1630
|
+
|
|
1631
|
+
`options.timeout` on the secrets-history gate is gitleaks' own deadline,
|
|
1632
|
+
not conductor's. A `conductor/option-is-gate-own` note says so: always in
|
|
1633
|
+
the SARIF log, and in the text report under the gate header whenever the
|
|
1634
|
+
full report is printed (with `--verbose`, or on any run that is not fully
|
|
1635
|
+
clean; a clean run without `--verbose` prints only its one-line summary).
|
|
1636
|
+
When it fires
|
|
1637
|
+
gitleaks exits 1, whether or not it had found a leak, and the gate is
|
|
1638
|
+
could-not-run. Leaks it found before the deadline are not listed as
|
|
1639
|
+
findings; the echoed gitleaks log line ("N leaks found in partial scan") is
|
|
1640
|
+
the only mention of them.
|
|
1641
|
+
|
|
1516
1642
|
### Running the gates as an advisory check
|
|
1517
1643
|
|
|
1518
1644
|
To run the gates without blocking a merge, set `advisory: true` on the
|
|
@@ -1555,7 +1681,7 @@ jobs:
|
|
|
1555
1681
|
node-version: '22.11.0'
|
|
1556
1682
|
- id: conductor
|
|
1557
1683
|
timeout-minutes: 5
|
|
1558
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1684
|
+
uses: vaultcompasshq/conductor@v0.11.0
|
|
1559
1685
|
with:
|
|
1560
1686
|
pr-comment: true
|
|
1561
1687
|
advisory: true
|
|
@@ -1691,7 +1817,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1691
1817
|
# the pull request runs before the action in this job: no install, build
|
|
1692
1818
|
# or test step here; those belong in a separate job. ...
|
|
1693
1819
|
- id: conductor
|
|
1694
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1820
|
+
uses: vaultcompasshq/conductor@v0.11.0
|
|
1695
1821
|
with:
|
|
1696
1822
|
output: conductor.sarif
|
|
1697
1823
|
pr-comment: true
|
|
@@ -1770,12 +1896,12 @@ per pull request.
|
|
|
1770
1896
|
|
|
1771
1897
|
```yaml
|
|
1772
1898
|
- id: conductor-package-a
|
|
1773
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1899
|
+
uses: vaultcompasshq/conductor@v0.11.0
|
|
1774
1900
|
with:
|
|
1775
1901
|
pr-comment: true
|
|
1776
1902
|
pr-comment-marker: 'package-a'
|
|
1777
1903
|
- id: conductor-package-b
|
|
1778
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1904
|
+
uses: vaultcompasshq/conductor@v0.11.0
|
|
1779
1905
|
with:
|
|
1780
1906
|
pr-comment: true
|
|
1781
1907
|
pr-comment-marker: 'package-b'
|
package/dist/cli.d.ts
CHANGED
|
@@ -1,3 +1,9 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import { Command } from 'commander';
|
|
3
|
+
/**
|
|
4
|
+
* Whether the text report is rendered for a terminal: only when it goes to
|
|
5
|
+
* stdout (no --output) and stdout is a TTY. A file, a pipe and the
|
|
6
|
+
* --text-report copy never are, so they stay byte for byte as before.
|
|
7
|
+
*/
|
|
8
|
+
export declare function rendersToTerminal(output: string | undefined, stdoutIsTTY: boolean | undefined): boolean;
|
|
3
9
|
export declare function buildProgram(): Command;
|
package/dist/cli.js
CHANGED
|
@@ -195,6 +195,14 @@ const PROJECT_OPTION_HELP = 'run against this directory instead of the current o
|
|
|
195
195
|
function applyAdvisory(exitCode, advisory) {
|
|
196
196
|
return advisory && exitCode === EXIT_BLOCKED ? EXIT_OK : exitCode;
|
|
197
197
|
}
|
|
198
|
+
/**
|
|
199
|
+
* Whether the text report is rendered for a terminal: only when it goes to
|
|
200
|
+
* stdout (no --output) and stdout is a TTY. A file, a pipe and the
|
|
201
|
+
* --text-report copy never are, so they stay byte for byte as before.
|
|
202
|
+
*/
|
|
203
|
+
export function rendersToTerminal(output, stdoutIsTTY) {
|
|
204
|
+
return output === undefined && stdoutIsTTY === true;
|
|
205
|
+
}
|
|
198
206
|
/**
|
|
199
207
|
* Reads the policy for one run, from the base ref in pull-request mode.
|
|
200
208
|
*
|
|
@@ -636,16 +644,20 @@ export function buildProgram() {
|
|
|
636
644
|
// there: each finding's `properties.blocking` is the gate's own
|
|
637
645
|
// decision (see output-sarif.ts) and is unaffected by this flag,
|
|
638
646
|
// exactly as the text report's per-finding BLOCKING marker is.
|
|
639
|
-
const renderTextReport = () => renderText(result, {
|
|
647
|
+
const renderTextReport = (terminal) => renderText(result, {
|
|
640
648
|
verbose: Boolean(options.verbose),
|
|
641
649
|
version: pkg.version,
|
|
642
650
|
compact: Boolean(options.compactOnRefusal),
|
|
643
651
|
advisory,
|
|
652
|
+
...(terminal ? { terminal: true } : {}),
|
|
644
653
|
});
|
|
645
|
-
|
|
654
|
+
// Only a report printed straight to a terminal is told so; a file,
|
|
655
|
+
// a pipe and the --text-report copy render exactly as before.
|
|
656
|
+
const toTerminal = rendersToTerminal(options.output, process.stdout.isTTY);
|
|
657
|
+
const rendered = format === 'sarif' ? `${renderSarif(result, pkg.version)}\n` : renderTextReport(toTerminal);
|
|
646
658
|
// The SAME result, rendered a second time, never a second run: the
|
|
647
659
|
// token in this file is for the run that set the exit code below.
|
|
648
|
-
const textReport = options.textReport === undefined ? undefined : renderTextReport();
|
|
660
|
+
const textReport = options.textReport === undefined ? undefined : renderTextReport(false);
|
|
649
661
|
if (options.output === undefined) {
|
|
650
662
|
process.stdout.write(rendered);
|
|
651
663
|
}
|
|
@@ -689,7 +701,10 @@ export function buildProgram() {
|
|
|
689
701
|
// Written after the report file, so a failure above still takes the
|
|
690
702
|
// catch below and these lines never describe a run that then exits 2
|
|
691
703
|
// for an unwritable file.
|
|
692
|
-
const logLines = [
|
|
704
|
+
const logLines = [
|
|
705
|
+
...gateLogLines(result, process.stderr.isTTY === true ? { terminal: true } : {}),
|
|
706
|
+
...versionSkewWarnings(result),
|
|
707
|
+
];
|
|
693
708
|
if (logLines.length > 0) {
|
|
694
709
|
process.stderr.write(`${logLines.join('\n')}\n`);
|
|
695
710
|
}
|
package/dist/gate-runner.d.ts
CHANGED
|
@@ -49,10 +49,37 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
|
|
|
49
49
|
* inside the pull request is never seen). Never unshallowed automatically:
|
|
50
50
|
* the remedy is a checkout setting, fetch-depth: 0.
|
|
51
51
|
*/
|
|
52
|
-
| 'history-shallow'
|
|
52
|
+
| 'history-shallow'
|
|
53
|
+
/**
|
|
54
|
+
* conductor stopped the gate at its time limit (`timeout-seconds` in the
|
|
55
|
+
* policy, else the product's default). Decided by the spawn error code
|
|
56
|
+
* ETIMEDOUT alone, never by the signal or the status: a child that handled
|
|
57
|
+
* SIGTERM can return status 0, or its blocked code, with a clean report.
|
|
58
|
+
* Raised for the version probe, the scan, and the intent gate's
|
|
59
|
+
* preparation steps; `timedOut.step` says which spawn was stopped.
|
|
60
|
+
*/
|
|
61
|
+
| 'timed-out';
|
|
62
|
+
/** Where a gate's time limit came from: the test hook, the policy, or the product default. */
|
|
63
|
+
export type TimeLimitSource = 'override' | 'policy' | 'default';
|
|
64
|
+
export interface TimeLimit {
|
|
65
|
+
ms: number;
|
|
66
|
+
source: TimeLimitSource;
|
|
67
|
+
}
|
|
68
|
+
/** Which of a gate's spawns was stopped at the limit. The intent gate's check is `scan`. */
|
|
69
|
+
export type TimedOutStep = 'version-probe' | 'scan' | 'import-spec' | 'freeze';
|
|
70
|
+
export interface TimedOut {
|
|
71
|
+
step: TimedOutStep;
|
|
72
|
+
limitSeconds: number;
|
|
73
|
+
elapsedSeconds: number;
|
|
74
|
+
limitSource: TimeLimitSource;
|
|
75
|
+
/** What spawnSync reported; null when the child handled SIGTERM and exited itself. Never used to classify. */
|
|
76
|
+
signal: string | null;
|
|
77
|
+
}
|
|
53
78
|
export interface CouldNotRun {
|
|
54
79
|
reason: CouldNotRunReason;
|
|
55
80
|
detail: string;
|
|
81
|
+
/** Present only for `timed-out`. */
|
|
82
|
+
timedOut?: TimedOut;
|
|
56
83
|
/**
|
|
57
84
|
* What the gate itself said about why it could not run: a short, bounded,
|
|
58
85
|
* sanitised excerpt of its own stderr (first line) or, failing that, of a
|
|
@@ -74,10 +101,41 @@ export declare const GATE_SAID_MAX_CHARS = 160;
|
|
|
74
101
|
export declare function breakWorkflowMarkers(text: string): string;
|
|
75
102
|
/**
|
|
76
103
|
* The could-not-run reasons that are conductor's OWN decision, made before
|
|
77
|
-
* the gate was spawned (or instead of spawning it),
|
|
78
|
-
* the gate itself said or did.
|
|
104
|
+
* the gate was spawned (or instead of spawning it), or the umbrella stopping
|
|
105
|
+
* it, as opposed to something the gate itself said or did.
|
|
79
106
|
*/
|
|
80
107
|
export declare const CONDUCTOR_OWN_REASONS: ReadonlySet<CouldNotRunReason>;
|
|
108
|
+
/**
|
|
109
|
+
* A gate's time limit, and where it came from. THE ONE PLACE the precedence
|
|
110
|
+
* is written: the test hook (`RunGateOptions.timeoutMs`, which no CLI path
|
|
111
|
+
* sets), then the policy's `timeout-seconds`, then the product's default.
|
|
112
|
+
* runGate and the intent gate's preparation in run.ts both call this, so the
|
|
113
|
+
* two cannot disagree about a gate's limit.
|
|
114
|
+
*/
|
|
115
|
+
export declare function resolveTimeLimit(gate: GatePolicy, override: number | undefined): TimeLimit;
|
|
116
|
+
/** What a spawn error was: the umbrella's deadline, or anything else. */
|
|
117
|
+
export type SpawnFailure = {
|
|
118
|
+
reason: 'timed-out';
|
|
119
|
+
signal: string | null;
|
|
120
|
+
} | {
|
|
121
|
+
reason: 'spawn-failed';
|
|
122
|
+
message: string;
|
|
123
|
+
};
|
|
124
|
+
/**
|
|
125
|
+
* Classifies a spawnSync result that carries an error. PURE, so it is tested
|
|
126
|
+
* on hand-built results.
|
|
127
|
+
*
|
|
128
|
+
* THE ERROR CODE ALONE decides it. ETIMEDOUT is timed-out and nothing else
|
|
129
|
+
* is. No status or signal condition belongs here: a child that traps SIGTERM,
|
|
130
|
+
* or ignores it and exits on its own, comes back with status 0 (or its
|
|
131
|
+
* blocked code) and signal null, and ENOBUFS arrives with the same SIGTERM a
|
|
132
|
+
* timeout does. The signal is recorded for the report and never classifies.
|
|
133
|
+
*/
|
|
134
|
+
export declare function spawnFailure(child: {
|
|
135
|
+
error?: Error | undefined;
|
|
136
|
+
status?: number | null;
|
|
137
|
+
signal?: NodeJS.Signals | string | null;
|
|
138
|
+
}): SpawnFailure | null;
|
|
81
139
|
/**
|
|
82
140
|
* conductor's own reason for a could-not-run, as a job-log excerpt: cleaned,
|
|
83
141
|
* one line, capped and with double quotes replaced, exactly like a gate's
|
|
@@ -94,12 +152,15 @@ export declare function cleanOutputLine(raw: string): string;
|
|
|
94
152
|
* What a gate that exited with a non-verdict code said about why.
|
|
95
153
|
*
|
|
96
154
|
* TOTAL, and never a decision: the caller has already settled that this is a
|
|
97
|
-
* could-not-run, and nothing here can change that.
|
|
98
|
-
*
|
|
99
|
-
*
|
|
100
|
-
*
|
|
101
|
-
*
|
|
102
|
-
*
|
|
155
|
+
* could-not-run, and nothing here can change that. stderr is preferred, since
|
|
156
|
+
* that is where every gate in the family prints its reason on exit 2
|
|
157
|
+
* (dep-guard, intent-guard and vault-guard all do), read by the rule in
|
|
158
|
+
* `statedReasonFromStderr`: the line the gate marks as the failure, never an
|
|
159
|
+
* informational line. Failing that, stdout is parsed only for a gate whose
|
|
160
|
+
* output is JSON on stdout, and only a string `reason` field (top level, or
|
|
161
|
+
* on `run`) is read; anything else, including output that does not parse, is
|
|
162
|
+
* simply no excerpt. An absent excerpt is better than quoting a warning as
|
|
163
|
+
* the cause; the full stderr is still printed in the text report.
|
|
103
164
|
*/
|
|
104
165
|
export declare function gateStatedReason(stderr: string, stdout: string | null | undefined, stdoutIsJson: boolean): string | null;
|
|
105
166
|
/**
|
|
@@ -267,6 +328,21 @@ export interface GateOutcome {
|
|
|
267
328
|
* decision (gateExitBlocks) never need the policy file.
|
|
268
329
|
*/
|
|
269
330
|
baseComparison?: BaseComparison;
|
|
331
|
+
/**
|
|
332
|
+
* The time limit this gate ran under and where it came from, carried like
|
|
333
|
+
* `enforce` so the report and the timed-out message never need the policy
|
|
334
|
+
* file. Set on every outcome runGate builds once the limit is resolved.
|
|
335
|
+
*/
|
|
336
|
+
timeLimit?: TimeLimit;
|
|
337
|
+
/**
|
|
338
|
+
* The `conductor/option-is-gate-own` note: set when the secrets-history
|
|
339
|
+
* gate's options carry `timeout`, which is gitleaks' own --timeout and not
|
|
340
|
+
* conductor's limit. On the OUTCOME rather than in `run.diagnostics`,
|
|
341
|
+
* because every could-not-run outcome carries an empty run, and the
|
|
342
|
+
* gate-error that gitleaks' own deadline produces is exactly the outcome
|
|
343
|
+
* that needs the note. Information only; nothing decides on it.
|
|
344
|
+
*/
|
|
345
|
+
gateOwnOption?: string;
|
|
270
346
|
}
|
|
271
347
|
export interface RunGateOptions {
|
|
272
348
|
/**
|
|
@@ -279,7 +355,10 @@ export interface RunGateOptions {
|
|
|
279
355
|
staged: boolean;
|
|
280
356
|
/** PATH to search. Injected so tests never depend on the machine. */
|
|
281
357
|
pathValue: string;
|
|
282
|
-
/**
|
|
358
|
+
/**
|
|
359
|
+
* A test hook: the time limit for every spawn of this gate, outranking the
|
|
360
|
+
* policy's timeout-seconds. No CLI path sets it. See `resolveTimeLimit`.
|
|
361
|
+
*/
|
|
283
362
|
timeoutMs?: number;
|
|
284
363
|
/** The contract and change set prepared for the intent gate, when there is one. */
|
|
285
364
|
intent?: IntentPreparation;
|
|
@@ -317,6 +396,19 @@ export interface RunGateOptions {
|
|
|
317
396
|
* would have to learn about.
|
|
318
397
|
*/
|
|
319
398
|
export declare function preparationFailed(gate: GatePolicy, detail: string): GateOutcome;
|
|
399
|
+
/**
|
|
400
|
+
* The intent gate whose preparation step (import-spec or freeze) was stopped
|
|
401
|
+
* at the gate's time limit. Shaped like `preparationFailed`, with the
|
|
402
|
+
* timed-out reason, so it composes the same way; the caller decides
|
|
403
|
+
* `enforce` under the same rule it applies to a failed preparation.
|
|
404
|
+
*/
|
|
405
|
+
export declare function preparationTimedOut(gate: GatePolicy, stopped: {
|
|
406
|
+
step: 'import-spec' | 'freeze';
|
|
407
|
+
elapsedMs: number;
|
|
408
|
+
signal: string | null;
|
|
409
|
+
limit: TimeLimit;
|
|
410
|
+
trustBase?: string;
|
|
411
|
+
}): GateOutcome;
|
|
320
412
|
/**
|
|
321
413
|
* EVERY program this binary would spawn, vetted against the trust base.
|
|
322
414
|
*
|