From 312326a3642c000d8de71ab92a20cda265c461fb Mon Sep 17 00:00:00 2001 From: Joey Mussalli Date: Mon, 24 Aug 2026 15:30:53 -0400 Subject: [PATCH] docs: document BRANCH and DEBUG, and info as a severity threshold Three gaps in the root README's inputs table, all cases where the script reads something the table does not mention. `BRANCH` and `DEBUG` are both read (the script's own header comment lists them) but neither appears in the table, so the only way to discover them is to read the source. `BRANCH` is not a nicety. The script works out the branch and repository three ways and on CodePipeline -- the primary integration here -- all three miss. CODEBUILD_WEBHOOK_HEAD_REF is documented as the head ref "of the webhook event that triggers the current build", so it is unset for pipeline-triggered builds. CODEBUILD_SOURCE_REPO_URL "may be empty" when the build originates from CodePipeline. And a pipeline source artifact is an unzipped snapshot with no .git for the final fallback. So every report and every trustabl-summary.md in that integration reads `Repository: .` / `Branch: unknown`, and the one variable that fixes it was undocumented. `SEVERITY_THRESHOLD` was documented as accepting `none/low/medium/high/critical`, but sev_rank ranks `info` at 0 and MAX_SEV can be `info`, so `SEVERITY_THRESHOLD=info` is accepted and does fail the build on info-only findings. Worth stating, because docs/EVALUATION.md says "info and META signals never fail a build on their own" -- true of the default, not true once you set this. - Add `BRANCH` and `DEBUG` rows. - Add `info` to the documented severity set. - Add a short section explaining why BRANCH is needed on CodePipeline, with the reasoning rather than just the instruction. Documentation only; no code changes. Refs: https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html --- README.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d8c5d00..5fa994d 100644 --- a/README.md +++ b/README.md @@ -19,13 +19,15 @@ One scanner (`scan/trustabl-scan.sh`), two integrations: | `TARGET` | `.` | Path or GitHub URL to scan. | | `VERSION` | `latest` | trustabl release tag (e.g. `v0.5.0`) or `latest`. | | `DETECTORS` | _(all)_ | Comma-separated SDK subset (`claude_sdk,openai_sdk,google_adk,...`). | +| `BRANCH` | _(detected)_ | Branch label for the report. **Set this on CodePipeline** — see below. | +| `DEBUG` | `false` | `true` turns on `set -x` command tracing. | | `STRICT` | `false` | Fail on any finding. | | `RULES_REF` | _(default)_ | Pin a `trustabl-rules` git ref. | | `RULES_REPO` | _(default)_ | Override the `trustabl-rules` source repo. | | `SARIF_FILE` | `trustabl.sarif` | SARIF output path. | | `JSON_FILE` | `trustabl.json` | JSON ScanResult output path. | | `RISK_SCORE_THRESHOLD` | `0` | Fail when risk (100 − readiness) >= N. `0` disables. | -| `SEVERITY_THRESHOLD` | `none` | Fail when any finding >= severity (`none/low/medium/high/critical`). | +| `SEVERITY_THRESHOLD` | `none` | Fail when any finding >= severity (`none/info/low/medium/high/critical`). | | `GITHUB_TOKEN` | _(none)_ | Optional — avoids GitHub's 60 req/hr anonymous rate limit. | ## Outputs @@ -34,6 +36,15 @@ One scanner (`scan/trustabl-scan.sh`), two integrations: (`TRUSTABL_READINESS_SCORE`, `TRUSTABL_RISK_SCORE`, `TRUSTABL_MAX_SEVERITY`, `TRUSTABL_FINDINGS_COUNT`, `TRUSTABL_EXIT_CODE`). +## Why `BRANCH` matters on CodePipeline + +The script tries three ways to work out the branch and repository, and on +CodePipeline all three miss. `CODEBUILD_WEBHOOK_HEAD_REF` is set only for +*webhook* events; `CODEBUILD_SOURCE_REPO_URL` "may be empty" when the build +originates from CodePipeline; and a pipeline source artifact is an unzipped +snapshot with no `.git` for the final fallback. Every report then reads +`Repository: .` / `Branch: unknown`. Set `BRANCH` explicitly to get a real label. + ## A note on "AWS Marketplace" AWS has **no self-serve CI-plugin catalog** like the GitHub/Azure/Bitbucket