@vaultcompass/conductor 0.8.1 → 0.9.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 +144 -35
- package/dist/cli.js +1 -1
- package/dist/envelope.d.ts +8 -0
- package/dist/exit-codes.d.ts +52 -2
- package/dist/exit-codes.js +64 -14
- package/dist/gate-runner.d.ts +22 -1
- package/dist/gate-runner.js +209 -23
- package/dist/git.d.ts +15 -0
- package/dist/git.js +20 -0
- package/dist/init-policy.js +38 -2
- package/dist/normalize.d.ts +11 -0
- package/dist/normalize.js +54 -2
- package/dist/osv-baseline.d.ts +84 -0
- package/dist/osv-baseline.js +325 -0
- package/dist/osv-coverage.d.ts +80 -0
- package/dist/osv-coverage.js +223 -0
- package/dist/output-sarif.js +43 -2
- package/dist/output-text.d.ts +5 -2
- package/dist/output-text.js +148 -13
- package/dist/policy.d.ts +10 -0
- package/dist/policy.js +12 -0
- package/dist/products.d.ts +32 -10
- package/dist/products.js +73 -9
- package/dist/requirements-pin.d.ts +47 -0
- package/dist/requirements-pin.js +256 -0
- package/dist/run.d.ts +13 -0
- package/dist/run.js +11 -2
- package/dist/trust-base.d.ts +19 -0
- package/dist/trust-base.js +30 -1
- package/dist/unread-manifests.d.ts +14 -0
- package/dist/unread-manifests.js +69 -0
- package/package.json +1 -1
- package/schema/guardrails.schema.json +4 -0
package/README.md
CHANGED
|
@@ -167,7 +167,7 @@ required.
|
|
|
167
167
|
A commit with a staged credential in it prints the full report and exits 1:
|
|
168
168
|
|
|
169
169
|
```
|
|
170
|
-
conductor 0.
|
|
170
|
+
conductor 0.9.0
|
|
171
171
|
verdict-token: blocked (1)
|
|
172
172
|
conductor run: 2 gate(s), 1 finding(s)
|
|
173
173
|
|
|
@@ -183,7 +183,7 @@ required.
|
|
|
183
183
|
|
|
184
184
|
deferred intent intent-guard did not run here; it runs from stage ci onwards
|
|
185
185
|
|
|
186
|
-
verdict: exit 1, 1 blocking finding(s)
|
|
186
|
+
verdict: exit 1, 1 blocking finding(s) in 1 of 2 enforced gate(s).
|
|
187
187
|
```
|
|
188
188
|
|
|
189
189
|
The `mode`, `corpusBuiltAt`, `lockfileFormat` and `online-flag` line under
|
|
@@ -243,6 +243,47 @@ decides the run, not even as a preview: step 1's preview gives you the same
|
|
|
243
243
|
report without putting a file the pull request controls behind a verdict on
|
|
244
244
|
the pull request page.
|
|
245
245
|
|
|
246
|
+
## Adoption ramp
|
|
247
|
+
|
|
248
|
+
A repository with history will not start clean, and a gate that is red on its
|
|
249
|
+
first pull request gets switched off. The order that works:
|
|
250
|
+
|
|
251
|
+
1. **Advisory first.** The first pull request runs with `advisory: true` and
|
|
252
|
+
`pr-comment: true`, as in "Adopting conductor" above. Findings print and
|
|
253
|
+
are commented, and none of them fails the run.
|
|
254
|
+
|
|
255
|
+
2. **Record what is already there, in each gate's own file.** conductor does
|
|
256
|
+
not write these and does not read them for the gates; each tool does.
|
|
257
|
+
- vault-guard keeps its own baseline of accepted findings. See the
|
|
258
|
+
[vault-guard documentation](https://github.com/vaultcompasshq/vault-guard)
|
|
259
|
+
for the file and how it is produced.
|
|
260
|
+
- osv-scanner reads `osv-scanner.toml` for ignored advisories, each with a
|
|
261
|
+
reason and an optional expiry. See the
|
|
262
|
+
[osv-scanner configuration docs](https://google.github.io/osv-scanner/configuration/).
|
|
263
|
+
- gitleaks reads `.gitleaks.toml` for rule tuning. Generic rules such as
|
|
264
|
+
`generic-api-key` are the usual noise on test fixtures and doc
|
|
265
|
+
placeholders; allowlist those paths there. See the
|
|
266
|
+
[gitleaks documentation](https://github.com/gitleaks/gitleaks).
|
|
267
|
+
|
|
268
|
+
3. **Accept an old history finding.** A secret that is already in history and
|
|
269
|
+
already rotated stays in every history scan. Put its fingerprint on its own
|
|
270
|
+
line in a `.gitleaksignore` file at the repository root. gitleaks' own
|
|
271
|
+
report carries the fingerprint, in the form `commit:path:rule:line`:
|
|
272
|
+
|
|
273
|
+
```
|
|
274
|
+
0a1b2c3d4e5f60718293a4b5c6d7e8f901234567:docs/example.md:generic-api-key:12
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
conductor reads `.gitleaksignore` from the base branch on a pull request,
|
|
278
|
+
so adding the line takes effect after its own merge, like any other
|
|
279
|
+
control change.
|
|
280
|
+
|
|
281
|
+
4. **Switch to enforce.** When a few ordinary pull requests report only what
|
|
282
|
+
you expect, remove `advisory: true`, and set `enforce: true` on the gates
|
|
283
|
+
you want to be able to refuse a merge. `conductor init` writes the intent
|
|
284
|
+
gate with `enforce: false` and `require-frozen: false` until a contract is
|
|
285
|
+
frozen, so a repository with no contract is not blocked by that gate.
|
|
286
|
+
|
|
246
287
|
## Why
|
|
247
288
|
|
|
248
289
|
Run all three family gates and you have three inits, three config files,
|
|
@@ -326,6 +367,7 @@ gates:
|
|
|
326
367
|
enabled: true
|
|
327
368
|
stage: ci
|
|
328
369
|
enforce: true
|
|
370
|
+
present-on-base: report
|
|
329
371
|
|
|
330
372
|
report:
|
|
331
373
|
format: text
|
|
@@ -361,13 +403,18 @@ blocking findings do not raise it, and its failing to run at all does not
|
|
|
361
403
|
make the run exit 2. That is the adoption ramp, so a gate can be switched on
|
|
362
404
|
and read for a few weeks before it is allowed to refuse anybody's commit.
|
|
363
405
|
`init` writes it out for every gate. For the intent gate it writes `true`
|
|
406
|
+
(and see `present-on-base` below for the vulnerabilities gate)
|
|
364
407
|
when a frozen contract already exists at init time
|
|
365
408
|
(`.intent-guard/intent-contract.yaml`, or the pre-1.3.0
|
|
366
409
|
`.conductor/intent-contract.yaml`), since the ramp is already climbed by
|
|
367
410
|
then, and leaving it unenforced would silently let a frozen contract's
|
|
368
411
|
protected paths produce findings that never fail the check. It writes
|
|
369
412
|
`false`, with a comment explaining why, when there is no contract yet to
|
|
370
|
-
enforce against
|
|
413
|
+
enforce against, and in that case it also writes `require-frozen: false`
|
|
414
|
+
under `options`, since intent-guard otherwise blocks on a missing contract.
|
|
415
|
+
The `options` comment is written per gate: gitleaks and osv-scanner have no
|
|
416
|
+
severity floor, so their comments point at `.gitleaks.toml` and
|
|
417
|
+
`osv-scanner.toml` rather than at `fail-on`.
|
|
371
418
|
|
|
372
419
|
**`options`** is handed to that gate unchanged. Each key is one of that
|
|
373
420
|
gate's own long flags with the leading dashes stripped: `fail-on: high`
|
|
@@ -383,7 +430,25 @@ gitleaks, and
|
|
|
383
430
|
`--format`, `--config` and `--lockfile` to osv-scanner, so those are
|
|
384
431
|
reserved too. Narrow what either
|
|
385
432
|
tool reports in its own config file (`.gitleaks.toml`, `osv-scanner.toml`)
|
|
386
|
-
instead.
|
|
433
|
+
instead. Two osv-scanner flags are written without being reserved: a run
|
|
434
|
+
that scans a requirements file always gets `--no-resolve`, and a
|
|
435
|
+
`no-resolve` key here is dropped from that run with a note; and a
|
|
436
|
+
pull-request run gets `--no-call-analysis=all` unless this block names
|
|
437
|
+
`call-analysis` or `no-call-analysis`, in which case that value is used.
|
|
438
|
+
|
|
439
|
+
**`present-on-base`** (the `vulnerabilities` gate only, beside `enforce`,
|
|
440
|
+
never under `options`) is `block` or `report`. On a pull-request run whose
|
|
441
|
+
osv-scanner scan blocked, the umbrella also scans the base branch copies of
|
|
442
|
+
the lockfiles that carry findings and labels each finding `introduced` or
|
|
443
|
+
`present-on-base`. `block` blocks on every finding; `report` reports the
|
|
444
|
+
present-on-base ones without blocking and blocks only on what the pull
|
|
445
|
+
request introduced. A policy without the key blocks on every finding, so no
|
|
446
|
+
existing policy is loosened; `init` writes `report` for a new repository.
|
|
447
|
+
On a pull request the key is read from the base branch's policy like every
|
|
448
|
+
other key, so a pull request cannot set it for itself. A run with no base (a
|
|
449
|
+
local run, a push) has no labels, and every finding blocks. The key on any
|
|
450
|
+
other gate is an error, and an older conductor rejects it, so move the
|
|
451
|
+
Action first.
|
|
387
452
|
|
|
388
453
|
**There is no shared severity threshold, on purpose.** One top-level
|
|
389
454
|
`failOn` would read as one decision and mean five different things, so
|
|
@@ -540,17 +605,47 @@ as well as for a leak, so the umbrella hands it `--exit-code 3`: 3 is a leak
|
|
|
540
605
|
when git itself fails (a base ref the checkout never fetched), so a clean
|
|
541
606
|
exit that logged an `ERR` line is could-not-run too, never a pass. A
|
|
542
607
|
gitleaks exit with no report file behind it is could-not-run. osv-scanner is
|
|
543
|
-
handed every tracked lockfile by name
|
|
544
|
-
`
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
`
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
608
|
+
handed every tracked lockfile by name, at any depth, never under
|
|
609
|
+
`node_modules`: `package-lock.json`, `npm-shrinkwrap.json`,
|
|
610
|
+
`pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `go.mod`, `poetry.lock`,
|
|
611
|
+
`Pipfile.lock`, `uv.lock`, `pdm.lock`, `Cargo.lock`, `Gemfile.lock`,
|
|
612
|
+
`composer.lock`, `gradle.lockfile`, `packages.lock.json`, `mix.lock`,
|
|
613
|
+
`pubspec.lock`, `Package.resolved`, `conan.lock`, `renv.lock`,
|
|
614
|
+
`packages.config`, `buildscript-gradle.lockfile`, `gems.locked`,
|
|
615
|
+
`pylock.toml`, `cabal.project.freeze`, `stack.yaml.lock` and
|
|
616
|
+
`verification-metadata.xml` inside a `gradle` directory, and pip
|
|
617
|
+
requirements files (`requirements.txt`, `requirements-dev.txt`,
|
|
618
|
+
`requirements_test.txt`, `requirements.prod.txt`, `dev-requirements.txt`)
|
|
619
|
+
whose every requirement, includes followed, is pinned with `==`. `go.sum`
|
|
620
|
+
is never handed over: osv-scanner reads `go.mod` for Go. A requirements
|
|
621
|
+
file with an unpinned line, or an include that is missing, untracked or
|
|
622
|
+
outside the repository, is not scanned and is named in a
|
|
623
|
+
`conductor/requirements-not-scanned` note with the line that stopped it,
|
|
624
|
+
because any version osv-scanner reported for it would be a guess.
|
|
625
|
+
Requirements files are scanned with `--no-resolve`: direct requirements
|
|
626
|
+
only, as written, and the report says so per file. On a pull request a
|
|
627
|
+
requirements file that is pinned on the base stays scanned even when the
|
|
628
|
+
pull request adds an unpinned line to it. When the repository tracks none
|
|
629
|
+
of these, osv-scanner is not spawned at all and the gate is reported clean
|
|
630
|
+
with a `conductor/nothing-to-scan` note, so a docs-only repository is not
|
|
631
|
+
red on every pull request. The note says that nothing was scanned and names
|
|
632
|
+
the tracked manifests that were not handed to osv-scanner (a
|
|
633
|
+
`pyproject.toml`, a `go.sum`, a `Dockerfile`, a workflow, or a requirements
|
|
634
|
+
file the pin check left out), so a green gate is not read as a scan of
|
|
635
|
+
them. A `go.mod` or a pinned requirements file is handed over and so is
|
|
636
|
+
never on that list. It says nothing about what other gates read. When
|
|
637
|
+
other lockfiles WERE handed over, the same list (a `Podfile.lock` beside a
|
|
638
|
+
scanned `mix.lock`, say) is printed as a `conductor/manifests-not-handed`
|
|
639
|
+
note under the gate instead. Its 1 is
|
|
640
|
+
blocked. Its own 128 ("no package sources found") on lockfiles it WAS
|
|
641
|
+
handed means they parsed to no packages; that is clean too, with a distinct
|
|
642
|
+
`conductor/lockfiles-empty` note naming the files. When some handed
|
|
643
|
+
lockfiles had packages and one had none (a lockfile rewritten to `{}` beside
|
|
644
|
+
others), the same note names the empty one and the `lockfiles` line marks it
|
|
645
|
+
`[no packages read]`; the verdict over the other files is unchanged. That
|
|
646
|
+
naming reads osv-scanner's own per-file count, which it prints at its
|
|
647
|
+
default verbosity. Lockfiles inside git
|
|
648
|
+
submodules are never listed. In a sparse
|
|
554
649
|
checkout a tracked lockfile that is not on disk is still handed over and
|
|
555
650
|
osv-scanner exits 127 on it, a false could-not-run that fails closed. Any other osv-scanner exit
|
|
556
651
|
(127 is its error code) is could-not-run. A gitleaks older than 8.19 or an
|
|
@@ -571,12 +666,19 @@ It decides nothing and never overrules a gate: it is derived from the exit
|
|
|
571
666
|
code and the `enforce` flags the run already had.
|
|
572
667
|
|
|
573
668
|
- `pass`: exit 0, and no gate, enforced or not, has a blocking finding or
|
|
574
|
-
could not run.
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
669
|
+
could not run. Under `present-on-base: report` a `pass` can carry known
|
|
670
|
+
vulnerabilities already on the base branch, reported and not blocking;
|
|
671
|
+
the report's third line then says `present-on-base: N reported, not
|
|
672
|
+
blocking`, the verdict sentence says the same, and the Action copies that
|
|
673
|
+
line to the job summary under the token.
|
|
674
|
+
- `nothing-checked`: exit 0, but nothing was checked. Either no gate ran at
|
|
675
|
+
all (none is enabled, or every enabled one was deferred to a later stage,
|
|
676
|
+
had nothing to judge, or was skipped), or every gate that ran examined
|
|
677
|
+
nothing: the vulnerabilities gate with no lockfile it reads, or the intent
|
|
678
|
+
gate with no contract to check against. The second case was `pass` in
|
|
679
|
+
0.8.x. The exit status is unchanged, since nothing failed, but this is not
|
|
680
|
+
a pass: nothing was verified. In the Action the `verdict` output carries
|
|
681
|
+
this token, so a workflow can tell it apart from `pass`.
|
|
580
682
|
- `advisory-blocked (N)`: the run would have exited 1, and `--advisory` made
|
|
581
683
|
it exit 0. N is the blocking findings on enforced gates.
|
|
582
684
|
- `unenforced-findings (N)`: exit 0, but a gate with `enforce: false` had
|
|
@@ -587,12 +689,13 @@ code and the `enforce` flags the run already had.
|
|
|
587
689
|
|
|
588
690
|
When several apply the order is `could-not-run`, then `blocked` or
|
|
589
691
|
`advisory-blocked`, then `unenforced-findings`, then `nothing-checked` (no gate
|
|
590
|
-
ran) or `pass`. A run with
|
|
692
|
+
ran, or none that ran checked anything) or `pass`. A run with
|
|
591
693
|
`--advisory` whose only blocking findings sit on an unenforced gate is
|
|
592
694
|
`unenforced-findings`, not `advisory-blocked`, because the flag did nothing
|
|
593
695
|
there. A gate skipped for want of a contract does not by itself move the token
|
|
594
|
-
off `pass` when another gate ran; when no gate ran,
|
|
595
|
-
|
|
696
|
+
off `pass` when another gate ran and checked something; when no gate ran, or
|
|
697
|
+
every gate that ran checked nothing, the token is `nothing-checked` and the
|
|
698
|
+
verdict sentence says "nothing was checked". A
|
|
596
699
|
gate that exited non-zero with no finding marked blocking counts as one in N,
|
|
597
700
|
so a state that is not a pass never prints a count of zero. The one-line
|
|
598
701
|
summary of a clean, non-verbose run has no token line, since it is one line by
|
|
@@ -1204,8 +1307,7 @@ request being judged, and the version-pin protection described above
|
|
|
1204
1307
|
"protects nothing" against a tree that controls its own judge (the
|
|
1205
1308
|
validate step's own comment in `action.yml` says so in those words). A tag
|
|
1206
1309
|
moves when someone pushes it. Name this action by owner and the full commit
|
|
1207
|
-
SHA instead. The recipes in this README
|
|
1208
|
-
updated to the v0.8.1 commit after that release is tagged.
|
|
1310
|
+
SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.9.0.
|
|
1209
1311
|
|
|
1210
1312
|
```yaml
|
|
1211
1313
|
name: guardrails
|
|
@@ -1227,7 +1329,7 @@ jobs:
|
|
|
1227
1329
|
with:
|
|
1228
1330
|
node-version: '22.11.0'
|
|
1229
1331
|
- id: conductor
|
|
1230
|
-
uses: vaultcompasshq/conductor@
|
|
1332
|
+
uses: vaultcompasshq/conductor@v0.9.0
|
|
1231
1333
|
with:
|
|
1232
1334
|
output: conductor.sarif
|
|
1233
1335
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -1302,7 +1404,7 @@ jobs:
|
|
|
1302
1404
|
# installs those itself, globally. Leave conductor-version unset so the
|
|
1303
1405
|
# umbrella is the default in the pinned action.yml.
|
|
1304
1406
|
- id: conductor
|
|
1305
|
-
uses: vaultcompasshq/conductor@
|
|
1407
|
+
uses: vaultcompasshq/conductor@v0.9.0
|
|
1306
1408
|
with:
|
|
1307
1409
|
output: conductor.sarif
|
|
1308
1410
|
# Exact versions, never a range and never "latest". These three
|
|
@@ -1313,9 +1415,9 @@ jobs:
|
|
|
1313
1415
|
# request of their own. On a pull request the action refuses a pin
|
|
1314
1416
|
# below what the pinned action.yml ships, and the three lines can
|
|
1315
1417
|
# be left out entirely to take that action's own versions.
|
|
1316
|
-
dep-guard-version: 0.
|
|
1317
|
-
vault-guard-version: 1.
|
|
1318
|
-
intent-guard-version: 1.8.
|
|
1418
|
+
dep-guard-version: 0.11.1
|
|
1419
|
+
vault-guard-version: 1.10.0
|
|
1420
|
+
intent-guard-version: 1.8.1
|
|
1319
1421
|
- uses: github/codeql-action/upload-sarif@v3
|
|
1320
1422
|
# Always: the log is most worth having on the run that failed.
|
|
1321
1423
|
if: always()
|
|
@@ -1453,7 +1555,7 @@ jobs:
|
|
|
1453
1555
|
node-version: '22.11.0'
|
|
1454
1556
|
- id: conductor
|
|
1455
1557
|
timeout-minutes: 5
|
|
1456
|
-
uses: vaultcompasshq/conductor@
|
|
1558
|
+
uses: vaultcompasshq/conductor@v0.9.0
|
|
1457
1559
|
with:
|
|
1458
1560
|
pr-comment: true
|
|
1459
1561
|
advisory: true
|
|
@@ -1589,7 +1691,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1589
1691
|
# the pull request runs before the action in this job: no install, build
|
|
1590
1692
|
# or test step here; those belong in a separate job. ...
|
|
1591
1693
|
- id: conductor
|
|
1592
|
-
uses: vaultcompasshq/conductor@
|
|
1694
|
+
uses: vaultcompasshq/conductor@v0.9.0
|
|
1593
1695
|
with:
|
|
1594
1696
|
output: conductor.sarif
|
|
1595
1697
|
pr-comment: true
|
|
@@ -1651,6 +1753,13 @@ the comment was authored by the GitHub Actions bot; a marker in anyone
|
|
|
1651
1753
|
else's comment is never adopted, and conductor creates its own comment
|
|
1652
1754
|
instead, exactly as if no marked comment existed.
|
|
1653
1755
|
|
|
1756
|
+
**The poster runs the `node` and `gh` that were on `PATH` when the Action
|
|
1757
|
+
started**, resolved by the Action's first step before any gate package is
|
|
1758
|
+
installed, and never a binary from the gate install directory. The gate
|
|
1759
|
+
install goes on `PATH` only after its signature audit passes. GitHub-hosted
|
|
1760
|
+
runners carry both; on a runner that has neither on `PATH` at that point the
|
|
1761
|
+
comment is skipped with a warning and the verdict is unaffected.
|
|
1762
|
+
|
|
1654
1763
|
**Running this Action more than once against the same pull request** (for
|
|
1655
1764
|
example, once per package in a monorepo) needs its own marker per run, or
|
|
1656
1765
|
those runs fight over one shared comment. Set `pr-comment-marker` to a
|
|
@@ -1661,12 +1770,12 @@ per pull request.
|
|
|
1661
1770
|
|
|
1662
1771
|
```yaml
|
|
1663
1772
|
- id: conductor-package-a
|
|
1664
|
-
uses: vaultcompasshq/conductor@
|
|
1773
|
+
uses: vaultcompasshq/conductor@v0.9.0
|
|
1665
1774
|
with:
|
|
1666
1775
|
pr-comment: true
|
|
1667
1776
|
pr-comment-marker: 'package-a'
|
|
1668
1777
|
- id: conductor-package-b
|
|
1669
|
-
uses: vaultcompasshq/conductor@
|
|
1778
|
+
uses: vaultcompasshq/conductor@v0.9.0
|
|
1670
1779
|
with:
|
|
1671
1780
|
pr-comment: true
|
|
1672
1781
|
pr-comment-marker: 'package-b'
|
package/dist/cli.js
CHANGED
|
@@ -566,7 +566,7 @@ export function buildProgram() {
|
|
|
566
566
|
.option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to the base branch (refs/conductor/trust-base, else refs/remotes/origin/<GITHUB_BASE_REF>, as a commit id) when GITHUB_BASE_REF is set.')
|
|
567
567
|
.option('--trust-base <ref>', 'pull-request mode: read .guardrails.yaml from this ref instead of from the tree being judged, and pass the same ref to every gate that supports it. A policy change in the pull request is reported as a proposal and never takes effect for the run, so a pull request cannot change the rules it is judged by. In Actions the composite action fetches the base branch and passes its full commit id on a pull_request event.')
|
|
568
568
|
.option('--output <path>', 'write the report to this file instead of to stdout, for a CI step that uploads it')
|
|
569
|
-
.option('--text-report <path>', 'with --format sarif, also write the text report to this file, from the same run: exactly what --format text would have rendered for this result, --verbose, --compact-on-refusal and --advisory respected, and no gate is run a second time. In a full report (any run that is not fully clean, or any run with --verbose) the second line is "verdict-token: <token>"; the one-line summary of a clean run without --verbose has none. The token is a label for this run\'s own exit decision: pass, nothing-checked (exit 0 but no gate ran), advisory-blocked (N), unenforced-findings (N), blocked (N) or could-not-run. Only meaningful with --format sarif: with --format text the text report is already the output, so the combination is a usage error (exit 2).')
|
|
569
|
+
.option('--text-report <path>', 'with --format sarif, also write the text report to this file, from the same run: exactly what --format text would have rendered for this result, --verbose, --compact-on-refusal and --advisory respected, and no gate is run a second time. In a full report (any run that is not fully clean, or any run with --verbose) the second line is "verdict-token: <token>"; the one-line summary of a clean run without --verbose has none. The token is a label for this run\'s own exit decision: pass, nothing-checked (exit 0 but nothing was checked: no gate ran, or every gate that ran had nothing to scan, read no packages, or had no contract), advisory-blocked (N), unenforced-findings (N), blocked (N) or could-not-run. Only meaningful with --format sarif: with --format text the text report is already the output, so the combination is a usage error (exit 2).')
|
|
570
570
|
.option('--spec <path>', 'the spec the intent gate imports its contract from, outranking a Spec: line in the pull request body and the branch-name convention. On a pull-request run (--trust-base) the spec is read from the base ref, and a frozen contract on the base takes precedence over it')
|
|
571
571
|
.option('--verbose', 'print the full per-gate report even when the run is clean. A clean run prints one summary line by default, because a pre-commit hook that prints a screenful on every commit is a hook a team switches off. Text output only; SARIF is unaffected.')
|
|
572
572
|
.option('--compact-on-refusal', 'when the trust base was refused and no gate ran, print a short body instead of the full refusal report: the version, the verdict, and the refusal reason (with its remedy, when one applies), never the full per-gate report. Built for the pull-request-comment step; every other run is unaffected, whatever --verbose says. Text output only; SARIF is unaffected.')
|
package/dist/envelope.d.ts
CHANGED
|
@@ -111,6 +111,14 @@ export interface NormalizedGateOutput {
|
|
|
111
111
|
/** One line per control input the head proposes to change. */
|
|
112
112
|
proposals: string[];
|
|
113
113
|
};
|
|
114
|
+
/**
|
|
115
|
+
* osv-scanner only: every package that carried a verdict which is not an
|
|
116
|
+
* advisory, one line each ("license_violations (click@8.1.7)"). osv-scanner
|
|
117
|
+
* exits 1 for those as well as for an advisory, and none of them is a
|
|
118
|
+
* finding here, so the exit-code exception for present-on-base findings
|
|
119
|
+
* (src/exit-codes.ts, gateExitBlocks, condition f) reads this instead.
|
|
120
|
+
*/
|
|
121
|
+
otherVerdicts?: string[];
|
|
114
122
|
}
|
|
115
123
|
export declare class NormalizeError extends Error {
|
|
116
124
|
constructor(message: string);
|
package/dist/exit-codes.d.ts
CHANGED
|
@@ -1,3 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The fields of a gate's outcome `gateExitBlocks` reads. A structural type
|
|
3
|
+
* rather than an import of GateOutcome, so this file stays free of the
|
|
4
|
+
* runner and any caller with these fields can ask.
|
|
5
|
+
*/
|
|
6
|
+
export interface ExitBlocksInput {
|
|
7
|
+
role: string;
|
|
8
|
+
product: string;
|
|
9
|
+
/** The child's own exit code, or null when there was no child. */
|
|
10
|
+
exitCode: number | null;
|
|
11
|
+
couldNotRun: unknown;
|
|
12
|
+
findings: ReadonlyArray<{
|
|
13
|
+
details: Record<string, unknown>;
|
|
14
|
+
}>;
|
|
15
|
+
baseComparison?: {
|
|
16
|
+
policy: 'block' | 'report';
|
|
17
|
+
otherVerdicts: readonly string[];
|
|
18
|
+
};
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Whether this gate's own child exit blocks the run.
|
|
22
|
+
*
|
|
23
|
+
* Every "the child exited non-zero" decision goes through here: the composed
|
|
24
|
+
* exit code, the verdict token's count, the verdict sentence, the
|
|
25
|
+
* not-enforced note and the SARIF gate-not-enforced notification. A reader
|
|
26
|
+
* that compares the raw exit with 0 instead would say "blocked" on a run
|
|
27
|
+
* that exits 0 (tests/osv-exit.test.ts holds every reader to this).
|
|
28
|
+
*
|
|
29
|
+
* False for an exit of 0 (or no child). For a non-zero exit, true unless ALL
|
|
30
|
+
* of these hold:
|
|
31
|
+
* (a) the gate is the vulnerabilities gate, osv-scanner in that role;
|
|
32
|
+
* (b) its base policy said present-on-base: report;
|
|
33
|
+
* (c) a base comparison ran (it is carried on the outcome only then);
|
|
34
|
+
* (d) at least one finding was parsed, since exit 1 with nothing parsed
|
|
35
|
+
* is a verdict this umbrella cannot read;
|
|
36
|
+
* (e) every finding is labelled present-on-base. Redundant by
|
|
37
|
+
* construction: under report an introduced finding stays blocking,
|
|
38
|
+
* which blocks the run through `hasBlockingFinding` whatever this
|
|
39
|
+
* returns. Kept so the predicate states the whole rule;
|
|
40
|
+
* (f) the head output carried no verdict that is not an advisory: no
|
|
41
|
+
* license_violations, no deprecated package, no other unmapped
|
|
42
|
+
* package-level field. osv-scanner exits 1 for those too, and none of
|
|
43
|
+
* them is a finding here.
|
|
44
|
+
*/
|
|
45
|
+
export declare function gateExitBlocks(gate: ExitBlocksInput): boolean;
|
|
1
46
|
export declare const EXIT_OK = 0;
|
|
2
47
|
export declare const EXIT_BLOCKED = 1;
|
|
3
48
|
export declare const EXIT_COULD_NOT_RUN = 2;
|
|
@@ -6,8 +51,13 @@ export interface ExitInput {
|
|
|
6
51
|
couldNotRun: {
|
|
7
52
|
reason: string;
|
|
8
53
|
} | null;
|
|
9
|
-
/**
|
|
10
|
-
|
|
54
|
+
/**
|
|
55
|
+
* Whether the child's own exit blocks: `gateExitBlocks(outcome)`, never the
|
|
56
|
+
* raw exit code compared with 0. REQUIRED, like `enforce`, so a caller
|
|
57
|
+
* that has not thought about the present-on-base exception does not
|
|
58
|
+
* compile.
|
|
59
|
+
*/
|
|
60
|
+
exitBlocks: boolean;
|
|
11
61
|
/** Whether any finding from this gate is one the gate itself blocks on. */
|
|
12
62
|
hasBlockingFinding: boolean;
|
|
13
63
|
/**
|
package/dist/exit-codes.js
CHANGED
|
@@ -30,20 +30,70 @@
|
|
|
30
30
|
// maximum of the children's, and that is deliberate.
|
|
31
31
|
//
|
|
32
32
|
// The umbrella never overrules a gate's own blocking decision. A gate that
|
|
33
|
-
// exited non-zero produces a non-zero composed code,
|
|
34
|
-
// per-finding `blocking` flag can only ADD to that,
|
|
35
|
-
// exists so a gate whose exit code somehow said clean
|
|
36
|
-
// carried a blocking finding still fails the run.
|
|
33
|
+
// exited non-zero produces a non-zero composed code, with exactly one
|
|
34
|
+
// exception, below. The per-finding `blocking` flag can only ADD to that,
|
|
35
|
+
// never subtract: it exists so a gate whose exit code somehow said clean
|
|
36
|
+
// while its own report carried a blocking finding still fails the run.
|
|
37
37
|
//
|
|
38
|
-
//
|
|
39
|
-
//
|
|
40
|
-
//
|
|
41
|
-
//
|
|
42
|
-
//
|
|
43
|
-
//
|
|
44
|
-
//
|
|
45
|
-
//
|
|
46
|
-
//
|
|
38
|
+
// Two written decisions change what reaches this composition, and both are
|
|
39
|
+
// the repository's own lines in its policy file rather than a judgment made
|
|
40
|
+
// here.
|
|
41
|
+
//
|
|
42
|
+
// First, a gate carrying `enforce: false` is left out of this composition
|
|
43
|
+
// entirely. That is the adoption ramp, so a gate can be switched on and read
|
|
44
|
+
// for a few weeks before it is allowed to refuse anybody's commit. It is not
|
|
45
|
+
// a downgrade: the gate still runs, its findings keep their own levels, its
|
|
46
|
+
// blocking flags are untouched, and both output formats say plainly that it
|
|
47
|
+
// blocked and was not enforced. Nothing here reads a gate's output and
|
|
48
|
+
// decides on its own judgment to ignore it.
|
|
49
|
+
//
|
|
50
|
+
// Second, the vulnerabilities gate under `present-on-base: report` (osv
|
|
51
|
+
// design, section 4.3): a non-zero osv-scanner exit does not block when ALL
|
|
52
|
+
// of (a) to (f) in `gateExitBlocks` hold, which is a compared pull-request
|
|
53
|
+
// run whose every parsed finding is also on the base branch, under a key the
|
|
54
|
+
// BASE policy wrote, with no non-advisory verdict in the output. That is a
|
|
55
|
+
// set difference of two runs of the same tool, not a judgment about any one
|
|
56
|
+
// finding, and the findings still print with their labels.
|
|
57
|
+
/**
|
|
58
|
+
* Whether this gate's own child exit blocks the run.
|
|
59
|
+
*
|
|
60
|
+
* Every "the child exited non-zero" decision goes through here: the composed
|
|
61
|
+
* exit code, the verdict token's count, the verdict sentence, the
|
|
62
|
+
* not-enforced note and the SARIF gate-not-enforced notification. A reader
|
|
63
|
+
* that compares the raw exit with 0 instead would say "blocked" on a run
|
|
64
|
+
* that exits 0 (tests/osv-exit.test.ts holds every reader to this).
|
|
65
|
+
*
|
|
66
|
+
* False for an exit of 0 (or no child). For a non-zero exit, true unless ALL
|
|
67
|
+
* of these hold:
|
|
68
|
+
* (a) the gate is the vulnerabilities gate, osv-scanner in that role;
|
|
69
|
+
* (b) its base policy said present-on-base: report;
|
|
70
|
+
* (c) a base comparison ran (it is carried on the outcome only then);
|
|
71
|
+
* (d) at least one finding was parsed, since exit 1 with nothing parsed
|
|
72
|
+
* is a verdict this umbrella cannot read;
|
|
73
|
+
* (e) every finding is labelled present-on-base. Redundant by
|
|
74
|
+
* construction: under report an introduced finding stays blocking,
|
|
75
|
+
* which blocks the run through `hasBlockingFinding` whatever this
|
|
76
|
+
* returns. Kept so the predicate states the whole rule;
|
|
77
|
+
* (f) the head output carried no verdict that is not an advisory: no
|
|
78
|
+
* license_violations, no deprecated package, no other unmapped
|
|
79
|
+
* package-level field. osv-scanner exits 1 for those too, and none of
|
|
80
|
+
* them is a finding here.
|
|
81
|
+
*/
|
|
82
|
+
export function gateExitBlocks(gate) {
|
|
83
|
+
if ((gate.exitCode ?? 0) === 0) {
|
|
84
|
+
return false;
|
|
85
|
+
}
|
|
86
|
+
const comparison = gate.baseComparison;
|
|
87
|
+
const reportedNotBlocking = gate.role === 'vulnerabilities' &&
|
|
88
|
+
gate.product === 'osv-scanner' &&
|
|
89
|
+
comparison !== undefined &&
|
|
90
|
+
comparison.policy === 'report' &&
|
|
91
|
+
gate.couldNotRun === null &&
|
|
92
|
+
gate.findings.length > 0 &&
|
|
93
|
+
gate.findings.every((finding) => finding.details.baseline === 'present-on-base') &&
|
|
94
|
+
comparison.otherVerdicts.length === 0;
|
|
95
|
+
return !reportedNotBlocking;
|
|
96
|
+
}
|
|
47
97
|
export const EXIT_OK = 0;
|
|
48
98
|
export const EXIT_BLOCKED = 1;
|
|
49
99
|
export const EXIT_COULD_NOT_RUN = 2;
|
|
@@ -52,7 +102,7 @@ export function composeExitCode(gates) {
|
|
|
52
102
|
if (enforced.some((gate) => gate.couldNotRun !== null)) {
|
|
53
103
|
return EXIT_COULD_NOT_RUN;
|
|
54
104
|
}
|
|
55
|
-
if (enforced.some((gate) =>
|
|
105
|
+
if (enforced.some((gate) => gate.exitBlocks || gate.hasBlockingFinding)) {
|
|
56
106
|
return EXIT_BLOCKED;
|
|
57
107
|
}
|
|
58
108
|
return EXIT_OK;
|
package/dist/gate-runner.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { Diagnostic, Finding, RunSummary } from './envelope.js';
|
|
2
2
|
import type { ContractSource, IntentPreparation } from './intent-prepare.js';
|
|
3
3
|
import type { GatePolicy, GateRole, GateStage, Product } from './policy.js';
|
|
4
|
+
import { type BaseComparison } from './osv-baseline.js';
|
|
4
5
|
import type { ResolvedBinary } from './resolve.js';
|
|
5
6
|
export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing' | 'spawn-failed' | 'gate-error' | 'unparseable-output'
|
|
6
7
|
/**
|
|
@@ -257,6 +258,15 @@ export interface GateOutcome {
|
|
|
257
258
|
found: string;
|
|
258
259
|
path: string;
|
|
259
260
|
};
|
|
261
|
+
/**
|
|
262
|
+
* The vulnerabilities gate only, and only when a base comparison ran (a
|
|
263
|
+
* pull-request run whose head scan blocked with at least one finding): the
|
|
264
|
+
* ref, the base policy's present-on-base value, the counts, the lockfiles
|
|
265
|
+
* the comparison was unavailable for, and any non-advisory verdict in the
|
|
266
|
+
* head output. Carried here, like `enforce`, so a report and the exit
|
|
267
|
+
* decision (gateExitBlocks) never need the policy file.
|
|
268
|
+
*/
|
|
269
|
+
baseComparison?: BaseComparison;
|
|
260
270
|
}
|
|
261
271
|
export interface RunGateOptions {
|
|
262
272
|
/**
|
|
@@ -354,8 +364,19 @@ export interface ExternalArgs {
|
|
|
354
364
|
* .gitleaksignore at its root for gitleaks to load on its own.
|
|
355
365
|
*/
|
|
356
366
|
scanRoot?: string;
|
|
357
|
-
/**
|
|
367
|
+
/**
|
|
368
|
+
* The files osv-scanner is handed: repository-relative on the head run,
|
|
369
|
+
* absolute copies under the work directory on the base run.
|
|
370
|
+
*/
|
|
358
371
|
lockfiles?: readonly string[];
|
|
372
|
+
/**
|
|
373
|
+
* Whether this invocation gets --no-resolve. Decided once, from the HEAD
|
|
374
|
+
* run's list (any requirements file), and handed to the base run as is, so
|
|
375
|
+
* the two command lines cannot differ in resolution mode because the base
|
|
376
|
+
* run scans a different subset (osv design, section 2.4). Absent means
|
|
377
|
+
* "decide from `lockfiles`".
|
|
378
|
+
*/
|
|
379
|
+
noResolve?: boolean;
|
|
359
380
|
}
|
|
360
381
|
/**
|
|
361
382
|
* The arguments the umbrella adds, per product.
|