From aa5cd575fb87e16059d2e61d00cb83b04911a9ee Mon Sep 17 00:00:00 2001 From: "Bacchus Jackson (BJaX)" <34331871+BacchusJackson@users.noreply.github.com> Date: Wed, 4 Nov 2026 12:23:33 -0600 Subject: [PATCH 1/3] Support OpenVEX and CycloneDX VEX in validate validate --vex, GATECHECK_VEX, and the config's vex.files read OpenVEX and CycloneDX VEX. Grype, CycloneDX, Trivy, and osv-scanner findings marked not exploitable are dropped after the deny list, so they skip the KEV, EPSS, and severity rules. Statements that name packages match by package URL, and the latest statement wins. Fixes #102 --- CHANGELOG.md | 1 + cmd/validate.go | 7 + docs/SUMMARY.md | 1 + docs/agent-guide.md | 3 + docs/cli-reference.md | 2 + docs/configuration.md | 6 + docs/validation.md | 2 +- docs/vex.md | 63 +++++ pkg/artifacts/cyclonedx.go | 21 ++ pkg/artifacts/grype.go | 23 +- pkg/artifacts/osv.go | 38 +++ pkg/artifacts/trivy.go | 7 +- pkg/gatecheck/config.go | 5 + pkg/gatecheck/download.go | 2 + pkg/gatecheck/osv.go | 1 + pkg/gatecheck/trivy.go | 1 + pkg/gatecheck/validate.go | 15 +- pkg/gatecheck/vex.go | 108 +++++++++ pkg/gatecheck/vex_test.go | 187 +++++++++++++++ pkg/vex/vex.go | 469 +++++++++++++++++++++++++++++++++++++ pkg/vex/vex_test.go | 192 +++++++++++++++ website/llms-full.txt | 3 + website/llms.txt | 1 + 23 files changed, 1152 insertions(+), 6 deletions(-) create mode 100644 docs/vex.md create mode 100644 pkg/gatecheck/vex.go create mode 100644 pkg/gatecheck/vex_test.go create mode 100644 pkg/vex/vex.go create mode 100644 pkg/vex/vex_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 9024bc5..d4bb81a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `gatecheck bootstrap --tools gosec,hadolint,zizmor` installs pinned gosec 2.30.0, hadolint 2.15.1, and zizmor 1.32.0. `gatecheck gosec`, `gatecheck hadolint`, and `gatecheck zizmor` run them. Their SARIF output is gated with the `sarif` config section. They are not part of the default install. zizmor publishes no checksum file, so its asset digests are pinned in gatecheck. - `gatecheck bootstrap --list` shows every supported tool. +- `validate --vex FILE`, `GATECHECK_VEX`, and the config's `vex.files` read OpenVEX and CycloneDX VEX documents. Grype, CycloneDX, Trivy, and osv-scanner findings marked `not_affected`, `fixed`, `false_positive`, or `resolved` are skipped before the KEV, EPSS, and severity rules. A statement that names packages matches by package URL. The latest statement wins. Fixes #102. ## [0.10.0] - 2026-10-30 diff --git a/cmd/validate.go b/cmd/validate.go index 26c366f..dbfd66c 100644 --- a/cmd/validate.go +++ b/cmd/validate.go @@ -4,6 +4,7 @@ import ( "fmt" "log/slog" "os" + "strings" "github.com/gatecheckdev/gatecheck/pkg/gatecheck" "github.com/spf13/cobra" @@ -59,6 +60,11 @@ var validateCmd = &cobra.Command{ gatecheck.WithKEVFile(RuntimeConfig.kevFile), } opts = append(opts, epssCacheOptions()...) + vexFiles, _ := cmd.Flags().GetStringSlice("vex") + if env := strings.TrimSpace(os.Getenv("GATECHECK_VEX")); len(vexFiles) == 0 && env != "" { + vexFiles = strings.Split(env, ",") + } + opts = append(opts, gatecheck.WithVEXFiles(vexFiles...)) err := gatecheck.Validate( RuntimeConfig.gatecheckConfig, RuntimeConfig.targetFile, @@ -85,6 +91,7 @@ func newValidateCommand() *cobra.Command { RuntimeConfig.EPSSNoCache.SetupCobra(validateCmd) RuntimeConfig.KEVFilename.SetupCobra(validateCmd) RuntimeConfig.Audit.SetupCobra(validateCmd) + validateCmd.Flags().StringSlice("vex", nil, "OpenVEX or CycloneDX VEX file; findings it marks not_affected, fixed, false_positive, or resolved are skipped (repeatable, env GATECHECK_VEX)") return validateCmd } diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 94f4df6..9cdfec3 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -9,6 +9,7 @@ - [List Reports](./list-reports.md) - [Gatecheck Bundle](./gatecheck-bundle.md) - [Validation](./validation.md) + - [VEX](./vex.md) - [Examples](./examples.md) - [Supported Reports](./supported-reports.md) - [Configuration](./configuration.md) diff --git a/docs/agent-guide.md b/docs/agent-guide.md index f60b43a..af31791 100644 --- a/docs/agent-guide.md +++ b/docs/agent-guide.md @@ -181,6 +181,8 @@ Opening the report, the config, and any `--epss-filename` or `--kev-filename` ha `--epss-filename` is the EPSS CSV used when an EPSS rule is enabled. `--kev-filename` is the CISA KEV JSON used when `kevLimitEnabled` is true. `--epss-cache-dir` and `--epss-no-cache` apply when that CSV is downloaded. `validate` has no `--epss-url` or `--kev-url` flag. `GATECHECK_EPSS_URL` and `GATECHECK_KEV_URL` still override those APIs when the matching file is not set. The defaults are the same URLs `download` uses. +`--vex FILE` (repeatable), `GATECHECK_VEX` (comma-separated, used when the flag is absent), and the config's `vex.files` name OpenVEX or CycloneDX VEX documents. Grype, CycloneDX, Trivy, and osv-scanner findings that a VEX file marks `not_affected` or `fixed` (OpenVEX), or `not_affected`, `false_positive`, `resolved`, or `resolved_with_pedigree` (CycloneDX `analysis.state`), are removed right after the `cveLimit` deny list, so they skip the KEV, EPSS, and severity rules. Ids match the finding's id or aliases. A statement that lists subcomponents or `affects` refs matches only those package URLs. The OpenVEX product itself is not checked. When several statements match, the latest timestamp wins. + EPSS data is loaded only when an EPSS limit or EPSS risk acceptance rule is enabled. KEV data is loaded only when `kevLimitEnabled` is true for Grype, CycloneDX, Trivy, or osv-scanner. With no local EPSS file, gatecheck downloads the current CSV and caches it until the published date changes. ## list @@ -229,6 +231,7 @@ A non-empty flag wins. An empty flag falls through to the environment variable, | Variable | Commands | Same as | | --- | --- | --- | | `GATECHECK_CONFIG_FILENAME` | `validate` | `--config` | +| `GATECHECK_VEX` | `validate` | `--vex`, comma-separated | | `GATECHECK_EPSS_FILENAME` | `list`, `validate` | `--epss-filename` | | `GATECHECK_EPSS_URL` | `download epss`, `list`, `list-all`, `validate` | `--epss-url` on commands that have that flag | | `GATECHECK_EPSS_CACHE_DIR` | `download epss`, `list`, `list-all`, `validate` | `--epss-cache-dir` | diff --git a/docs/cli-reference.md b/docs/cli-reference.md index d70b374..ae61ca4 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -114,6 +114,7 @@ gatecheck validate [FILE] - `--epss-no-cache`: download on every run. `GATECHECK_EPSS_CACHE=off` does the same. - `--kev-filename`: CISA KEV JSON to use when a KEV rule is enabled. - `-a`, `--audit`: print the error from the check and exit 0. A missing report, a missing config, or a bad flag still exits 255. +- `--vex`: OpenVEX or CycloneDX VEX file. Findings it marks not exploitable are skipped. Repeat the flag for more files. `GATECHECK_VEX` is a comma-separated list used when the flag is absent. Files in the config's `vex.files` are read too. A VEX file that cannot be read exits 255. See [VEX](./vex.md). `validate` has no `--epss-url` or `--kev-url` flag. `GATECHECK_EPSS_URL` and `GATECHECK_KEV_URL` still override those APIs when the matching file flag is empty. The defaults are the same URLs `download` uses. @@ -305,6 +306,7 @@ Prints help for a command. `gatecheck validate --help` does the same. | Variable | Commands | Same as | | --- | --- | --- | | `GATECHECK_CONFIG_FILENAME` | `validate` | `--config` | +| `GATECHECK_VEX` | `validate` | `--vex`, comma-separated | | `GATECHECK_EPSS_FILENAME` | `list`, `validate` | `--epss-filename` | | `GATECHECK_EPSS_URL` | `download epss`, `list`, `list-all`, `validate` | `--epss-url` on `download epss` and `list` | | `GATECHECK_EPSS_CACHE_DIR` | `download epss`, `list`, `list-all`, `validate` | `--epss-cache-dir` | diff --git a/docs/configuration.md b/docs/configuration.md index 68d2f93..35c3af2 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -178,6 +178,8 @@ coverage: lineThreshold: 0 functionThreshold: 0 branchThreshold: 0 +vex: + files: [] ``` ## version and metadata @@ -198,6 +200,10 @@ osv-scanner counts one finding per vulnerability group. Aliases of that group ar `cveLimit` and `cveRiskAcceptance` each have `enabled` and `cves`. A CVE entry is `id` plus an optional `metadata.tags` list. `id` is compared without regard to case. +## VEX + +`vex.files` lists OpenVEX or CycloneDX VEX documents. `validate` reads them along with any `--vex` files, and skips the Grype, CycloneDX, Trivy, and osv-scanner findings they mark as not exploitable. Relative paths are read from the working directory. See [VEX](./vex.md). + ```yaml grype: cveLimit: diff --git a/docs/validation.md b/docs/validation.md index 779daac..dd6fe4f 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -29,7 +29,7 @@ Rules run in this order. A failure returns immediately, except where a rule only 1. **CVE limit.** `cveLimit`, when enabled, fails if any listed id is in the report. Ids are compared without regard to case. 2. **Disabled Grype, Trivy, and osv-scanner severities.** Grype, Trivy, and osv-scanner drop findings whose severity limit is disabled. If the EPSS limit is also enabled, a finding at a disabled severity stays in the report when it has an EPSS score greater than or equal to that limit. CycloneDX leaves findings at a disabled severity in the report, so they still go through the KEV and EPSS rules. -3. **CVE risk acceptance.** Matching ids are removed and skip the remaining rules. +3. **CVE risk acceptance and VEX.** Matching ids are removed and skip the remaining rules. Findings that a VEX file passed with `--vex`, `GATECHECK_VEX`, or `vex.files` marks `not_affected`, `fixed`, `false_positive`, or `resolved` are removed too. See [VEX](./vex.md). 4. **KEV limit.** When `kevLimitEnabled` is true, a CVE that is in the catalog fails the report. The catalog is `--kev-filename` or, with no file, the CISA feed. `GATECHECK_KEV_URL` overrides the feed. There is no `--kev-url` flag on `validate`. 5. **EPSS risk acceptance.** A CVE is removed when the configured `score` is greater than that CVE's EPSS score. A CVE with no EPSS row is kept. A CVE whose score is equal to the configured score is kept. 6. **EPSS limit.** A CVE fails when its EPSS score is greater than `score`. A CVE with no EPSS row passes this rule. A score equal to the limit passes. Data comes from `--epss-filename` or `GATECHECK_EPSS_FILENAME`, or from the API. `GATECHECK_EPSS_URL` overrides the API. There is no `--epss-url` flag on `validate`. diff --git a/docs/vex.md b/docs/vex.md new file mode 100644 index 0000000..d5d2dab --- /dev/null +++ b/docs/vex.md @@ -0,0 +1,63 @@ +# VEX + +A VEX (Vulnerability Exploitability eXchange) document says whether a vulnerability actually affects your software. `validate` reads OpenVEX and CycloneDX VEX files and skips the findings they mark as not exploitable. Your risk decisions can then live in a VEX file that other tools also read, not only in the `cveRiskAcceptance` lists in the gatecheck config. + +```shell +gatecheck validate --config gatecheck.yaml --vex app.openvex.json grype-report.json +gatecheck validate --vex app.openvex.json --vex vendor.cdx.json trivy-report.json +``` + +VEX applies to Grype, CycloneDX, Trivy, and osv-scanner reports, and to those reports inside a bundle. SARIF, Semgrep, Gitleaks, and coverage reports are not affected. + +## Where the files come from + +- `--vex FILE` on `validate`. Repeat the flag for more files. +- `GATECHECK_VEX`, a comma-separated list of files. It is read only when `--vex` is not given. +- `vex.files` in the config. These are read along with the flag or environment files. + +```yaml +vex: + files: + - .vex/app.openvex.json +``` + +Relative paths are read from the working directory. A file that is missing, is not JSON, or is neither format is an error, and `validate` exits 255 without checking the report. + +## Which statuses skip a finding + +| Format | Skips the finding | Keeps the finding | +| --- | --- | --- | +| OpenVEX `status` | `not_affected`, `fixed` | `affected`, `under_investigation` | +| CycloneDX `analysis.state` | `not_affected`, `false_positive`, `resolved`, `resolved_with_pedigree` | `exploitable`, `in_triage` | + +A CycloneDX vulnerability with no `analysis` is ignored. + +## Matching a statement to a finding + +A statement matches a finding when one of its ids matches one of the finding's ids, without regard to case. + +- OpenVEX ids are `vulnerability.name`, `vulnerability.@id`, and `vulnerability.aliases`. The older form, where `vulnerability` is a plain string, also works. +- CycloneDX ids are the vulnerability `id` and its `references[].id`. +- Finding ids are the Grype vulnerability id plus `relatedVulnerabilities`, the CycloneDX id plus its references, Trivy's `VulnerabilityID` plus `VendorIDs`, and the osv-scanner id plus its aliases. + +A statement can also name packages, as package URLs (purls): + +- OpenVEX: the `subcomponents` of each product, or the older statement-level `subcomponents`. Each one is an `@id` or `identifiers.purl`. +- CycloneDX: the `affects[].ref` entries. A ref is looked up in the document's components to find its purl. A ref that is already a purl is used as-is. + +When a statement names packages, it matches only findings in one of them. The purl type, namespace, and name have to be equal. The version has to be equal too when the statement's purl has one. Qualifiers such as `?arch=amd64` and subpaths are ignored. When a statement names no packages, or the finding has no purl, the id alone decides. + +gatecheck does not check the OpenVEX product itself, such as `pkg:oci/app@sha256:...`. It does not know which product the report was made from. Keep one VEX file per product, and pass the one that goes with the report. + +Finding purls come from Grype `artifact.purl`, the CycloneDX component for each `affects` ref, and Trivy `PkgIdentifier.PURL`. For osv-scanner they are built from the ecosystem, name, and version, for Go, npm, PyPI, crates.io, Maven, RubyGems, NuGet, Packagist, Pub, and Hex. A CycloneDX vulnerability that affects several packages is skipped only when every one of them is covered. + +When several statements match a finding, the one with the latest timestamp decides. The timestamp is `last_updated` or `timestamp` on the statement, then on the document. For CycloneDX it is `analysis.lastUpdated`, then `updated`, `analysis.firstIssued`, `published`, and `metadata.timestamp`. Ties go to the statement read last. An `affected` statement dated after a `not_affected` one puts the finding back. + +## Where VEX runs in validation + +VEX runs right after the CVE deny list and alongside `cveRiskAcceptance`. See [Validation](./validation.md). + +- A `cveLimit` deny list entry still fails the report, even when a VEX file says the CVE is not exploitable. +- A finding that VEX skips is not counted by the KEV limit, the EPSS rules, or the severity limits. + +Each skipped finding is logged at info level with its id, the VEX status, the justification, and the file it came from. diff --git a/pkg/artifacts/cyclonedx.go b/pkg/artifacts/cyclonedx.go index 60f1210..a5e12d8 100644 --- a/pkg/artifacts/cyclonedx.go +++ b/pkg/artifacts/cyclonedx.go @@ -20,6 +20,27 @@ type CyclonedxComponent struct { BOMRef string `json:"bom-ref"` Name string `json:"name"` Version string `json:"version"` + PURL string `json:"purl"` +} + +// AffectedPURLs returns the package URLs of the components a vulnerability +// affects. A ref that is itself a package URL is returned as-is. +func (r CyclonedxReportMin) AffectedPURLs(v CyclonedxVulnerability) []string { + var out []string + for _, affected := range v.Affects { + found := false + for _, component := range r.Components { + if component.BOMRef == affected.Ref && component.PURL != "" { + out = append(out, component.PURL) + found = true + break + } + } + if !found && strings.HasPrefix(affected.Ref, "pkg:") { + out = append(out, affected.Ref) + } + } + return out } type CyclonedxVulnerability struct { diff --git a/pkg/artifacts/grype.go b/pkg/artifacts/grype.go index f1b7ca2..4ce2719 100644 --- a/pkg/artifacts/grype.go +++ b/pkg/artifacts/grype.go @@ -11,8 +11,26 @@ type GrypeReportMin struct { } type GrypeMatch struct { - Artifact GrypeArtifact `json:"artifact"` - Vulnerability GrypeVulnerability `json:"vulnerability"` + Artifact GrypeArtifact `json:"artifact"` + Vulnerability GrypeVulnerability `json:"vulnerability"` + RelatedVulnerabilities []GrypeRelatedVulnerability `json:"relatedVulnerabilities"` +} + +// GrypeRelatedVulnerability is another id for the same vulnerability, such as +// the CVE behind a GHSA. +type GrypeRelatedVulnerability struct { + ID string `json:"id"` +} + +// IDs returns the vulnerability id followed by related ids. +func (m GrypeMatch) IDs() []string { + ids := []string{m.Vulnerability.ID} + for _, related := range m.RelatedVulnerabilities { + if related.ID != "" && !containsFold(ids, related.ID) { + ids = append(ids, related.ID) + } + } + return ids } type GrypeDescriptor struct { @@ -23,6 +41,7 @@ type GrypeDescriptor struct { type GrypeArtifact struct { Name string `json:"name"` Version string `json:"version"` + PURL string `json:"purl"` } type GrypeVulnerability struct { diff --git a/pkg/artifacts/osv.go b/pkg/artifacts/osv.go index 8a027e2..2f303eb 100644 --- a/pkg/artifacts/osv.go +++ b/pkg/artifacts/osv.go @@ -66,6 +66,42 @@ type OSVFinding struct { Package string Version string Link string + // PURL is built from the ecosystem, name, and version. It is empty for an + // ecosystem with no package URL type here. + PURL string +} + +var osvPURLTypes = map[string]string{ + "go": "golang", + "npm": "npm", + "pypi": "pypi", + "crates.io": "cargo", + "maven": "maven", + "rubygems": "gem", + "nuget": "nuget", + "packagist": "composer", + "pub": "pub", + "hex": "hex", +} + +// osvPURL builds a package URL for an osv-scanner package. +func osvPURL(info OSVPackageInfo) string { + purlType, ok := osvPURLTypes[strings.ToLower(info.Ecosystem)] + if !ok || info.Name == "" { + return "" + } + name := info.Name + if purlType == "maven" { + name = strings.Replace(name, ":", "/", 1) + } + if purlType == "pypi" { + name = strings.ToLower(strings.ReplaceAll(name, "_", "-")) + } + purl := "pkg:" + purlType + "/" + name + if info.Version != "" { + purl += "@" + info.Version + } + return purl } // Findings returns one entry per vulnerability group. @@ -143,6 +179,7 @@ func findingFromGroup(pkg OSVPackage, group OSVGroup) (OSVFinding, bool) { Package: pkg.Package.Name, Version: pkg.Package.Version, Link: osvLink(ids[0]), + PURL: osvPURL(pkg.Package), }, true } @@ -159,6 +196,7 @@ func findingFromVuln(pkg OSVPackage, vuln OSVVulnerability) OSVFinding { Package: pkg.Package.Name, Version: pkg.Package.Version, Link: link, + PURL: osvPURL(pkg.Package), } } diff --git a/pkg/artifacts/trivy.go b/pkg/artifacts/trivy.go index ae5fc7c..17b7227 100644 --- a/pkg/artifacts/trivy.go +++ b/pkg/artifacts/trivy.go @@ -29,7 +29,10 @@ type TrivyVulnerability struct { Severity string `json:"Severity"` Title string `json:"Title"` PrimaryURL string `json:"PrimaryURL"` - DataSource *struct { + PkgIdentifier struct { + PURL string `json:"PURL"` + } `json:"PkgIdentifier"` + DataSource *struct { ID string `json:"ID"` Name string `json:"Name"` URL string `json:"URL"` @@ -43,6 +46,7 @@ type TrivyFinding struct { Package string Version string Link string + PURL string } // Findings returns package vulnerabilities. Other Trivy result classes are skipped. @@ -76,6 +80,7 @@ func (r *TrivyReportMin) Findings() []TrivyFinding { Package: vuln.PkgName, Version: vuln.InstalledVersion, Link: link, + PURL: vuln.PkgIdentifier.PURL, }) } } diff --git a/pkg/gatecheck/config.go b/pkg/gatecheck/config.go index 5062291..0fd832e 100644 --- a/pkg/gatecheck/config.go +++ b/pkg/gatecheck/config.go @@ -11,6 +11,7 @@ import ( "path" "github.com/gatecheckdev/gatecheck/pkg/format" + "github.com/gatecheckdev/gatecheck/pkg/vex" "github.com/pelletier/go-toml/v2" "github.com/spf13/viper" "gopkg.in/yaml.v3" @@ -32,6 +33,9 @@ type Config struct { Gitleaks configGitleaksReport `json:"gitleaks" toml:"gitleaks" yaml:"gitleaks"` Sarif configSarifReport `json:"sarif" toml:"sarif" yaml:"sarif"` Coverage configCoverageReport `json:"coverage" toml:"coverage" yaml:"coverage"` + VEX configVEX `json:"vex" toml:"vex" yaml:"vex"` + + vexDoc *vex.Document } func (c *Config) String() string { @@ -243,6 +247,7 @@ func NewDefaultConfig() *Config { FunctionThreshold: 0, BranchThreshold: 0, }, + VEX: configVEX{Files: []string{}}, } } diff --git a/pkg/gatecheck/download.go b/pkg/gatecheck/download.go index d5d9cc0..ce37dc0 100644 --- a/pkg/gatecheck/download.go +++ b/pkg/gatecheck/download.go @@ -24,6 +24,8 @@ type fetchOptions struct { epssCacheOn bool epssCacheDir string epssCacheDirSet bool + + vexFiles []string } func defaultOptions() *fetchOptions { diff --git a/pkg/gatecheck/osv.go b/pkg/gatecheck/osv.go index ceec16b..a544cd1 100644 --- a/pkg/gatecheck/osv.go +++ b/pkg/gatecheck/osv.go @@ -105,6 +105,7 @@ func validateOSVRules(config *Config, findings []artifacts.OSVFinding, catalog * } findings = removeIgnoredOSVSeverities(config, findings, data) findings = ruleOSVCVEAllow(config, findings) + findings = ruleOSVVEX(config, findings) if !ruleOSVKEVLimit(config, findings, catalog) { return newValidationErr("osv-scanner: CVE matched to KEV Catalog") } diff --git a/pkg/gatecheck/trivy.go b/pkg/gatecheck/trivy.go index 0c5fa87..bc2f5e4 100644 --- a/pkg/gatecheck/trivy.go +++ b/pkg/gatecheck/trivy.go @@ -106,6 +106,7 @@ func validateTrivyRules(config *Config, findings []artifacts.TrivyFinding, catal } findings = removeIgnoredTrivySeverities(config, findings, data) findings = ruleTrivyCVEAllow(config, findings) + findings = ruleTrivyVEX(config, findings) if !ruleTrivyKEVLimit(config, findings, catalog) { return newValidationErr("Trivy: CVE matched to KEV Catalog") } diff --git a/pkg/gatecheck/validate.go b/pkg/gatecheck/validate.go index 487655a..941888a 100644 --- a/pkg/gatecheck/validate.go +++ b/pkg/gatecheck/validate.go @@ -36,6 +36,15 @@ func Validate(config *Config, reportSrc io.Reader, targetFilename string, option if err != nil { return err } + vexDoc, err := loadVEX(config, options) + if err != nil { + return err + } + if vexDoc != nil { + withVEX := *config + withVEX.vexDoc = vexDoc + config = &withVEX + } kind := resolveKind(content, targetFilename, false) reportSrc = bytes.NewReader(content) slog.Debug("validate", "filename", targetFilename, "filetype", kind) @@ -836,8 +845,9 @@ func validateGrypeRules(config *Config, report *artifacts.GrypeReportMin, catalo // Ignore any CVEs that don't meet the vulnerability threshold or the EPPS threshold removeIgnoredSeverityCVEs(config, report, data) - // 2. CVE Allowance - remove from matches + // 2. CVE Allowance and VEX - remove from matches ruleGrypeCVEAllow(config, report) + ruleGrypeVEX(config, report) // 3. KEV Catalog Limit - fail matching if !ruleGrypeKEVLimit(config, report, catalog) { @@ -866,8 +876,9 @@ func validateCyclonedxRules(config *Config, report *artifacts.CyclonedxReportMin return newValidationErr("CycloneDx: CVE explicitly denied") } - // 2. CVE Allowance - remove from matches + // 2. CVE Allowance and VEX - remove from matches ruleCyclonedxCVEAllow(config, report) + ruleCyclonedxVEX(config, report) // 3. KEV Catalog Limit - fail matching if !ruleCyclonedxKEVLimit(config, report, catalog) { diff --git a/pkg/gatecheck/vex.go b/pkg/gatecheck/vex.go new file mode 100644 index 0000000..79e6364 --- /dev/null +++ b/pkg/gatecheck/vex.go @@ -0,0 +1,108 @@ +package gatecheck + +import ( + "log/slog" + "slices" + + "github.com/gatecheckdev/gatecheck/pkg/artifacts" + "github.com/gatecheckdev/gatecheck/pkg/vex" +) + +type configVEX struct { + // Files are OpenVEX or CycloneDX VEX documents. Relative paths are read + // from the working directory. + Files []string `json:"files" toml:"files" yaml:"files"` +} + +// WithVEXFiles adds VEX documents to the ones listed in the config. +func WithVEXFiles(filenames ...string) optionFunc { + return func(o *fetchOptions) { + o.vexFiles = append(o.vexFiles, filenames...) + } +} + +// loadVEX reads the config's VEX files and the ones passed as options. +func loadVEX(config *Config, options *fetchOptions) (*vex.Document, error) { + files := append(slices.Clone(config.VEX.Files), options.vexFiles...) + if len(files) == 0 { + return nil, nil + } + doc, err := vex.Load(files...) + if err != nil { + return nil, err + } + slog.Info("loaded vex statements", "files", len(files), "statements", doc.Len()) + return doc, nil +} + +// vexSuppressed logs and reports whether doc marks a finding not exploitable. +func vexSuppressed(doc *vex.Document, artifact string, f vex.Finding, severity string) bool { + if doc == nil { + return false + } + s, ok := doc.Suppressed(f) + if !ok { + return false + } + slog.Info("vex: not exploitable, removing from subsequent rules", + "artifact", artifact, + "id", f.IDs[0], + "severity", severity, + "status", s.Status, + "justification", s.Justification, + "source", s.Source, + ) + return true +} + +func ruleGrypeVEX(config *Config, report *artifacts.GrypeReportMin) { + if config.vexDoc == nil { + return + } + report.Matches = slices.DeleteFunc(report.Matches, func(m artifacts.GrypeMatch) bool { + return vexSuppressed(config.vexDoc, "grype", vex.Finding{IDs: m.IDs(), PURL: m.Artifact.PURL}, m.Vulnerability.Severity) + }) +} + +func ruleCyclonedxVEX(config *Config, report *artifacts.CyclonedxReportMin) { + if config.vexDoc == nil { + return + } + report.Vulnerabilities = slices.DeleteFunc(report.Vulnerabilities, func(v artifacts.CyclonedxVulnerability) bool { + ids := []string{v.Identity()} + for _, ref := range v.References { + if ref.ID != "" { + ids = append(ids, ref.ID) + } + } + purls := report.AffectedPURLs(v) + if len(purls) == 0 { + purls = []string{""} + } + // The vulnerability is suppressed only when every affected package is. + for _, purl := range purls[1:] { + if _, ok := config.vexDoc.Suppressed(vex.Finding{IDs: ids, PURL: purl}); !ok { + return false + } + } + return vexSuppressed(config.vexDoc, "cyclonedx", vex.Finding{IDs: ids, PURL: purls[0]}, v.HighestSeverity()) + }) +} + +func ruleTrivyVEX(config *Config, findings []artifacts.TrivyFinding) []artifacts.TrivyFinding { + if config.vexDoc == nil { + return findings + } + return slices.DeleteFunc(findings, func(f artifacts.TrivyFinding) bool { + return vexSuppressed(config.vexDoc, "trivy", vex.Finding{IDs: f.IDs, PURL: f.PURL}, f.Severity) + }) +} + +func ruleOSVVEX(config *Config, findings []artifacts.OSVFinding) []artifacts.OSVFinding { + if config.vexDoc == nil { + return findings + } + return slices.DeleteFunc(findings, func(f artifacts.OSVFinding) bool { + return vexSuppressed(config.vexDoc, "osv-scanner", vex.Finding{IDs: f.IDs, PURL: f.PURL}, f.Severity) + }) +} diff --git a/pkg/gatecheck/vex_test.go b/pkg/gatecheck/vex_test.go new file mode 100644 index 0000000..676b104 --- /dev/null +++ b/pkg/gatecheck/vex_test.go @@ -0,0 +1,187 @@ +package gatecheck + +import ( + "bytes" + "errors" + "os" + "path/filepath" + "slices" + "testing" + + "github.com/gatecheckdev/gatecheck/pkg/archive" + "github.com/gatecheckdev/gatecheck/pkg/artifacts" + "github.com/gatecheckdev/gatecheck/pkg/vex" +) + +// grypeCriticals are the critical matches in test/grype-report.json, as +// vulnerability id and package URL. +var grypeCriticals = [][2]string{ + {"GHSA-2jcg-qqmg-46q6", "pkg:npm/monorepo-symlink-test@0.0.0"}, + {"GHSA-5mrr-rgp6-x4gr", "pkg:npm/marsdb@0.6.11"}, + {"CVE-2015-9235", "pkg:npm/jsonwebtoken"}, + {"CVE-2023-37466", "pkg:npm/vm2@3.9.17"}, + {"GHSA-g644-9gfx-q4q4", "pkg:npm/vm2@3.9.17"}, + {"CVE-2019-10744", "pkg:npm/lodash@2.4.2"}, + {"CVE-2023-32314", "pkg:npm/vm2@3.9.17"}, +} + +func writeOpenVEX(t *testing.T, pairs [][2]string, status string) string { + t.Helper() + var buf bytes.Buffer + buf.WriteString(`{"@context":"https://openvex.dev/ns/v0.2.0","statements":[`) + for i, p := range pairs { + if i > 0 { + buf.WriteString(",") + } + buf.WriteString(`{"vulnerability":{"name":"` + p[0] + `"},"products":[{"@id":"pkg:oci/app","subcomponents":[{"@id":"` + p[1] + `"}]}],"status":"` + status + `","justification":"vulnerable_code_not_present"}`) + } + buf.WriteString(`]}`) + name := filepath.Join(t.TempDir(), "app.openvex.json") + if err := os.WriteFile(name, buf.Bytes(), 0o600); err != nil { + t.Fatal(err) + } + return name +} + +func criticalLimitConfig() *Config { + config := NewDefaultConfig() + config.Grype.SeverityLimit.Critical = configLimit{Enabled: true, Limit: 0} + config.Trivy.SeverityLimit.Critical = configLimit{Enabled: true, Limit: 0} + config.OSVScanner.SeverityLimit.Critical = configLimit{Enabled: true, Limit: 0} + config.OSVScanner.SeverityLimit.High = configLimit{Enabled: true, Limit: 0} + config.OSVScanner.SeverityLimit.Medium = configLimit{Enabled: true, Limit: 0} + config.OSVScanner.SeverityLimit.Low = configLimit{Enabled: true, Limit: 0} + return config +} + +func validateFile(t *testing.T, config *Config, filename string, opts ...Option) error { + t.Helper() + f, err := os.Open(filename) + if err != nil { + t.Fatal(err) + } + defer func() { _ = f.Close() }() + return Validate(config, f, filename, opts...) +} + +func TestValidateGrypeWithVEX(t *testing.T) { + report := "../../test/grype-report.json" + if err := validateFile(t, criticalLimitConfig(), report); !errors.Is(err, ErrValidationFailure) { + t.Fatalf("without vex: %v", err) + } + + all := writeOpenVEX(t, grypeCriticals, "not_affected") + if err := validateFile(t, criticalLimitConfig(), report, WithVEXFiles(all)); err != nil { + t.Fatalf("with vex flag: %v", err) + } + + config := criticalLimitConfig() + config.VEX.Files = []string{all} + if err := validateFile(t, config, report); err != nil { + t.Fatalf("with vex config: %v", err) + } + + partial := writeOpenVEX(t, grypeCriticals[1:], "not_affected") + if err := validateFile(t, criticalLimitConfig(), report, WithVEXFiles(partial)); !errors.Is(err, ErrValidationFailure) { + t.Fatalf("partial vex should still fail: %v", err) + } + + affected := writeOpenVEX(t, grypeCriticals, "affected") + if err := validateFile(t, criticalLimitConfig(), report, WithVEXFiles(affected)); !errors.Is(err, ErrValidationFailure) { + t.Fatalf("affected status should not suppress: %v", err) + } + + wrongPkg := writeOpenVEX(t, [][2]string{{"CVE-2019-10744", "pkg:npm/lodash@9.9.9"}}, "not_affected") + cfg := NewDefaultConfig() + cfg.Grype.CVELimit = configCVELimit{Enabled: true, CVEs: []configCVE{{ID: "GHSA-jf85-cpcp-j695"}}} + if err := validateFile(t, cfg, report, WithVEXFiles(wrongPkg)); !errors.Is(err, ErrValidationFailure) { + t.Fatalf("deny list must still fail: %v", err) + } + + if err := validateFile(t, criticalLimitConfig(), report, WithVEXFiles("missing.openvex.json")); err == nil || errors.Is(err, ErrValidationFailure) { + t.Fatalf("missing vex file should be an error, got %v", err) + } +} + +func TestValidateTrivyAndOSVWithVEX(t *testing.T) { + trivy := "../../test/trivy-report.json" + if err := validateFile(t, criticalLimitConfig(), trivy); !errors.Is(err, ErrValidationFailure) { + t.Fatalf("trivy without vex: %v", err) + } + trivyVEX := writeOpenVEX(t, [][2]string{{"CVE-2023-0464", "pkg:generic/openssl"}, {"GHSA-jfh8-c2jp-5v3q", "pkg:maven/x/y"}}, "fixed") + if err := validateFile(t, criticalLimitConfig(), trivy, WithVEXFiles(trivyVEX)); err != nil { + t.Fatalf("trivy with vex: %v", err) + } + + osv := "../../test/osv-scanner-report.json" + if err := validateFile(t, criticalLimitConfig(), osv); !errors.Is(err, ErrValidationFailure) { + t.Fatalf("osv without vex: %v", err) + } + osvVEX := writeOpenVEX(t, [][2]string{ + {"GO-2021-0053", "pkg:golang/github.com/gogo/protobuf@1.3.1"}, + {"GHSA-m5pq-gvj9-9vr8", "pkg:cargo/regex"}, + {"RUSTSEC-2021-0145", "pkg:cargo/ansi_term@0.12.1"}, + }, "not_affected") + if err := validateFile(t, criticalLimitConfig(), osv, WithVEXFiles(osvVEX)); err != nil { + t.Fatalf("osv with vex: %v", err) + } + wrongEcosystem := writeOpenVEX(t, [][2]string{ + {"GO-2021-0053", "pkg:npm/github.com/gogo/protobuf"}, + {"GHSA-m5pq-gvj9-9vr8", "pkg:cargo/regex"}, + {"RUSTSEC-2021-0145", "pkg:cargo/ansi_term"}, + }, "not_affected") + if err := validateFile(t, criticalLimitConfig(), osv, WithVEXFiles(wrongEcosystem)); !errors.Is(err, ErrValidationFailure) { + t.Fatalf("osv vex for another ecosystem should not match: %v", err) + } +} + +func TestValidateBundleWithVEX(t *testing.T) { + content, err := os.ReadFile("../../test/grype-report.json") + if err != nil { + t.Fatal(err) + } + bundle := archive.NewBundle() + if err := bundle.AddFrom(bytes.NewReader(content), "grype-report.json", nil); err != nil { + t.Fatal(err) + } + var buf bytes.Buffer + if _, err := archive.TarGzipBundle(&buf, bundle); err != nil { + t.Fatal(err) + } + raw := buf.Bytes() + if err := Validate(criticalLimitConfig(), bytes.NewReader(raw), "bundle.tar.gz"); !errors.Is(err, ErrValidationFailure) { + t.Fatalf("bundle without vex: %v", err) + } + vexFile := writeOpenVEX(t, grypeCriticals, "not_affected") + if err := Validate(criticalLimitConfig(), bytes.NewReader(raw), "bundle.tar.gz", WithVEXFiles(vexFile)); err != nil { + t.Fatalf("bundle with vex: %v", err) + } +} + +func TestCyclonedxVEXNeedsEveryAffectedPackage(t *testing.T) { + report := &artifacts.CyclonedxReportMin{ + Components: []artifacts.CyclonedxComponent{ + {BOMRef: "login", PURL: "pkg:deb/ubuntu/login@4.8.1?arch=arm64"}, + {BOMRef: "passwd", PURL: "pkg:deb/ubuntu/passwd@4.8.1?arch=arm64"}, + }, + Vulnerabilities: []artifacts.CyclonedxVulnerability{ + {ID: "CVE-2023-29383", Affects: []artifacts.CyclondexAffectedPackage{{Ref: "login"}, {Ref: "passwd"}}}, + }, + } + run := func(pairs [][2]string) int { + doc, err := vex.Load(writeOpenVEX(t, pairs, "not_affected")) + if err != nil { + t.Fatal(err) + } + r := *report + r.Vulnerabilities = slices.Clone(report.Vulnerabilities) + ruleCyclonedxVEX(&Config{vexDoc: doc}, &r) + return len(r.Vulnerabilities) + } + if got := run([][2]string{{"CVE-2023-29383", "pkg:deb/ubuntu/login"}}); got != 1 { + t.Fatalf("one of two packages covered, remaining %d", got) + } + if got := run([][2]string{{"CVE-2023-29383", "pkg:deb/ubuntu/login"}, {"CVE-2023-29383", "pkg:deb/ubuntu/passwd@4.8.1"}}); got != 0 { + t.Fatalf("both packages covered, remaining %d", got) + } +} diff --git a/pkg/vex/vex.go b/pkg/vex/vex.go new file mode 100644 index 0000000..06ca53c --- /dev/null +++ b/pkg/vex/vex.go @@ -0,0 +1,469 @@ +// Package vex reads OpenVEX and CycloneDX VEX documents and decides which +// scanner findings they mark as not exploitable. +package vex + +import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "io" + "net/url" + "os" + "strings" + "time" +) + +// Format is the kind of VEX document. +type Format string + +const ( + FormatOpenVEX Format = "openvex" + FormatCycloneDX Format = "cyclonedx" +) + +// ErrUnknownFormat means the document is neither OpenVEX nor CycloneDX VEX. +var ErrUnknownFormat = errors.New("not an OpenVEX or CycloneDX VEX document") + +// Statement is one VEX claim about one vulnerability. +type Statement struct { + // IDs are the vulnerability id and its aliases. + IDs []string + // Packages are package URLs the statement is limited to. Empty means the + // statement applies to every package with a matching id. + Packages []string + // Status is the status word from the document, such as not_affected or + // false_positive. + Status string + // Justification is the OpenVEX justification or CycloneDX analysis + // justification, when there is one. + Justification string + // Suppress is true when Status means the finding is not exploitable. + Suppress bool + // Source is the file the statement came from. + Source string + Timestamp time.Time +} + +// Document is the merged set of statements from one or more VEX files. +type Document struct { + Statements []Statement +} + +// Finding is the part of a scanner finding VEX matching needs. +type Finding struct { + IDs []string + PURL string +} + +// Load reads and merges VEX files. +func Load(filenames ...string) (*Document, error) { + doc := &Document{} + for _, name := range filenames { + if strings.TrimSpace(name) == "" { + continue + } + f, err := os.Open(name) + if err != nil { + return nil, err + } + part, err := Decode(f, name) + _ = f.Close() + if err != nil { + return nil, fmt.Errorf("vex %s: %w", name, err) + } + doc.Merge(part) + } + return doc, nil +} + +// Decode reads one OpenVEX or CycloneDX VEX document. source names it in logs. +func Decode(r io.Reader, source string) (*Document, error) { + body, err := io.ReadAll(r) + if err != nil { + return nil, err + } + var probe struct { + Context string `json:"@context"` + BOMFormat string `json:"bomFormat"` + Statements json.RawMessage `json:"statements"` + } + if err := json.Unmarshal(body, &probe); err != nil { + return nil, err + } + switch { + case strings.Contains(strings.ToLower(probe.Context), "openvex") || len(probe.Statements) > 0: + return decodeOpenVEX(body, source) + case strings.EqualFold(probe.BOMFormat, "CycloneDX"): + return decodeCycloneDX(body, source) + default: + return nil, ErrUnknownFormat + } +} + +// Merge appends other's statements. Later files win ties on timestamp. +func (d *Document) Merge(other *Document) { + if other == nil { + return + } + d.Statements = append(d.Statements, other.Statements...) +} + +// Len is the number of statements. +func (d *Document) Len() int { + if d == nil { + return 0 + } + return len(d.Statements) +} + +// Match returns the statement that decides f, and whether there is one. +// When several statements match, the one with the latest timestamp wins, and +// the later one in file order breaks ties. A later "affected" statement +// therefore overrides an earlier "not_affected". +func (d *Document) Match(f Finding) (Statement, bool) { + if d == nil { + return Statement{}, false + } + var best Statement + found := false + for _, s := range d.Statements { + if !s.matches(f) { + continue + } + if !found || !s.Timestamp.Before(best.Timestamp) { + best = s + found = true + } + } + return best, found +} + +// Suppressed reports whether the deciding statement for f marks it not exploitable. +func (d *Document) Suppressed(f Finding) (Statement, bool) { + s, ok := d.Match(f) + if !ok || !s.Suppress { + return Statement{}, false + } + return s, true +} + +func (s Statement) matches(f Finding) bool { + idMatch := false + for _, want := range s.IDs { + for _, got := range f.IDs { + if want != "" && strings.EqualFold(want, got) { + idMatch = true + } + } + } + if !idMatch { + return false + } + if len(s.Packages) == 0 || strings.TrimSpace(f.PURL) == "" { + return true + } + for _, p := range s.Packages { + if PURLMatches(p, f.PURL) { + return true + } + } + return false +} + +// PURLMatches compares package URLs by type, namespace, and name. The version +// must also match when want has one. Qualifiers and subpaths are ignored. +func PURLMatches(want, got string) bool { + wb, wv, ok := splitPURL(want) + if !ok { + return false + } + gb, gv, ok := splitPURL(got) + if !ok { + return false + } + if wb != gb { + return false + } + return wv == "" || wv == gv +} + +func splitPURL(p string) (base, version string, ok bool) { + p = strings.TrimSpace(p) + if !strings.HasPrefix(strings.ToLower(p), "pkg:") { + return "", "", false + } + if i := strings.IndexAny(p, "?#"); i >= 0 { + p = p[:i] + } + if i := strings.LastIndex(p, "@"); i > strings.LastIndex(p, "/") { + version = p[i+1:] + p = p[:i] + } + if v, err := url.PathUnescape(version); err == nil { + version = v + } + if b, err := url.PathUnescape(p); err == nil { + p = b + } + parts := strings.SplitN(p[len("pkg:"):], "/", 2) + if len(parts) != 2 || parts[1] == "" { + return "", "", false + } + return strings.ToLower(parts[0]) + "/" + parts[1], version, true +} + +// OpenVEX + +type openVEXDoc struct { + Timestamp string `json:"timestamp"` + LastUpdated string `json:"last_updated"` + Statements []openVEXStatement `json:"statements"` +} + +type openVEXStatement struct { + Vulnerability json.RawMessage `json:"vulnerability"` + Products []json.RawMessage `json:"products"` + Subcomponents []json.RawMessage `json:"subcomponents"` + Status string `json:"status"` + Justification string `json:"justification"` + Timestamp string `json:"timestamp"` + LastUpdated string `json:"last_updated"` +} + +type openVEXVulnerability struct { + ID string `json:"@id"` + Name string `json:"name"` + Aliases []string `json:"aliases"` +} + +type openVEXComponent struct { + ID string `json:"@id"` + Identifiers map[string]string `json:"identifiers"` + Subcomponents []json.RawMessage `json:"subcomponents"` +} + +func decodeOpenVEX(body []byte, source string) (*Document, error) { + var raw openVEXDoc + if err := json.Unmarshal(body, &raw); err != nil { + return nil, err + } + docTime := firstTime(raw.LastUpdated, raw.Timestamp) + doc := &Document{} + for _, st := range raw.Statements { + ids, err := openVEXIDs(st.Vulnerability) + if err != nil { + return nil, err + } + if len(ids) == 0 { + continue + } + var pkgs []string + for _, sub := range st.Subcomponents { + pkgs = append(pkgs, componentPURLs(sub)...) + } + for _, product := range st.Products { + pkgs = append(pkgs, productSubcomponentPURLs(product)...) + } + ts := firstTime(st.LastUpdated, st.Timestamp) + if ts.IsZero() { + ts = docTime + } + status := strings.ToLower(strings.TrimSpace(st.Status)) + doc.Statements = append(doc.Statements, Statement{ + IDs: ids, + Packages: pkgs, + Status: status, + Justification: st.Justification, + Suppress: status == "not_affected" || status == "fixed", + Source: source, + Timestamp: ts, + }) + } + return doc, nil +} + +func openVEXIDs(raw json.RawMessage) ([]string, error) { + if len(bytes.TrimSpace(raw)) == 0 { + return nil, nil + } + var name string + if err := json.Unmarshal(raw, &name); err == nil { + return appendID(nil, name), nil + } + var v openVEXVulnerability + if err := json.Unmarshal(raw, &v); err != nil { + return nil, fmt.Errorf("statement vulnerability: %w", err) + } + ids := appendID(nil, v.Name) + ids = appendID(ids, v.ID) + for _, alias := range v.Aliases { + ids = appendID(ids, alias) + } + return ids, nil +} + +// componentPURLs returns the package URLs that identify one component entry, +// which is either a string or an object with @id and identifiers.purl. +func componentPURLs(raw json.RawMessage) []string { + var id string + if err := json.Unmarshal(raw, &id); err == nil { + return purlOnly(id) + } + var c openVEXComponent + if err := json.Unmarshal(raw, &c); err != nil { + return nil + } + out := purlOnly(c.ID) + out = append(out, purlOnly(c.Identifiers["purl"])...) + return out +} + +// productSubcomponentPURLs returns the package URLs of a product's +// subcomponents. The product itself is what was scanned, such as an image, so +// it does not narrow which findings match. +func productSubcomponentPURLs(raw json.RawMessage) []string { + var c openVEXComponent + if err := json.Unmarshal(raw, &c); err != nil { + return nil + } + var out []string + for _, sub := range c.Subcomponents { + out = append(out, componentPURLs(sub)...) + } + return out +} + +// CycloneDX + +type cdxDoc struct { + Metadata struct { + Timestamp string `json:"timestamp"` + } `json:"metadata"` + Components []cdxComponent `json:"components"` + Vulnerabilities []struct { + ID string `json:"id"` + References []struct { + ID string `json:"id"` + } `json:"references"` + Analysis *struct { + State string `json:"state"` + Justification string `json:"justification"` + LastUpdated string `json:"lastUpdated"` + FirstIssued string `json:"firstIssued"` + } `json:"analysis"` + Affects []struct { + Ref string `json:"ref"` + } `json:"affects"` + Updated string `json:"updated"` + Published string `json:"published"` + } `json:"vulnerabilities"` +} + +type cdxComponent struct { + BOMRef string `json:"bom-ref"` + PURL string `json:"purl"` + Components []cdxComponent `json:"components"` +} + +func decodeCycloneDX(body []byte, source string) (*Document, error) { + var raw cdxDoc + if err := json.Unmarshal(body, &raw); err != nil { + return nil, err + } + refs := map[string]string{} + var walk func([]cdxComponent) + walk = func(components []cdxComponent) { + for _, c := range components { + if c.BOMRef != "" && c.PURL != "" { + refs[c.BOMRef] = c.PURL + } + walk(c.Components) + } + } + walk(raw.Components) + + docTime := firstTime(raw.Metadata.Timestamp) + doc := &Document{} + for _, v := range raw.Vulnerabilities { + if v.Analysis == nil || strings.TrimSpace(v.Analysis.State) == "" { + continue + } + ids := appendID(nil, v.ID) + for _, ref := range v.References { + ids = appendID(ids, ref.ID) + } + if len(ids) == 0 { + continue + } + var pkgs []string + for _, a := range v.Affects { + if p, ok := refs[a.Ref]; ok { + pkgs = append(pkgs, p) + continue + } + pkgs = append(pkgs, purlOnly(a.Ref)...) + } + ts := firstTime(v.Analysis.LastUpdated, v.Updated, v.Analysis.FirstIssued, v.Published) + if ts.IsZero() { + ts = docTime + } + state := strings.ToLower(strings.TrimSpace(v.Analysis.State)) + doc.Statements = append(doc.Statements, Statement{ + IDs: ids, + Packages: pkgs, + Status: state, + Justification: v.Analysis.Justification, + Suppress: cdxSuppresses(state), + Source: source, + Timestamp: ts, + }) + } + return doc, nil +} + +func cdxSuppresses(state string) bool { + switch state { + case "not_affected", "false_positive", "resolved", "resolved_with_pedigree": + return true + default: + return false + } +} + +func purlOnly(id string) []string { + id = strings.TrimSpace(id) + if strings.HasPrefix(strings.ToLower(id), "pkg:") { + return []string{id} + } + return nil +} + +func appendID(ids []string, id string) []string { + id = strings.TrimSpace(id) + if id == "" { + return ids + } + for _, got := range ids { + if strings.EqualFold(got, id) { + return ids + } + } + return append(ids, id) +} + +func firstTime(values ...string) time.Time { + for _, v := range values { + v = strings.TrimSpace(v) + if v == "" { + continue + } + if t, err := time.Parse(time.RFC3339Nano, v); err == nil { + return t + } + if t, err := time.Parse("2006-01-02", v); err == nil { + return t + } + } + return time.Time{} +} diff --git a/pkg/vex/vex_test.go b/pkg/vex/vex_test.go new file mode 100644 index 0000000..5c53e41 --- /dev/null +++ b/pkg/vex/vex_test.go @@ -0,0 +1,192 @@ +package vex + +import ( + "os" + "path/filepath" + "strings" + "testing" +) + +const openVEXSample = `{ + "@context": "https://openvex.dev/ns/v0.2.0", + "@id": "https://example.com/vex/1", + "author": "ada", + "timestamp": "2026-10-01T00:00:00Z", + "version": 1, + "statements": [ + { + "vulnerability": {"name": "CVE-2026-0001", "aliases": ["GHSA-aaaa-bbbb-cccc"]}, + "products": [ + {"@id": "pkg:oci/app@sha256:abc", "subcomponents": [{"@id": "pkg:golang/example.com/lib@v1.2.3"}]} + ], + "status": "not_affected", + "justification": "vulnerable_code_not_in_execute_path" + }, + { + "vulnerability": {"name": "CVE-2026-0002"}, + "products": [{"@id": "pkg:oci/app"}], + "status": "fixed" + }, + { + "vulnerability": {"name": "CVE-2026-0003"}, + "products": [{"@id": "pkg:oci/app"}], + "status": "under_investigation" + }, + { + "vulnerability": {"name": "CVE-2026-0004"}, + "products": [{"@id": "pkg:oci/app"}], + "status": "not_affected", + "justification": "component_not_present", + "timestamp": "2026-10-01T00:00:00Z" + }, + { + "vulnerability": {"name": "CVE-2026-0004"}, + "products": [{"@id": "pkg:oci/app"}], + "status": "affected", + "action_statement": "upgrade", + "timestamp": "2026-10-05T00:00:00Z" + } + ] +}` + +const openVEXLegacy = `{ + "@context": "https://openvex.dev/ns", + "statements": [ + {"vulnerability": "CVE-2026-0009", "products": ["pkg:npm/left-pad@1.0.0"], "subcomponents": ["pkg:npm/left-pad@1.0.0"], "status": "not_affected"} + ] +}` + +const cdxVEX = `{ + "bomFormat": "CycloneDX", + "specVersion": "1.5", + "components": [{"bom-ref": "lib-1", "name": "lib", "purl": "pkg:pypi/requests@2.31.0"}], + "vulnerabilities": [ + {"id": "CVE-2026-0100", "analysis": {"state": "not_affected", "justification": "code_not_reachable"}, "affects": [{"ref": "lib-1"}]}, + {"id": "CVE-2026-0101", "analysis": {"state": "false_positive"}, "affects": [{"ref": "pkg:pypi/urllib3@2.0.0"}]}, + {"id": "CVE-2026-0102", "analysis": {"state": "exploitable"}}, + {"id": "CVE-2026-0103", "analysis": {"state": "resolved"}}, + {"id": "CVE-2026-0104"} + ] +}` + +func decode(t *testing.T, body string) *Document { + t.Helper() + doc, err := Decode(strings.NewReader(body), "test.json") + if err != nil { + t.Fatal(err) + } + return doc +} + +func TestOpenVEX(t *testing.T) { + doc := decode(t, openVEXSample) + cases := []struct { + name string + f Finding + want bool + }{ + {"subcomponent match", Finding{IDs: []string{"CVE-2026-0001"}, PURL: "pkg:golang/example.com/lib@v1.2.3"}, true}, + {"alias match", Finding{IDs: []string{"GHSA-AAAA-BBBB-CCCC"}, PURL: "pkg:golang/example.com/lib@v1.2.3"}, true}, + {"other package", Finding{IDs: []string{"CVE-2026-0001"}, PURL: "pkg:golang/example.com/other@v1.2.3"}, false}, + {"other version", Finding{IDs: []string{"CVE-2026-0001"}, PURL: "pkg:golang/example.com/lib@v1.2.4"}, false}, + {"no purl on finding", Finding{IDs: []string{"CVE-2026-0001"}}, true}, + {"fixed, product only", Finding{IDs: []string{"cve-2026-0002"}, PURL: "pkg:deb/debian/openssl@3"}, true}, + {"under investigation", Finding{IDs: []string{"CVE-2026-0003"}}, false}, + {"later affected wins", Finding{IDs: []string{"CVE-2026-0004"}}, false}, + {"unknown id", Finding{IDs: []string{"CVE-1999-0001"}}, false}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + _, got := doc.Suppressed(tc.f) + if got != tc.want { + t.Fatalf("suppressed=%v want %v", got, tc.want) + } + }) + } + s, _ := doc.Suppressed(Finding{IDs: []string{"CVE-2026-0001"}}) + if s.Justification != "vulnerable_code_not_in_execute_path" || s.Source != "test.json" { + t.Fatalf("statement %+v", s) + } +} + +func TestOpenVEXLegacyStrings(t *testing.T) { + doc := decode(t, openVEXLegacy) + if _, ok := doc.Suppressed(Finding{IDs: []string{"CVE-2026-0009"}, PURL: "pkg:npm/left-pad@1.0.0"}); !ok { + t.Fatal("legacy statement should match") + } + if _, ok := doc.Suppressed(Finding{IDs: []string{"CVE-2026-0009"}, PURL: "pkg:npm/left-pad@2.0.0"}); ok { + t.Fatal("other version should not match") + } +} + +func TestCycloneDXVEX(t *testing.T) { + doc := decode(t, cdxVEX) + if doc.Len() != 4 { + t.Fatalf("statements %d", doc.Len()) + } + cases := []struct { + f Finding + want bool + }{ + {Finding{IDs: []string{"CVE-2026-0100"}, PURL: "pkg:pypi/requests@2.31.0"}, true}, + {Finding{IDs: []string{"CVE-2026-0100"}, PURL: "pkg:pypi/flask@2.31.0"}, false}, + {Finding{IDs: []string{"CVE-2026-0101"}, PURL: "pkg:pypi/urllib3@2.0.0?arch=x"}, true}, + {Finding{IDs: []string{"CVE-2026-0102"}}, false}, + {Finding{IDs: []string{"CVE-2026-0103"}}, true}, + {Finding{IDs: []string{"CVE-2026-0104"}}, false}, + } + for _, tc := range cases { + if _, got := doc.Suppressed(tc.f); got != tc.want { + t.Errorf("%v suppressed=%v want %v", tc.f, got, tc.want) + } + } +} + +func TestLoadMergesFiles(t *testing.T) { + dir := t.TempDir() + a := filepath.Join(dir, "a.openvex.json") + b := filepath.Join(dir, "b.cdx.json") + if err := os.WriteFile(a, []byte(openVEXSample), 0o600); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(b, []byte(cdxVEX), 0o600); err != nil { + t.Fatal(err) + } + doc, err := Load(a, "", b) + if err != nil { + t.Fatal(err) + } + if doc.Len() != 9 { + t.Fatalf("statements %d", doc.Len()) + } + if _, err := Load(filepath.Join(dir, "missing.json")); err == nil { + t.Fatal("missing file should fail") + } + bad := filepath.Join(dir, "bad.json") + if err := os.WriteFile(bad, []byte(`{"matches": []}`), 0o600); err != nil { + t.Fatal(err) + } + if _, err := Load(bad); err == nil || !strings.Contains(err.Error(), ErrUnknownFormat.Error()) { + t.Fatalf("unknown format error %v", err) + } +} + +func TestPURLMatches(t *testing.T) { + cases := []struct { + want, got string + ok bool + }{ + {"pkg:npm/%40scope/name@1.0.0", "pkg:npm/@scope/name@1.0.0", true}, + {"pkg:npm/@scope/name", "pkg:npm/@scope/name@9.9.9", true}, + {"PKG:NPM/name", "pkg:npm/name@1", true}, + {"pkg:npm/name@1", "pkg:npm/name@2", false}, + {"pkg:npm/name", "pkg:pypi/name", false}, + {"pkg:golang/a/b@v1#sub", "pkg:golang/a/b@v1?x=y", true}, + {"not-a-purl", "pkg:npm/name", false}, + } + for _, tc := range cases { + if got := PURLMatches(tc.want, tc.got); got != tc.ok { + t.Errorf("PURLMatches(%q, %q) = %v", tc.want, tc.got, got) + } + } +} diff --git a/website/llms-full.txt b/website/llms-full.txt index f60b43a..af31791 100644 --- a/website/llms-full.txt +++ b/website/llms-full.txt @@ -181,6 +181,8 @@ Opening the report, the config, and any `--epss-filename` or `--kev-filename` ha `--epss-filename` is the EPSS CSV used when an EPSS rule is enabled. `--kev-filename` is the CISA KEV JSON used when `kevLimitEnabled` is true. `--epss-cache-dir` and `--epss-no-cache` apply when that CSV is downloaded. `validate` has no `--epss-url` or `--kev-url` flag. `GATECHECK_EPSS_URL` and `GATECHECK_KEV_URL` still override those APIs when the matching file is not set. The defaults are the same URLs `download` uses. +`--vex FILE` (repeatable), `GATECHECK_VEX` (comma-separated, used when the flag is absent), and the config's `vex.files` name OpenVEX or CycloneDX VEX documents. Grype, CycloneDX, Trivy, and osv-scanner findings that a VEX file marks `not_affected` or `fixed` (OpenVEX), or `not_affected`, `false_positive`, `resolved`, or `resolved_with_pedigree` (CycloneDX `analysis.state`), are removed right after the `cveLimit` deny list, so they skip the KEV, EPSS, and severity rules. Ids match the finding's id or aliases. A statement that lists subcomponents or `affects` refs matches only those package URLs. The OpenVEX product itself is not checked. When several statements match, the latest timestamp wins. + EPSS data is loaded only when an EPSS limit or EPSS risk acceptance rule is enabled. KEV data is loaded only when `kevLimitEnabled` is true for Grype, CycloneDX, Trivy, or osv-scanner. With no local EPSS file, gatecheck downloads the current CSV and caches it until the published date changes. ## list @@ -229,6 +231,7 @@ A non-empty flag wins. An empty flag falls through to the environment variable, | Variable | Commands | Same as | | --- | --- | --- | | `GATECHECK_CONFIG_FILENAME` | `validate` | `--config` | +| `GATECHECK_VEX` | `validate` | `--vex`, comma-separated | | `GATECHECK_EPSS_FILENAME` | `list`, `validate` | `--epss-filename` | | `GATECHECK_EPSS_URL` | `download epss`, `list`, `list-all`, `validate` | `--epss-url` on commands that have that flag | | `GATECHECK_EPSS_CACHE_DIR` | `download epss`, `list`, `list-all`, `validate` | `--epss-cache-dir` | diff --git a/website/llms.txt b/website/llms.txt index 1a2c812..4e7a392 100644 --- a/website/llms.txt +++ b/website/llms.txt @@ -13,6 +13,7 @@ Report type comes from the file contents. The filename is the fallback when the - [Supported reports](https://docs.gatecheck.dev/supported-reports.html): how file contents and filenames select the report type - [Configuration](https://docs.gatecheck.dev/configuration.html): config keys and threshold units - [Validation](https://docs.gatecheck.dev/validation.html): rule order and exit codes +- [VEX](https://docs.gatecheck.dev/vex.html): skip findings an OpenVEX or CycloneDX VEX file marks not exploitable - [List reports](https://docs.gatecheck.dev/list-reports.html): tables, standard input, and EPSS columns - [Bundles](https://docs.gatecheck.dev/gatecheck-bundle.html): create, add, and remove - [Examples](https://docs.gatecheck.dev/examples.html): config, bundle, audit, and standard input From 5d134d828c7ddb0bd625a9dc35277706eda2a97e Mon Sep 17 00:00:00 2001 From: "Bacchus Jackson (BJaX)" <34331871+BacchusJackson@users.noreply.github.com> Date: Wed, 4 Nov 2026 12:27:33 -0600 Subject: [PATCH 2/3] Gate SBOM package licenses The license config section checks Syft JSON and CycloneDX components against deny and allow glob patterns, with SPDX AND, OR, and WITH expressions evaluated. denyUnknown fails packages with no license, and packageRiskAcceptance skips packages by purl or name. Syft JSON now lists its packages and validates with these rules instead of erroring. Fixes #103 --- CHANGELOG.md | 2 + docs/SUMMARY.md | 1 + docs/agent-guide.md | 16 +- docs/bootstrap.md | 2 +- docs/configuration.md | 23 ++ docs/gatecheck-bundle.md | 2 +- docs/licenses.md | 60 +++ docs/supported-reports.md | 6 +- docs/validation.md | 8 +- pkg/artifacts/cyclonedx.go | 4 + pkg/artifacts/syft.go | 84 +++++ pkg/gatecheck/config.go | 4 +- pkg/gatecheck/license.go | 145 ++++++++ pkg/gatecheck/license_test.go | 121 ++++++ pkg/gatecheck/list.go | 3 +- pkg/gatecheck/report_kind_test.go | 11 +- pkg/gatecheck/validate.go | 10 +- pkg/license/license.go | 302 +++++++++++++++ pkg/license/license_test.go | 73 ++++ test/cyclonedx-alpine-sbom.json | 589 ++++++++++++++++++++++++++++++ test/syft-alpine.json | 194 ++++++++++ website/llms-full.txt | 16 +- website/llms.txt | 1 + 23 files changed, 1649 insertions(+), 28 deletions(-) create mode 100644 docs/licenses.md create mode 100644 pkg/artifacts/syft.go create mode 100644 pkg/gatecheck/license.go create mode 100644 pkg/gatecheck/license_test.go create mode 100644 pkg/license/license.go create mode 100644 pkg/license/license_test.go create mode 100644 test/cyclonedx-alpine-sbom.json create mode 100644 test/syft-alpine.json diff --git a/CHANGELOG.md b/CHANGELOG.md index d4bb81a..8d818e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `gatecheck bootstrap --tools gosec,hadolint,zizmor` installs pinned gosec 2.30.0, hadolint 2.15.1, and zizmor 1.32.0. `gatecheck gosec`, `gatecheck hadolint`, and `gatecheck zizmor` run them. Their SARIF output is gated with the `sarif` config section. They are not part of the default install. zizmor publishes no checksum file, so its asset digests are pinned in gatecheck. - `gatecheck bootstrap --list` shows every supported tool. +- The `license` config section fails Syft JSON and CycloneDX SBOMs whose package licenses match `deny` patterns, fall outside a non-empty `allow` list, or are missing when `denyUnknown` is set. SPDX `AND`, `OR`, and `WITH` expressions are evaluated. `packageRiskAcceptance` skips packages by purl or name. Fixes #103. +- `list` prints the packages and licenses in Syft JSON, and `validate` and bundles check Syft JSON with the license rules. Both used to return an error. - `validate --vex FILE`, `GATECHECK_VEX`, and the config's `vex.files` read OpenVEX and CycloneDX VEX documents. Grype, CycloneDX, Trivy, and osv-scanner findings marked `not_affected`, `fixed`, `false_positive`, or `resolved` are skipped before the KEV, EPSS, and severity rules. A statement that names packages matches by package URL. The latest statement wins. Fixes #102. ## [0.10.0] - 2026-10-30 diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 9cdfec3..a06349a 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -10,6 +10,7 @@ - [Gatecheck Bundle](./gatecheck-bundle.md) - [Validation](./validation.md) - [VEX](./vex.md) + - [License gating](./licenses.md) - [Examples](./examples.md) - [Supported Reports](./supported-reports.md) - [Configuration](./configuration.md) diff --git a/docs/agent-guide.md b/docs/agent-guide.md index af31791..dd10da1 100644 --- a/docs/agent-guide.md +++ b/docs/agent-guide.md @@ -54,7 +54,7 @@ The managed binary wins when it is present. `gatecheck grype`, `gatecheck syft`, A platform with no release asset for a requested GitHub-hosted tool fails that tool and the command exits 255. A platform with no semgrep wheel prints a skip message on stderr and continues. Current pins are Grype `0.121.0`, Syft `1.55.0`, Gitleaks `8.30.1`, semgrep `1.182.1`, Trivy `0.76.1`, osv-scanner `2.7.0`, gosec `2.30.0`, hadolint `2.15.1`, and zizmor `1.32.0`, in `internal/bootstrap/versions.go`. -Syft is installed so it can write CycloneDX (`syft -o cyclonedx-json`). That BOM is listed and validated as CycloneDX. Native Syft JSON is recognized from `descriptor.name` or the schema URL, and `list` and `validate` then return an error. A filename containing `syft` does the same when the contents are ambiguous. CycloneDX is a report format, and coverage tools are left to the language toolchain. +Syft is installed so it can write CycloneDX (`syft -o cyclonedx-json`). That BOM is listed and validated as CycloneDX. Native Syft JSON is recognized from `descriptor.name` or the schema URL. `list` prints its packages and licenses, and `validate` runs the license rules on it. CycloneDX is a report format, and coverage tools are left to the language toolchain. ## Report type @@ -66,7 +66,7 @@ Content rules, in this order: 2. `bomFormat` of `CycloneDX` is CycloneDX JSON. This wins when the name contains `grype` or `syft`, and it wins when the tool that wrote the BOM was Grype, Syft, Trivy, or another tool. CycloneDX XML is not read. 3. SARIF 2.1.0. The top-level `version` is the string `2.1.0` and `runs` is an array. A `$schema` that mentions SARIF is enough when `runs` is missing or null. Another version returns an error when the name says `sarif`. 4. Grype JSON. `descriptor.name` is `grype`, or `matches` is a non-empty array of objects with `vulnerability` and `artifact`. -5. Syft JSON. `descriptor.name` is `syft`, or `schema.url` points at the Syft schema. `list` and `validate` then return an error. Syft JSON is not implemented. A Syft CycloneDX BOM is CycloneDX, not Syft. +5. Syft JSON. `descriptor.name` is `syft`, or `schema.url` points at the Syft schema. `list` prints packages and licenses, and `validate` runs the license rules. A Syft CycloneDX BOM is CycloneDX, not Syft. 6. Semgrep JSON. `results` is an array of objects with `check_id`, or `results` and `errors` are both arrays. Semgrep's SARIF output is SARIF, not this type. 7. Gitleaks JSON. A non-empty array of objects with `RuleID` and one of `File`, `Commit`, or `Fingerprint`. 8. Trivy JSON. `SchemaVersion` is a number, and `ArtifactType` is set or `Results` is an array. Vulnerability entries are listed and validated. Misconfigurations, secrets, and licenses are ignored. A CycloneDX BOM from Trivy is CycloneDX. @@ -98,7 +98,7 @@ From standard input, `list` requires `-i` / `--input-type`, so the command does `list-all` lists a file when the contents or the name identify Grype, Semgrep, Gitleaks, Syft, CycloneDX, SARIF, Trivy, osv-scanner, or a bundle. Coverage files are skipped with a warning. There is no `--input-type` on `list-all`. -Inside a bundle, `validate` uses the same content rules on each stored file, and falls back to the label. The label is the base name of the file that was added. Labels that still do not match are skipped. Syft JSON inside a bundle is skipped. +Inside a bundle, `validate` uses the same content rules on each stored file, and falls back to the label. The label is the base name of the file that was added. Labels that still do not match are skipped. Syft JSON inside a bundle is checked with the license rules. ## Config @@ -112,7 +112,7 @@ gatecheck config convert --file gatecheck.yaml --output toml `config convert` reads `-f` / `--file` (default `gatecheck.yaml`). The extension selects the decoder: `.yaml`, `.yml`, `.json`, or `.toml`. -A partial file is fine. Omitted fields keep the default. Unknown keys are ignored. With no config, `validate` uses the built-in default: every rule disabled, coverage thresholds `0`. Grype, CycloneDX, Trivy, osv-scanner, SARIF, Semgrep, Gitleaks, coverage, and bundle reports pass under that default. Syft JSON still returns an error. An old config with no `sarif` section leaves those limits disabled. +A partial file is fine. Omitted fields keep the default. Unknown keys are ignored. With no config, `validate` uses the built-in default: every rule disabled, coverage thresholds `0`. Grype, CycloneDX, Trivy, osv-scanner, SARIF, Semgrep, Gitleaks, coverage, and bundle reports pass under that default. Syft JSON passes too, since the license rules are off by default. An old config with no `sarif` section leaves those limits disabled. `GATECHECK_CONFIG_FILENAME` is the same setting as `validate --config` / `-f`. @@ -135,13 +135,17 @@ Field names below are the ones `config init` emits. In YAML they are case sensit - `severityLimit` has `critical`, `high`, `medium`, and `low`. Each has `enabled` and `limit`, with the same count rule as Grype. The severity comes from the SARIF property `security-severity` when a result or its rule has one. The value is a number from 0 to 10, or a numeric string. 9.0 and above is critical, 7.0 to 8.9 is high, 4.0 to 6.9 is medium, above 0 and below 4.0 is low, and 0 is none. A result property wins over the same property on the rule. When neither is set, gatecheck uses the SARIF level. A missing result level uses the rule's `defaultConfiguration.level`, then `warning`. `error` is high, `warning` is medium, `note` is low, and `none` is ignored. - `ruleLimit` and `ruleRiskAcceptance` each have `enabled` and `rules`. A rule entry is `id` plus an optional `metadata.tags` list. `id` is compared without regard to case. `ruleLimit` denies those ids. `ruleRiskAcceptance` removes them. +`license` gates package licenses in Syft JSON and CycloneDX BOMs. `enabled` turns it on. `deny` and `allow` are case-insensitive glob patterns such as `GPL-*`, which matches `GPL-3.0-only` but not `LGPL-2.1-only`. A non-empty `allow` fails every license outside it. `denyUnknown` fails packages with no license, `NOASSERTION`, or `NONE`. `packageRiskAcceptance` entries skip a package by `purl` (type, namespace, and name, plus version when given) or by `name`. SPDX expressions are evaluated: `OR` passes when either side passes, `AND` needs both, and `X WITH Y` is denied when `X` is denied unless `allow` names the full `X WITH Y`. Several license entries on one package must all pass. Syft licenses are `spdxExpression`, then `value`. CycloneDX licenses are `expression`, `license.id`, then `license.name`, and nested components are included. A CycloneDX BOM runs both the license and vulnerability rules, and reports both failures. + +`vex.files` lists OpenVEX or CycloneDX VEX documents, read along with `--vex`. + `coverage.lineThreshold`, `functionThreshold`, and `branchThreshold` are ratios from 0 to 1: covered lines, functions, or branches divided by the total. The report fails when its ratio is less than the threshold. A ratio equal to the threshold passes. `0.8` is 80 percent. `80` fails a report whose real line coverage is 0.8, because 0.8 is less than 80. There is no `enabled` flag. The default `0` allows any coverage, because a ratio is never less than 0. `list` prints these numbers as percents in the table footer. The config still wants the ratio. A report with no records of a kind, such as LCOV without branch records, has no ratio for it. `list` prints `N/A`, and `validate` skips that threshold with a warning. Grype, CycloneDX, Trivy, and osv-scanner rules run in this order. A failure returns immediately, except where a rule only removes findings. Trivy counts vulnerability entries only. osv-scanner counts one finding per group. 1. CVE limit, when enabled. 2. Disabled Grype, Trivy, and osv-scanner severities are dropped. If the EPSS limit is also enabled, a finding at a disabled severity stays when its EPSS score is greater than or equal to that limit. CycloneDX leaves findings at a disabled severity in the report. -3. CVE risk acceptance removes matching ids. +3. CVE risk acceptance removes matching ids. VEX statements that mark a finding not exploitable remove it here too. 4. KEV limit, when `kevLimitEnabled` is true. 5. EPSS risk acceptance. 6. EPSS limit. @@ -260,6 +264,6 @@ Create the config with `gatecheck config init > gatecheck.yaml` and set real thr - `validate` takes the report as its positional argument. The config is `--config` / `-f`. `gatecheck validate gatecheck.yaml grype-report.json` tries to open the config as a report. `config convert` uses `--file` / `-f`, which is a different flag. - `list` on a pipe needs `--input-type`. Clear contents still win over that flag. `validate` needs a filesystem path. - `list` ignores every filename after the first. Use `list-all` for several files. `list-all` skips coverage files such as `lcov.info`. List those with `gatecheck list lcov.info`. -- Native Syft JSON is recognized and then returns an error. Use CycloneDX output from Syft when you want `validate` to score it. That BOM is CycloneDX even when the filename contains `syft`. +- Native Syft JSON gets only the license rules. Use CycloneDX output when you also want vulnerabilities scored. That BOM is CycloneDX even when the filename contains `syft`. - `gatecheck semgrep --version` reaches osemgrep without `--experimental`, and osemgrep then tries to run `pysemgrep`. Pass the flag: `gatecheck semgrep --experimental --version`. - `--audit` still exits 255 when the report, the config, or a named EPSS or KEV file cannot be opened. diff --git a/docs/bootstrap.md b/docs/bootstrap.md index 94d4d27..6178807 100644 --- a/docs/bootstrap.md +++ b/docs/bootstrap.md @@ -156,7 +156,7 @@ Coverage files (LCOV, Clover, Cobertura) come from the language toolchain. Boots CycloneDX is a report format. Syft writes it with `-o cyclonedx-json`, and Grype can write a CycloneDX vulnerability report. Those are the files `list` and `validate` score. Any other tool's CycloneDX JSON BOM is scored the same way. There is no separate CycloneDX scanner. -Syft's own JSON is still rejected. `list` and `validate` return an error for that document. A filename that contains `syft` does the same when the contents are ambiguous. Syft is installed so it can write CycloneDX. +Syft's own JSON (`-o syft-json`) is a package list. `list` prints its packages and licenses, and `validate` checks them with the license rules. See [License gating](./licenses.md). Syft also writes CycloneDX, which gets the same license rules plus the vulnerability rules when the BOM has vulnerabilities. Trivy JSON (`trivy fs --format json`, `trivy image --format json`, and the other Trivy scanners' JSON output) is a report type. The contents identify it. A filename containing `trivy` is the fallback when the contents are ambiguous. A CycloneDX BOM stays CycloneDX even when the name contains `trivy`. Misconfigurations, secrets, and licenses are ignored. Trivy SARIF is a SARIF report. diff --git a/docs/configuration.md b/docs/configuration.md index 35c3af2..54d2d52 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -180,6 +180,12 @@ coverage: branchThreshold: 0 vex: files: [] +license: + enabled: false + deny: [] + allow: [] + denyUnknown: false + packageRiskAcceptance: [] ``` ## version and metadata @@ -275,6 +281,23 @@ sarif: See [Validation](./validation.md) for which results are counted and the order of the rules. +## License + +`license` gates the package licenses in Syft JSON and CycloneDX BOMs. + +```yaml +license: + enabled: true + deny: [GPL-*, AGPL-*] + allow: [] + denyUnknown: false + packageRiskAcceptance: + - name: busybox + - purl: pkg:apk/alpine/apk-tools +``` + +`deny` and `allow` are case-insensitive glob patterns. A non-empty `allow` fails every license that matches none of its patterns. `denyUnknown` fails packages with no declared license. `packageRiskAcceptance` entries match by `purl`, or by `name` when there is no purl. SPDX expressions with `AND`, `OR`, and `WITH` are evaluated. See [License gating](./licenses.md). + ## Coverage `lineThreshold`, `functionThreshold`, and `branchThreshold` are ratios from 0 to 1: diff --git a/docs/gatecheck-bundle.md b/docs/gatecheck-bundle.md index 2b51a82..97f20f5 100644 --- a/docs/gatecheck-bundle.md +++ b/docs/gatecheck-bundle.md @@ -45,4 +45,4 @@ The table columns are label, digest, tags, and size. gatecheck validate --config gatecheck.yaml gatecheck-bundle.tar.gz ``` -Each stored file is checked on its own with the same rules as a standalone file. Files that do not match a supported type are skipped, including Syft JSON. A Grype failure and a Semgrep failure in the same bundle are both reported, and the command exits 1. +Each stored file is checked on its own with the same rules as a standalone file. Files that do not match a supported type are skipped. Syft JSON is checked with the license rules. A Grype failure and a Semgrep failure in the same bundle are both reported, and the command exits 1. diff --git a/docs/licenses.md b/docs/licenses.md new file mode 100644 index 0000000..0965cec --- /dev/null +++ b/docs/licenses.md @@ -0,0 +1,60 @@ +# License gating + +`validate` can fail an SBOM whose packages use licenses you do not want, such as GPL in a closed-source product, or packages with no license at all. + +License rules read two kinds of report: + +- Syft JSON (`syft -o syft-json` or `syft -o json`). Each `artifacts[]` entry is a package. Its licenses are each `spdxExpression`, or `value` when the expression is empty. Older Syft output, where `licenses` is a list of strings, also works. +- CycloneDX JSON. Each component, including nested `components`, is a package. Its licenses are each `licenses[].expression`, `licenses[].license.id`, or `licenses[].license.name`. + +Bundles check each Syft or CycloneDX file inside them the same way. + +```shell +gatecheck syft dir:. -o syft-json=sbom.syft.json -o cyclonedx-json=sbom.cdx.json +gatecheck validate --config gatecheck.yaml sbom.syft.json +gatecheck list sbom.syft.json +``` + +`gatecheck list` on Syft JSON prints each package with its version, type, and licenses. + +## Config + +```yaml +license: + enabled: true + deny: + - GPL-* + - AGPL-* + allow: [] + denyUnknown: false + packageRiskAcceptance: + - name: busybox + - purl: pkg:apk/alpine/apk-tools + metadata: + tags: + - reviewed 2026-11 +``` + +- `enabled` turns the rules on. With `enabled: false` (the default), Syft JSON and CycloneDX BOMs pass the license rules. +- `deny` lists patterns that fail a license. +- `allow`, when it is not empty, fails every license that matches none of its patterns. Leave it empty to allow everything that is not denied. +- `denyUnknown` fails a package that declares no license, or only `NOASSERTION`, `NONE`, or `UNKNOWN`. With `false`, those packages pass. +- `packageRiskAcceptance` skips the license check for listed packages. An entry with `purl` matches by package URL type, namespace, and name, and by version when the purl has one. Otherwise `name` matches the package name without regard to case. + +Patterns are case-insensitive globs. `*` matches any run of characters, and `?` matches one. `GPL-*` matches `GPL-2.0-only` and `GPL-3.0-or-later`. It does not match `LGPL-2.1-only` or a bare `GPL`. A pattern with no wildcard has to equal the license. Free-text names such as `Public Domain` are compared the same way. + +## Expressions + +Licenses can be SPDX expressions. `AND` binds tighter than `OR`, parentheses group, and the operators are case-insensitive. + +- `MIT OR GPL-3.0-only` passes when either side passes, since you can choose MIT. +- `MIT AND GPL-3.0-only` passes only when both sides pass. +- `GPL-2.0-only WITH Classpath-exception-2.0` is checked as the full string and as `GPL-2.0-only`. A deny pattern that matches either one fails it. An `allow` entry that matches the full `WITH` string passes it even when the base license is denied. + +A package that lists several licenses has to pass each of them, as if they were joined with `AND`. A string that is not a valid expression, such as `GPL v2 or later`, is checked as one license name. + +## Results + +Each failing package is logged with its name, version, purl, and the reason, such as `GPL-2.0-only is denied by "GPL-*"`. The report then fails with `validation failure: License: N package(s) failed the license policy`, and `validate` exits 1. + +For a CycloneDX BOM, the license rules and the vulnerability rules both run. Both failures are reported. diff --git a/docs/supported-reports.md b/docs/supported-reports.md index 1af36ad..ff90e39 100644 --- a/docs/supported-reports.md +++ b/docs/supported-reports.md @@ -8,7 +8,7 @@ Content rules, in this order: 2. `bomFormat` of `CycloneDX` is CycloneDX JSON. This wins when the name contains `grype`, `syft`, `trivy`, or `osv`, and it wins when the tool that wrote the BOM was Grype, Syft, Trivy, or another tool. 3. SARIF 2.1.0. The top-level `version` is the string `2.1.0` and `runs` is an array. A `$schema` that mentions SARIF is enough when `runs` is missing or null. gosec (`-fmt sarif`), hadolint (`-f sarif`), and zizmor (`--format sarif`) write this type, and `gatecheck bootstrap --tools gosec,hadolint,zizmor` installs them. 4. Grype JSON. `descriptor.name` is `grype`, or `matches` is a non-empty array of objects with `vulnerability` and `artifact`. -5. Syft JSON. `descriptor.name` is `syft`, or `schema.url` points at the Syft schema. `list` and `validate` then return an error. Syft JSON is not implemented. A Syft CycloneDX BOM is CycloneDX, not Syft. +5. Syft JSON. `descriptor.name` is `syft`, or `schema.url` points at the Syft schema. `list` prints its packages and licenses. `validate` runs the license rules. A Syft CycloneDX BOM is CycloneDX, not Syft. 6. Semgrep JSON. `results` is an array of objects with `check_id`, or `results` and `errors` are both arrays. Semgrep's SARIF output is SARIF, not this type. 7. Gitleaks JSON. A non-empty array of objects with `RuleID` and one of `File`, `Commit`, or `Fingerprint`. 8. Trivy JSON (`--format json`). `SchemaVersion` is a number, and `ArtifactType` is set or `Results` is an array. Vulnerability entries are listed and validated. Misconfigurations, secrets, and licenses in the same file are ignored. @@ -52,7 +52,7 @@ grype bkimminich/juice-shop:latest -o json | gatecheck list --input-type grype `list-all` lists a file when the contents or the name identify Grype, Semgrep, Gitleaks, Syft, CycloneDX, SARIF, Trivy, osv-scanner, or a bundle. Coverage files are skipped with a warning. There is no `--input-type` flag on `list-all`. -Inside a bundle, `validate` uses the same content rules on each stored file, and falls back to the label. The label is the base name of the file you added. Labels that still do not match are skipped. Syft JSON inside a bundle is skipped. +Inside a bundle, `validate` uses the same content rules on each stored file, and falls back to the label. The label is the base name of the file you added. Labels that still do not match are skipped. Syft JSON inside a bundle is checked with the license rules. What each command can do: @@ -66,5 +66,5 @@ What each command can do: | Trivy | yes | yes | yes | | osv-scanner | yes | yes | yes | | LCOV, Clover, Cobertura | yes | yes | yes | -| Syft JSON | error | error | the file is stored, and validation skips that label | +| Syft JSON | yes, packages and licenses | yes, license rules | yes | | Bundle | when the contents are a bundle, or the name contains `bundle` or `gatecheck` | when the contents are a bundle, or the name contains `bundle` | yes, as an ordinary file | diff --git a/docs/validation.md b/docs/validation.md index dd6fe4f..7b448cc 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -9,7 +9,7 @@ Pass the config with `--config` or `-f`, or with `GATECHECK_CONFIG_FILENAME`. Th The report type comes from the file contents, and from the filename when the contents are ambiguous. See [Supported Reports](./supported-reports.md). -With no config, gatecheck uses the default: every rule disabled, coverage thresholds `0`. Grype, CycloneDX, Trivy, osv-scanner, SARIF, Semgrep, Gitleaks, coverage, and bundle reports pass under that default. Syft JSON still returns an error. An old config with no `sarif` section leaves those limits disabled. +With no config, gatecheck uses the default: every rule disabled, coverage thresholds `0`. Grype, CycloneDX, Trivy, osv-scanner, SARIF, Semgrep, Gitleaks, coverage, and bundle reports pass under that default. Syft JSON passes too, since the license rules are off by default. An old config with no `sarif` section leaves those limits disabled. ## Exit status @@ -41,6 +41,10 @@ EPSS scores in the config are ratios from 0 to 1. When a rule needs EPSS scores and `--epss-filename` is not set, gatecheck downloads the current EPSS file and caches it until the published date changes. Requests send a User-Agent with the gatecheck version and project URL. +## Licenses + +Syft JSON and CycloneDX BOMs are checked against the `license` section of the config: deny patterns, an optional allow list, packages with no license, and per-package risk acceptance. For a CycloneDX BOM the license rules run alongside the vulnerability rules above, and both failures are reported. See [License gating](./licenses.md). + ## Semgrep 1. Findings whose severity limit is disabled are dropped. @@ -74,4 +78,4 @@ Line, function, and branch coverage are each `covered / total`. The config thres ## Bundles -A bundle is validated when its contents are a Gatecheck bundle, or when the filename contains `bundle` and the contents do not identify another type. Each stored file is validated with the rules above. The file contents pick the type, and the label is the fallback. Labels that still do not match are skipped, including Syft JSON. Failures are combined, and the command exits 1 if any label fails a threshold. +A bundle is validated when its contents are a Gatecheck bundle, or when the filename contains `bundle` and the contents do not identify another type. Each stored file is validated with the rules above. The file contents pick the type, and the label is the fallback. Labels that still do not match are skipped. Syft JSON in a bundle is checked with the license rules. Failures are combined, and the command exits 1 if any label fails a threshold. diff --git a/pkg/artifacts/cyclonedx.go b/pkg/artifacts/cyclonedx.go index a5e12d8..b474038 100644 --- a/pkg/artifacts/cyclonedx.go +++ b/pkg/artifacts/cyclonedx.go @@ -21,6 +21,10 @@ type CyclonedxComponent struct { Name string `json:"name"` Version string `json:"version"` PURL string `json:"purl"` + Type string `json:"type"` + // Licenses are the declared licenses. + Licenses []CyclonedxLicenseChoice `json:"licenses"` + Components []CyclonedxComponent `json:"components"` } // AffectedPURLs returns the package URLs of the components a vulnerability diff --git a/pkg/artifacts/syft.go b/pkg/artifacts/syft.go new file mode 100644 index 0000000..c85c771 --- /dev/null +++ b/pkg/artifacts/syft.go @@ -0,0 +1,84 @@ +package artifacts + +import ( + "encoding/json" + "strings" +) + +// SyftReportMin is the package list of a Syft JSON document. +type SyftReportMin struct { + Artifacts []SyftArtifact `json:"artifacts"` +} + +// SyftArtifact is one package Syft found. +type SyftArtifact struct { + Name string `json:"name"` + Version string `json:"version"` + Type string `json:"type"` + PURL string `json:"purl"` + Licenses []json.RawMessage `json:"licenses"` +} + +// LicenseNames returns each declared license. Newer Syft writes objects with +// spdxExpression and value. Older Syft writes plain strings. +func (a SyftArtifact) LicenseNames() []string { + var out []string + for _, raw := range a.Licenses { + var s string + if err := json.Unmarshal(raw, &s); err == nil { + out = appendLicense(out, s) + continue + } + var obj struct { + Value string `json:"value"` + SPDXExpression string `json:"spdxExpression"` + } + if err := json.Unmarshal(raw, &obj); err != nil { + continue + } + if obj.SPDXExpression != "" { + out = appendLicense(out, obj.SPDXExpression) + } else { + out = appendLicense(out, obj.Value) + } + } + return out +} + +// CyclonedxLicenseChoice is one entry of a CycloneDX licenses array. +type CyclonedxLicenseChoice struct { + License *struct { + ID string `json:"id"` + Name string `json:"name"` + } `json:"license"` + Expression string `json:"expression"` +} + +// LicenseNames returns the SPDX id, name, or expression of each entry. +func (c CyclonedxComponent) LicenseNames() []string { + var out []string + for _, choice := range c.Licenses { + switch { + case choice.Expression != "": + out = appendLicense(out, choice.Expression) + case choice.License != nil && choice.License.ID != "": + out = appendLicense(out, choice.License.ID) + case choice.License != nil: + out = appendLicense(out, choice.License.Name) + } + } + return out +} + +func appendLicense(out []string, license string) []string { + license = strings.TrimSpace(license) + if license == "" { + return out + } + for _, got := range out { + if got == license { + return out + } + } + return append(out, license) +} diff --git a/pkg/gatecheck/config.go b/pkg/gatecheck/config.go index 0fd832e..2564b89 100644 --- a/pkg/gatecheck/config.go +++ b/pkg/gatecheck/config.go @@ -34,6 +34,7 @@ type Config struct { Sarif configSarifReport `json:"sarif" toml:"sarif" yaml:"sarif"` Coverage configCoverageReport `json:"coverage" toml:"coverage" yaml:"coverage"` VEX configVEX `json:"vex" toml:"vex" yaml:"vex"` + License configLicense `json:"license" toml:"license" yaml:"license"` vexDoc *vex.Document } @@ -247,7 +248,8 @@ func NewDefaultConfig() *Config { FunctionThreshold: 0, BranchThreshold: 0, }, - VEX: configVEX{Files: []string{}}, + VEX: configVEX{Files: []string{}}, + License: defaultConfigLicense(), } } diff --git a/pkg/gatecheck/license.go b/pkg/gatecheck/license.go new file mode 100644 index 0000000..c327c8b --- /dev/null +++ b/pkg/gatecheck/license.go @@ -0,0 +1,145 @@ +package gatecheck + +import ( + "encoding/json" + "errors" + "fmt" + "io" + "log/slog" + "slices" + "sort" + "strings" + + "github.com/gatecheckdev/gatecheck/pkg/artifacts" + "github.com/gatecheckdev/gatecheck/pkg/license" + "github.com/gatecheckdev/gatecheck/pkg/vex" + "github.com/olekukonko/tablewriter" +) + +// configLicense gates SBOM package licenses. It applies to Syft JSON and to +// CycloneDX components. +type configLicense struct { + Enabled bool `json:"enabled" toml:"enabled" yaml:"enabled"` + // Deny are case-insensitive glob patterns, such as "GPL-*". + Deny []string `json:"deny" toml:"deny" yaml:"deny"` + // Allow, when not empty, fails every license that matches none of these patterns. + Allow []string `json:"allow" toml:"allow" yaml:"allow"` + // DenyUnknown fails packages that declare no license. + DenyUnknown bool `json:"denyUnknown" toml:"denyUnknown" yaml:"denyUnknown"` + // PackageRiskAcceptance skips license checks for these packages. + PackageRiskAcceptance []configLicensePackage `json:"packageRiskAcceptance" toml:"packageRiskAcceptance" yaml:"packageRiskAcceptance"` +} + +type configLicensePackage struct { + // Name matches the package name without regard to case. + Name string `json:"name" toml:"name" yaml:"name"` + // PURL matches by type, namespace, and name, and by version when it has one. + PURL string `json:"purl" toml:"purl" yaml:"purl"` + Metadata struct { + Tags []string `json:"tags" toml:"tags" yaml:"tags"` + } `json:"metadata" toml:"metadata" yaml:"metadata"` +} + +func (c configLicensePackage) matches(pkg license.Package) bool { + if c.PURL != "" { + return pkg.PURL != "" && vex.PURLMatches(c.PURL, pkg.PURL) + } + return c.Name != "" && strings.EqualFold(c.Name, pkg.Name) +} + +func defaultConfigLicense() configLicense { + return configLicense{ + Deny: []string{}, + Allow: []string{}, + PackageRiskAcceptance: []configLicensePackage{}, + } +} + +// ruleLicense returns a validation error when a package license fails the policy. +func ruleLicense(config *Config, artifact string, pkgs []license.Package) error { + cfg := config.License + if !cfg.Enabled { + slog.Debug("license limit not enabled", "artifact", artifact, "packages", len(pkgs)) + return nil + } + policy := license.Policy{Deny: cfg.Deny, Allow: cfg.Allow, DenyUnknown: cfg.DenyUnknown} + var violations []license.Violation + for _, pkg := range pkgs { + v, failed := policy.Check(pkg) + if !failed { + continue + } + if slices.ContainsFunc(cfg.PackageRiskAcceptance, func(c configLicensePackage) bool { return c.matches(pkg) }) { + slog.Info("license risk accepted for package", "artifact", artifact, "package", pkg.Name, "version", pkg.Version, "license", v.License) + continue + } + violations = append(violations, v) + } + if len(violations) == 0 { + slog.Info("license limit valid", "artifact", artifact, "packages", len(pkgs)) + return nil + } + for _, v := range violations { + slog.Error("license violation", "artifact", artifact, "package", v.Package.Name, "version", v.Package.Version, "purl", v.Package.PURL, "reason", v.Reason) + } + return newValidationErr(fmt.Sprintf("License: %d package(s) failed the license policy", len(violations))) +} + +func syftPackages(report *artifacts.SyftReportMin) []license.Package { + pkgs := make([]license.Package, 0, len(report.Artifacts)) + for _, a := range report.Artifacts { + pkgs = append(pkgs, license.Package{Name: a.Name, Version: a.Version, PURL: a.PURL, Licenses: a.LicenseNames()}) + } + return pkgs +} + +// cyclonedxPackages flattens components, including nested ones. +func cyclonedxPackages(components []artifacts.CyclonedxComponent) []license.Package { + var pkgs []license.Package + for _, c := range components { + pkgs = append(pkgs, license.Package{Name: c.Name, Version: c.Version, PURL: c.PURL, Licenses: c.LicenseNames()}) + pkgs = append(pkgs, cyclonedxPackages(c.Components)...) + } + return pkgs +} + +func validateSyftReport(r io.Reader, config *Config) error { + slog.Debug("validate syft report") + report := &artifacts.SyftReportMin{} + if err := json.NewDecoder(r).Decode(report); err != nil { + slog.Error("decode syft report for validation", "error", err) + return errors.New("cannot run Syft validation: Report decoding failed, See log for details") + } + return ruleLicense(config, "syft", syftPackages(report)) +} + +func listSyft(table *tablewriter.Table, src io.Reader) error { + report := &artifacts.SyftReportMin{} + if err := json.NewDecoder(src).Decode(report); err != nil { + return err + } + if len(report.Artifacts) == 0 { + return emptyReport("No syft packages") + } + rows := make([][]string, 0, len(report.Artifacts)) + for _, a := range report.Artifacts { + licenses := strings.Join(a.LicenseNames(), ", ") + if licenses == "" { + licenses = "-" + } + rows = append(rows, []string{a.Name, a.Version, a.Type, licenses}) + } + sort.SliceStable(rows, func(i, j int) bool { + if rows[i][0] == rows[j][0] { + return rows[i][1] < rows[j][1] + } + return rows[i][0] < rows[j][0] + }) + table.Header([]string{"Syft Package", "Version", "Type", "Licenses"}) + for _, row := range rows { + if err := table.Append(row); err != nil { + return err + } + } + return nil +} diff --git a/pkg/gatecheck/license_test.go b/pkg/gatecheck/license_test.go new file mode 100644 index 0000000..c3ba2b3 --- /dev/null +++ b/pkg/gatecheck/license_test.go @@ -0,0 +1,121 @@ +package gatecheck + +import ( + "bytes" + "errors" + "os" + "strings" + "testing" + + "github.com/gatecheckdev/gatecheck/pkg/archive" +) + +const ( + syftAlpine = "../../test/syft-alpine.json" + cdxAlpine = "../../test/cyclonedx-alpine-sbom.json" +) + +func licenseConfig(mod func(*configLicense)) *Config { + config := NewDefaultConfig() + config.License.Enabled = true + mod(&config.License) + return config +} + +func TestLicenseGateOnSBOMs(t *testing.T) { + for _, report := range []string{syftAlpine, cdxAlpine} { + t.Run(report, func(t *testing.T) { + if err := validateFile(t, NewDefaultConfig(), report); err != nil { + t.Fatalf("license rules off: %v", err) + } + + denyGPL := licenseConfig(func(c *configLicense) { c.Deny = []string{"GPL-*"} }) + if err := validateFile(t, denyGPL, report); !errors.Is(err, ErrValidationFailure) || !strings.Contains(err.Error(), "License") { + t.Fatalf("deny GPL: %v", err) + } + + denyAGPL := licenseConfig(func(c *configLicense) { c.Deny = []string{"AGPL-*"} }) + if err := validateFile(t, denyAGPL, report); err != nil { + t.Fatalf("deny AGPL: %v", err) + } + + allowPermissive := licenseConfig(func(c *configLicense) { + c.Allow = []string{"MIT", "Apache-2.0", "BSD-*", "Zlib", "MPL-2.0"} + }) + if err := validateFile(t, allowPermissive, report); !errors.Is(err, ErrValidationFailure) { + t.Fatalf("allow list without GPL: %v", err) + } + + allowAll := licenseConfig(func(c *configLicense) { + c.Allow = []string{"MIT", "Apache-2.0", "BSD-*", "Zlib", "MPL-2.0", "GPL-2.0-*"} + }) + if err := validateFile(t, allowAll, report); err != nil { + t.Fatalf("allow list with every license: %v", err) + } + + accepted := licenseConfig(func(c *configLicense) { + c.Deny = []string{"GPL-*"} + for _, name := range []string{"alpine-baselayout", "alpine-baselayout-data", "apk-tools", "busybox", "busybox-binsh", "ssl_client", "scanelf", "musl-utils"} { + c.PackageRiskAcceptance = append(c.PackageRiskAcceptance, configLicensePackage{Name: name}) + } + c.PackageRiskAcceptance = append(c.PackageRiskAcceptance, configLicensePackage{PURL: "pkg:apk/alpine/libc-utils"}) + }) + if err := validateFile(t, accepted, report); err != nil { + t.Fatalf("risk accepted packages: %v", err) + } + }) + } +} + +func TestLicenseDenyUnknown(t *testing.T) { + src := []byte(`{"descriptor":{"name":"syft"},"artifacts":[{"name":"mystery","version":"1.0","licenses":[]},{"name":"old","version":"2","licenses":["MIT"]}]}`) + config := licenseConfig(func(c *configLicense) { c.DenyUnknown = true }) + if err := Validate(config, bytes.NewReader(src), "bom.syft.json"); !errors.Is(err, ErrValidationFailure) { + t.Fatalf("unknown license should fail: %v", err) + } + config.License.PackageRiskAcceptance = []configLicensePackage{{Name: "MYSTERY"}} + if err := Validate(config, bytes.NewReader(src), "bom.syft.json"); err != nil { + t.Fatalf("accepted unknown: %v", err) + } +} + +func TestLicenseInBundleAndList(t *testing.T) { + content, err := os.ReadFile(syftAlpine) + if err != nil { + t.Fatal(err) + } + var out bytes.Buffer + if err := List(&out, bytes.NewReader(content), "syft-alpine.json"); err != nil { + t.Fatal(err) + } + for _, want := range []string{"SYFT PACKAGE", "busybox", "GPL-2.0-only", "MPL-2.0 AND MIT"} { + if !strings.Contains(out.String(), want) { + t.Fatalf("list output missing %q:\n%s", want, out.String()) + } + } + + bundle := archive.NewBundle() + if err := bundle.AddFrom(bytes.NewReader(content), "syft-alpine.json", nil); err != nil { + t.Fatal(err) + } + var buf bytes.Buffer + if _, err := archive.TarGzipBundle(&buf, bundle); err != nil { + t.Fatal(err) + } + denyGPL := licenseConfig(func(c *configLicense) { c.Deny = []string{"GPL-*"} }) + if err := Validate(denyGPL, bytes.NewReader(buf.Bytes()), "bundle.tar.gz"); !errors.Is(err, ErrValidationFailure) { + t.Fatalf("bundle license gate: %v", err) + } +} + +func TestCyclonedxLicenseAndVulnErrorsJoin(t *testing.T) { + config := licenseConfig(func(c *configLicense) { c.Deny = []string{"GPL-*"} }) + config.Cyclonedx.SeverityLimit.Low = configLimit{Enabled: true, Limit: 0} + err := validateFile(t, config, "../../test/cyclonedx-grype-sbom.json") + if !errors.Is(err, ErrValidationFailure) { + t.Fatal(err) + } + if !strings.Contains(err.Error(), "License") || !strings.Contains(err.Error(), "Severity Limit") { + t.Fatalf("want both failures, got %v", err) + } +} diff --git a/pkg/gatecheck/list.go b/pkg/gatecheck/list.go index a2ed671..54b93a9 100644 --- a/pkg/gatecheck/list.go +++ b/pkg/gatecheck/list.go @@ -116,8 +116,7 @@ func List(dst io.Writer, src io.Reader, inputFilename string, options ...ListOpt } case artifacts.KindSyft: - slog.Warn("syft decoder is not supported yet") - return errors.New("syft not implemented yet") + err = listSyft(table, src) case artifacts.KindSARIF: err = ListSarif(table, src) diff --git a/pkg/gatecheck/report_kind_test.go b/pkg/gatecheck/report_kind_test.go index a6d3195..8e8c66e 100644 --- a/pkg/gatecheck/report_kind_test.go +++ b/pkg/gatecheck/report_kind_test.go @@ -325,13 +325,14 @@ func TestTrivyAndOSVContentWinsOverFilename(t *testing.T) { } } -func TestSyftJSONStillErrors(t *testing.T) { +func TestSyftJSONListsAndValidates(t *testing.T) { src := []byte(`{"descriptor":{"name":"syft"},"artifacts":[]}`) - if err := List(&bytes.Buffer{}, bytes.NewReader(src), "scan.json"); err == nil || !strings.Contains(err.Error(), "syft") { - t.Fatal(err) + var out bytes.Buffer + if err := List(&out, bytes.NewReader(src), "scan.json"); err != nil || !strings.Contains(out.String(), "No syft packages") { + t.Fatalf("list: %v %q", err, out.String()) } - if err := Validate(NewDefaultConfig(), bytes.NewReader(src), "bom.syft.json"); err == nil || !strings.Contains(err.Error(), "syft") { - t.Fatal(err) + if err := Validate(NewDefaultConfig(), bytes.NewReader(src), "bom.syft.json"); err != nil { + t.Fatalf("validate with license rules off: %v", err) } } diff --git a/pkg/gatecheck/validate.go b/pkg/gatecheck/validate.go index 941888a..2996ff0 100644 --- a/pkg/gatecheck/validate.go +++ b/pkg/gatecheck/validate.go @@ -69,7 +69,7 @@ func Validate(config *Config, reportSrc io.Reader, targetFilename string, option return validateOSVReportWithFetch(reportSrc, config, options) case artifacts.KindSyft: - return errors.New("syft validation not supported yet") + return validateSyftReport(reportSrc, config) case artifacts.KindSARIF: return validateSarifReport(reportSrc, config) @@ -803,6 +803,9 @@ func validateBundle(r io.Reader, config *Config, options *fetchOptions) error { case artifacts.KindSARIF: err := validateSarifReport(bytes.NewBuffer(content), config) errs = errors.Join(errs, err) + case artifacts.KindSyft: + err := validateSyftReport(bytes.NewBuffer(content), config) + errs = errors.Join(errs, err) case artifacts.KindLCOV, artifacts.KindClover, artifacts.KindCobertura, artifacts.KindCoverage: err := validateCoverage(bytes.NewBuffer(content), kind, fileLabel, config) errs = errors.Join(errs, err) @@ -871,6 +874,11 @@ func validateGrypeRules(config *Config, report *artifacts.GrypeReportMin, catalo } func validateCyclonedxRules(config *Config, report *artifacts.CyclonedxReportMin, catalog *kev.Catalog, data *epss.Data) error { + licenseErr := ruleLicense(config, "cyclonedx", cyclonedxPackages(report.Components)) + return errors.Join(licenseErr, validateCyclonedxVulnerabilities(config, report, catalog, data)) +} + +func validateCyclonedxVulnerabilities(config *Config, report *artifacts.CyclonedxReportMin, catalog *kev.Catalog, data *epss.Data) error { // 1. Deny List - Fail Matching if !ruleCyclonedxCVEDeny(config, report) { return newValidationErr("CycloneDx: CVE explicitly denied") diff --git a/pkg/license/license.go b/pkg/license/license.go new file mode 100644 index 0000000..c2a42ac --- /dev/null +++ b/pkg/license/license.go @@ -0,0 +1,302 @@ +// Package license checks SBOM package licenses against allow and deny lists. +// +// Licenses are SPDX ids, SPDX expressions, or free-text names. An expression +// such as "MIT OR GPL-3.0-only" passes when one side passes, and +// "MIT AND GPL-3.0-only" passes only when both sides pass. +package license + +import ( + "fmt" + "path" + "strings" +) + +// Package is one SBOM package and the licenses it declares. More than one +// entry means every entry applies, as if joined with AND. +type Package struct { + Name string + Version string + PURL string + Licenses []string +} + +// Policy is a set of license rules. +type Policy struct { + // Deny patterns fail a license. Patterns are case-insensitive globs, so + // "GPL-*" matches "GPL-3.0-only" but not "LGPL-2.1-only". + Deny []string + // Allow patterns, when set, fail every license that matches none of them. + Allow []string + // DenyUnknown fails a package that declares no license, or only + // NOASSERTION or NONE. + DenyUnknown bool +} + +// Violation explains why a package failed. +type Violation struct { + Package Package + // License is the declared license that failed, or "" for an unknown one. + License string + Reason string +} + +func (v Violation) Error() string { + name := v.Package.Name + if v.Package.Version != "" { + name += "@" + v.Package.Version + } + if v.License == "" { + return fmt.Sprintf("%s: %s", name, v.Reason) + } + return fmt.Sprintf("%s: %s: %s", name, v.License, v.Reason) +} + +// Check returns a violation for pkg, or false when it passes. +func (p Policy) Check(pkg Package) (Violation, bool) { + known := knownLicenses(pkg.Licenses) + if len(known) == 0 { + if p.DenyUnknown { + return Violation{Package: pkg, Reason: "no license declared"}, true + } + return Violation{}, false + } + for _, declared := range known { + expr, err := Parse(declared) + if err != nil { + // An unparseable string is checked as one license name. + expr = leaf{id: strings.TrimSpace(declared)} + } + if reason, ok := p.eval(expr); !ok { + return Violation{Package: pkg, License: declared, Reason: reason}, true + } + } + return Violation{}, false +} + +func knownLicenses(values []string) []string { + var out []string + for _, v := range values { + v = strings.TrimSpace(v) + switch strings.ToUpper(v) { + case "", "NOASSERTION", "NONE", "UNKNOWN": + continue + } + out = append(out, v) + } + return out +} + +func (p Policy) eval(e Expr) (string, bool) { + switch e := e.(type) { + case and: + for _, side := range []Expr{e.left, e.right} { + if reason, ok := p.eval(side); !ok { + return reason, false + } + } + return "", true + case or: + left, ok := p.eval(e.left) + if ok { + return "", true + } + right, ok := p.eval(e.right) + if ok { + return "", true + } + return left + "; " + right, false + case leaf: + return p.leaf(e) + default: + return "unsupported expression", false + } +} + +func (p Policy) leaf(l leaf) (string, bool) { + full := l.String() + // An allow pattern for the exact "X WITH Y" form beats a deny for X. + if l.exception != "" && matchAny(p.Allow, full) { + return "", true + } + if pattern, ok := firstMatch(p.Deny, full, l.id); ok { + return fmt.Sprintf("%s is denied by %q", full, pattern), false + } + if len(p.Allow) > 0 && !matchAny(p.Allow, full) && !matchAny(p.Allow, l.id) { + return full + " is not in the allow list", false + } + return "", true +} + +func matchAny(patterns []string, values ...string) bool { + _, ok := firstMatch(patterns, values...) + return ok +} + +func firstMatch(patterns []string, values ...string) (string, bool) { + for _, pattern := range patterns { + pat := strings.ToLower(strings.TrimSpace(pattern)) + if pat == "" { + continue + } + for _, v := range values { + v = strings.ToLower(strings.TrimSpace(v)) + if v == "" { + continue + } + if ok, err := path.Match(pat, v); err == nil && ok { + return pattern, true + } + if pat == v { + return pattern, true + } + } + } + return "", false +} + +// Expr is a parsed SPDX license expression. +type Expr interface { + String() string +} + +type leaf struct { + id string + exception string +} + +func (l leaf) String() string { + if l.exception == "" { + return l.id + } + return l.id + " WITH " + l.exception +} + +type and struct{ left, right Expr } + +func (a and) String() string { return "(" + a.left.String() + " AND " + a.right.String() + ")" } + +type or struct{ left, right Expr } + +func (o or) String() string { return "(" + o.left.String() + " OR " + o.right.String() + ")" } + +// Parse reads an SPDX license expression. AND binds tighter than OR. +// Operators are case-insensitive. +func Parse(s string) (Expr, error) { + p := &parser{tokens: tokenize(s)} + if len(p.tokens) == 0 { + return nil, fmt.Errorf("empty license expression") + } + e, err := p.or() + if err != nil { + return nil, err + } + if p.pos != len(p.tokens) { + return nil, fmt.Errorf("unexpected %q in %q", p.tokens[p.pos], s) + } + return e, nil +} + +func tokenize(s string) []string { + var out []string + var cur strings.Builder + flush := func() { + if cur.Len() > 0 { + out = append(out, cur.String()) + cur.Reset() + } + } + for _, r := range s { + switch r { + case '(', ')': + flush() + out = append(out, string(r)) + case ' ', '\t', '\n', '\r': + flush() + default: + cur.WriteRune(r) + } + } + flush() + return out +} + +type parser struct { + tokens []string + pos int +} + +func (p *parser) peek() string { + if p.pos >= len(p.tokens) { + return "" + } + return p.tokens[p.pos] +} + +func (p *parser) or() (Expr, error) { + left, err := p.and() + if err != nil { + return nil, err + } + for strings.EqualFold(p.peek(), "OR") { + p.pos++ + right, err := p.and() + if err != nil { + return nil, err + } + left = or{left, right} + } + return left, nil +} + +func (p *parser) and() (Expr, error) { + left, err := p.term() + if err != nil { + return nil, err + } + for strings.EqualFold(p.peek(), "AND") { + p.pos++ + right, err := p.term() + if err != nil { + return nil, err + } + left = and{left, right} + } + return left, nil +} + +func (p *parser) term() (Expr, error) { + tok := p.peek() + switch { + case tok == "": + return nil, fmt.Errorf("expression ends early") + case tok == "(": + p.pos++ + e, err := p.or() + if err != nil { + return nil, err + } + if p.peek() != ")" { + return nil, fmt.Errorf("missing )") + } + p.pos++ + return e, nil + case tok == ")" || isOperator(tok): + return nil, fmt.Errorf("unexpected %q", tok) + } + p.pos++ + l := leaf{id: tok} + if strings.EqualFold(p.peek(), "WITH") { + p.pos++ + exc := p.peek() + if exc == "" || exc == "(" || exc == ")" || isOperator(exc) { + return nil, fmt.Errorf("WITH needs an exception id") + } + p.pos++ + l.exception = exc + } + return l, nil +} + +func isOperator(tok string) bool { + return strings.EqualFold(tok, "AND") || strings.EqualFold(tok, "OR") || strings.EqualFold(tok, "WITH") +} diff --git a/pkg/license/license_test.go b/pkg/license/license_test.go new file mode 100644 index 0000000..74a722b --- /dev/null +++ b/pkg/license/license_test.go @@ -0,0 +1,73 @@ +package license + +import "testing" + +func TestParse(t *testing.T) { + cases := map[string]string{ + "MIT": "MIT", + "MIT OR Apache-2.0": "(MIT OR Apache-2.0)", + "MIT or Apache-2.0 and BSD-3-Clause": "(MIT OR (Apache-2.0 AND BSD-3-Clause))", + "(MIT OR Apache-2.0) AND BSD-3-Clause": "((MIT OR Apache-2.0) AND BSD-3-Clause)", + "GPL-2.0-only WITH Classpath-exception-2.0": "GPL-2.0-only WITH Classpath-exception-2.0", + } + for in, want := range cases { + got, err := Parse(in) + if err != nil { + t.Fatalf("%q: %v", in, err) + } + if got.String() != want { + t.Errorf("%q parsed as %q, want %q", in, got.String(), want) + } + } + for _, bad := range []string{"", "MIT OR", "(MIT", "AND MIT", "MIT WITH", "public domain"} { + if _, err := Parse(bad); err == nil { + t.Errorf("%q should not parse", bad) + } + } +} + +func TestPolicyCheck(t *testing.T) { + deny := Policy{Deny: []string{"GPL-*", "AGPL-*"}} + allow := Policy{Allow: []string{"MIT", "Apache-2.0", "BSD-*"}} + cases := []struct { + name string + policy Policy + licenses []string + fail bool + }{ + {"deny match", deny, []string{"GPL-3.0-only"}, true}, + {"deny case", deny, []string{"gpl-2.0-or-later"}, true}, + {"deny does not hit LGPL", deny, []string{"LGPL-2.1-only"}, false}, + {"or with a way out", deny, []string{"MIT OR GPL-3.0-only"}, false}, + {"and needs both", deny, []string{"MIT AND GPL-3.0-only"}, true}, + {"two entries are and", deny, []string{"MIT", "AGPL-3.0-only"}, true}, + {"with keeps base deny", deny, []string{"GPL-2.0-only WITH Classpath-exception-2.0"}, true}, + {"free text name", Policy{Deny: []string{"public domain"}}, []string{"Public Domain"}, true}, + {"allow hit", allow, []string{"BSD-3-Clause"}, false}, + {"allow miss", allow, []string{"MPL-2.0"}, true}, + {"allow or", allow, []string{"MPL-2.0 OR MIT"}, false}, + {"unknown passes by default", deny, nil, false}, + {"noassertion is unknown", Policy{DenyUnknown: true}, []string{"NOASSERTION"}, true}, + {"deny unknown", Policy{DenyUnknown: true}, []string{""}, true}, + {"deny unknown with license", Policy{DenyUnknown: true}, []string{"MIT"}, false}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + v, fail := tc.policy.Check(Package{Name: "pkg", Version: "1", Licenses: tc.licenses}) + if fail != tc.fail { + t.Fatalf("fail=%v want %v (%v)", fail, tc.fail, v) + } + if fail && v.Error() == "" { + t.Fatal("empty violation") + } + }) + } + + exception := Policy{Deny: []string{"GPL-*"}, Allow: []string{"GPL-2.0-only WITH Classpath-exception-2.0", "MIT"}} + if v, fail := exception.Check(Package{Licenses: []string{"GPL-2.0-only WITH Classpath-exception-2.0"}}); fail { + t.Fatalf("explicit WITH allow should pass: %v", v) + } + if _, fail := exception.Check(Package{Licenses: []string{"GPL-2.0-only"}}); !fail { + t.Fatal("bare GPL should still fail") + } +} diff --git a/test/cyclonedx-alpine-sbom.json b/test/cyclonedx-alpine-sbom.json new file mode 100644 index 0000000..81bca95 --- /dev/null +++ b/test/cyclonedx-alpine-sbom.json @@ -0,0 +1,589 @@ +{ + "bomFormat": "CycloneDX", + "specVersion": "1.7", + "components": [ + { + "bom-ref": "pkg:apk/alpine/alpine-baselayout@3.6.5-r0?arch=aarch64&distro=alpine-3.20.10&package-id=8d645c7d2c9ab6eb", + "type": "library", + "name": "alpine-baselayout", + "version": "3.6.5-r0", + "purl": "pkg:apk/alpine/alpine-baselayout@3.6.5-r0?arch=aarch64&distro=alpine-3.20.10", + "licenses": [ + { + "license": { + "id": "GPL-2.0-only" + } + } + ] + }, + { + "bom-ref": "pkg:apk/alpine/alpine-baselayout-data@3.6.5-r0?arch=aarch64&distro=alpine-3.20.10&package-id=977c0e9c1bdcda77&upstream=alpine-baselayout", + "type": "library", + "name": "alpine-baselayout-data", + "version": "3.6.5-r0", + "purl": "pkg:apk/alpine/alpine-baselayout-data@3.6.5-r0?arch=aarch64&distro=alpine-3.20.10&upstream=alpine-baselayout", + "licenses": [ + { + "license": { + "id": "GPL-2.0-only" + } + } + ] + }, + { + "bom-ref": "pkg:apk/alpine/alpine-keys@2.4-r1?arch=aarch64&distro=alpine-3.20.10&package-id=7dd8dd3195a50a7c", + "type": "library", + "name": "alpine-keys", + "version": "2.4-r1", + "purl": "pkg:apk/alpine/alpine-keys@2.4-r1?arch=aarch64&distro=alpine-3.20.10", + "licenses": [ + { + "license": { + "id": "MIT" + } + } + ] + }, + { + "bom-ref": "pkg:apk/alpine/apk-tools@2.14.4-r1?arch=aarch64&distro=alpine-3.20.10&package-id=aa9849d247add51e", + "type": "library", + "name": "apk-tools", + "version": "2.14.4-r1", + "purl": "pkg:apk/alpine/apk-tools@2.14.4-r1?arch=aarch64&distro=alpine-3.20.10", + "licenses": [ + { + "license": { + "id": "GPL-2.0-only" + } + } + ] + }, + { + "bom-ref": "pkg:apk/alpine/busybox@1.36.1-r31?arch=aarch64&distro=alpine-3.20.10&package-id=a6a0537c11acf05d", + "type": "library", + "name": "busybox", + "version": "1.36.1-r31", + "purl": "pkg:apk/alpine/busybox@1.36.1-r31?arch=aarch64&distro=alpine-3.20.10", + "licenses": [ + { + "license": { + "id": "GPL-2.0-only" + } + } + ] + }, + { + "bom-ref": "pkg:apk/alpine/busybox-binsh@1.36.1-r31?arch=aarch64&distro=alpine-3.20.10&package-id=3f5c5e6b53d979db&upstream=busybox", + "type": "library", + "name": "busybox-binsh", + "version": "1.36.1-r31", + "purl": "pkg:apk/alpine/busybox-binsh@1.36.1-r31?arch=aarch64&distro=alpine-3.20.10&upstream=busybox", + "licenses": [ + { + "license": { + "id": "GPL-2.0-only" + } + } + ] + }, + { + "bom-ref": "pkg:apk/alpine/ca-certificates-bundle@20260413-r0?arch=aarch64&distro=alpine-3.20.10&package-id=8d8969ab763f5c88&upstream=ca-certificates", + "type": "library", + "name": "ca-certificates-bundle", + "version": "20260413-r0", + "purl": "pkg:apk/alpine/ca-certificates-bundle@20260413-r0?arch=aarch64&distro=alpine-3.20.10&upstream=ca-certificates", + "licenses": [ + { + "expression": "MPL-2.0 AND MIT" + } + ] + }, + { + "bom-ref": "pkg:apk/alpine/libcrypto3@3.3.7-r0?arch=aarch64&distro=alpine-3.20.10&package-id=07354995b7aa075a&upstream=openssl", + "type": "library", + "name": "libcrypto3", + "version": "3.3.7-r0", + "purl": "pkg:apk/alpine/libcrypto3@3.3.7-r0?arch=aarch64&distro=alpine-3.20.10&upstream=openssl", + "licenses": [ + { + "license": { + "id": "Apache-2.0" + } + } + ] + }, + { + "bom-ref": "pkg:apk/alpine/libssl3@3.3.7-r0?arch=aarch64&distro=alpine-3.20.10&package-id=c9c2a9d7c134be14&upstream=openssl", + "type": "library", + "name": "libssl3", + "version": "3.3.7-r0", + "purl": "pkg:apk/alpine/libssl3@3.3.7-r0?arch=aarch64&distro=alpine-3.20.10&upstream=openssl", + "licenses": [ + { + "license": { + "id": "Apache-2.0" + } + } + ] + }, + { + "bom-ref": "pkg:apk/alpine/musl@1.2.5-r3?arch=aarch64&distro=alpine-3.20.10&package-id=6dcdd7dc29c063ea", + "type": "library", + "name": "musl", + "version": "1.2.5-r3", + "purl": "pkg:apk/alpine/musl@1.2.5-r3?arch=aarch64&distro=alpine-3.20.10", + "licenses": [ + { + "license": { + "id": "MIT" + } + } + ] + }, + { + "bom-ref": "pkg:apk/alpine/musl-utils@1.2.5-r3?arch=aarch64&distro=alpine-3.20.10&package-id=ff0cffffebef70f2&upstream=musl", + "type": "library", + "name": "musl-utils", + "version": "1.2.5-r3", + "purl": "pkg:apk/alpine/musl-utils@1.2.5-r3?arch=aarch64&distro=alpine-3.20.10&upstream=musl", + "licenses": [ + { + "expression": "MIT AND BSD-2-Clause AND GPL-2.0-or-later" + } + ] + }, + { + "bom-ref": "pkg:apk/alpine/scanelf@1.3.7-r2?arch=aarch64&distro=alpine-3.20.10&package-id=79597b43a49073ac&upstream=pax-utils", + "type": "library", + "name": "scanelf", + "version": "1.3.7-r2", + "purl": "pkg:apk/alpine/scanelf@1.3.7-r2?arch=aarch64&distro=alpine-3.20.10&upstream=pax-utils", + "licenses": [ + { + "license": { + "id": "GPL-2.0-only" + } + } + ] + }, + { + "bom-ref": "pkg:apk/alpine/ssl_client@1.36.1-r31?arch=aarch64&distro=alpine-3.20.10&package-id=08e4498c1dfeec93&upstream=busybox", + "type": "library", + "name": "ssl_client", + "version": "1.36.1-r31", + "purl": "pkg:apk/alpine/ssl_client@1.36.1-r31?arch=aarch64&distro=alpine-3.20.10&upstream=busybox", + "licenses": [ + { + "license": { + "id": "GPL-2.0-only" + } + } + ] + }, + { + "bom-ref": "pkg:apk/alpine/zlib@1.3.2-r0?arch=aarch64&distro=alpine-3.20.10&package-id=ba8a89789a796fe2", + "type": "library", + "name": "zlib", + "version": "1.3.2-r0", + "purl": "pkg:apk/alpine/zlib@1.3.2-r0?arch=aarch64&distro=alpine-3.20.10", + "licenses": [ + { + "license": { + "id": "Zlib" + } + } + ] + }, + { + "bom-ref": "os:alpine@3.20.10", + "type": "operating-system", + "name": "alpine", + "version": "3.20.10" + }, + { + "bom-ref": "f0db0f411c110503", + "type": "file", + "name": "/bin/busybox" + }, + { + "bom-ref": "f525f0a1036978a5", + "type": "file", + "name": "/etc/apk/keys/alpine-devel@lists.alpinelinux.org-524d27bb.rsa.pub" + }, + { + "bom-ref": "3ba45d1d547b1424", + "type": "file", + "name": "/etc/apk/keys/alpine-devel@lists.alpinelinux.org-58199dcc.rsa.pub" + }, + { + "bom-ref": "7723c5097858eb68", + "type": "file", + "name": "/etc/apk/keys/alpine-devel@lists.alpinelinux.org-616a9724.rsa.pub" + }, + { + "bom-ref": "90dcfe46d4dcc5ec", + "type": "file", + "name": "/etc/apk/keys/alpine-devel@lists.alpinelinux.org-616adfeb.rsa.pub" + }, + { + "bom-ref": "e5835d981b2fee6b", + "type": "file", + "name": "/etc/apk/keys/alpine-devel@lists.alpinelinux.org-616ae350.rsa.pub" + }, + { + "bom-ref": "b2256fb4f656b7eb", + "type": "file", + "name": "/etc/busybox-paths.d/busybox" + }, + { + "bom-ref": "55d8bde864a2e4d0", + "type": "file", + "name": "/etc/crontabs/root" + }, + { + "bom-ref": "063e6cd8b0d3cf42", + "type": "file", + "name": "/etc/fstab" + }, + { + "bom-ref": "70019bb68bf73d23", + "type": "file", + "name": "/etc/group" + }, + { + "bom-ref": "61556d6a3233f99e", + "type": "file", + "name": "/etc/hostname" + }, + { + "bom-ref": "f3e5bbc7933fc706", + "type": "file", + "name": "/etc/hosts" + }, + { + "bom-ref": "0b9fb05c533a6bde", + "type": "file", + "name": "/etc/inittab" + }, + { + "bom-ref": "a1fc9d67313ac16f", + "type": "file", + "name": "/etc/logrotate.d/acpid" + }, + { + "bom-ref": "bbf768273e89d6cc", + "type": "file", + "name": "/etc/modprobe.d/aliases.conf" + }, + { + "bom-ref": "9724c527f80e835f", + "type": "file", + "name": "/etc/modprobe.d/blacklist.conf" + }, + { + "bom-ref": "5e0a5e2924fe7c18", + "type": "file", + "name": "/etc/modprobe.d/i386.conf" + }, + { + "bom-ref": "840ba917e6477e6f", + "type": "file", + "name": "/etc/modprobe.d/kms.conf" + }, + { + "bom-ref": "0b52b21de82aa4de", + "type": "file", + "name": "/etc/modules" + }, + { + "bom-ref": "ca01744f6abf62a8", + "type": "file", + "name": "/etc/motd" + }, + { + "bom-ref": "f65cd89eebd66906", + "type": "file", + "name": "/etc/network/if-up.d/dad" + }, + { + "bom-ref": "85c2de71aeb0d590", + "type": "file", + "name": "/etc/nsswitch.conf" + }, + { + "bom-ref": "e945200420ea2216", + "type": "file", + "name": "/etc/passwd" + }, + { + "bom-ref": "38d7d6b2e8357c74", + "type": "file", + "name": "/etc/profile" + }, + { + "bom-ref": "44b090735cce19f9", + "type": "file", + "name": "/etc/profile.d/20locale.sh" + }, + { + "bom-ref": "cf2f98bc3fd3886c", + "type": "file", + "name": "/etc/profile.d/README" + }, + { + "bom-ref": "7ac2ee07f58f98ff", + "type": "file", + "name": "/etc/profile.d/color_prompt.sh.disabled" + }, + { + "bom-ref": "5748aaf4f7b0f49d", + "type": "file", + "name": "/etc/protocols" + }, + { + "bom-ref": "bb7a6c1456671f60", + "type": "file", + "name": "/etc/securetty" + }, + { + "bom-ref": "65bacafb62664e4a", + "type": "file", + "name": "/etc/services" + }, + { + "bom-ref": "d9e66d863bf2cfb5", + "type": "file", + "name": "/etc/shadow" + }, + { + "bom-ref": "6b6c83f6ddd83cc2", + "type": "file", + "name": "/etc/shells" + }, + { + "bom-ref": "3cccc320c5389e49", + "type": "file", + "name": "/etc/ssl/certs/ca-certificates.crt" + }, + { + "bom-ref": "dcfd59e518c93e1f", + "type": "file", + "name": "/etc/ssl/ct_log_list.cnf" + }, + { + "bom-ref": "c72980d672658959", + "type": "file", + "name": "/etc/ssl/ct_log_list.cnf.dist" + }, + { + "bom-ref": "e75f6024e3c25f7b", + "type": "file", + "name": "/etc/ssl/openssl.cnf" + }, + { + "bom-ref": "e83e69311924a1cd", + "type": "file", + "name": "/etc/ssl/openssl.cnf.dist" + }, + { + "bom-ref": "269b36ee85799405", + "type": "file", + "name": "/etc/sysctl.conf" + }, + { + "bom-ref": "63be7584820e3b87", + "type": "file", + "name": "/etc/udhcpc/udhcpc.conf" + }, + { + "bom-ref": "ff161ad11e2d1be4", + "type": "file", + "name": "/lib/apk/db/installed" + }, + { + "bom-ref": "d3c74e83e59cdd93", + "type": "file", + "name": "/lib/ld-musl-aarch64.so.1" + }, + { + "bom-ref": "f5f63b6d871d6edf", + "type": "file", + "name": "/lib/libapk.so.2.14.0" + }, + { + "bom-ref": "809b5bd9e0a0bf1c", + "type": "file", + "name": "/lib/libcrypto.so.3" + }, + { + "bom-ref": "70a12d60ca0001dd", + "type": "file", + "name": "/lib/libssl.so.3" + }, + { + "bom-ref": "8c8d7f41ff1caa14", + "type": "file", + "name": "/lib/libz.so.1.3.2" + }, + { + "bom-ref": "13708919fd945ffa", + "type": "file", + "name": "/lib/sysctl.d/00-alpine.conf" + }, + { + "bom-ref": "b8e9653ba4dfcefa", + "type": "file", + "name": "/sbin/apk" + }, + { + "bom-ref": "72c345c75405efa9", + "type": "file", + "name": "/sbin/ldconfig" + }, + { + "bom-ref": "45178d0710b10089", + "type": "file", + "name": "/usr/bin/getconf" + }, + { + "bom-ref": "b1c82795b6a29b56", + "type": "file", + "name": "/usr/bin/getent" + }, + { + "bom-ref": "d7ba18c69a1c9f75", + "type": "file", + "name": "/usr/bin/iconv" + }, + { + "bom-ref": "5a1e9dd654491ff5", + "type": "file", + "name": "/usr/bin/ldd" + }, + { + "bom-ref": "61c72a83cf3de1a5", + "type": "file", + "name": "/usr/bin/scanelf" + }, + { + "bom-ref": "fd31193927548c38", + "type": "file", + "name": "/usr/bin/ssl_client" + }, + { + "bom-ref": "596094337a9d5cb5", + "type": "file", + "name": "/usr/lib/engines-3/afalg.so" + }, + { + "bom-ref": "cbc84813407d7d65", + "type": "file", + "name": "/usr/lib/engines-3/capi.so" + }, + { + "bom-ref": "c5e52c7c8018e26f", + "type": "file", + "name": "/usr/lib/engines-3/loader_attic.so" + }, + { + "bom-ref": "d183a9f039c01937", + "type": "file", + "name": "/usr/lib/engines-3/padlock.so" + }, + { + "bom-ref": "9263c6bc54fc0212", + "type": "file", + "name": "/usr/lib/ossl-modules/legacy.so" + }, + { + "bom-ref": "4e940b86ce8bb587", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-4a6a0840.rsa.pub" + }, + { + "bom-ref": "7e4862f880e4dc3f", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-5243ef4b.rsa.pub" + }, + { + "bom-ref": "521e0bfb89da8540", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-524d27bb.rsa.pub" + }, + { + "bom-ref": "22210e7bad097cc5", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-5261cecb.rsa.pub" + }, + { + "bom-ref": "c73224490842bf10", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-58199dcc.rsa.pub" + }, + { + "bom-ref": "51f6c7c6354786d4", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-58cbb476.rsa.pub" + }, + { + "bom-ref": "bbd7e11715b9fee7", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-58e4f17d.rsa.pub" + }, + { + "bom-ref": "1ce1d7eb06117f2e", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-5e69ca50.rsa.pub" + }, + { + "bom-ref": "9072f026ca8de515", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-60ac2099.rsa.pub" + }, + { + "bom-ref": "5350974c1c023b5b", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-6165ee59.rsa.pub" + }, + { + "bom-ref": "c53e2e504a30e422", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-61666e3f.rsa.pub" + }, + { + "bom-ref": "074513a088daabef", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-616a9724.rsa.pub" + }, + { + "bom-ref": "7fee1900710c0dec", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-616abc23.rsa.pub" + }, + { + "bom-ref": "a8b8a8115eca1204", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-616ac3bc.rsa.pub" + }, + { + "bom-ref": "8480185278908e6a", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-616adfeb.rsa.pub" + }, + { + "bom-ref": "41ca39bf7e8b0808", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-616ae350.rsa.pub" + }, + { + "bom-ref": "1b9a22727b486aa3", + "type": "file", + "name": "/usr/share/apk/keys/alpine-devel@lists.alpinelinux.org-616db30d.rsa.pub" + }, + { + "bom-ref": "58a73c2f639ded8c", + "type": "file", + "name": "/usr/share/udhcpc/default.script" + } + ] +} \ No newline at end of file diff --git a/test/syft-alpine.json b/test/syft-alpine.json new file mode 100644 index 0000000..18ad57d --- /dev/null +++ b/test/syft-alpine.json @@ -0,0 +1,194 @@ +{ + "descriptor": { + "name": "syft", + "version": "1.55.0" + }, + "schema": { + "version": "16.1.11", + "url": "https://raw.githubusercontent.com/anchore/syft/main/schema/json/schema-16.1.11.json" + }, + "artifacts": [ + { + "name": "alpine-baselayout", + "version": "3.6.5-r0", + "type": "apk", + "purl": "pkg:apk/alpine/alpine-baselayout@3.6.5-r0?arch=aarch64&distro=alpine-3.20.10", + "licenses": [ + { + "value": "GPL-2.0-only", + "spdxExpression": "GPL-2.0-only", + "type": "declared" + } + ] + }, + { + "name": "alpine-baselayout-data", + "version": "3.6.5-r0", + "type": "apk", + "purl": "pkg:apk/alpine/alpine-baselayout-data@3.6.5-r0?arch=aarch64&distro=alpine-3.20.10&upstream=alpine-baselayout", + "licenses": [ + { + "value": "GPL-2.0-only", + "spdxExpression": "GPL-2.0-only", + "type": "declared" + } + ] + }, + { + "name": "alpine-keys", + "version": "2.4-r1", + "type": "apk", + "purl": "pkg:apk/alpine/alpine-keys@2.4-r1?arch=aarch64&distro=alpine-3.20.10", + "licenses": [ + { + "value": "MIT", + "spdxExpression": "MIT", + "type": "declared" + } + ] + }, + { + "name": "apk-tools", + "version": "2.14.4-r1", + "type": "apk", + "purl": "pkg:apk/alpine/apk-tools@2.14.4-r1?arch=aarch64&distro=alpine-3.20.10", + "licenses": [ + { + "value": "GPL-2.0-only", + "spdxExpression": "GPL-2.0-only", + "type": "declared" + } + ] + }, + { + "name": "busybox", + "version": "1.36.1-r31", + "type": "apk", + "purl": "pkg:apk/alpine/busybox@1.36.1-r31?arch=aarch64&distro=alpine-3.20.10", + "licenses": [ + { + "value": "GPL-2.0-only", + "spdxExpression": "GPL-2.0-only", + "type": "declared" + } + ] + }, + { + "name": "busybox-binsh", + "version": "1.36.1-r31", + "type": "apk", + "purl": "pkg:apk/alpine/busybox-binsh@1.36.1-r31?arch=aarch64&distro=alpine-3.20.10&upstream=busybox", + "licenses": [ + { + "value": "GPL-2.0-only", + "spdxExpression": "GPL-2.0-only", + "type": "declared" + } + ] + }, + { + "name": "ca-certificates-bundle", + "version": "20260413-r0", + "type": "apk", + "purl": "pkg:apk/alpine/ca-certificates-bundle@20260413-r0?arch=aarch64&distro=alpine-3.20.10&upstream=ca-certificates", + "licenses": [ + { + "value": "MPL-2.0 AND MIT", + "spdxExpression": "MPL-2.0 AND MIT", + "type": "declared" + } + ] + }, + { + "name": "libcrypto3", + "version": "3.3.7-r0", + "type": "apk", + "purl": "pkg:apk/alpine/libcrypto3@3.3.7-r0?arch=aarch64&distro=alpine-3.20.10&upstream=openssl", + "licenses": [ + { + "value": "Apache-2.0", + "spdxExpression": "Apache-2.0", + "type": "declared" + } + ] + }, + { + "name": "libssl3", + "version": "3.3.7-r0", + "type": "apk", + "purl": "pkg:apk/alpine/libssl3@3.3.7-r0?arch=aarch64&distro=alpine-3.20.10&upstream=openssl", + "licenses": [ + { + "value": "Apache-2.0", + "spdxExpression": "Apache-2.0", + "type": "declared" + } + ] + }, + { + "name": "musl", + "version": "1.2.5-r3", + "type": "apk", + "purl": "pkg:apk/alpine/musl@1.2.5-r3?arch=aarch64&distro=alpine-3.20.10", + "licenses": [ + { + "value": "MIT", + "spdxExpression": "MIT", + "type": "declared" + } + ] + }, + { + "name": "musl-utils", + "version": "1.2.5-r3", + "type": "apk", + "purl": "pkg:apk/alpine/musl-utils@1.2.5-r3?arch=aarch64&distro=alpine-3.20.10&upstream=musl", + "licenses": [ + { + "value": "MIT AND BSD-2-Clause AND GPL-2.0-or-later", + "spdxExpression": "MIT AND BSD-2-Clause AND GPL-2.0-or-later", + "type": "declared" + } + ] + }, + { + "name": "scanelf", + "version": "1.3.7-r2", + "type": "apk", + "purl": "pkg:apk/alpine/scanelf@1.3.7-r2?arch=aarch64&distro=alpine-3.20.10&upstream=pax-utils", + "licenses": [ + { + "value": "GPL-2.0-only", + "spdxExpression": "GPL-2.0-only", + "type": "declared" + } + ] + }, + { + "name": "ssl_client", + "version": "1.36.1-r31", + "type": "apk", + "purl": "pkg:apk/alpine/ssl_client@1.36.1-r31?arch=aarch64&distro=alpine-3.20.10&upstream=busybox", + "licenses": [ + { + "value": "GPL-2.0-only", + "spdxExpression": "GPL-2.0-only", + "type": "declared" + } + ] + }, + { + "name": "zlib", + "version": "1.3.2-r0", + "type": "apk", + "purl": "pkg:apk/alpine/zlib@1.3.2-r0?arch=aarch64&distro=alpine-3.20.10", + "licenses": [ + { + "value": "Zlib", + "spdxExpression": "Zlib", + "type": "declared" + } + ] + } + ] +} \ No newline at end of file diff --git a/website/llms-full.txt b/website/llms-full.txt index af31791..dd10da1 100644 --- a/website/llms-full.txt +++ b/website/llms-full.txt @@ -54,7 +54,7 @@ The managed binary wins when it is present. `gatecheck grype`, `gatecheck syft`, A platform with no release asset for a requested GitHub-hosted tool fails that tool and the command exits 255. A platform with no semgrep wheel prints a skip message on stderr and continues. Current pins are Grype `0.121.0`, Syft `1.55.0`, Gitleaks `8.30.1`, semgrep `1.182.1`, Trivy `0.76.1`, osv-scanner `2.7.0`, gosec `2.30.0`, hadolint `2.15.1`, and zizmor `1.32.0`, in `internal/bootstrap/versions.go`. -Syft is installed so it can write CycloneDX (`syft -o cyclonedx-json`). That BOM is listed and validated as CycloneDX. Native Syft JSON is recognized from `descriptor.name` or the schema URL, and `list` and `validate` then return an error. A filename containing `syft` does the same when the contents are ambiguous. CycloneDX is a report format, and coverage tools are left to the language toolchain. +Syft is installed so it can write CycloneDX (`syft -o cyclonedx-json`). That BOM is listed and validated as CycloneDX. Native Syft JSON is recognized from `descriptor.name` or the schema URL. `list` prints its packages and licenses, and `validate` runs the license rules on it. CycloneDX is a report format, and coverage tools are left to the language toolchain. ## Report type @@ -66,7 +66,7 @@ Content rules, in this order: 2. `bomFormat` of `CycloneDX` is CycloneDX JSON. This wins when the name contains `grype` or `syft`, and it wins when the tool that wrote the BOM was Grype, Syft, Trivy, or another tool. CycloneDX XML is not read. 3. SARIF 2.1.0. The top-level `version` is the string `2.1.0` and `runs` is an array. A `$schema` that mentions SARIF is enough when `runs` is missing or null. Another version returns an error when the name says `sarif`. 4. Grype JSON. `descriptor.name` is `grype`, or `matches` is a non-empty array of objects with `vulnerability` and `artifact`. -5. Syft JSON. `descriptor.name` is `syft`, or `schema.url` points at the Syft schema. `list` and `validate` then return an error. Syft JSON is not implemented. A Syft CycloneDX BOM is CycloneDX, not Syft. +5. Syft JSON. `descriptor.name` is `syft`, or `schema.url` points at the Syft schema. `list` prints packages and licenses, and `validate` runs the license rules. A Syft CycloneDX BOM is CycloneDX, not Syft. 6. Semgrep JSON. `results` is an array of objects with `check_id`, or `results` and `errors` are both arrays. Semgrep's SARIF output is SARIF, not this type. 7. Gitleaks JSON. A non-empty array of objects with `RuleID` and one of `File`, `Commit`, or `Fingerprint`. 8. Trivy JSON. `SchemaVersion` is a number, and `ArtifactType` is set or `Results` is an array. Vulnerability entries are listed and validated. Misconfigurations, secrets, and licenses are ignored. A CycloneDX BOM from Trivy is CycloneDX. @@ -98,7 +98,7 @@ From standard input, `list` requires `-i` / `--input-type`, so the command does `list-all` lists a file when the contents or the name identify Grype, Semgrep, Gitleaks, Syft, CycloneDX, SARIF, Trivy, osv-scanner, or a bundle. Coverage files are skipped with a warning. There is no `--input-type` on `list-all`. -Inside a bundle, `validate` uses the same content rules on each stored file, and falls back to the label. The label is the base name of the file that was added. Labels that still do not match are skipped. Syft JSON inside a bundle is skipped. +Inside a bundle, `validate` uses the same content rules on each stored file, and falls back to the label. The label is the base name of the file that was added. Labels that still do not match are skipped. Syft JSON inside a bundle is checked with the license rules. ## Config @@ -112,7 +112,7 @@ gatecheck config convert --file gatecheck.yaml --output toml `config convert` reads `-f` / `--file` (default `gatecheck.yaml`). The extension selects the decoder: `.yaml`, `.yml`, `.json`, or `.toml`. -A partial file is fine. Omitted fields keep the default. Unknown keys are ignored. With no config, `validate` uses the built-in default: every rule disabled, coverage thresholds `0`. Grype, CycloneDX, Trivy, osv-scanner, SARIF, Semgrep, Gitleaks, coverage, and bundle reports pass under that default. Syft JSON still returns an error. An old config with no `sarif` section leaves those limits disabled. +A partial file is fine. Omitted fields keep the default. Unknown keys are ignored. With no config, `validate` uses the built-in default: every rule disabled, coverage thresholds `0`. Grype, CycloneDX, Trivy, osv-scanner, SARIF, Semgrep, Gitleaks, coverage, and bundle reports pass under that default. Syft JSON passes too, since the license rules are off by default. An old config with no `sarif` section leaves those limits disabled. `GATECHECK_CONFIG_FILENAME` is the same setting as `validate --config` / `-f`. @@ -135,13 +135,17 @@ Field names below are the ones `config init` emits. In YAML they are case sensit - `severityLimit` has `critical`, `high`, `medium`, and `low`. Each has `enabled` and `limit`, with the same count rule as Grype. The severity comes from the SARIF property `security-severity` when a result or its rule has one. The value is a number from 0 to 10, or a numeric string. 9.0 and above is critical, 7.0 to 8.9 is high, 4.0 to 6.9 is medium, above 0 and below 4.0 is low, and 0 is none. A result property wins over the same property on the rule. When neither is set, gatecheck uses the SARIF level. A missing result level uses the rule's `defaultConfiguration.level`, then `warning`. `error` is high, `warning` is medium, `note` is low, and `none` is ignored. - `ruleLimit` and `ruleRiskAcceptance` each have `enabled` and `rules`. A rule entry is `id` plus an optional `metadata.tags` list. `id` is compared without regard to case. `ruleLimit` denies those ids. `ruleRiskAcceptance` removes them. +`license` gates package licenses in Syft JSON and CycloneDX BOMs. `enabled` turns it on. `deny` and `allow` are case-insensitive glob patterns such as `GPL-*`, which matches `GPL-3.0-only` but not `LGPL-2.1-only`. A non-empty `allow` fails every license outside it. `denyUnknown` fails packages with no license, `NOASSERTION`, or `NONE`. `packageRiskAcceptance` entries skip a package by `purl` (type, namespace, and name, plus version when given) or by `name`. SPDX expressions are evaluated: `OR` passes when either side passes, `AND` needs both, and `X WITH Y` is denied when `X` is denied unless `allow` names the full `X WITH Y`. Several license entries on one package must all pass. Syft licenses are `spdxExpression`, then `value`. CycloneDX licenses are `expression`, `license.id`, then `license.name`, and nested components are included. A CycloneDX BOM runs both the license and vulnerability rules, and reports both failures. + +`vex.files` lists OpenVEX or CycloneDX VEX documents, read along with `--vex`. + `coverage.lineThreshold`, `functionThreshold`, and `branchThreshold` are ratios from 0 to 1: covered lines, functions, or branches divided by the total. The report fails when its ratio is less than the threshold. A ratio equal to the threshold passes. `0.8` is 80 percent. `80` fails a report whose real line coverage is 0.8, because 0.8 is less than 80. There is no `enabled` flag. The default `0` allows any coverage, because a ratio is never less than 0. `list` prints these numbers as percents in the table footer. The config still wants the ratio. A report with no records of a kind, such as LCOV without branch records, has no ratio for it. `list` prints `N/A`, and `validate` skips that threshold with a warning. Grype, CycloneDX, Trivy, and osv-scanner rules run in this order. A failure returns immediately, except where a rule only removes findings. Trivy counts vulnerability entries only. osv-scanner counts one finding per group. 1. CVE limit, when enabled. 2. Disabled Grype, Trivy, and osv-scanner severities are dropped. If the EPSS limit is also enabled, a finding at a disabled severity stays when its EPSS score is greater than or equal to that limit. CycloneDX leaves findings at a disabled severity in the report. -3. CVE risk acceptance removes matching ids. +3. CVE risk acceptance removes matching ids. VEX statements that mark a finding not exploitable remove it here too. 4. KEV limit, when `kevLimitEnabled` is true. 5. EPSS risk acceptance. 6. EPSS limit. @@ -260,6 +264,6 @@ Create the config with `gatecheck config init > gatecheck.yaml` and set real thr - `validate` takes the report as its positional argument. The config is `--config` / `-f`. `gatecheck validate gatecheck.yaml grype-report.json` tries to open the config as a report. `config convert` uses `--file` / `-f`, which is a different flag. - `list` on a pipe needs `--input-type`. Clear contents still win over that flag. `validate` needs a filesystem path. - `list` ignores every filename after the first. Use `list-all` for several files. `list-all` skips coverage files such as `lcov.info`. List those with `gatecheck list lcov.info`. -- Native Syft JSON is recognized and then returns an error. Use CycloneDX output from Syft when you want `validate` to score it. That BOM is CycloneDX even when the filename contains `syft`. +- Native Syft JSON gets only the license rules. Use CycloneDX output when you also want vulnerabilities scored. That BOM is CycloneDX even when the filename contains `syft`. - `gatecheck semgrep --version` reaches osemgrep without `--experimental`, and osemgrep then tries to run `pysemgrep`. Pass the flag: `gatecheck semgrep --experimental --version`. - `--audit` still exits 255 when the report, the config, or a named EPSS or KEV file cannot be opened. diff --git a/website/llms.txt b/website/llms.txt index 4e7a392..d77fceb 100644 --- a/website/llms.txt +++ b/website/llms.txt @@ -14,6 +14,7 @@ Report type comes from the file contents. The filename is the fallback when the - [Configuration](https://docs.gatecheck.dev/configuration.html): config keys and threshold units - [Validation](https://docs.gatecheck.dev/validation.html): rule order and exit codes - [VEX](https://docs.gatecheck.dev/vex.html): skip findings an OpenVEX or CycloneDX VEX file marks not exploitable +- [License gating](https://docs.gatecheck.dev/licenses.html): fail SBOMs with denied, unlisted, or missing licenses - [List reports](https://docs.gatecheck.dev/list-reports.html): tables, standard input, and EPSS columns - [Bundles](https://docs.gatecheck.dev/gatecheck-bundle.html): create, add, and remove - [Examples](https://docs.gatecheck.dev/examples.html): config, bundle, audit, and standard input From 307061ef8a79f4d16fe4a811442913354cdd1166 Mon Sep 17 00:00:00 2001 From: "Bacchus Jackson (BJaX)" <34331871+BacchusJackson@users.noreply.github.com> Date: Wed, 4 Nov 2026 12:37:16 -0600 Subject: [PATCH 3/3] Modernize CLI config and drop configkit Build a fresh command tree per call and read every setting flag, then environment variable, then default. Remove configkit and Viper. - Exit 2 for usage, IO, and decode errors and 3 for EPSS or KEV data errors. --audit only ignores threshold failures. - --log-level and --log-format on every command. --silent keeps warnings. - --format table|markdown|json on list, list-all, and validate. - validate gains --input-type (with stdin), --epss-url, and --kev-url. list-all gains --epss-filename and --epss-url. - One config encoder and decoder. config init indents, and unknown keys are reported as warnings. validate warns when there is no config. - Coverage thresholds over 1 are read as percents. - Fix the env var panics, the KEV file reading GATECHECK_EPSS_FILENAME, bundle create not truncating, bundle remove of a missing label exiting 0, and the case-sensitive Grype KEV compare. Fixes #73 --- AGENTS.md | 6 +- CHANGELOG.md | 30 +++ cmd/bundle.go | 168 ++++++++--------- cmd/cli-config.go | 236 ----------------------- cmd/cli_test.go | 355 +++++++++++++++++++++++++++++++++++ cmd/config.go | 109 +++++------ cmd/download.go | 52 +++-- cmd/download_test.go | 12 -- cmd/fetch.go | 78 ++++++++ cmd/gatecheck/main.go | 34 +--- cmd/gatecheck/main_test.go | 28 ++- cmd/list.go | 271 +++++++++++++------------- cmd/logging.go | 113 +++++++++++ cmd/root.go | 200 ++++++++++---------- cmd/settings.go | 87 +++++++++ cmd/update.go | 11 -- cmd/update_test.go | 18 +- cmd/validate.go | 218 ++++++++++++++------- docs/agent-guide.md | 58 +++--- docs/bootstrap.md | 4 +- docs/cli-reference.md | 92 ++++++--- docs/configuration.md | 4 +- docs/examples.md | 2 +- docs/gatecheck-bundle.md | 2 +- docs/library-usage.md | 9 +- docs/list-reports.md | 9 +- docs/usage.md | 9 +- docs/validation.md | 21 ++- docs/vex.md | 2 +- go.mod | 15 +- go.sum | 29 +-- pkg/epss/epss.go | 7 +- pkg/format/json.go | 93 +++++++++ pkg/gatecheck/bundle.go | 8 + pkg/gatecheck/config.go | 199 +++++++++++++------- pkg/gatecheck/config_test.go | 91 +++++++++ pkg/gatecheck/download.go | 11 +- pkg/gatecheck/list.go | 42 ++++- pkg/gatecheck/osv.go | 3 +- pkg/gatecheck/trivy.go | 3 +- pkg/gatecheck/validate.go | 24 ++- website/llms-full.txt | 58 +++--- 42 files changed, 1791 insertions(+), 1030 deletions(-) delete mode 100644 cmd/cli-config.go create mode 100644 cmd/cli_test.go create mode 100644 cmd/fetch.go create mode 100644 cmd/logging.go create mode 100644 cmd/settings.go create mode 100644 pkg/format/json.go create mode 100644 pkg/gatecheck/config_test.go diff --git a/AGENTS.md b/AGENTS.md index b1f068a..d03b842 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ This file is for agents changing the gatecheck repository. To use the gatecheck ## Layout -- `cmd/`: Cobra commands. `cmd/gatecheck` is `main`. `newCommand` wires flags. Command behavior that is not flag parsing lives in `pkg/gatecheck`. +- `cmd/`: Cobra commands. `cmd/gatecheck` is `main`. `newCommand` builds the command and its flags. Command behavior that is not flag parsing lives in `pkg/gatecheck`. - `internal/fetch`: download and SHA-256 checks. `internal/bootstrap`: scanner install and passthrough. Pinned versions are the constants in `internal/bootstrap/versions.go`. - `pkg/`: report decoding, validation, bundles, EPSS, and KEV. - `docs/`: mdBook source for docs.gatecheck.dev. `docs/agent-guide.md` is the agent guide embedded by `docs/embed.go`. @@ -26,5 +26,7 @@ This file is for agents changing the gatecheck repository. To use the gatecheck - Check `gatecheck --help` before describing a flag. `docs/cli-reference.md` matches the CLI on main. - Report type is detected from file contents. A lowercase filename substring is the fallback when the contents are ambiguous. See `docs/supported-reports.md`. - Coverage thresholds and EPSS scores are ratios from 0 to 1. -- Exit codes from `cmd/gatecheck`: 0 success, 1 threshold failure (`gatecheck.ErrValidationFailure`), 255 any other error (`os.Exit(-1)`). `grype`, `syft`, `gitleaks`, `semgrep`, `osemgrep`, `trivy`, and `osv-scanner` return the scanner's status. A missing scanner still exits 255. +- Exit codes come from `cmd.ExitCode`: 0 success, 1 threshold failure (`gatecheck.ErrValidationFailure`), 3 EPSS or KEV data failure (`gatecheck.ErrExternalData`), 2 any other error. The scanner passthrough commands return the scanner's status. A missing scanner exits 2. +- `cmd.NewGatecheckCommand` builds a new command tree on each call. Keep command state in the command's flags, not package variables. Settings are read flag, then `GATECHECK_*` environment variable, then default, through the helpers in `cmd/settings.go`. +- Tests in `cmd/cli_test.go` run the real command tree. Add a case there for a new flag or exit path. - Do not add copyright notices. diff --git a/CHANGELOG.md b/CHANGELOG.md index 8d818e6..c0d1004 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,14 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [UNRELEASED] +This release reworks the CLI settings layer and changes exit codes. See Changed. Fixes #73. + ### Added +- `--log-level debug|info|warn|error` and `--log-format text|json` on every command, with `GATECHECK_LOG_LEVEL` and `GATECHECK_LOG_FORMAT`. Text logs are colored only on a terminal, and `NO_COLOR` turns color off. +- `validate --format table|markdown|json` prints the result to stdout. `list` and `list-all` take `--format table|markdown|json`. `list-all --format json` is one array keyed by file. +- `validate --input-type`, and `validate` reads stdin when FILE is omitted and `--input-type` is set. +- `validate --epss-url` and `--kev-url`. `list-all --epss-filename` and `--epss-url`. +- `GATECHECK_KEV_FILENAME` sets `--kev-filename`. +- `validate` warns when there is no config, and when the config has keys gatecheck does not read. `config convert` warns about those keys too. + - `gatecheck bootstrap --tools gosec,hadolint,zizmor` installs pinned gosec 2.30.0, hadolint 2.15.1, and zizmor 1.32.0. `gatecheck gosec`, `gatecheck hadolint`, and `gatecheck zizmor` run them. Their SARIF output is gated with the `sarif` config section. They are not part of the default install. zizmor publishes no checksum file, so its asset digests are pinned in gatecheck. - `gatecheck bootstrap --list` shows every supported tool. - The `license` config section fails Syft JSON and CycloneDX SBOMs whose package licenses match `deny` patterns, fall outside a non-empty `allow` list, or are missing when `denyUnknown` is set. SPDX `AND`, `OR`, and `WITH` expressions are evaluated. `packageRiskAcceptance` skips packages by purl or name. Fixes #103. - `list` prints the packages and licenses in Syft JSON, and `validate` and bundles check Syft JSON with the license rules. Both used to return an error. - `validate --vex FILE`, `GATECHECK_VEX`, and the config's `vex.files` read OpenVEX and CycloneDX VEX documents. Grype, CycloneDX, Trivy, and osv-scanner findings marked `not_affected`, `fixed`, `false_positive`, or `resolved` are skipped before the KEV, EPSS, and severity rules. A statement that names packages matches by package URL. The latest statement wins. Fixes #102. +### Changed + +- Exit codes: 2 for usage errors, files that cannot be read or written, and reports, configs, or VEX files that cannot be decoded; 3 when EPSS or KEV data cannot be loaded. These used to be 255. A missing scanner for a passthrough command also exits 2. +- `--audit` only turns a threshold failure into exit 0. Unsupported reports, decode errors, and EPSS or KEV failures now fail in audit mode too. +- `--silent` keeps warnings. It used to show errors only. Use `--log-level error` for the old behavior. +- Coverage thresholds over 1 are read as percents, so `80` means `0.8`, with a warning. +- `config init` and `config convert` indent JSON and YAML by two spaces, and indent TOML tables. JSON config files write `metadata` for CVE entries instead of `Metadata`. Both spellings are read. +- `list-all` exits 2 when a file cannot be read or listed. It still lists the other files first. It loads EPSS data once per run instead of once per file. +- `bundle remove` of a label that is not in the bundle exits 2 and leaves the bundle unchanged. +- Each run builds a new command tree. configkit and Viper are gone. Settings are read flag, then environment variable, then default. + +### Fixed + +- `GATECHECK_VERBOSE`, `GATECHECK_SILENT`, and `GATECHECK_AUDIT` panicked on any value. They now take booleans, and a bad value is a usage error. +- `--audit=false` lost to `GATECHECK_AUDIT=true`. A flag now wins over its variable. +- The KEV file setting read `GATECHECK_EPSS_FILENAME`, so setting that variable made `validate` read the EPSS CSV as KEV. +- `bundle create` did not truncate an existing file, and `bundle add` and `bundle remove` could leave old bytes after a shorter bundle. +- The Grype KEV rule compared ids with case. It now ignores case and also checks a match's related CVE ids. +- EPSS CSV files with a `+0000` offset in the `score_date` header failed to parse. +- Config files are closed after reading. The EPSS and KEV files passed to `validate` and `list` are closed when the command ends. + ## [0.10.0] - 2026-10-30 ### Added diff --git a/cmd/bundle.go b/cmd/bundle.go index e244593..a1adb7d 100644 --- a/cmd/bundle.go +++ b/cmd/bundle.go @@ -1,7 +1,7 @@ package cmd import ( - "log/slog" + "io" "os" "path" @@ -9,100 +9,90 @@ import ( "github.com/spf13/cobra" ) -var bundleCmd = &cobra.Command{ - Use: "bundle", - Short: "create and manage a gatecheck bundle", -} - -var bundleCreateCmd = &cobra.Command{ - Use: "create BUNDLE_FILE TARGET_FILE", - Short: "create a new bundle with a new file", - Aliases: []string{"init"}, - Args: cobra.ExactArgs(2), - PreRunE: func(cmd *cobra.Command, args []string) error { - bundleFilename := args[0] - targetFilename := args[1] - - bundleFile, err := os.OpenFile(bundleFilename, os.O_CREATE|os.O_WRONLY, 0o644) - if err != nil { - return err - } - targetFile, err := os.Open(targetFilename) - if err != nil { - return err - } +func newBundleCommand() *cobra.Command { + bundleCmd := &cobra.Command{ + Use: "bundle", + Short: "create and manage a gatecheck bundle", + } - RuntimeConfig.bundleFile = bundleFile - RuntimeConfig.targetFile = targetFile - RuntimeConfig.BundleTagValue = RuntimeConfig.BundleTag.Value().([]string) - return nil - }, - RunE: func(cmd *cobra.Command, args []string) error { - targetFilename := args[1] - label := path.Base(targetFilename) - bf, tf := RuntimeConfig.bundleFile, RuntimeConfig.targetFile - tags := RuntimeConfig.BundleTagValue - return gatecheck.CreateBundle(bf, tf, label, tags) - }, -} + createCmd := &cobra.Command{ + Use: "create BUNDLE_FILE TARGET_FILE", + Short: "create a new bundle with one file, replacing BUNDLE_FILE if it exists", + Aliases: []string{"init"}, + Args: cobra.ExactArgs(2), + RunE: func(cmd *cobra.Command, args []string) error { + target, err := os.Open(args[1]) + if err != nil { + return err + } + defer func() { _ = target.Close() }() + bundleFile, err := os.OpenFile(args[0], os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o644) + if err != nil { + return err + } + err = gatecheck.CreateBundle(bundleFile, target, path.Base(args[1]), stringSliceSetting(cmd, "tag", "GATECHECK_BUNDLE_TAG")) + return closeAfter(bundleFile, err) + }, + } -var bundleAddCmd = &cobra.Command{ - Use: "add BUNDLE_FILE TARGET_FILE", - Short: "add a file to a bundle", - Args: cobra.ExactArgs(2), - PreRunE: func(cmd *cobra.Command, args []string) error { - bundleFilename := args[0] - targetFilename := args[1] + addCmd := &cobra.Command{ + Use: "add BUNDLE_FILE TARGET_FILE", + Short: "add a file to a bundle", + Args: cobra.ExactArgs(2), + RunE: func(cmd *cobra.Command, args []string) error { + target, err := os.Open(args[1]) + if err != nil { + return err + } + defer func() { _ = target.Close() }() + bundleFile, err := os.OpenFile(args[0], os.O_RDWR, 0o644) + if err != nil { + return err + } + err = gatecheck.AppendToBundle(bundleFile, target, path.Base(args[1]), stringSliceSetting(cmd, "tag", "GATECHECK_BUNDLE_TAG")) + return closeAfter(bundleFile, truncateAtOffset(bundleFile, err)) + }, + } - bundleFile, err := os.OpenFile(bundleFilename, os.O_RDWR, 0o644) - if err != nil { - return err - } - targetFile, err := os.Open(targetFilename) - if err != nil { - return err - } + removeCmd := &cobra.Command{ + Use: "remove BUNDLE_FILE LABEL", + Short: "remove a file from a bundle by label", + Aliases: []string{"rm"}, + Args: cobra.ExactArgs(2), + RunE: func(cmd *cobra.Command, args []string) error { + bundleFile, err := os.OpenFile(args[0], os.O_RDWR, 0o644) + if err != nil { + return err + } + err = gatecheck.RemoveFromBundle(bundleFile, args[1]) + return closeAfter(bundleFile, truncateAtOffset(bundleFile, err)) + }, + } - RuntimeConfig.bundleFile = bundleFile - RuntimeConfig.targetFile = targetFile - RuntimeConfig.BundleTagValue = RuntimeConfig.BundleTag.Value().([]string) - return nil - }, - RunE: func(cmd *cobra.Command, args []string) error { - targetFilename := args[1] - slog.Info("bundle tag", "environment", os.Getenv("GATECHECK_BUNDLE_TAG")) - label := path.Base(targetFilename) - bf, tf := RuntimeConfig.bundleFile, RuntimeConfig.targetFile - tags := RuntimeConfig.BundleTagValue - return gatecheck.AppendToBundle(bf, tf, label, tags) - }, + for _, c := range []*cobra.Command{createCmd, addCmd} { + c.Flags().StringSliceP("tag", "t", nil, "tags for the added file, repeatable or comma-separated (env GATECHECK_BUNDLE_TAG)") + } + bundleCmd.AddCommand(createCmd, addCmd, removeCmd) + return bundleCmd } -var bundleRemoveCmd = &cobra.Command{ - Use: "remove BUNDLE_FILE TARGET_FILE", - Short: "remove a file from a bundle by label", - Aliases: []string{"rm"}, - Args: cobra.ExactArgs(2), - PreRunE: func(cmd *cobra.Command, args []string) error { - bundleFilename := args[0] - - bundleFile, err := os.OpenFile(bundleFilename, os.O_RDWR, 0o644) - if err != nil { - return err - } - RuntimeConfig.bundleFile = bundleFile - return nil - }, - RunE: func(cmd *cobra.Command, args []string) error { - label := args[1] - return gatecheck.RemoveFromBundle(RuntimeConfig.bundleFile, label) - }, +// truncateAtOffset drops bytes left over from a longer old bundle after it +// was rewritten in place. +func truncateAtOffset(f *os.File, err error) error { + if err != nil { + return err + } + offset, err := f.Seek(0, io.SeekCurrent) + if err != nil { + return err + } + return f.Truncate(offset) } -func newBundleCommand() *cobra.Command { - RuntimeConfig.BundleTag.SetupCobra(bundleCreateCmd) - RuntimeConfig.BundleTag.SetupCobra(bundleAddCmd) - - bundleCmd.AddCommand(bundleCreateCmd, bundleAddCmd, bundleRemoveCmd) - return bundleCmd +func closeAfter(f *os.File, err error) error { + closeErr := f.Close() + if err != nil { + return err + } + return closeErr } diff --git a/cmd/cli-config.go b/cmd/cli-config.go deleted file mode 100644 index 4848441..0000000 --- a/cmd/cli-config.go +++ /dev/null @@ -1,236 +0,0 @@ -package cmd - -import ( - "io" - "os" - "strings" - - "github.com/gatecheckdev/configkit" - "github.com/gatecheckdev/gatecheck/pkg/gatecheck" - "github.com/spf13/cobra" -) - -var ( - metadataFlagUsage = "flag_usage" - metadataFieldType = "field_type" - metadataActionInputName = "action_input_name" - // metadataRequired = "required" -) - -type metaConfig struct { - BundleTag configkit.MetaField - EPSSURL configkit.MetaField - KEVURL configkit.MetaField - EPSSFilename configkit.MetaField - EPSSCacheDir configkit.MetaField - EPSSNoCache configkit.MetaField - KEVFilename configkit.MetaField - Verbose configkit.MetaField - Silent configkit.MetaField - ConfigFilename configkit.MetaField - Audit configkit.MetaField - BundleTagValue []string - bundleFile *os.File - targetFile *os.File - epssFile *os.File - kevFile *os.File - listSrcReader io.Reader - listSrcName string - listFormat string - gatecheckConfig *gatecheck.Config - // listAll bool - // configOutputWriter io.Writer - // configOutputFormat string -} - -var RuntimeConfig = metaConfig{ - BundleTag: configkit.MetaField{ - FieldName: "BundleTag", - EnvKey: "GATECHECK_BUNDLE_TAG", - DefaultValue: []string{}, - FlagValueP: new([]string), - EnvToValueFunc: func(s string) any { - return strings.Split(s, ",") - }, - Metadata: map[string]string{ - metadataFlagUsage: "file properties for metadata", - metadataFieldType: "string", - metadataActionInputName: "bundle_tag", - }, - CobraSetupFunc: func(f configkit.MetaField, cmd *cobra.Command) { - valueP := f.FlagValueP.(*[]string) - usage := f.Metadata[metadataFlagUsage] - cmd.Flags().StringSliceVarP(valueP, "tag", "t", []string{}, usage) - }, - }, - EPSSURL: configkit.MetaField{ - FieldName: "EPSSURL", - EnvKey: "GATECHECK_EPSS_URL", - DefaultValue: "", - FlagValueP: new(string), - CobraSetupFunc: func(f configkit.MetaField, cmd *cobra.Command) { - valueP := f.FlagValueP.(*string) - usage := f.Metadata[metadataFlagUsage] - cmd.Flags().StringVar(valueP, "epss-url", "", usage) - }, - Metadata: map[string]string{ - metadataFlagUsage: "The url for the FIRST.org EPSS API (\"\" will use FIRST.org official API)", - metadataFieldType: "string", - metadataActionInputName: "epss_url", - }, - }, - KEVURL: configkit.MetaField{ - FieldName: "KEVURL", - EnvKey: "GATECHECK_KEV_URL", - DefaultValue: "", - FlagValueP: new(string), - CobraSetupFunc: func(f configkit.MetaField, cmd *cobra.Command) { - valueP := f.FlagValueP.(*string) - usage := f.Metadata[metadataFlagUsage] - cmd.Flags().StringVar(valueP, "kev-url", "", usage) - }, - Metadata: map[string]string{ - metadataFlagUsage: "The url for the CISA KEV API (\"\" will use CISA Official API)", - metadataFieldType: "string", - metadataActionInputName: "kev_url", - }, - }, - EPSSFilename: configkit.MetaField{ - FieldName: "EPSSFilename", - EnvKey: "GATECHECK_EPSS_FILENAME", - DefaultValue: "", - FlagValueP: new(string), - CobraSetupFunc: func(f configkit.MetaField, cmd *cobra.Command) { - valueP := f.FlagValueP.(*string) - usage := f.Metadata[metadataFlagUsage] - cmd.Flags().StringVar(valueP, "epss-filename", "", usage) - }, - Metadata: map[string]string{ - metadataFlagUsage: "the filename for a FIRST.org EPSS csv file", - metadataFieldType: "string", - metadataActionInputName: "epss_filename", - }, - }, - EPSSCacheDir: configkit.MetaField{ - FieldName: "EPSSCacheDir", - EnvKey: "GATECHECK_EPSS_CACHE_DIR", - DefaultValue: "", - FlagValueP: new(string), - CobraSetupFunc: func(f configkit.MetaField, cmd *cobra.Command) { - valueP := f.FlagValueP.(*string) - usage := f.Metadata[metadataFlagUsage] - cmd.Flags().StringVar(valueP, "epss-cache-dir", "", usage) - }, - Metadata: map[string]string{ - metadataFlagUsage: "cache directory for EPSS downloads (default: user cache dir, env GATECHECK_EPSS_CACHE_DIR)", - metadataFieldType: "string", - metadataActionInputName: "epss_cache_dir", - }, - }, - EPSSNoCache: configkit.MetaField{ - FieldName: "EPSSNoCache", - DefaultValue: false, - FlagValueP: new(bool), - CobraSetupFunc: func(f configkit.MetaField, cmd *cobra.Command) { - valueP := f.FlagValueP.(*bool) - usage := f.Metadata[metadataFlagUsage] - cmd.Flags().BoolVar(valueP, "epss-no-cache", false, usage) - }, - Metadata: map[string]string{ - metadataFlagUsage: "download EPSS on every run instead of using the local cache (env GATECHECK_EPSS_CACHE=off)", - metadataFieldType: "bool", - metadataActionInputName: "epss_no_cache", - }, - }, - KEVFilename: configkit.MetaField{ - FieldName: "KEVFilename", - EnvKey: "GATECHECK_EPSS_FILENAME", - DefaultValue: "", - FlagValueP: new(string), - CobraSetupFunc: func(f configkit.MetaField, cmd *cobra.Command) { - valueP := f.FlagValueP.(*string) - usage := f.Metadata[metadataFlagUsage] - cmd.Flags().StringVar(valueP, "kev-filename", "", usage) - }, - Metadata: map[string]string{ - metadataFlagUsage: "the filename for a FIRST.org KEV json file", - metadataFieldType: "string", - metadataActionInputName: "kev_filename", - }, - }, - Verbose: configkit.MetaField{ - FieldName: "Verbose", - EnvKey: "GATECHECK_VERBOSE", - DefaultValue: false, - FlagValueP: new(bool), - CobraSetupFunc: func(f configkit.MetaField, cmd *cobra.Command) { - valueP := f.FlagValueP.(*bool) - usage := f.Metadata[metadataFlagUsage] - cmd.PersistentFlags().BoolVarP(valueP, "verbose", "v", false, usage) - }, - Metadata: map[string]string{ - metadataFlagUsage: "log level set to debug", - metadataFieldType: "bool", - metadataActionInputName: "verbose", - }, - }, - Silent: configkit.MetaField{ - FieldName: "Silent", - EnvKey: "GATECHECK_SILENT", - DefaultValue: false, - FlagValueP: new(bool), - CobraSetupFunc: func(f configkit.MetaField, cmd *cobra.Command) { - valueP := f.FlagValueP.(*bool) - usage := f.Metadata[metadataFlagUsage] - cmd.PersistentFlags().BoolVar(valueP, "silent", false, usage) - }, - Metadata: map[string]string{ - metadataFlagUsage: "log level set to only warnings & errors", - metadataFieldType: "bool", - metadataActionInputName: "silent", - }, - }, - ConfigFilename: configkit.MetaField{ - FieldName: "ConfigFilename", - EnvKey: "GATECHECK_CONFIG_FILENAME", - DefaultValue: "", - FlagValueP: new(string), - CobraSetupFunc: func(f configkit.MetaField, cmd *cobra.Command) { - valueP := f.FlagValueP.(*string) - usage := f.Metadata[metadataFlagUsage] - cmd.PersistentFlags().StringVarP(valueP, "config", "f", "", usage) - }, - Metadata: map[string]string{ - metadataFlagUsage: "a validation configuration file", - metadataFieldType: "string", - metadataActionInputName: "config_filename", - }, - }, - Audit: configkit.MetaField{ - FieldName: "Audit", - EnvKey: "GATECHECK_AUDIT", - DefaultValue: false, - FlagValueP: new(bool), - CobraSetupFunc: func(f configkit.MetaField, cmd *cobra.Command) { - valueP := f.FlagValueP.(*bool) - usage := f.Metadata[metadataFlagUsage] - cmd.PersistentFlags().BoolVarP(valueP, "audit", "a", false, usage) - }, - Metadata: map[string]string{ - metadataFlagUsage: "audit mode - will run all rules but wil always exit 0 for validation failures", - metadataFieldType: "bool", - metadataActionInputName: "audit", - }, - }, -} - -func epssCacheOptions() []gatecheck.Option { - var opts []gatecheck.Option - if p, ok := RuntimeConfig.EPSSNoCache.FlagValueP.(*bool); ok && p != nil && *p { - opts = append(opts, gatecheck.WithEPSSCache(false)) - } - if p, ok := RuntimeConfig.EPSSCacheDir.FlagValueP.(*string); ok && p != nil && strings.TrimSpace(*p) != "" { - opts = append(opts, gatecheck.WithEPSSCacheDir(*p)) - } - return opts -} diff --git a/cmd/cli_test.go b/cmd/cli_test.go new file mode 100644 index 0000000..c018ba0 --- /dev/null +++ b/cmd/cli_test.go @@ -0,0 +1,355 @@ +package cmd + +import ( + "bytes" + "encoding/json" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/gatecheckdev/gatecheck/pkg/archive" +) + +const ( + grypeReport = "../test/grype-report.json" + kevJSON = "../test/known_exploited_vulnerabilities.json" + epssCSV = "../test/epss_scores-2023-06-01.csv" +) + +type result struct { + stdout, stderr string + code int +} + +// run executes a fresh command tree, the same way main does. +func run(t *testing.T, stdin string, args ...string) result { + t.Helper() + var out, errb bytes.Buffer + root := NewGatecheckCommand() + root.SetOut(&out) + root.SetErr(&errb) + root.SetIn(strings.NewReader(stdin)) + root.SetArgs(args) + err := root.Execute() + return result{stdout: out.String(), stderr: errb.String(), code: ExitCode(err)} +} + +func writeFile(t *testing.T, name, body string) string { + t.Helper() + path := filepath.Join(t.TempDir(), name) + if err := os.WriteFile(path, []byte(body), 0o600); err != nil { + t.Fatal(err) + } + return path +} + +func clearEnv(t *testing.T) { + t.Helper() + for _, key := range []string{ + "GATECHECK_CONFIG_FILENAME", "GATECHECK_AUDIT", "GATECHECK_VERBOSE", "GATECHECK_SILENT", + "GATECHECK_LOG_LEVEL", "GATECHECK_LOG_FORMAT", "GATECHECK_EPSS_FILENAME", "GATECHECK_KEV_FILENAME", + "GATECHECK_EPSS_URL", "GATECHECK_KEV_URL", "GATECHECK_VEX", "GATECHECK_BUNDLE_TAG", + } { + t.Setenv(key, "") + } +} + +const criticalLimit = "version: \"1\"\ngrype:\n severityLimit:\n critical:\n enabled: true\n limit: 0\n" + +func TestFreshCommandTreePerCall(t *testing.T) { + a, b := NewGatecheckCommand(), NewGatecheckCommand() + if a == b { + t.Fatal("same root returned twice") + } + findA, _, _ := a.Find([]string{"validate"}) + findB, _, _ := b.Find([]string{"validate"}) + if findA == findB { + t.Fatal("validate command is shared between trees") + } + if err := findA.Flags().Set("audit", "true"); err != nil { + t.Fatal(err) + } + if findB.Flags().Lookup("audit").Value.String() != "false" { + t.Fatal("flag value leaked between trees") + } +} + +func TestValidateExitCodes(t *testing.T) { + clearEnv(t) + config := writeFile(t, "gatecheck.yaml", criticalLimit) + + if r := run(t, "", "validate", "-f", config, grypeReport); r.code != ExitValidation { + t.Fatalf("threshold failure: %+v", r) + } + if r := run(t, "", "validate", "--audit", "-f", config, grypeReport); r.code != ExitOK || !strings.Contains(r.stderr, "validation failure") { + t.Fatalf("audit should exit 0 and print the failure: %+v", r) + } + if r := run(t, "", "validate", "--audit", "-f", config, "missing.json"); r.code != ExitUsage { + t.Fatalf("audit must not hide a missing file: %+v", r) + } + if r := run(t, "", "validate", "--audit", "-f", "missing.yaml", grypeReport); r.code != ExitUsage { + t.Fatalf("missing config: %+v", r) + } + if r := run(t, "", "validate", "--bogus"); r.code != ExitUsage { + t.Fatalf("bad flag: %+v", r) + } + if r := run(t, "", "validate"); r.code != ExitUsage { + t.Fatalf("no file: %+v", r) + } + unsupported := writeFile(t, "notes.txt", "hello") + if r := run(t, "", "validate", "--audit", unsupported); r.code != ExitUsage { + t.Fatalf("audit must not hide an unsupported report: %+v", r) + } + + kev := writeFile(t, "gatecheck.yaml", "version: \"1\"\ngrype:\n kevLimitEnabled: true\n") + if r := run(t, "", "validate", "-f", kev, "--kev-url", "http://127.0.0.1:1/kev.json", grypeReport); r.code != ExitFetch { + t.Fatalf("kev fetch failure: %+v", r) + } + if r := run(t, "", "validate", "--audit", "-f", kev, "--kev-url", "http://127.0.0.1:1/kev.json", grypeReport); r.code != ExitFetch { + t.Fatalf("audit must not hide a fetch failure: %+v", r) + } + if r := run(t, "", "validate", "-f", kev, "--kev-filename", kevJSON, grypeReport); r.code == ExitFetch || r.code == ExitUsage { + t.Fatalf("local kev file: %+v", r) + } +} + +func TestEnvironmentSettings(t *testing.T) { + clearEnv(t) + config := writeFile(t, "gatecheck.yaml", criticalLimit) + + t.Setenv("GATECHECK_CONFIG_FILENAME", config) + if r := run(t, "", "validate", grypeReport); r.code != ExitValidation { + t.Fatalf("config from env: %+v", r) + } + t.Setenv("GATECHECK_AUDIT", "true") + if r := run(t, "", "validate", grypeReport); r.code != ExitOK { + t.Fatalf("audit from env: %+v", r) + } + if r := run(t, "", "validate", "--audit=false", grypeReport); r.code != ExitValidation { + t.Fatalf("--audit=false must beat GATECHECK_AUDIT=true: %+v", r) + } + t.Setenv("GATECHECK_AUDIT", "") + + for _, key := range []string{"GATECHECK_VERBOSE", "GATECHECK_SILENT", "GATECHECK_AUDIT"} { + t.Setenv(key, "true") + r := run(t, "", "validate", grypeReport) + if r.code == ExitUsage { + t.Fatalf("%s=true: %+v", key, r) + } + t.Setenv(key, "maybe") + r = run(t, "", "validate", grypeReport) + if r.code != ExitUsage || !strings.Contains(r.stderr, key) { + t.Fatalf("%s=maybe should be a usage error: %+v", key, r) + } + t.Setenv(key, "") + } + + // GATECHECK_KEV_FILENAME is its own setting, not the EPSS one. + t.Setenv("GATECHECK_CONFIG_FILENAME", writeFile(t, "kev.yaml", "version: \"1\"\ngrype:\n kevLimitEnabled: true\n")) + t.Setenv("GATECHECK_KEV_URL", "http://127.0.0.1:1/kev.json") + t.Setenv("GATECHECK_EPSS_FILENAME", epssCSV) + if r := run(t, "", "validate", grypeReport); r.code != ExitFetch { + t.Fatalf("EPSS file must not be read as KEV: %+v", r) + } + t.Setenv("GATECHECK_KEV_FILENAME", kevJSON) + if r := run(t, "", "validate", grypeReport); r.code == ExitFetch || r.code == ExitUsage { + t.Fatalf("GATECHECK_KEV_FILENAME: %+v", r) + } +} + +func TestLogging(t *testing.T) { + clearEnv(t) + r := run(t, "", "validate", grypeReport) + if !strings.Contains(r.stderr, "no config file") { + t.Fatalf("missing no-config warning: %q", r.stderr) + } + r = run(t, "", "--silent", "validate", grypeReport) + if !strings.Contains(r.stderr, "no config file") || strings.Contains(r.stderr, "INF") { + t.Fatalf("--silent should keep warnings and drop info: %q", r.stderr) + } + r = run(t, "", "--log-level", "error", "validate", grypeReport) + if strings.Contains(r.stderr, "no config file") { + t.Fatalf("--log-level error should drop warnings: %q", r.stderr) + } + r = run(t, "", "--log-format", "json", "validate", grypeReport) + lines := strings.Split(strings.TrimSpace(r.stderr), "\n") + var entry map[string]any + if err := json.Unmarshal([]byte(lines[0]), &entry); err != nil || entry["level"] == nil { + t.Fatalf("json log line %q: %v", lines[0], err) + } + if r := run(t, "", "--log-format", "xml", "version"); r.code != ExitUsage { + t.Fatalf("bad log format: %+v", r) + } + if r := run(t, "", "-v", "--silent", "version"); r.code != ExitUsage { + t.Fatalf("verbose and silent together: %+v", r) + } + t.Setenv("GATECHECK_LOG_LEVEL", "debug") + if r := run(t, "", "validate", grypeReport); !strings.Contains(r.stderr, "DBG") { + t.Fatalf("GATECHECK_LOG_LEVEL=debug: %q", r.stderr) + } +} + +func TestValidateConfigWarningsAndFormat(t *testing.T) { + clearEnv(t) + typo := writeFile(t, "gatecheck.yaml", criticalLimit+"grpye:\n kevLimitEnabled: true\n") + r := run(t, "", "validate", "-f", typo, "--format", "json", grypeReport) + if r.code != ExitValidation || !strings.Contains(r.stderr, "grpye") { + t.Fatalf("unknown key warning: %+v", r) + } + var got validateResult + if err := json.Unmarshal([]byte(r.stdout), &got); err != nil { + t.Fatalf("json result %q: %v", r.stdout, err) + } + if got.Passed || len(got.Failures) != 1 || !strings.Contains(got.Failures[0], "Grype") { + t.Fatalf("result %+v", got) + } + + r = run(t, "", "validate", "--format", "table", grypeReport) + if r.code != ExitOK || !strings.Contains(r.stdout, "pass") { + t.Fatalf("table pass: %+v", r) + } + r = run(t, "", "validate", "-f", typo, "--format", "markdown", grypeReport) + if !strings.Contains(r.stdout, "| fail") { + t.Fatalf("markdown: %q", r.stdout) + } + if r := run(t, "", "validate", "--format", "yaml", grypeReport); r.code != ExitUsage { + t.Fatalf("bad format: %+v", r) + } +} + +func TestValidateInputTypeStdin(t *testing.T) { + clearEnv(t) + body, err := os.ReadFile(grypeReport) + if err != nil { + t.Fatal(err) + } + config := writeFile(t, "gatecheck.yaml", criticalLimit) + if r := run(t, string(body), "validate", "-f", config, "--input-type", "grype"); r.code != ExitValidation { + t.Fatalf("stdin: %+v", r) + } + lcov := writeFile(t, "report.txt", "SF:a.go\nDA:1,1\nDA:2,0\nLF:2\nLH:1\nend_of_record\n") + cov := writeFile(t, "gatecheck.yaml", "version: \"1\"\ncoverage:\n lineThreshold: 80\n") + r := run(t, "", "validate", "-f", cov, "--input-type", "lcov", lcov) + if r.code != ExitValidation || !strings.Contains(r.stderr, "percent") { + t.Fatalf("lcov via --input-type with a percent threshold: %+v", r) + } + cov40 := writeFile(t, "gatecheck.yaml", "version: \"1\"\ncoverage:\n lineThreshold: 40\n") + if r := run(t, "", "validate", "-f", cov40, "-i", "lcov", lcov); r.code != ExitOK { + t.Fatalf("40 percent of a 50 percent report should pass: %+v", r) + } +} + +func TestListFormats(t *testing.T) { + clearEnv(t) + r := run(t, "", "list", "--format", "json", grypeReport) + var table struct { + Columns []string `json:"columns"` + Rows []map[string]string `json:"rows"` + } + if err := json.Unmarshal([]byte(r.stdout), &table); err != nil || len(table.Rows) == 0 { + t.Fatalf("list json %q: %v", r.stdout, err) + } + if _, ok := table.Rows[0][table.Columns[0]]; !ok { + t.Fatalf("rows are not keyed by column: %+v", table.Rows[0]) + } + if r := run(t, "", "list", "--markdown", grypeReport); !strings.HasPrefix(strings.TrimSpace(r.stdout), "|") { + t.Fatalf("markdown: %q", r.stdout) + } + if r := run(t, "", "list", "--markdown", "--format", "json", grypeReport); r.code != ExitUsage { + t.Fatalf("conflicting format flags: %+v", r) + } + + empty := writeFile(t, "gitleaks-report.json", "[]") + r = run(t, "", "list-all", "--format", "json", grypeReport, empty) + var all []struct { + File string `json:"file"` + Report json.RawMessage `json:"report"` + } + if err := json.Unmarshal([]byte(r.stdout), &all); err != nil || len(all) != 2 || all[0].File != grypeReport { + t.Fatalf("list-all json %q: %v", r.stdout, err) + } + if r := run(t, "", "list-all", grypeReport, "missing.json"); r.code != ExitUsage || !strings.Contains(r.stdout, "GRYPE") { + t.Fatalf("list-all with a missing file: %+v", r) + } + if r := run(t, "", "list-all", "--epss", "--epss-filename", epssCSV, grypeReport); r.code != ExitOK || !strings.Contains(r.stdout, "EPSS") { + t.Fatalf("list-all --epss-filename: %+v", r) + } +} + +func TestBundleCommands(t *testing.T) { + clearEnv(t) + dir := t.TempDir() + bundle := filepath.Join(dir, "gatecheck-bundle.tar.gz") + big := make([]byte, 200_000) + for i := range big { + big[i] = byte('a' + i%26) + } + if err := os.WriteFile(bundle, big, 0o600); err != nil { + t.Fatal(err) + } + if r := run(t, "", "bundle", "create", "-t", "ci,main", bundle, grypeReport); r.code != ExitOK { + t.Fatalf("create over a larger file: %+v", r) + } + readBundle := func() *archive.Bundle { + t.Helper() + f, err := os.Open(bundle) + if err != nil { + t.Fatal(err) + } + defer func() { _ = f.Close() }() + b := archive.NewBundle() + if err := archive.UntarGzipBundle(f, b); err != nil { + t.Fatalf("bundle is corrupt: %v", err) + } + return b + } + b := readBundle() + if tags := b.Manifest().Files["grype-report.json"].Tags; strings.Join(tags, ",") != "ci,main" { + t.Fatalf("tags %v", tags) + } + + if r := run(t, "", "bundle", "add", bundle, epssCSV); r.code != ExitOK { + t.Fatalf("add: %+v", r) + } + if r := run(t, "", "bundle", "remove", bundle, "epss_scores-2023-06-01.csv"); r.code != ExitOK { + t.Fatalf("remove: %+v", r) + } + info, err := os.Stat(bundle) + if err != nil { + t.Fatal(err) + } + if len(readBundle().Manifest().Files) != 1 { + t.Fatal("remove did not remove") + } + if r := run(t, "", "bundle", "remove", bundle, "not-there.json"); r.code != ExitUsage { + t.Fatalf("removing a missing label should fail: %+v", r) + } + after, err := os.Stat(bundle) + if err != nil { + t.Fatal(err) + } + if after.Size() != info.Size() { + t.Fatal("failed remove changed the bundle") + } +} + +func TestConfigCommands(t *testing.T) { + clearEnv(t) + r := run(t, "", "config", "init") + if r.code != ExitOK || !strings.Contains(r.stdout, "\n severityLimit:") { + t.Fatalf("config init should be indented by two spaces: %q", r.stdout) + } + r = run(t, "", "config", "init", "-o", "json") + if !strings.Contains(r.stdout, "\n \"version\"") { + t.Fatalf("json init: %q", r.stdout) + } + if r := run(t, "", "config", "init", "-o", "xml"); r.code != ExitUsage { + t.Fatalf("bad output: %+v", r) + } + src := writeFile(t, "gatecheck.yaml", criticalLimit) + r = run(t, "", "config", "convert", "-f", src, "-o", "toml") + if r.code != ExitOK || !strings.Contains(r.stdout, "[grype") { + t.Fatalf("convert: %+v", r) + } +} diff --git a/cmd/config.go b/cmd/config.go index ba12036..b0b70a7 100644 --- a/cmd/config.go +++ b/cmd/config.go @@ -2,76 +2,55 @@ package cmd import ( "errors" + "log/slog" + "strings" "github.com/gatecheckdev/gatecheck/pkg/gatecheck" "github.com/spf13/cobra" ) -var configCmd = &cobra.Command{ - Use: "config", - Short: "manage the gatecheck configuration file", -} - -var configInitCmd = &cobra.Command{ - Use: "init", - Short: "output an example configuration file", - RunE: func(cmd *cobra.Command, args []string) error { - output, _ := cmd.Flags().GetString("output") - - switch output { - case "json", ".json": - output = ".json" - case "toml", ".toml": - output = ".toml" - case "yaml", "yml", ".yaml", ".yml": - output = ".yaml" - default: - return errors.New("invalid --output format, must be json,toml,yaml, or yml") - } - - return gatecheck.NewConfigEncoder(cmd.OutOrStdout(), output).Encode(gatecheck.NewDefaultConfig()) - }, -} - -var configConvertCmd = &cobra.Command{ - Use: "convert", - Short: "convert and existing configuration file into another format", - PreRunE: func(cmd *cobra.Command, args []string) error { - configFilename, _ := cmd.Flags().GetString("file") - RuntimeConfig.gatecheckConfig = &gatecheck.Config{} - err := gatecheck.NewConfigDecoder(configFilename).Decode(RuntimeConfig.gatecheckConfig) - if err != nil { - return err - } - - return nil - }, - RunE: func(cmd *cobra.Command, args []string) error { - output, _ := cmd.Flags().GetString("output") - - switch output { - case "json", ".json": - output = ".json" - case "toml", ".toml": - output = ".toml" - case "yaml", "yml", ".yaml", ".yml": - output = ".yaml" - default: - return errors.New("invalid --output format, must be json, toml, yaml, or yml") - } - - return gatecheck.NewConfigEncoder(cmd.OutOrStdout(), output).Encode(RuntimeConfig.gatecheckConfig) - }, -} - func newConfigCommand() *cobra.Command { - configConvertCmd.Flags().StringP("file", "f", "gatecheck.yaml", "gatecheck validation config file") - configConvertCmd.Flags().StringP("output", "o", "yaml", "Format to convert into formats=[json yaml yml toml]") - configInitCmd.Flags().StringP("output", "o", "yaml", "Format to convert into formats=[json yaml yml toml]") - - _ = configConvertCmd.MarkFlagFilename("file", "json", "yaml", "yml", "toml") - _ = configInitCmd.MarkFlagFilename("file", "json", "yaml", "yml", "toml") - - configCmd.AddCommand(configInitCmd, configConvertCmd) + configCmd := &cobra.Command{ + Use: "config", + Short: "manage the gatecheck configuration file", + } + + initCmd := &cobra.Command{ + Use: "init", + Short: "print the default configuration file", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + output, _ := cmd.Flags().GetString("output") + return gatecheck.EncodeConfigTo(cmd.OutOrStdout(), gatecheck.NewDefaultConfig(), output) + }, + } + + convertCmd := &cobra.Command{ + Use: "convert", + Short: "convert an existing configuration file into another format", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + filename, _ := cmd.Flags().GetString("file") + output, _ := cmd.Flags().GetString("output") + if _, err := gatecheck.ConfigFormat(output); err != nil { + return err + } + config := &gatecheck.Config{} + err := gatecheck.NewConfigDecoder(filename).Decode(config) + if errors.Is(err, gatecheck.ErrUnknownConfigKeys) { + slog.Warn("config has keys gatecheck does not read; they are dropped from the output", "filename", filename, "keys", strings.TrimPrefix(err.Error(), gatecheck.ErrUnknownConfigKeys.Error()+": ")) + } else if err != nil { + return err + } + return gatecheck.EncodeConfigTo(cmd.OutOrStdout(), config, output) + }, + } + + convertCmd.Flags().StringP("file", "f", "gatecheck.yaml", "gatecheck validation config file") + convertCmd.Flags().StringP("output", "o", "yaml", "format to write: json, yaml, yml, or toml") + initCmd.Flags().StringP("output", "o", "yaml", "format to write: json, yaml, yml, or toml") + _ = convertCmd.MarkFlagFilename("file", "json", "yaml", "yml", "toml") + + configCmd.AddCommand(initCmd, convertCmd) return configCmd } diff --git a/cmd/download.go b/cmd/download.go index d8b900c..de41ff3 100644 --- a/cmd/download.go +++ b/cmd/download.go @@ -5,35 +5,33 @@ import ( "github.com/spf13/cobra" ) -var downloadCmd = &cobra.Command{ - Use: "download", - Short: "output data from supported APIs", -} +func newDownloadCommand() *cobra.Command { + downloadCmd := &cobra.Command{ + Use: "download", + Short: "output data from supported APIs", + } -var downloadEPSSCmd = &cobra.Command{ - Use: "epss", - Short: "download epss data from FIRST API as csv to STDOUT", - RunE: func(cmd *cobra.Command, args []string) error { - url := RuntimeConfig.EPSSURL.Value().(string) - opts := append([]gatecheck.Option{gatecheck.WithEPSSURL(url)}, epssCacheOptions()...) - return gatecheck.DownloadEPSS(cmd.OutOrStdout(), opts...) - }, -} + epssCmd := &cobra.Command{ + Use: "epss", + Short: "download epss data from FIRST API as csv to STDOUT", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + opts := append([]gatecheck.Option{gatecheck.WithEPSSURL(stringSetting(cmd, "epss-url", "GATECHECK_EPSS_URL"))}, epssCacheOptions(cmd)...) + return gatecheck.DownloadEPSS(cmd.OutOrStdout(), opts...) + }, + } + addEPSSFlags(epssCmd, false) -var downloadKEVCmd = &cobra.Command{ - Use: "kev", - Short: "download kev catalog from CISA as json to STDOUT", - RunE: func(cmd *cobra.Command, args []string) error { - url := RuntimeConfig.KEVURL.Value().(string) - return gatecheck.DownloadKEV(cmd.OutOrStdout(), gatecheck.WithKEVURL(url)) - }, -} + kevCmd := &cobra.Command{ + Use: "kev", + Short: "download kev catalog from CISA as json to STDOUT", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + return gatecheck.DownloadKEV(cmd.OutOrStdout(), gatecheck.WithKEVURL(stringSetting(cmd, "kev-url", "GATECHECK_KEV_URL"))) + }, + } + kevCmd.Flags().String("kev-url", "", `CISA KEV JSON URL; "" uses the official feed (env GATECHECK_KEV_URL)`) -func newDownloadCommand() *cobra.Command { - RuntimeConfig.EPSSURL.SetupCobra(downloadEPSSCmd) - RuntimeConfig.EPSSCacheDir.SetupCobra(downloadEPSSCmd) - RuntimeConfig.EPSSNoCache.SetupCobra(downloadEPSSCmd) - RuntimeConfig.KEVURL.SetupCobra(downloadKEVCmd) - downloadCmd.AddCommand(downloadEPSSCmd, downloadKEVCmd) + downloadCmd.AddCommand(epssCmd, kevCmd) return downloadCmd } diff --git a/cmd/download_test.go b/cmd/download_test.go index 1b296ad..67a2aaa 100644 --- a/cmd/download_test.go +++ b/cmd/download_test.go @@ -17,18 +17,6 @@ import ( func TestEPSSDownloadCommandCachesAndKeepsFlags(t *testing.T) { t.Setenv("GATECHECK_EPSS_CACHE", "") t.Setenv("GATECHECK_EPSS_CACHE_DIR", "") - t.Cleanup(func() { - if p, ok := RuntimeConfig.EPSSNoCache.FlagValueP.(*bool); ok && p != nil { - *p = false - } - if p, ok := RuntimeConfig.EPSSCacheDir.FlagValueP.(*string); ok && p != nil { - *p = "" - } - if p, ok := RuntimeConfig.EPSSURL.FlagValueP.(*string); ok && p != nil { - *p = "" - } - }) - var gets atomic.Int32 payload := gzipCSV(t, "#model_version:v2025.03.14,score_date:2026-10-22T00:00:00Z\ncve,epss,percentile\nCVE-2024-1234,0.42,0.84\n") srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { diff --git a/cmd/fetch.go b/cmd/fetch.go new file mode 100644 index 0000000..3105d9b --- /dev/null +++ b/cmd/fetch.go @@ -0,0 +1,78 @@ +package cmd + +import ( + "os" + "strings" + + "github.com/gatecheckdev/gatecheck/pkg/gatecheck" + "github.com/spf13/cobra" +) + +const inputTypes = "grype|cyclonedx|semgrep|gitleaks|trivy|osv|syft|sarif|bundle|lcov|clover|cobertura" + +// addEPSSFlags adds the EPSS source and cache flags. withFile adds --epss-filename. +func addEPSSFlags(cmd *cobra.Command, withFile bool) { + flags := cmd.Flags() + flags.String("epss-url", "", `FIRST.org EPSS CSV URL; "" uses the official feed (env GATECHECK_EPSS_URL)`) + flags.String("epss-cache-dir", "", "cache directory for EPSS downloads (default: user cache dir, env GATECHECK_EPSS_CACHE_DIR)") + flags.Bool("epss-no-cache", false, "download EPSS on every run instead of using the local cache (env GATECHECK_EPSS_CACHE=off)") + if withFile { + flags.String("epss-filename", "", "local FIRST.org EPSS CSV to use instead of downloading (env GATECHECK_EPSS_FILENAME)") + } +} + +func addKEVFlags(cmd *cobra.Command) { + flags := cmd.Flags() + flags.String("kev-url", "", `CISA KEV JSON URL; "" uses the official feed (env GATECHECK_KEV_URL)`) + flags.String("kev-filename", "", "local CISA KEV JSON to use instead of downloading (env GATECHECK_KEV_FILENAME)") +} + +// epssCacheOptions reads --epss-no-cache and --epss-cache-dir. GATECHECK_EPSS_CACHE +// and GATECHECK_EPSS_CACHE_DIR are read by the epss package when these are unset. +func epssCacheOptions(cmd *cobra.Command) []gatecheck.Option { + var opts []gatecheck.Option + if noCache, _ := cmd.Flags().GetBool("epss-no-cache"); noCache { + opts = append(opts, gatecheck.WithEPSSCache(false)) + } + if dir, _ := cmd.Flags().GetString("epss-cache-dir"); strings.TrimSpace(dir) != "" { + opts = append(opts, gatecheck.WithEPSSCacheDir(dir)) + } + return opts +} + +// fetchOptions builds the EPSS and KEV options for validate. The returned +// function closes any files it opened. +func fetchOptions(cmd *cobra.Command) ([]gatecheck.Option, func(), error) { + var files []*os.File + closeAll := func() { + for _, f := range files { + _ = f.Close() + } + } + opts := []gatecheck.Option{ + gatecheck.WithEPSSURL(stringSetting(cmd, "epss-url", "GATECHECK_EPSS_URL")), + gatecheck.WithKEVURL(stringSetting(cmd, "kev-url", "GATECHECK_KEV_URL")), + } + opts = append(opts, epssCacheOptions(cmd)...) + + if name := stringSetting(cmd, "epss-filename", "GATECHECK_EPSS_FILENAME"); name != "" { + f, err := os.Open(name) + if err != nil { + return nil, closeAll, err + } + files = append(files, f) + opts = append(opts, gatecheck.WithEPSSFile(f)) + } + if cmd.Flags().Lookup("kev-filename") != nil { + if name := stringSetting(cmd, "kev-filename", "GATECHECK_KEV_FILENAME"); name != "" { + f, err := os.Open(name) + if err != nil { + closeAll() + return nil, func() {}, err + } + files = append(files, f) + opts = append(opts, gatecheck.WithKEVFile(f)) + } + } + return opts, closeAll, nil +} diff --git a/cmd/gatecheck/main.go b/cmd/gatecheck/main.go index 2885150..53ac985 100644 --- a/cmd/gatecheck/main.go +++ b/cmd/gatecheck/main.go @@ -2,27 +2,15 @@ package main import ( - "errors" "fmt" - "log/slog" "os" "runtime" - "time" - - "github.com/lmittmann/tint" "github.com/gatecheckdev/gatecheck/cmd" "github.com/gatecheckdev/gatecheck/pkg/epss" "github.com/gatecheckdev/gatecheck/pkg/gatecheck" ) -const ( - exitSystemFail int = -1 - exitOk int = 0 - exitValidationFail int = 1 - exitFileAccessFail int = 2 -) - // GatecheckVersion see CHANGELOG.md const GatecheckVersion = "[Not Provided]" @@ -49,27 +37,9 @@ func run() int { Compiler: runtime.Compiler, } epss.SetVersion(cliVersion) - - // Colorized logging output for the CLI - logHandler := tint.NewTextHandler(os.Stderr, &tint.Options{Level: cmd.LogLeveler, TimeFormat: time.TimeOnly}) - slog.SetDefault(slog.New(logHandler)) - - command := cmd.NewGatecheckCommand() - - err := command.Execute() - return status(err) + return status(cmd.NewGatecheckCommand().Execute()) } func status(err error) int { - if err == nil { - return exitOk - } - var coder interface{ ExitCode() int } - if errors.As(err, &coder) { - return coder.ExitCode() - } - if errors.Is(err, gatecheck.ErrValidationFailure) { - return exitValidationFail - } - return exitSystemFail + return cmd.ExitCode(err) } diff --git a/cmd/gatecheck/main_test.go b/cmd/gatecheck/main_test.go index e713719..05af303 100644 --- a/cmd/gatecheck/main_test.go +++ b/cmd/gatecheck/main_test.go @@ -3,8 +3,10 @@ package main import ( "errors" "fmt" + "os" "testing" + "github.com/gatecheckdev/gatecheck/internal/bootstrap" "github.com/gatecheckdev/gatecheck/pkg/gatecheck" ) @@ -14,16 +16,22 @@ func (e exitStub) Error() string { return fmt.Sprintf("exit status %d", int(e)) func (e exitStub) ExitCode() int { return int(e) } func TestStatus(t *testing.T) { - if status(nil) != exitOk { - t.Fatal("nil") + cases := []struct { + err error + want int + }{ + {nil, 0}, + {exitStub(4), 4}, + {fmt.Errorf("%w: semgrep", gatecheck.ErrValidationFailure), 1}, + {errors.New("boom"), 2}, + {os.ErrNotExist, 2}, + {bootstrap.ErrNotInstalled, 2}, + {fmt.Errorf("%w: kev", gatecheck.ErrExternalData), 3}, + {errors.Join(fmt.Errorf("%w: a", gatecheck.ErrValidationFailure), fmt.Errorf("%w: b", gatecheck.ErrExternalData)), 1}, } - if status(exitStub(4)) != 4 { - t.Fatal("passthrough") - } - if status(fmt.Errorf("%w: semgrep", gatecheck.ErrValidationFailure)) != exitValidationFail { - t.Fatal("validation") - } - if status(errors.New("boom")) != exitSystemFail { - t.Fatal("system") + for _, tc := range cases { + if got := status(tc.err); got != tc.want { + t.Errorf("status(%v) = %d, want %d", tc.err, got, tc.want) + } } } diff --git a/cmd/list.go b/cmd/list.go index 7f2b36f..c3dc201 100644 --- a/cmd/list.go +++ b/cmd/list.go @@ -2,171 +2,170 @@ package cmd import ( "bytes" + "encoding/json" "errors" "fmt" - "io" "log/slog" "os" + "strings" "github.com/gatecheckdev/gatecheck/pkg/gatecheck" "github.com/spf13/cobra" ) -var listCmd = &cobra.Command{ - Use: "list", - Short: "print a table of the findings in a report or files in a gatecheck bundle", - Aliases: []string{"ls", "print"}, - PreRunE: func(cmd *cobra.Command, args []string) error { - inputType, _ := cmd.Flags().GetString("input-type") - if inputType == "" && len(args) == 0 { - return errors.New("need either input-type for STDIN or filename as argument") - } - - var err error = nil - - if len(args) == 0 { - RuntimeConfig.listSrcReader = cmd.InOrStdin() - RuntimeConfig.listSrcName = fmt.Sprintf("stdin:%s", inputType) - } else { - RuntimeConfig.listSrcReader, err = os.Open(args[0]) - RuntimeConfig.listSrcName = args[0] - } - - if err != nil { - return err - } - - RuntimeConfig.listFormat = "ascii" - - if markdownFlag, _ := cmd.Flags().GetBool("markdown"); markdownFlag { - RuntimeConfig.listFormat = "markdown" - } - - if epss, _ := cmd.Flags().GetBool("epss"); !epss { - return nil - } - - RuntimeConfig.epssFile = nil - - epssFilename := RuntimeConfig.EPSSFilename.Value().(string) - - if epssFilename == "" { - return nil - } - - RuntimeConfig.epssFile, err = os.Open(epssFilename) - if err != nil { - return err - } - - return nil - }, - RunE: func(cmd *cobra.Command, args []string) error { - epss, _ := cmd.Flags().GetBool("epss") - - dst := cmd.OutOrStdout() - src := RuntimeConfig.listSrcReader - srcName := RuntimeConfig.listSrcName - displayOpt := gatecheck.WithDisplayFormat(RuntimeConfig.listFormat) +func addListFormatFlags(cmd *cobra.Command) { + cmd.Flags().String("format", "table", "output format: "+strings.Join(gatecheck.ListFormats, ", ")) + cmd.Flags().Bool("markdown", false, "print as a markdown table, the same as --format markdown") + cmd.Flags().Bool("epss", false, "add EPSS scores to Grype, CycloneDX, Trivy, and osv-scanner tables") + addEPSSFlags(cmd, true) +} - if !epss { - return gatecheck.List(dst, src, srcName, displayOpt) +func listFormat(cmd *cobra.Command) (string, error) { + listFmt, _ := cmd.Flags().GetString("format") + if markdown, _ := cmd.Flags().GetBool("markdown"); markdown { + if cmd.Flags().Changed("format") && listFmt != "markdown" { + return "", fmt.Errorf("--markdown conflicts with --format %s", listFmt) } + listFmt = "markdown" + } + if err := oneOf("--format", listFmt, gatecheck.ListFormats...); err != nil { + return "", err + } + return listFmt, nil +} - epssURL := RuntimeConfig.EPSSURL.Value().(string) - epssFile := RuntimeConfig.epssFile - - // if file is nil, API will be used - // if epssURL is empty, default API will be used - epssOpt, err := gatecheck.WithEPSS(epssFile, epssURL, epssCacheOptions()...) +// epssListOption loads EPSS data once for list and list-all. +func epssListOption(cmd *cobra.Command) (gatecheck.ListOptionFunc, error) { + var file *os.File + if name := stringSetting(cmd, "epss-filename", "GATECHECK_EPSS_FILENAME"); name != "" { + f, err := os.Open(name) if err != nil { - return err + return nil, err } - return gatecheck.List(dst, src, srcName, displayOpt, epssOpt) - }, + defer func() { _ = f.Close() }() + file = f + } + url := stringSetting(cmd, "epss-url", "GATECHECK_EPSS_URL") + return gatecheck.WithEPSS(file, url, epssCacheOptions(cmd)...) } -var listAllCmd = &cobra.Command{ - Use: "list-all [FILE...]", - Short: "list multiple report files", - RunE: func(cmd *cobra.Command, args []string) error { - epss, _ := cmd.Flags().GetBool("epss") - markdown, _ := cmd.Flags().GetBool("markdown") - slog.Debug("run list all", "epss", fmt.Sprintf("%v", epss), "markdown", fmt.Sprintf("%v", markdown)) - - for _, filename := range args { - cmd.Printf("%s\n", filename) - - src, err := os.Open(filename) - if err != nil { - if errors.Is(err, os.ErrNotExist) { - slog.Error("file not found, skip", "filename", filename) - continue - } - slog.Error("cannot open file, skip", "filename", filename, "error", err) - continue - } - content, err := io.ReadAll(src) - if closeErr := src.Close(); closeErr != nil { - slog.Debug("close file", "filename", filename, "error", closeErr) +func newListCommand() *cobra.Command { + cmd := &cobra.Command{ + Use: "list [FILE]", + Short: "print a table of the findings in a report or files in a gatecheck bundle", + Aliases: []string{"ls", "print"}, + Args: cobra.MaximumNArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + inputType, _ := cmd.Flags().GetString("input-type") + if inputType == "" && len(args) == 0 { + return errors.New("need either --input-type for stdin or a filename argument") } + listFmt, err := listFormat(cmd) if err != nil { - slog.Error("cannot read file, skip", "filename", filename, "error", err) - continue - } - - supported, withEPSS := gatecheck.ListAllAction(content, filename) - if !supported { - slog.Warn("file not supported, skip", "filename", filename) - continue + return err } - epssURL := RuntimeConfig.EPSSURL.Value().(string) - epssFile := RuntimeConfig.epssFile - - opts := []gatecheck.ListOptionFunc{} - displayOpt := gatecheck.WithDisplayFormat("ascii") - if markdown { - displayOpt = gatecheck.WithDisplayFormat("markdown") + src := cmd.InOrStdin() + srcName := "stdin:" + inputType + if len(args) == 1 { + f, err := os.Open(args[0]) + if err != nil { + return err + } + defer func() { _ = f.Close() }() + src = f + srcName = args[0] + if inputType != "" { + srcName = inputType + } } - opts = append(opts, displayOpt) - if epss && withEPSS { - epssOpt, err := gatecheck.WithEPSS(epssFile, epssURL, epssCacheOptions()...) + opts := []gatecheck.ListOptionFunc{gatecheck.WithDisplayFormat(listFmt)} + if epss, _ := cmd.Flags().GetBool("epss"); epss { + epssOpt, err := epssListOption(cmd) if err != nil { - slog.Error("epss fetch failure, skip", "filename", filename, "error", err) - continue + return err } opts = append(opts, epssOpt) } + return gatecheck.List(cmd.OutOrStdout(), src, srcName, opts...) + }, + } + cmd.Flags().StringP("input-type", "i", "", "report type when the contents are ambiguous, and the type of stdin when FILE is omitted ["+inputTypes+"]") + addListFormatFlags(cmd) + return cmd +} - dst := cmd.OutOrStdout() - err = gatecheck.List(dst, bytes.NewReader(content), filename, opts...) +func newListAllCommand() *cobra.Command { + cmd := &cobra.Command{ + Use: "list-all FILE...", + Short: "list multiple report files", + Args: cobra.MinimumNArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + listFmt, err := listFormat(cmd) if err != nil { - slog.Error("cannot list report, skip", "filename", filename, "error", err) - continue + return err } + withEPSS, _ := cmd.Flags().GetBool("epss") + var epssOpt gatecheck.ListOptionFunc - } - return nil - }, -} - -func newListAllCommand() *cobra.Command { - listAllCmd.Flags().Bool("markdown", false, "print as a markdown table") - listAllCmd.Flags().Bool("epss", false, "List with EPSS data") - RuntimeConfig.EPSSCacheDir.SetupCobra(listAllCmd) - RuntimeConfig.EPSSNoCache.SetupCobra(listAllCmd) - return listAllCmd -} + type listed struct { + File string `json:"file"` + Report json.RawMessage `json:"report"` + } + listedJSON := []listed{} -func newListCommand() *cobra.Command { - listCmd.Flags().StringP("input-type", "i", "", "stdin type word used when the report content is ambiguous [grype|cyclonedx|semgrep|gitleaks|trivy|osv|syft|sarif|bundle|lcov]") - listCmd.Flags().Bool("markdown", false, "print as a markdown table") - listCmd.Flags().Bool("epss", false, "List with EPSS data") - RuntimeConfig.EPSSURL.SetupCobra(listCmd) - RuntimeConfig.EPSSFilename.SetupCobra(listCmd) - RuntimeConfig.EPSSCacheDir.SetupCobra(listCmd) - RuntimeConfig.EPSSNoCache.SetupCobra(listCmd) - return listCmd + var failed int + for _, filename := range args { + content, err := os.ReadFile(filename) + if err != nil { + slog.Error("cannot read file, skip", "filename", filename, "error", err) + failed++ + continue + } + supported, epssCapable := gatecheck.ListAllAction(content, filename) + if !supported { + slog.Warn("file not supported, skip", "filename", filename) + continue + } + opts := []gatecheck.ListOptionFunc{gatecheck.WithDisplayFormat(listFmt)} + if withEPSS && epssCapable { + if epssOpt == nil { + if epssOpt, err = epssListOption(cmd); err != nil { + return err + } + } + opts = append(opts, epssOpt) + } + if listFmt == "json" { + var buf bytes.Buffer + if err := gatecheck.List(&buf, bytes.NewReader(content), filename, opts...); err != nil { + slog.Error("cannot list report, skip", "filename", filename, "error", err) + failed++ + continue + } + listedJSON = append(listedJSON, listed{File: filename, Report: bytes.TrimSpace(buf.Bytes())}) + continue + } + cmd.Printf("%s\n", filename) + if err := gatecheck.List(cmd.OutOrStdout(), bytes.NewReader(content), filename, opts...); err != nil { + slog.Error("cannot list report, skip", "filename", filename, "error", err) + failed++ + } + } + if listFmt == "json" { + enc := json.NewEncoder(cmd.OutOrStdout()) + enc.SetIndent("", " ") + if err := enc.Encode(listedJSON); err != nil { + return err + } + } + if failed > 0 { + return fmt.Errorf("%d of %d files could not be listed", failed, len(args)) + } + return nil + }, + } + addListFormatFlags(cmd) + return cmd } diff --git a/cmd/logging.go b/cmd/logging.go new file mode 100644 index 0000000..09e37cb --- /dev/null +++ b/cmd/logging.go @@ -0,0 +1,113 @@ +package cmd + +import ( + "fmt" + "io" + "log/slog" + "os" + "strings" + "time" + + "github.com/lmittmann/tint" + "github.com/spf13/cobra" +) + +var ( + logLevels = []string{"debug", "info", "warn", "error"} + logFormats = []string{"text", "json"} +) + +func addLoggingFlags(root *cobra.Command) { + flags := root.PersistentFlags() + flags.BoolP("verbose", "v", false, "debug logging, the same as --log-level debug (env GATECHECK_VERBOSE)") + flags.Bool("silent", false, "only warnings and errors, the same as --log-level warn (env GATECHECK_SILENT)") + flags.String("log-level", "info", "log level: "+strings.Join(logLevels, ", ")+" (env GATECHECK_LOG_LEVEL)") + flags.String("log-format", "text", "log format on stderr: "+strings.Join(logFormats, ", ")+" (env GATECHECK_LOG_FORMAT)") + root.MarkFlagsMutuallyExclusive("verbose", "silent", "log-level") +} + +// logLevel picks the level. Flags beat environment variables. Among flags or +// among variables, verbose and silent beat a log level. +func logLevel(cmd *cobra.Command) (slog.Level, error) { + flags := cmd.Flags() + switch { + case flags.Changed("verbose"): + return slog.LevelDebug, nil + case flags.Changed("silent"): + return slog.LevelWarn, nil + case flags.Changed("log-level"): + v, _ := flags.GetString("log-level") + return parseLevel(v, "--log-level") + } + verbose, err := boolSetting(cmd, "verbose", "GATECHECK_VERBOSE") + if err != nil { + return 0, err + } + silent, err := boolSetting(cmd, "silent", "GATECHECK_SILENT") + if err != nil { + return 0, err + } + switch { + case verbose && silent: + return 0, fmt.Errorf("GATECHECK_VERBOSE and GATECHECK_SILENT cannot both be true") + case verbose: + return slog.LevelDebug, nil + case silent: + return slog.LevelWarn, nil + } + return parseLevel(stringSetting(cmd, "log-level", "GATECHECK_LOG_LEVEL"), "log level") +} + +func parseLevel(v, name string) (slog.Level, error) { + switch strings.ToLower(strings.TrimSpace(v)) { + case "debug": + return slog.LevelDebug, nil + case "", "info": + return slog.LevelInfo, nil + case "warn", "warning": + return slog.LevelWarn, nil + case "error": + return slog.LevelError, nil + default: + return 0, fmt.Errorf("invalid %s %q, must be one of %s", name, v, strings.Join(logLevels, ", ")) + } +} + +// setupLogging installs the default slog logger on the command's stderr. +func setupLogging(cmd *cobra.Command) error { + level, err := logLevel(cmd) + if err != nil { + return err + } + logFormat := strings.ToLower(stringSetting(cmd, "log-format", "GATECHECK_LOG_FORMAT")) + if err := oneOf("log format", logFormat, logFormats...); err != nil { + return err + } + slog.SetDefault(slog.New(newLogHandler(cmd.ErrOrStderr(), logFormat, level))) + slog.Debug("logging configured", "level", level.String(), "format", logFormat) + return nil +} + +func newLogHandler(w io.Writer, format string, level slog.Level) slog.Handler { + if format == "json" { + return slog.NewJSONHandler(w, &slog.HandlerOptions{Level: level}) + } + return tint.NewTextHandler(w, &tint.Options{ + Level: level, + TimeFormat: time.TimeOnly, + NoColor: !colorOutput(w), + }) +} + +// colorOutput is true for a terminal when NO_COLOR is unset. +func colorOutput(w io.Writer) bool { + if _, ok := os.LookupEnv("NO_COLOR"); ok { + return false + } + f, ok := w.(*os.File) + if !ok { + return false + } + info, err := f.Stat() + return err == nil && info.Mode()&os.ModeCharDevice != 0 +} diff --git a/cmd/root.go b/cmd/root.go index cb3410c..5e608c0 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -1,117 +1,117 @@ -// Package cmd contains the CLI code for Gatecheck +// Package cmd contains the CLI code for Gatecheck. // -// # Organization Methodology -// -// The goal for this package is readability, ease of maintainence, and -// seperation of concerns for easier testing and debugging. -// -// newCommand functions should only build the command structure -// to include flag, cli options, and viper bindings. -// sub commands can also be included here as determined by the complexity -// of the command. -// -// run functions are specific to cobra's runE functions -// it handles parsing arguments, opening files, and early returning errors. -// These commands eventually result in calls to functions in the package -// github.com/gatecheckdev/gatecheck/pkg/gatecheck - -// The root file contains common helper functions used by other commands. -// Major commands can be in seperate files for ease of readability. +// NewGatecheckCommand builds a fresh command tree on every call, so commands +// hold no state between runs. Each newCommand function wires flags and +// reads settings in the order flag, then environment variable, then default. +// Command behavior that is not flag parsing lives in +// github.com/gatecheckdev/gatecheck/pkg/gatecheck. package cmd import ( - "log/slog" - "sync" + "errors" + "fmt" "github.com/gatecheckdev/gatecheck/pkg/gatecheck" "github.com/spf13/cobra" - "github.com/spf13/viper" ) -var ( - ApplicationMetadata gatecheck.ApplicationMetadata - LogLeveler *slog.LevelVar = &slog.LevelVar{} +// ApplicationMetadata is the build information printed by version. main sets it. +var ApplicationMetadata gatecheck.ApplicationMetadata + +// Exit codes. +const ( + ExitOK = 0 + // ExitValidation means a report failed a configured threshold. + ExitValidation = 1 + // ExitUsage means a bad command line, a file that could not be read or + // written, or a report or config that could not be decoded. + ExitUsage = 2 + // ExitFetch means EPSS or KEV data could not be downloaded or read. + ExitFetch = 3 ) -var gatecheckCmd = &cobra.Command{ - Use: "gatecheck", - Short: "Report validation tool", - PersistentPreRun: func(cmd *cobra.Command, args []string) { - verbose := RuntimeConfig.Verbose.Value().(bool) - silent := RuntimeConfig.Silent.Value().(bool) - - switch { - case verbose: - LogLeveler.Set(slog.LevelDebug) - slog.Debug("debug logging enabled") - case silent: - LogLeveler.Set(slog.LevelError) - slog.Debug("silent logging enabled") - } - }, - RunE: func(cmd *cobra.Command, args []string) error { - versionFlag, _ := cmd.Flags().GetBool("version") - if versionFlag { - return versionCmd.RunE(cmd, args) - } - return nil - }, -} - -var versionCmd = &cobra.Command{ - Use: "version", - Short: "print version and build information", - RunE: func(cmd *cobra.Command, args []string) error { - _, err := ApplicationMetadata.WriteTo(cmd.OutOrStdout()) - return err - }, +// ExitCode maps an error returned by the command tree to a process status. +// Scanner passthrough commands return the scanner's own status. +func ExitCode(err error) int { + if err == nil { + return ExitOK + } + var coder interface{ ExitCode() int } + if errors.As(err, &coder) { + return coder.ExitCode() + } + switch { + case errors.Is(err, gatecheck.ErrValidationFailure): + return ExitValidation + case errors.Is(err, gatecheck.ErrExternalData): + return ExitFetch + default: + return ExitUsage + } } -var setupOnce sync.Once - -// NewGatecheckCommand the root for all CLI commands +// NewGatecheckCommand returns a new root command and its subcommands. func NewGatecheckCommand() *cobra.Command { - setupOnce.Do(func() { - RuntimeConfig.Verbose.SetupCobra(gatecheckCmd) - RuntimeConfig.Silent.SetupCobra(gatecheckCmd) - - gatecheckCmd.MarkFlagsMutuallyExclusive("verbose", "silent") - gatecheckCmd.Flags().Bool("version", false, "print version and build information") - - _ = viper.BindEnv("cli.audit", "GATECHECK_CLI_AUDIT") - - _ = viper.BindEnv("cli.list.epss-file", "GATECHECK_EPSS_FILE") - _ = viper.BindEnv("cli.validate.epss-file", "GATECHECK_EPSS_FILE") - - _ = viper.BindEnv("cli.validate.kev-file", "GATECHECK_KEV_FILE") - - _ = viper.BindEnv("api.epss-url", "GATECHECK_EPSS_URL") - _ = viper.BindEnv("api.kev-url", "GATECHECK_KEV_URL") + root := &cobra.Command{ + Use: "gatecheck", + Short: "Report validation tool", + SilenceUsage: true, + SilenceErrors: false, + Args: cobra.NoArgs, + PersistentPreRunE: func(cmd *cobra.Command, _ []string) error { + return setupLogging(cmd) + }, + RunE: func(cmd *cobra.Command, _ []string) error { + if show, _ := cmd.Flags().GetBool("version"); show { + _, err := ApplicationMetadata.WriteTo(cmd.OutOrStdout()) + return err + } + return nil + }, + } + addLoggingFlags(root) + root.Flags().Bool("version", false, "print version and build information") + root.SetFlagErrorFunc(func(cmd *cobra.Command, err error) error { + return fmt.Errorf("%w\nRun '%s --help' for usage", err, cmd.CommandPath()) + }) - gatecheckCmd.SilenceUsage = true + root.AddCommand( + newVersionCommand(), + newConfigCommand(), + newListCommand(), + newListAllCommand(), + newBundleCommand(), + newValidateCommand(), + newDownloadCommand(), + newAgentGuideCommand(), + newBootstrapCommand(), + newUpdateCommand(), + ) + for _, tool := range []struct{ name, short string }{ + {"grype", "Run the managed grype scanner"}, + {"syft", "Run the managed syft scanner"}, + {"gitleaks", "Run the managed gitleaks scanner"}, + {"semgrep", "Run osemgrep from the managed semgrep wheel"}, + {"osemgrep", "Run osemgrep from the managed semgrep wheel"}, + {"trivy", "Run the managed trivy scanner"}, + {"osv-scanner", "Run the managed osv-scanner"}, + {"gosec", "Run the managed gosec scanner"}, + {"hadolint", "Run the managed hadolint linter"}, + {"zizmor", "Run the managed zizmor scanner"}, + } { + root.AddCommand(newPassthroughCommand(tool.name, tool.short)) + } + return root +} - gatecheckCmd.AddCommand( - versionCmd, - newConfigCommand(), - newListCommand(), - newListAllCommand(), - newBundleCommand(), - newValidateCommand(), - newDownloadCommand(), - newAgentGuideCommand(), - newBootstrapCommand(), - newPassthroughCommand("grype", "Run the managed grype scanner"), - newPassthroughCommand("syft", "Run the managed syft scanner"), - newPassthroughCommand("gitleaks", "Run the managed gitleaks scanner"), - newPassthroughCommand("semgrep", "Run osemgrep from the managed semgrep wheel"), - newPassthroughCommand("osemgrep", "Run osemgrep from the managed semgrep wheel"), - newPassthroughCommand("trivy", "Run the managed trivy scanner"), - newPassthroughCommand("osv-scanner", "Run the managed osv-scanner"), - newPassthroughCommand("gosec", "Run the managed gosec scanner"), - newPassthroughCommand("hadolint", "Run the managed hadolint linter"), - newPassthroughCommand("zizmor", "Run the managed zizmor scanner"), - ) - addCommandOnce(gatecheckCmd, updateCmd) - }) - return gatecheckCmd +func newVersionCommand() *cobra.Command { + return &cobra.Command{ + Use: "version", + Short: "print version and build information", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + _, err := ApplicationMetadata.WriteTo(cmd.OutOrStdout()) + return err + }, + } } diff --git a/cmd/settings.go b/cmd/settings.go new file mode 100644 index 0000000..7bb9acb --- /dev/null +++ b/cmd/settings.go @@ -0,0 +1,87 @@ +package cmd + +import ( + "fmt" + "os" + "strconv" + "strings" + + "github.com/spf13/cobra" +) + +// Settings are read flag first, then environment variable, then the flag's +// default. An empty environment variable counts as unset. + +func envValue(env string) (string, bool) { + if env == "" { + return "", false + } + v, ok := os.LookupEnv(env) + if !ok || strings.TrimSpace(v) == "" { + return "", false + } + return strings.TrimSpace(v), true +} + +func stringSetting(cmd *cobra.Command, flag, env string) string { + f := cmd.Flags().Lookup(flag) + if f != nil && f.Changed { + return f.Value.String() + } + if v, ok := envValue(env); ok { + return v + } + if f != nil { + return f.Value.String() + } + return "" +} + +func boolSetting(cmd *cobra.Command, flag, env string) (bool, error) { + f := cmd.Flags().Lookup(flag) + if f != nil && f.Changed { + return strconv.ParseBool(f.Value.String()) + } + if v, ok := envValue(env); ok { + b, err := strconv.ParseBool(v) + if err != nil { + return false, fmt.Errorf("%s=%q is not a boolean (use true or false)", env, v) + } + return b, nil + } + if f != nil { + return strconv.ParseBool(f.Value.String()) + } + return false, nil +} + +func stringSliceSetting(cmd *cobra.Command, flag, env string) []string { + f := cmd.Flags().Lookup(flag) + if f != nil && f.Changed { + values, _ := cmd.Flags().GetStringSlice(flag) + return values + } + if v, ok := envValue(env); ok { + var out []string + for _, part := range strings.Split(v, ",") { + if part = strings.TrimSpace(part); part != "" { + out = append(out, part) + } + } + return out + } + if f != nil { + values, _ := cmd.Flags().GetStringSlice(flag) + return values + } + return nil +} + +func oneOf(name, value string, allowed ...string) error { + for _, a := range allowed { + if value == a { + return nil + } + } + return fmt.Errorf("invalid %s %q, must be one of %s", name, value, strings.Join(allowed, ", ")) +} diff --git a/cmd/update.go b/cmd/update.go index 227af19..0484e47 100644 --- a/cmd/update.go +++ b/cmd/update.go @@ -52,14 +52,3 @@ and latest versions and does not download.`, command.Flags().BoolVarP(&yes, "yes", "y", false, "do not ask for confirmation") return command } - -func addCommandOnce(root *cobra.Command, command *cobra.Command) { - for _, existing := range root.Commands() { - if existing.Name() == command.Name() { - return - } - } - root.AddCommand(command) -} - -var updateCmd = newUpdateCommand() diff --git a/cmd/update_test.go b/cmd/update_test.go index 7432947..f9d0485 100644 --- a/cmd/update_test.go +++ b/cmd/update_test.go @@ -15,6 +15,7 @@ import ( ) func TestUpdateCommandFlags(t *testing.T) { + updateCmd := newUpdateCommand() if updateCmd.Name() != "update" { t.Fatalf("name %s", updateCmd.Name()) } @@ -119,36 +120,21 @@ func resetUpdateCommand(t *testing.T) { t.Helper() updateAPIBase = "" updateExecutable = "" - if err := updateCmd.Flags().Set("check", "false"); err != nil { - t.Fatal(err) - } - if err := updateCmd.Flags().Set("version", ""); err != nil { - t.Fatal(err) - } - if err := updateCmd.Flags().Set("yes", "false"); err != nil { - t.Fatal(err) - } t.Cleanup(func() { updateAPIBase = "" updateExecutable = "" - _ = updateCmd.Flags().Set("check", "false") - _ = updateCmd.Flags().Set("version", "") - _ = updateCmd.Flags().Set("yes", "false") - updateCmd.SetArgs(nil) }) } func executeUpdate(t *testing.T, stdin string, args ...string) (string, string, error) { t.Helper() - addCommandOnce(gatecheckCmd, updateCmd) out := &bytes.Buffer{} errBuf := &bytes.Buffer{} - root := updateCmd.Root() + root := NewGatecheckCommand() root.SetOut(out) root.SetErr(errBuf) root.SetIn(strings.NewReader(stdin)) root.SetArgs(append([]string{"update"}, args...)) err := root.Execute() - t.Cleanup(func() { root.SetArgs([]string{}) }) return out.String(), errBuf.String(), err } diff --git a/cmd/validate.go b/cmd/validate.go index dbfd66c..2ede836 100644 --- a/cmd/validate.go +++ b/cmd/validate.go @@ -1,97 +1,185 @@ package cmd import ( + "encoding/json" + "errors" "fmt" + "io" "log/slog" "os" "strings" + "github.com/gatecheckdev/gatecheck/pkg/format" "github.com/gatecheckdev/gatecheck/pkg/gatecheck" "github.com/spf13/cobra" ) -var validateCmd = &cobra.Command{ - Use: "validate [FILE]", - Short: "compare vulnerabilities to configured thresholds", - Args: cobra.ExactArgs(1), - PreRunE: func(cmd *cobra.Command, args []string) error { - configFilename := RuntimeConfig.ConfigFilename.Value().(string) +var validateFormats = []string{"table", "markdown", "json"} - RuntimeConfig.gatecheckConfig = gatecheck.NewDefaultConfig() - if configFilename != "" { - err := gatecheck.NewConfigDecoder(configFilename).Decode(RuntimeConfig.gatecheckConfig) - if err != nil { - return err - } - } +func newValidateCommand() *cobra.Command { + cmd := &cobra.Command{ + Use: "validate [FILE]", + Short: "compare a report or bundle to configured thresholds", + Long: `Compare a report or bundle to the thresholds in a config file. - var err error +FILE is required unless --input-type is set, in which case the report is read +from stdin. Exit status: 0 pass, 1 threshold failure, 2 usage, file, or +decode error, 3 EPSS or KEV data could not be loaded. --audit turns a +threshold failure into exit 0. It does not hide any other error.`, + Args: cobra.MaximumNArgs(1), + RunE: runValidate, + } + flags := cmd.Flags() + flags.StringP("config", "f", "", "validation config file (env GATECHECK_CONFIG_FILENAME)") + flags.StringP("input-type", "i", "", "report type when the contents are ambiguous, and the type of stdin when FILE is omitted ["+inputTypes+"]") + flags.BoolP("audit", "a", false, "exit 0 when a threshold fails; other errors still fail (env GATECHECK_AUDIT)") + flags.String("format", "", "also print the result to stdout: "+strings.Join(validateFormats, ", ")) + flags.StringSlice("vex", nil, "OpenVEX or CycloneDX VEX file; findings it marks not_affected, fixed, false_positive, or resolved are skipped (repeatable, env GATECHECK_VEX)") + addEPSSFlags(cmd, true) + addKEVFlags(cmd) + _ = cmd.MarkFlagFilename("config", "json", "yaml", "yml", "toml") + return cmd +} - epssFilename := RuntimeConfig.EPSSFilename.Value().(string) - if epssFilename != "" { - RuntimeConfig.epssFile, err = os.Open(epssFilename) - } - if err != nil { +func runValidate(cmd *cobra.Command, args []string) error { + outputFormat, _ := cmd.Flags().GetString("format") + if outputFormat != "" { + if err := oneOf("--format", outputFormat, validateFormats...); err != nil { return err } + } + audit, err := boolSetting(cmd, "audit", "GATECHECK_AUDIT") + if err != nil { + return err + } + inputType, _ := cmd.Flags().GetString("input-type") + if len(args) == 0 && inputType == "" { + return errors.New("need a FILE argument, or --input-type to read the report from stdin") + } - kevFilename := RuntimeConfig.KEVFilename.Value().(string) - if kevFilename != "" { - RuntimeConfig.kevFile, err = os.Open(kevFilename) - } - if err != nil { - return err - } + config, err := loadValidateConfig(cmd) + if err != nil { + return err + } - targetFilename := args[0] - slog.Debug("open target file", "filename", targetFilename) - RuntimeConfig.targetFile, err = os.Open(targetFilename) + var src io.Reader + name := "stdin" + if len(args) == 1 { + name = args[0] + slog.Debug("open target file", "filename", name) + f, err := os.Open(name) if err != nil { return err } + defer func() { _ = f.Close() }() + src = f + } else { + src = cmd.InOrStdin() + } + kindHint := name + if inputType != "" { + kindHint = inputType + } - return nil - }, - RunE: func(cmd *cobra.Command, args []string) error { - opts := []gatecheck.Option{ - gatecheck.WithEPSSURL(RuntimeConfig.EPSSURL.Value().(string)), - gatecheck.WithKEVURL(RuntimeConfig.KEVURL.Value().(string)), - gatecheck.WithEPSSFile(RuntimeConfig.epssFile), // TODO: fix this - gatecheck.WithKEVFile(RuntimeConfig.kevFile), - } - opts = append(opts, epssCacheOptions()...) - vexFiles, _ := cmd.Flags().GetStringSlice("vex") - if env := strings.TrimSpace(os.Getenv("GATECHECK_VEX")); len(vexFiles) == 0 && env != "" { - vexFiles = strings.Split(env, ",") - } - opts = append(opts, gatecheck.WithVEXFiles(vexFiles...)) - err := gatecheck.Validate( - RuntimeConfig.gatecheckConfig, - RuntimeConfig.targetFile, - args[0], - opts..., - ) + opts, closeFiles, err := fetchOptions(cmd) + if err != nil { + return err + } + defer closeFiles() + opts = append(opts, gatecheck.WithVEXFiles(stringSliceSetting(cmd, "vex", "GATECHECK_VEX")...)) - audit := RuntimeConfig.Audit.Value().(bool) - if audit && err != nil { - slog.Error("validation failure in audit mode") - _, err = fmt.Fprintln(cmd.ErrOrStderr(), err) + validateErr := gatecheck.Validate(config, src, kindHint, opts...) + + if outputFormat != "" { + if err := writeValidateResult(cmd.OutOrStdout(), outputFormat, name, validateErr); err != nil { return err } + } + if audit && errors.Is(validateErr, gatecheck.ErrValidationFailure) { + slog.Warn("validation failure ignored in audit mode") + _, _ = fmt.Fprintln(cmd.ErrOrStderr(), validateErr) + return nil + } + return validateErr +} - return err - }, +func loadValidateConfig(cmd *cobra.Command) (*gatecheck.Config, error) { + config := gatecheck.NewDefaultConfig() + filename := stringSetting(cmd, "config", "GATECHECK_CONFIG_FILENAME") + if filename == "" { + slog.Warn("no config file; using the default config, which has every rule disabled") + return config, nil + } + err := gatecheck.NewConfigDecoder(filename).Decode(config) + if errors.Is(err, gatecheck.ErrUnknownConfigKeys) { + slog.Warn("config has keys gatecheck does not read; check them for typos", "filename", filename, "keys", strings.TrimPrefix(err.Error(), gatecheck.ErrUnknownConfigKeys.Error()+": ")) + return config, nil + } + if err != nil { + return nil, err + } + return config, nil } -func newValidateCommand() *cobra.Command { +type validateResult struct { + Report string `json:"report"` + Passed bool `json:"passed"` + Failures []string `json:"failures"` + Error string `json:"error,omitempty"` +} - RuntimeConfig.ConfigFilename.SetupCobra(validateCmd) - RuntimeConfig.EPSSFilename.SetupCobra(validateCmd) - RuntimeConfig.EPSSCacheDir.SetupCobra(validateCmd) - RuntimeConfig.EPSSNoCache.SetupCobra(validateCmd) - RuntimeConfig.KEVFilename.SetupCobra(validateCmd) - RuntimeConfig.Audit.SetupCobra(validateCmd) - validateCmd.Flags().StringSlice("vex", nil, "OpenVEX or CycloneDX VEX file; findings it marks not_affected, fixed, false_positive, or resolved are skipped (repeatable, env GATECHECK_VEX)") +func newValidateResult(name string, err error) validateResult { + result := validateResult{Report: name, Passed: err == nil, Failures: []string{}} + if err == nil { + return result + } + if !errors.Is(err, gatecheck.ErrValidationFailure) { + result.Error = err.Error() + return result + } + prefix := gatecheck.ErrValidationFailure.Error() + ": " + var walk func(error) + walk = func(e error) { + if joined, ok := e.(interface{ Unwrap() []error }); ok { + for _, child := range joined.Unwrap() { + walk(child) + } + return + } + if errors.Is(e, gatecheck.ErrValidationFailure) { + result.Failures = append(result.Failures, strings.TrimPrefix(e.Error(), prefix)) + return + } + result.Error = e.Error() + } + walk(err) + return result +} - return validateCmd +func writeValidateResult(w io.Writer, outputFormat, name string, err error) error { + result := newValidateResult(name, err) + if outputFormat == "json" { + enc := json.NewEncoder(w) + enc.SetIndent("", " ") + return enc.Encode(result) + } + table := format.NewTable(w) + if outputFormat == "markdown" { + format.SetMarkdown(table) + } + table.Header([]string{"Report", "Result", "Detail"}) + switch { + case result.Passed: + _ = table.Append([]string{name, "pass", "-"}) + case result.Error != "" && len(result.Failures) == 0: + _ = table.Append([]string{name, "error", result.Error}) + default: + for _, failure := range result.Failures { + _ = table.Append([]string{name, "fail", failure}) + } + if result.Error != "" { + _ = table.Append([]string{name, "error", result.Error}) + } + } + return table.Render() } diff --git a/docs/agent-guide.md b/docs/agent-guide.md index dd10da1..77b5847 100644 --- a/docs/agent-guide.md +++ b/docs/agent-guide.md @@ -19,7 +19,7 @@ Logs go to stderr. Tables, `config init`, downloads, and this guide go to stdout - `completion bash|fish|powershell|zsh` prints a shell completion script. - `help [command]` prints the same text as ` --help`. -Global flags, on every command: `-v` / `--verbose` (debug logs) and `--silent` (errors only). They cannot be set together. `-h` / `--help` is also global. The scanner commands pass every argument through, including `--help`, so `gatecheck grype --help` is Grype's help. +Global flags, on every command: `-v` / `--verbose` (debug logs), `--silent` (warnings and errors), `--log-level debug|info|warn|error` (default `info`), and `--log-format text|json` (default `text`). Only one of `--verbose`, `--silent`, and `--log-level` can be set. `-h` / `--help` is also global. The scanner commands pass every argument through, including `--help`, so `gatecheck grype --help` is Grype's help. ## Scanners @@ -50,9 +50,9 @@ gatecheck zizmor --format sarif .github/workflows > zizmor.sarif `gatecheck semgrep scan` and `gatecheck osemgrep scan` insert `--experimental` after `scan` when that flag is absent. Other osemgrep commands need `--experimental` from the caller. `gatecheck semgrep --experimental --version` prints the osemgrep version. When the program that runs is the Python `semgrep` on `PATH`, the flag is left alone. `gatecheck osemgrep` looks for the managed binary, then `osemgrep` on `PATH`. -The managed binary wins when it is present. `gatecheck grype`, `gatecheck syft`, `gatecheck gitleaks`, `gatecheck trivy`, `gatecheck osv-scanner`, `gatecheck gosec`, `gatecheck hadolint`, and `gatecheck zizmor` otherwise run that name on `PATH`. `gatecheck semgrep` tries `semgrep` and then `osemgrep` on `PATH`. If none exist, the command prints `gatecheck: is not installed; run `gatecheck bootstrap`` and exits 255. A scanner's own exit status is returned as-is. +The managed binary wins when it is present. `gatecheck grype`, `gatecheck syft`, `gatecheck gitleaks`, `gatecheck trivy`, `gatecheck osv-scanner`, `gatecheck gosec`, `gatecheck hadolint`, and `gatecheck zizmor` otherwise run that name on `PATH`. `gatecheck semgrep` tries `semgrep` and then `osemgrep` on `PATH`. If none exist, the command prints `gatecheck: is not installed; run `gatecheck bootstrap`` and exits 2. A scanner's own exit status is returned as-is. -A platform with no release asset for a requested GitHub-hosted tool fails that tool and the command exits 255. A platform with no semgrep wheel prints a skip message on stderr and continues. Current pins are Grype `0.121.0`, Syft `1.55.0`, Gitleaks `8.30.1`, semgrep `1.182.1`, Trivy `0.76.1`, osv-scanner `2.7.0`, gosec `2.30.0`, hadolint `2.15.1`, and zizmor `1.32.0`, in `internal/bootstrap/versions.go`. +A platform with no release asset for a requested GitHub-hosted tool fails that tool and the command exits 2. A platform with no semgrep wheel prints a skip message on stderr and continues. Current pins are Grype `0.121.0`, Syft `1.55.0`, Gitleaks `8.30.1`, semgrep `1.182.1`, Trivy `0.76.1`, osv-scanner `2.7.0`, gosec `2.30.0`, hadolint `2.15.1`, and zizmor `1.32.0`, in `internal/bootstrap/versions.go`. Syft is installed so it can write CycloneDX (`syft -o cyclonedx-json`). That BOM is listed and validated as CycloneDX. Native Syft JSON is recognized from `descriptor.name` or the schema URL. `list` prints its packages and licenses, and `validate` runs the license rules on it. CycloneDX is a report format, and coverage tools are left to the language toolchain. @@ -112,7 +112,7 @@ gatecheck config convert --file gatecheck.yaml --output toml `config convert` reads `-f` / `--file` (default `gatecheck.yaml`). The extension selects the decoder: `.yaml`, `.yml`, `.json`, or `.toml`. -A partial file is fine. Omitted fields keep the default. Unknown keys are ignored. With no config, `validate` uses the built-in default: every rule disabled, coverage thresholds `0`. Grype, CycloneDX, Trivy, osv-scanner, SARIF, Semgrep, Gitleaks, coverage, and bundle reports pass under that default. Syft JSON passes too, since the license rules are off by default. An old config with no `sarif` section leaves those limits disabled. +A partial file is fine. Omitted fields keep the default. Unknown keys, such as a misspelled `severityLimt`, are named in a warning on stderr, and the rest of the file is still used. With no config, `validate` uses the built-in default: every rule disabled, coverage thresholds `0`. Grype, CycloneDX, Trivy, osv-scanner, SARIF, Semgrep, Gitleaks, coverage, and bundle reports pass under that default. Syft JSON passes too, since the license rules are off by default. An old config with no `sarif` section leaves those limits disabled. `GATECHECK_CONFIG_FILENAME` is the same setting as `validate --config` / `-f`. @@ -139,7 +139,7 @@ Field names below are the ones `config init` emits. In YAML they are case sensit `vex.files` lists OpenVEX or CycloneDX VEX documents, read along with `--vex`. -`coverage.lineThreshold`, `functionThreshold`, and `branchThreshold` are ratios from 0 to 1: covered lines, functions, or branches divided by the total. The report fails when its ratio is less than the threshold. A ratio equal to the threshold passes. `0.8` is 80 percent. `80` fails a report whose real line coverage is 0.8, because 0.8 is less than 80. There is no `enabled` flag. The default `0` allows any coverage, because a ratio is never less than 0. `list` prints these numbers as percents in the table footer. The config still wants the ratio. A report with no records of a kind, such as LCOV without branch records, has no ratio for it. `list` prints `N/A`, and `validate` skips that threshold with a warning. +`coverage.lineThreshold`, `functionThreshold`, and `branchThreshold` are ratios from 0 to 1: covered lines, functions, or branches divided by the total. The report fails when its ratio is less than the threshold. A ratio equal to the threshold passes. `0.8` is 80 percent. A threshold over 1 is read as a percent, so `80` means `0.8`, and a warning says so. There is no `enabled` flag. The default `0` allows any coverage, because a ratio is never less than 0. `list` prints these numbers as percents in the table footer. The config still wants the ratio. A report with no records of a kind, such as LCOV without branch records, has no ratio for it. `list` prints `N/A`, and `validate` skips that threshold with a warning. Grype, CycloneDX, Trivy, and osv-scanner rules run in this order. A failure returns immediately, except where a rule only removes findings. Trivy counts vulnerability entries only. osv-scanner counts one finding per group. @@ -173,17 +173,18 @@ gatecheck validate --config gatecheck.yaml grype-report.json gatecheck validate --audit --config gatecheck.yaml gatecheck-bundle.tar.gz ``` -The report path is the only positional argument, and it is required. Pass the config with `--config` or `-f`. +The report path is the positional argument. With no path, `--input-type` is required and the report is read from stdin. Pass the config with `--config` or `-f`. With no config, a warning says every rule is disabled. -Exit status: +Exit status, for `validate` and every other gatecheck command: -- `0`: the report passed. With `--audit` / `-a`, a check error is printed and the process also exits 0. +- `0`: success. With `--audit` / `-a`, a threshold failure is printed to stderr and the process still exits 0. - `1`: a threshold failed and `--audit` is off. The error text starts with `validation failure:`. -- `255`: the report or config could not be opened, the config extension is not supported, the command line was rejected, or another check error occurred with `--audit` off. +- `2`: usage error, a file that could not be opened or written, or a report, config, or VEX file that could not be decoded. `--audit` does not change this. +- `3`: EPSS or KEV data could not be downloaded or read. `--audit` does not change this. -Opening the report, the config, and any `--epss-filename` or `--kev-filename` happens before the audit check. A missing file still exits 255 when `--audit` is set. +`--format table|markdown|json` also prints the result to stdout. JSON is `{"report": "...", "passed": false, "failures": ["Grype: Severity Limit Exceeded"]}`, plus `"error"` when the check stopped on something else. Without `--format`, stdout is empty. -`--epss-filename` is the EPSS CSV used when an EPSS rule is enabled. `--kev-filename` is the CISA KEV JSON used when `kevLimitEnabled` is true. `--epss-cache-dir` and `--epss-no-cache` apply when that CSV is downloaded. `validate` has no `--epss-url` or `--kev-url` flag. `GATECHECK_EPSS_URL` and `GATECHECK_KEV_URL` still override those APIs when the matching file is not set. The defaults are the same URLs `download` uses. +`--epss-filename` is the EPSS CSV used when an EPSS rule is enabled. `--kev-filename` is the CISA KEV JSON used when `kevLimitEnabled` is true. `--epss-url` and `--kev-url` change the feeds. `--epss-cache-dir` and `--epss-no-cache` apply when that CSV is downloaded. `--vex FILE` (repeatable), `GATECHECK_VEX` (comma-separated, used when the flag is absent), and the config's `vex.files` name OpenVEX or CycloneDX VEX documents. Grype, CycloneDX, Trivy, and osv-scanner findings that a VEX file marks `not_affected` or `fixed` (OpenVEX), or `not_affected`, `false_positive`, `resolved`, or `resolved_with_pedigree` (CycloneDX `analysis.state`), are removed right after the `cveLimit` deny list, so they skip the KEV, EPSS, and severity rules. Ids match the finding's id or aliases. A statement that lists subcomponents or `affects` refs matches only those package URLs. The OpenVEX product itself is not checked. When several statements match, the latest timestamp wins. @@ -193,14 +194,15 @@ EPSS data is loaded only when an EPSS limit or EPSS risk acceptance rule is enab ```shell gatecheck list grype-report.json -gatecheck list --markdown --epss grype-report.json +gatecheck list --format markdown --epss grype-report.json +gatecheck list --format json trivy-report.json grype image:tag -o json | gatecheck ls --input-type grype gatecheck list-all grype-report.json semgrep-report.json ``` -`list` opens the first filename only. Further filenames are ignored. `--markdown` prints a markdown table. A Grype, CycloneDX, SARIF, Semgrep, Gitleaks, Trivy, or osv-scanner report with no findings prints one sentence and no table, with or without `--markdown`: `No grype vulnerabilities`, `No cyclonedx vulnerabilities`, `No sarif findings`, `No semgrep findings`, `No gitleaks findings`, `No trivy vulnerabilities`, or `No osv-scanner vulnerabilities`. `--epss` adds EPSS score and percentile columns for Grype, CycloneDX, Trivy, and osv-scanner. Other report types still list, and those columns are omitted. `--epss-url` empty uses `https://epss.cyentia.com`. `--epss-filename` reads that CSV instead of calling the API. +`list` takes one filename, or stdin with `--input-type`. `--format table|markdown|json` picks the output, and `--markdown` is the same as `--format markdown`. JSON is `{"columns": [...], "rows": [{column: value}], "footer": {...}}`. A Grype, CycloneDX, SARIF, Semgrep, Gitleaks, Trivy, osv-scanner, or Syft report with nothing in it prints one sentence and no table: `No grype vulnerabilities`, `No cyclonedx vulnerabilities`, `No sarif findings`, `No semgrep findings`, `No gitleaks findings`, `No trivy vulnerabilities`, `No osv-scanner vulnerabilities`, or `No syft packages`. In JSON that is `{"columns": [], "rows": [], "message": "..."}`. Syft JSON lists package, version, type, and licenses. `--epss` adds EPSS score and percentile columns for Grype, CycloneDX, Trivy, and osv-scanner. Other report types still list, and those columns are omitted. `--epss-url` empty uses `https://epss.cyentia.com`. `--epss-filename` reads that CSV instead of calling the API. -`list-all` prints each filename, then its table, or that sentence when the report has no findings. A file whose contents and name are not a supported `list-all` type is skipped with a warning. A missing file is skipped. A list error is logged and the command continues. The command exits 0. `--epss` adds EPSS data for Grype, CycloneDX, Trivy, and osv-scanner, including a file whose name does not contain those words when the contents do. There is no `--epss-filename` flag, and `GATECHECK_EPSS_FILENAME` is not read. `GATECHECK_EPSS_URL` overrides the API. `--epss-cache-dir` and `--epss-no-cache` are accepted. +`list-all` prints each filename, then its table, or that sentence when the report has nothing in it. With `--format json` it prints one array of `{"file": ..., "report": ...}`. A file whose contents and name are not a supported `list-all` type is skipped with a warning. A file that cannot be read or listed is logged, the rest are still listed, and the command then exits 2. `--epss` adds EPSS data for Grype, CycloneDX, Trivy, and osv-scanner, loaded once per run. `--epss-filename`, `--epss-url`, `--epss-cache-dir`, and `--epss-no-cache` work as on `list`. ## bundle @@ -213,7 +215,7 @@ gatecheck bundle remove gatecheck-bundle.tar.gz semgrep-report.json gatecheck list gatecheck-bundle.tar.gz ``` -The stored label is the base name of the target file (`reports/grype-report.json` is stored as `grype-report.json`). Later validation uses the file contents to pick the type, and the label when the contents are ambiguous. Repeat `-t` / `--tag` for more than one tag. When the flag is omitted, `GATECHECK_BUNDLE_TAG` is read as a comma-separated list. `bundle add` requires an existing bundle. `bundle remove` takes the label, not a path that is opened. A label that is not in the bundle is logged and the command exits 0. There is no `bundle list` subcommand. `gatecheck list` prints label, SHA-256 digest, tags, and size. +The stored label is the base name of the target file (`reports/grype-report.json` is stored as `grype-report.json`). Later validation uses the file contents to pick the type, and the label when the contents are ambiguous. Repeat `-t` / `--tag` for more than one tag. When the flag is omitted, `GATECHECK_BUNDLE_TAG` is read as a comma-separated list. `bundle create` replaces an existing file. `bundle add` requires an existing bundle. `bundle remove` takes the label, not a path that is opened. A label that is not in the bundle exits 2 and leaves the bundle unchanged. There is no `bundle list` subcommand. `gatecheck list` prints label, SHA-256 digest, tags, and size. ## download @@ -230,23 +232,25 @@ EPSS requests send a User-Agent with the gatecheck version and `https://github.c ## Environment variables -A non-empty flag wins. An empty flag falls through to the environment variable, then to the default. - | Variable | Commands | Same as | | --- | --- | --- | | `GATECHECK_CONFIG_FILENAME` | `validate` | `--config` | +| `GATECHECK_AUDIT` | `validate` | `--audit` | | `GATECHECK_VEX` | `validate` | `--vex`, comma-separated | -| `GATECHECK_EPSS_FILENAME` | `list`, `validate` | `--epss-filename` | -| `GATECHECK_EPSS_URL` | `download epss`, `list`, `list-all`, `validate` | `--epss-url` on commands that have that flag | +| `GATECHECK_EPSS_FILENAME` | `list`, `list-all`, `validate` | `--epss-filename` | +| `GATECHECK_EPSS_URL` | `download epss`, `list`, `list-all`, `validate` | `--epss-url` | | `GATECHECK_EPSS_CACHE_DIR` | `download epss`, `list`, `list-all`, `validate` | `--epss-cache-dir` | | `GATECHECK_EPSS_CACHE` | `download epss`, `list`, `list-all`, `validate` | `--epss-no-cache` when the value is `off` | -| `GATECHECK_KEV_URL` | `download kev`, `validate` | `--kev-url` on `download kev` | +| `GATECHECK_KEV_FILENAME` | `validate` | `--kev-filename` | +| `GATECHECK_KEV_URL` | `download kev`, `validate` | `--kev-url` | | `GATECHECK_BUNDLE_TAG` | `bundle create`, `bundle add` | `--tag`, as a comma-separated list | +| `GATECHECK_VERBOSE` | every command | `--verbose` | +| `GATECHECK_SILENT` | every command | `--silent` | +| `GATECHECK_LOG_LEVEL` | every command | `--log-level` | +| `GATECHECK_LOG_FORMAT` | every command | `--log-format` | | `GATECHECK_HOME` | `bootstrap`, `grype`, `syft`, `gitleaks`, `semgrep`, `osemgrep`, `trivy`, `osv-scanner`, `gosec`, `hadolint`, `zizmor` | data directory; binaries are in `bin` under it | -`GATECHECK_EPSS_CACHE` also disables the cache for `0`, `false`, `no`, `disabled`, `disable`, and `none`. - -`GATECHECK_EPSS_FILE`, `GATECHECK_KEV_FILE`, and `GATECHECK_CLI_AUDIT` are not read. There is no `GATECHECK_KEV_FILENAME`. The KEV filename setting is bound to `GATECHECK_EPSS_FILENAME`, so that variable also selects the KEV file. Pass a local catalog with `--kev-filename`. `GATECHECK_VERBOSE`, `GATECHECK_SILENT`, and `GATECHECK_AUDIT` are not parsed as booleans. Use `--verbose`, `--silent`, and `--audit`. A non-empty value in those three variables can panic. +A flag on the command line wins over its variable. An empty variable counts as unset. `GATECHECK_AUDIT`, `GATECHECK_VERBOSE`, and `GATECHECK_SILENT` take `true`, `false`, `1`, `0`, `t`, or `f`, and any other value exits 2. `GATECHECK_EPSS_CACHE` also disables the cache for `0`, `false`, `no`, `disabled`, `disable`, and `none`. ## Minimal CI @@ -260,10 +264,10 @@ Create the config with `gatecheck config init > gatecheck.yaml` and set real thr ## Common mistakes - The contents do not identify a type and the filename has no lowercase type word (`scan.json`, `Grype.json`). A real bundle named `project.gcb` is still recognized from its contents. An empty document such as `{"matches":[]}` still needs a name such as `grype-report.json`, or `--input-type grype` on standard input. -- Coverage thresholds are ratios. Set `coverage.lineThreshold` to `0.8` for 80 percent, not `80` or `80.0`. +- Coverage thresholds are ratios. Set `coverage.lineThreshold` to `0.8` for 80 percent. A value over 1, such as `80`, is read as a percent with a warning. - `validate` takes the report as its positional argument. The config is `--config` / `-f`. `gatecheck validate gatecheck.yaml grype-report.json` tries to open the config as a report. `config convert` uses `--file` / `-f`, which is a different flag. -- `list` on a pipe needs `--input-type`. Clear contents still win over that flag. `validate` needs a filesystem path. -- `list` ignores every filename after the first. Use `list-all` for several files. `list-all` skips coverage files such as `lcov.info`. List those with `gatecheck list lcov.info`. +- `list` and `validate` on a pipe need `--input-type`. Clear contents still win over that flag. +- `list` takes one filename, and a second one exits 2. Use `list-all` for several files. `list-all` skips coverage files such as `lcov.info`. List those with `gatecheck list lcov.info`. - Native Syft JSON gets only the license rules. Use CycloneDX output when you also want vulnerabilities scored. That BOM is CycloneDX even when the filename contains `syft`. - `gatecheck semgrep --version` reaches osemgrep without `--experimental`, and osemgrep then tries to run `pysemgrep`. Pass the flag: `gatecheck semgrep --experimental --version`. -- `--audit` still exits 255 when the report, the config, or a named EPSS or KEV file cannot be opened. +- `--audit` only hides threshold failures. It still exits 2 when the report, the config, or a named EPSS, KEV, or VEX file cannot be opened, and 3 when EPSS or KEV data cannot be loaded. diff --git a/docs/bootstrap.md b/docs/bootstrap.md index 6178807..9e07963 100644 --- a/docs/bootstrap.md +++ b/docs/bootstrap.md @@ -72,7 +72,7 @@ Published assets: - Trivy: macOS amd64 and arm64; Linux 386, amd64, armv7, arm64, ppc64le, and s390x; Windows amd64; FreeBSD amd64. - gosec: macOS amd64 and arm64; Linux amd64, arm64, ppc64le, and s390x; Windows amd64 and arm64. -A platform with no asset fails that tool. The message looks like `grype has no published release asset for windows/arm64`. Other requested tools still install. The command exits 255 when any requested tool failed this way, or when a download or checksum check failed. +A platform with no asset fails that tool. The message looks like `grype has no published release asset for windows/arm64`. Other requested tools still install. The command exits 2 when any requested tool failed this way, or when a download or checksum check failed. ## osv-scanner @@ -142,7 +142,7 @@ Arguments, standard input, standard output, standard error, and the scanner's ex The managed binary is used when it is present. Otherwise gatecheck looks on `PATH`: `grype`, `syft`, `gitleaks`, `trivy`, `osv-scanner`, `gosec`, `hadolint`, or `zizmor` for those commands; `semgrep` and then `osemgrep` for `gatecheck semgrep`; `osemgrep` only for `gatecheck osemgrep`. `--experimental` is inserted only when the program that will run is named `osemgrep`. A Python `semgrep` on `PATH` is left unchanged. -When neither copy exists, the command prints one line and exits 255: +When neither copy exists, the command prints one line and exits 2: ``` gatecheck: grype is not installed; run `gatecheck bootstrap` diff --git a/docs/cli-reference.md b/docs/cli-reference.md index ae61ca4..1917dfd 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -2,13 +2,25 @@ Global flags, accepted on every command: -- `-v`, `--verbose`: print debug logs. -- `--silent`: hide debug, info, and warning logs. Errors are still printed. +- `-v`, `--verbose`: print debug logs. The same as `--log-level debug`. `GATECHECK_VERBOSE=true` is the same setting. +- `--silent`: print only warnings and errors. The same as `--log-level warn`. `GATECHECK_SILENT=true` is the same setting. +- `--log-level`: `debug`, `info`, `warn`, or `error`. The default is `info`. `GATECHECK_LOG_LEVEL` is the same setting. +- `--log-format`: `text` or `json`. The default is `text`, colored only when standard error is a terminal and `NO_COLOR` is unset. `GATECHECK_LOG_FORMAT` is the same setting. - `-h`, `--help`: help for that command. -`--verbose` and `--silent` cannot be set together. +`--verbose`, `--silent`, and `--log-level` cannot be set together. A flag wins over any of the variables. Among the variables, `GATECHECK_VERBOSE` and `GATECHECK_SILENT` win over `GATECHECK_LOG_LEVEL`, and setting both of them to true is an error. -When a setting has both a flag and an environment variable, a non-empty flag wins. An empty flag falls through to the environment variable, then to the default. +Every setting is read in the same order: a flag on the command line, then its environment variable, then the default. An empty environment variable counts as unset. Boolean variables take `true`, `false`, `1`, `0`, `t`, or `f`. Any other value is a usage error, and the command exits 2. + +## Exit status + +- `0`: success. +- `1`: `validate` found a threshold failure. +- `2`: a usage error, a file that could not be read or written, or a report, config, or VEX file that could not be decoded. +- `3`: EPSS or KEV data could not be downloaded or read. +- The scanner commands (`grype`, `syft`, `gitleaks`, `semgrep`, `osemgrep`, `trivy`, `osv-scanner`, `gosec`, `hadolint`, `zizmor`) return the scanner's own status. + +`validate --audit` turns status 1 into 0. It does not change 2 or 3. ## gatecheck @@ -35,9 +47,9 @@ Prints the logo and the build information: CLI version, git commit, build date, gatecheck config init ``` -Prints a default config to standard output. Every rule is disabled and every coverage threshold is `0`. +Prints a default config to standard output. Every rule is disabled and every coverage threshold is `0`. JSON and YAML are indented by two spaces, and TOML tables are indented. -- `-o`, `--output`: `json`, `.json`, `toml`, `.toml`, `yaml`, `yml`, `.yaml`, or `.yml`. The default is `yaml`. Any other value is an error. The match is case sensitive. +- `-o`, `--output`: `json`, `toml`, `yaml`, or `yml`, with or without a leading dot, in any case. The default is `yaml`. Any other value is an error. ```shell gatecheck config init > gatecheck.yaml @@ -50,7 +62,7 @@ gatecheck config init --output json > gatecheck.json gatecheck config convert ``` -Reads a config file and prints it in another format. +Reads a config file and prints it in another format. Keys gatecheck does not read are named in a warning and left out of the output. - `-f`, `--file`: file to read. The default is `gatecheck.yaml`. The extension picks the decoder (`.yaml`, `.yml`, `.json`, `.toml`). - `-o`, `--output`: format to write. Same accepted values as `config init`. The default is `yaml`. @@ -67,38 +79,42 @@ gatecheck list [FILE] Aliases: `ls`, `print`. -Prints a table for one report. The first filename is the one that is opened. Further filenames are ignored. Use `list-all` for more than one file. A Grype, CycloneDX, SARIF, Semgrep, Gitleaks, Trivy, or osv-scanner report with no findings prints one sentence and no table: `No grype vulnerabilities`, `No cyclonedx vulnerabilities`, `No sarif findings`, `No semgrep findings`, `No gitleaks findings`, `No trivy vulnerabilities`, or `No osv-scanner vulnerabilities`. `--markdown` prints that same sentence. +Prints a table for one report. Use `list-all` for more than one file. A Grype, CycloneDX, SARIF, Semgrep, Gitleaks, Trivy, osv-scanner, or Syft report with nothing in it prints one sentence and no table: `No grype vulnerabilities`, `No cyclonedx vulnerabilities`, `No sarif findings`, `No semgrep findings`, `No gitleaks findings`, `No trivy vulnerabilities`, `No osv-scanner vulnerabilities`, or `No syft packages`. Markdown prints that same sentence. The report type comes from the file contents. See [Supported Reports](./supported-reports.md). With no filename, the command reads standard input and `--input-type` is required. -- `-i`, `--input-type`: type word used when reading standard input and the contents are ambiguous. It is matched with the same rules as a filename. `grype`, `cyclonedx`, `sarif`, `semgrep`, `gitleaks`, `trivy`, `osv`, `syft`, `bundle`, and the coverage words all work. Clear contents win over this flag. See [Supported Reports](./supported-reports.md). -- `--markdown`: print a markdown table. +- `-i`, `--input-type`: type word used when the contents are ambiguous, and the type of standard input. It is matched with the same rules as a filename. `grype`, `cyclonedx`, `sarif`, `semgrep`, `gitleaks`, `trivy`, `osv`, `syft`, `bundle`, and the coverage words `lcov`, `clover`, and `cobertura` all work. Clear contents win over this flag. See [Supported Reports](./supported-reports.md). +- `--format`: `table` (the default), `markdown`, or `json`. JSON is `{"columns": [...], "rows": [{column: value}], "footer": {...}}`. A report with nothing in it is `{"columns": [], "rows": [], "message": "No grype vulnerabilities"}`. A bundle is its manifest. +- `--markdown`: the same as `--format markdown`. It cannot be combined with another `--format`. - `--epss`: add EPSS score and percentile columns. This changes the table for Grype, CycloneDX, Trivy, and osv-scanner. Other report types still list, and the EPSS data is not shown. With no local file, gatecheck downloads the current EPSS CSV and caches it until the published date changes. Requests send a User-Agent with the gatecheck version and project URL. - `--epss-filename`: read that CSV instead of calling the API. `GATECHECK_EPSS_FILENAME` is the same setting. - `--epss-url`: EPSS API URL. An empty value uses `https://epss.cyentia.com`. `GATECHECK_EPSS_URL` is the same setting. - `--epss-cache-dir`: cache directory for that download. `GATECHECK_EPSS_CACHE_DIR` is the same setting. - `--epss-no-cache`: download on every run. `GATECHECK_EPSS_CACHE=off` does the same. +A failed EPSS download or an unreadable EPSS file exits 3. + ```shell gatecheck list grype-report.json -gatecheck list --markdown --epss grype-report.json +gatecheck list --format markdown --epss grype-report.json +gatecheck list --format json trivy-report.json grype bkimminich/juice-shop:latest -o json | gatecheck ls --input-type grype ``` ## gatecheck list-all ``` -gatecheck list-all [FILE...] +gatecheck list-all FILE... ``` -Prints each filename, then its table, or one sentence when that report has no findings. A file whose contents and name are not a supported `list-all` type is skipped with a warning. Coverage files are in that skipped set. A missing file is skipped. A list error is logged and the command continues. The command exits 0 after the last file. +Prints each filename, then its table, or one sentence when that report has nothing in it. A file whose contents and name are not a supported `list-all` type is skipped with a warning. Coverage files are in that skipped set. A file that cannot be read or listed is logged and the command goes on to the next one. When any file could not be read or listed, the command exits 2 after the last file. At least one file is required. -- `--markdown`: print markdown tables. -- `--epss`: download EPSS data and add it for Grype, CycloneDX, Trivy, and osv-scanner reports. The type comes from the file contents, then the filename. The download happens per file and is cached until the published date changes. There is no `--epss-filename` flag. `GATECHECK_EPSS_URL` overrides the API. `GATECHECK_EPSS_FILENAME` is not read by this command. Requests send a User-Agent with the gatecheck version and project URL. -- `--epss-cache-dir`: cache directory for that download. `GATECHECK_EPSS_CACHE_DIR` is the same setting. -- `--epss-no-cache`: download on every run. `GATECHECK_EPSS_CACHE=off` does the same. +- `--format`: `table`, `markdown`, or `json`. JSON is one array: `[{"file": "grype-report.json", "report": {...}}]`, where `report` is what `list --format json` prints. Skipped files are not in the array. +- `--markdown`: the same as `--format markdown`. +- `--epss`: add EPSS data for Grype, CycloneDX, Trivy, and osv-scanner reports. The type comes from the file contents, then the filename. EPSS data is loaded once, the first time a file needs it. +- `--epss-filename`, `--epss-url`, `--epss-cache-dir`, and `--epss-no-cache`: the same as on `list`, with the same environment variables. ## gatecheck validate @@ -106,21 +122,23 @@ Prints each filename, then its table, or one sentence when that report has no fi gatecheck validate [FILE] ``` -`FILE` is required. The config is a flag. +`FILE` is the report or bundle. With no `FILE`, `--input-type` is required, and the report is read from standard input. The config is a flag. -- `-f`, `--config`: config file. `GATECHECK_CONFIG_FILENAME` is the same setting. With neither, the built-in default config is used (every rule disabled, coverage thresholds `0`). +- `-f`, `--config`: config file. `GATECHECK_CONFIG_FILENAME` is the same setting. With neither, the built-in default config is used (every rule disabled, coverage thresholds `0`), and a warning says so. Keys in the config that gatecheck does not read are named in a warning, and the rest of the file is still used. +- `-i`, `--input-type`: report type word, the same as on `list`. It is used when the contents are ambiguous, and it is required when reading standard input. +- `-a`, `--audit`: print a threshold failure and exit 0. Any other error still fails: a missing report or config is 2, and an EPSS or KEV fetch failure is 3. `GATECHECK_AUDIT` is the same setting. +- `--format`: also print the result to standard output as `table`, `markdown`, or `json`. With no `--format`, standard output is empty. JSON is `{"report": "grype-report.json", "passed": false, "failures": ["Grype: Severity Limit Exceeded"]}`, plus `"error"` when the check stopped on something other than a threshold. +- `--vex`: OpenVEX or CycloneDX VEX file. Findings it marks not exploitable are skipped. Repeat the flag for more files. `GATECHECK_VEX` is a comma-separated list used when the flag is absent. Files in the config's `vex.files` are read too. A VEX file that cannot be read exits 2. See [VEX](./vex.md). - `--epss-filename`: EPSS CSV to use when an EPSS rule is enabled. `GATECHECK_EPSS_FILENAME` is the same setting. +- `--epss-url`: EPSS feed URL. `GATECHECK_EPSS_URL` is the same setting. - `--epss-cache-dir`: cache directory used when that CSV is downloaded. `GATECHECK_EPSS_CACHE_DIR` is the same setting. - `--epss-no-cache`: download on every run. `GATECHECK_EPSS_CACHE=off` does the same. -- `--kev-filename`: CISA KEV JSON to use when a KEV rule is enabled. -- `-a`, `--audit`: print the error from the check and exit 0. A missing report, a missing config, or a bad flag still exits 255. -- `--vex`: OpenVEX or CycloneDX VEX file. Findings it marks not exploitable are skipped. Repeat the flag for more files. `GATECHECK_VEX` is a comma-separated list used when the flag is absent. Files in the config's `vex.files` are read too. A VEX file that cannot be read exits 255. See [VEX](./vex.md). - -`validate` has no `--epss-url` or `--kev-url` flag. `GATECHECK_EPSS_URL` and `GATECHECK_KEV_URL` still override those APIs when the matching file flag is empty. The defaults are the same URLs `download` uses. +- `--kev-filename`: CISA KEV JSON to use when a KEV rule is enabled. `GATECHECK_KEV_FILENAME` is the same setting. +- `--kev-url`: KEV feed URL. `GATECHECK_KEV_URL` is the same setting. EPSS data is loaded only when an EPSS limit or EPSS risk acceptance rule is enabled. When `--epss-filename` is not set, gatecheck downloads the current EPSS file and caches it until the published date changes. Requests send a User-Agent with the gatecheck version and project URL. -KEV data is loaded only when `kevLimitEnabled` is true for Grype or CycloneDX. +KEV data is loaded only when `kevLimitEnabled` is true for Grype, CycloneDX, Trivy, or osv-scanner. ```shell gatecheck validate --config gatecheck.yaml grype-report.json @@ -137,7 +155,7 @@ gatecheck bundle create BUNDLE_FILE TARGET_FILE Alias: `init`. -Creates a bundle and stores the target file in it. The label is the base name of the target file (`reports/grype-report.json` is stored as `grype-report.json`). +Creates a bundle and stores the target file in it. An existing `BUNDLE_FILE` is replaced. The label is the base name of the target file (`reports/grype-report.json` is stored as `grype-report.json`). - `-t`, `--tag`: tag stored on that file. Repeat the flag for more than one tag. `GATECHECK_BUNDLE_TAG` is a comma-separated list used when no tag flag is passed. @@ -161,7 +179,7 @@ gatecheck bundle remove BUNDLE_FILE LABEL Alias: `rm`. -Deletes the file with that label. The label is the base name used when the file was added, not a path that is opened. A label that is not in the bundle is logged and the command still exits 0. +Deletes the file with that label. The label is the base name used when the file was added, not a path that is opened. A label that is not in the bundle is an error: the bundle is left as it was and the command exits 2. ## gatecheck download epss @@ -177,6 +195,8 @@ EPSS scores are cached in the user cache directory, under `gatecheck/epss`. gate - `--epss-cache-dir`: cache directory. `GATECHECK_EPSS_CACHE_DIR` is the same setting. - `--epss-no-cache`: download on every run. `GATECHECK_EPSS_CACHE=off` does the same. +A failed download exits 3. + ```shell gatecheck download epss > epss.csv ``` @@ -191,6 +211,8 @@ Writes the CISA Known Exploited Vulnerabilities catalog as JSON to standard outp - `--kev-url`: API URL. An empty value uses `https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json`. `GATECHECK_KEV_URL` is the same setting. +A failed download exits 3. + ```shell gatecheck download kev > kev.json ``` @@ -235,7 +257,7 @@ The managed copy is preferred. If it is absent, the same tool name on `PATH` is `semgrep` and `osemgrep` run the osemgrep binary from the semgrep wheel. For `scan`, `--experimental` is added when you omitted it and the program that will run is named `osemgrep`. Other osemgrep commands need you to pass `--experimental`. `gatecheck semgrep --experimental --version` prints the osemgrep version. -If no binary is found, the command prints `gatecheck: is not installed; run `gatecheck bootstrap`` and exits 255. +If no binary is found, the command prints `gatecheck: is not installed; run `gatecheck bootstrap`` and exits 2. ## gatecheck agent-guide @@ -306,11 +328,19 @@ Prints help for a command. `gatecheck validate --help` does the same. | Variable | Commands | Same as | | --- | --- | --- | | `GATECHECK_CONFIG_FILENAME` | `validate` | `--config` | +| `GATECHECK_AUDIT` | `validate` | `--audit` | | `GATECHECK_VEX` | `validate` | `--vex`, comma-separated | -| `GATECHECK_EPSS_FILENAME` | `list`, `validate` | `--epss-filename` | -| `GATECHECK_EPSS_URL` | `download epss`, `list`, `list-all`, `validate` | `--epss-url` on `download epss` and `list` | +| `GATECHECK_EPSS_FILENAME` | `list`, `list-all`, `validate` | `--epss-filename` | +| `GATECHECK_EPSS_URL` | `download epss`, `list`, `list-all`, `validate` | `--epss-url` | | `GATECHECK_EPSS_CACHE_DIR` | `download epss`, `list`, `list-all`, `validate` | `--epss-cache-dir` | | `GATECHECK_EPSS_CACHE` | `download epss`, `list`, `list-all`, `validate` | `--epss-no-cache` when the value is `off` | -| `GATECHECK_KEV_URL` | `download kev`, `validate` | `--kev-url` on `download kev` | +| `GATECHECK_KEV_FILENAME` | `validate` | `--kev-filename` | +| `GATECHECK_KEV_URL` | `download kev`, `validate` | `--kev-url` | | `GATECHECK_BUNDLE_TAG` | `bundle create`, `bundle add` | `--tag`, as a comma-separated list | +| `GATECHECK_VERBOSE` | every command | `--verbose` | +| `GATECHECK_SILENT` | every command | `--silent` | +| `GATECHECK_LOG_LEVEL` | every command | `--log-level` | +| `GATECHECK_LOG_FORMAT` | every command | `--log-format` | | `GATECHECK_HOME` | `bootstrap`, `grype`, `syft`, `gitleaks`, `semgrep`, `osemgrep`, `trivy`, `osv-scanner`, `gosec`, `hadolint`, `zizmor` | data directory; binaries are in `bin` under it | + +A flag on the command line wins over its variable. An empty variable counts as unset. `GATECHECK_AUDIT`, `GATECHECK_VERBOSE`, and `GATECHECK_SILENT` take `true`, `false`, `1`, `0`, `t`, or `f`, and any other value exits 2. `GATECHECK_EPSS_CACHE` also disables the cache for `0`, `false`, `no`, `disabled`, `disable`, and `none`. diff --git a/docs/configuration.md b/docs/configuration.md index 54d2d52..7bdc550 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -14,7 +14,7 @@ gatecheck config convert --file gatecheck.yaml --output json `config convert` reads `--file` / `-f` (default `gatecheck.yaml`) and writes the other format to standard output. -A partial file is fine. Omitted fields keep the default. Keys the decoder does not know are ignored. +A partial file is fine. Omitted fields keep the default. Keys gatecheck does not read are named in a warning when `validate` or `config convert` loads the file, and the rest of the file is still used. `GATECHECK_CONFIG_FILENAME` is the same setting as `validate --config`. @@ -306,7 +306,7 @@ license: - function coverage is covered functions divided by total functions - branch coverage is covered branches divided by total branches -The report fails when its ratio is less than the threshold. `0.8` is 80 percent. `80.0` fails a report whose real line coverage is 0.8, because 0.8 is less than 80. +The report fails when its ratio is less than the threshold. `0.8` is 80 percent. A threshold over 1 is read as a percent: `80` means `0.8`, and `validate` logs a warning. Write the ratio to avoid the warning. There is no `enabled` flag. The default `0` allows any coverage, because a ratio is never less than 0. diff --git a/docs/examples.md b/docs/examples.md index eb0f520..9d20778 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -34,7 +34,7 @@ gatecheck validate --config gatecheck.yaml gatecheck-bundle.tar.gz gatecheck validate --audit --config gatecheck.yaml grype-report.json ``` -A threshold failure is printed and the process exits 0. A missing report still exits 255. +A threshold failure is printed and the process exits 0. A missing report still exits 2, and an EPSS or KEV download failure still exits 3. ## Bootstrap a scanner diff --git a/docs/gatecheck-bundle.md b/docs/gatecheck-bundle.md index 97f20f5..5b1d6f2 100644 --- a/docs/gatecheck-bundle.md +++ b/docs/gatecheck-bundle.md @@ -27,7 +27,7 @@ The bundle file has to exist already. gatecheck bundle remove gatecheck-bundle.tar.gz semgrep-report.json ``` -`bundle rm` is the same command. The second argument is the label. A label that is not in the bundle is logged, and the command exits 0. +`bundle rm` is the same command. The second argument is the label. A label that is not in the bundle is an error. The bundle is left unchanged and the command exits 2. ## Inspect diff --git a/docs/library-usage.md b/docs/library-usage.md index f516491..66681bd 100644 --- a/docs/library-usage.md +++ b/docs/library-usage.md @@ -7,11 +7,12 @@ import "github.com/gatecheckdev/gatecheck/pkg/gatecheck" ``` - `NewDefaultConfig` returns the same defaults as `gatecheck config init`: rules disabled, coverage thresholds `0`. -- `NewConfigDecoder` reads `.yaml`, `.yml`, `.json`, or `.toml`. The extension selects the format. -- `NewConfigEncoder` writes a config. Pass `.yaml`, `.yml`, `.json`, or `.toml`, including the dot. +- `NewConfigDecoder` reads `.yaml`, `.yml`, `.json`, or `.toml`. The extension selects the format. When the file has keys gatecheck does not read, `Decode` still fills the config and returns an error wrapping `ErrUnknownConfigKeys`. Check it with `errors.Is` and treat it as a warning. `DecodeConfig` does the same for bytes you already have. +- `EncodeConfigTo` and `NewConfigEncoder` write a config as `json`, `yaml`, `yml`, or `toml`, with or without the dot. JSON and YAML are indented by two spaces. `ConfigFormat` checks a format name. - `Validate` takes the config, a reader, and the filename. The bytes select the report type. The filename is the fallback, with the same words as the CLI. -- `List` writes a table. A Grype, CycloneDX, SARIF, Semgrep, Gitleaks, Trivy, or osv-scanner report with no findings writes one sentence instead, such as `No gitleaks findings`, `No trivy vulnerabilities`, or `No osv-scanner vulnerabilities`. `WithDisplayFormat("markdown")` matches `--markdown` and writes that same sentence when the report is empty. `WithEPSS` matches `--epss` and takes an open CSV file or a URL. +- `List` writes a table. `WithDisplayFormat` takes `table`, `markdown`, or `json`. A Grype, CycloneDX, SARIF, Semgrep, Gitleaks, Trivy, or osv-scanner report with no findings writes one sentence instead, such as `No gitleaks findings`, `No trivy vulnerabilities`, or `No osv-scanner vulnerabilities`. `WithDisplayFormat("markdown")` matches `--markdown` and writes that same sentence when the report is empty. `WithEPSS` matches `--epss` and takes an open CSV file or a URL. - `CreateBundle`, `AppendToBundle`, and `RemoveFromBundle` are `bundle create`, `bundle add`, and `bundle remove`. -- `DownloadEPSS` and `DownloadKEV` write the API payloads. `WithEPSSURL`, `WithKEVURL`, `WithEPSSFile`, and `WithKEVFile` override the defaults. +- `DownloadEPSS` and `DownloadKEV` write the API payloads. `WithEPSSURL`, `WithKEVURL`, `WithEPSSFile`, and `WithKEVFile` override the defaults. `WithVEXFiles` adds VEX documents to `Validate`. +- Errors: `ErrValidationFailure` is a threshold failure. `ErrExternalData` means EPSS or KEV data could not be loaded. `ErrBundleLabelNotFound` comes from `RemoveFromBundle`. The CLI maps these to exit codes 1, 3, and 2 with `cmd.ExitCode`. Report types are described in [Supported Reports](./supported-reports.md). Config fields are described in [Configuration](./configuration.md). diff --git a/docs/list-reports.md b/docs/list-reports.md index 76166c5..6b5817d 100644 --- a/docs/list-reports.md +++ b/docs/list-reports.md @@ -22,7 +22,7 @@ gatecheck ls grype-scan-report.json The report type comes from the file contents. The filename, or `--input-type` on standard input, is used when the contents are ambiguous. `grype-scan-report.json` still works. See [Supported Reports](./supported-reports.md). -`--markdown` prints a markdown table instead of the plain text table. +`--format markdown` (or `--markdown`) prints a markdown table instead of the plain text table. `--format json` prints `{"columns": [...], "rows": [{column: value}]}`, plus a `footer` object for coverage. `--epss` adds the EPSS score and percentile for Grype, CycloneDX, Trivy, and osv-scanner. Other reports ignore that data. With no `--epss-filename`, gatecheck downloads the CSV from FIRST. `GATECHECK_EPSS_FILENAME` and `GATECHECK_EPSS_URL` are the same settings as those flags. @@ -41,11 +41,12 @@ Columns: - Trivy: severity, package, version, link. With `--epss`: CVE id, severity, EPSS score, EPSS percentile, package, version, link. Misconfigurations are omitted. - osv-scanner: severity, package, version, link. With `--epss`: id, severity, EPSS score, EPSS percentile, package, version, link. The id is the first CVE alias, or the OSV id when there is no CVE. Groups are listed once. - Coverage: lines, functions, and branches covered, with a percent in the footer. The percent is only for display. The config file uses a ratio. See [Configuration](./configuration.md). -- Bundle: label, SHA-256 digest, tags, size. +- Syft JSON: package, version, type, licenses. +- Bundle: label, SHA-256 digest, tags, size. With `--format json`, the bundle manifest. -A Grype, CycloneDX, SARIF, Semgrep, Gitleaks, Trivy, or osv-scanner report with no findings prints one sentence and no table. The lines are `No grype vulnerabilities`, `No cyclonedx vulnerabilities`, `No sarif findings`, `No semgrep findings`, `No gitleaks findings`, `No trivy vulnerabilities`, and `No osv-scanner vulnerabilities`. `--markdown` prints that same line. +A Grype, CycloneDX, SARIF, Semgrep, Gitleaks, Trivy, osv-scanner, or Syft report with nothing in it prints one sentence and no table. The lines are `No grype vulnerabilities`, `No cyclonedx vulnerabilities`, `No sarif findings`, `No semgrep findings`, `No gitleaks findings`, `No trivy vulnerabilities`, `No osv-scanner vulnerabilities`, and `No syft packages`. Markdown prints that same line. JSON prints `{"columns": [], "rows": [], "message": "..."}`. -`list` opens the first filename only. `list-all` walks every filename, prints the name, then the table or that sentence, and skips files it does not support. Coverage files are in that skipped set. `--epss` on `list-all` adds EPSS columns for Grype, CycloneDX, Trivy, and osv-scanner, including a file whose name does not contain those words when the contents do. It always uses the API (`GATECHECK_EPSS_URL` to override it). +`list` takes one filename. A second one is a usage error. `list-all` walks every filename, prints the name, then the table or that sentence, and skips files it does not support. Coverage files are in that skipped set. `--epss` on `list-all` adds EPSS columns for Grype, CycloneDX, Trivy, and osv-scanner, including a file whose name does not contain those words when the contents do. The EPSS data is loaded once per run, from `--epss-filename` or the API. With `--format json`, `list-all` prints one array of `{"file": ..., "report": ...}`. When a file cannot be read or listed, the others are still listed and the command exits 2. ```shell gatecheck list-all grype-scan-report.json semgrep-report.json diff --git a/docs/usage.md b/docs/usage.md index 23d30ad..46f5b34 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -23,11 +23,12 @@ Logs go to standard error. Tables, downloaded data, and `config init` go to stan Exit status: -- `0` when the command succeeds. With `validate --audit`, an error returned by the check also exits 0. +- `0` when the command succeeds. With `validate --audit`, a threshold failure also exits 0. - `1` when a report misses a configured threshold and `--audit` is off. -- `255` for a missing file, a rejected command line, or a check error when `--audit` is off. -- The scanner commands return that program's own status. A scanner that is neither installed nor on `PATH` exits 255. +- `2` for a rejected command line, a file that could not be read or written, or a report, config, or VEX file that could not be decoded. `--audit` does not change this. +- `3` when EPSS or KEV data could not be downloaded or read. `--audit` does not change this. +- The scanner commands return that program's own status. A scanner that is neither installed nor on `PATH` exits 2. [Validation](./validation.md) lists which `validate` failures are which status. -`--verbose` (`-v`) prints debug logs. `--silent` hides debug, info, and warning logs, and errors are still printed. The two flags cannot be used together. They are available on every command. +`--verbose` (`-v`) prints debug logs. `--silent` prints only warnings and errors. `--log-level debug|info|warn|error` sets the level directly, and only one of those three flags can be set. `--log-format json` writes one JSON object per log line instead of text. They are available on every command, and `GATECHECK_VERBOSE`, `GATECHECK_SILENT`, `GATECHECK_LOG_LEVEL`, and `GATECHECK_LOG_FORMAT` set them from the environment. diff --git a/docs/validation.md b/docs/validation.md index 7b448cc..cb4b238 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -5,19 +5,26 @@ gatecheck validate --config gatecheck.yaml grype-report.json gatecheck validate --config gatecheck.yaml gatecheck-bundle.tar.gz ``` -Pass the config with `--config` or `-f`, or with `GATECHECK_CONFIG_FILENAME`. The only positional argument is the report path, and it is required. +Pass the config with `--config` or `-f`, or with `GATECHECK_CONFIG_FILENAME`. The positional argument is the report path. With no path, `--input-type` names the report type and the report is read from standard input: + +```shell +grype dir:. -o json | gatecheck validate --config gatecheck.yaml --input-type grype +``` + +`--format table`, `markdown`, or `json` also prints the result to standard output. Keys in the config that gatecheck does not read are named in a warning, so a typo such as `severityLimt` does not silently disable a rule. The report type comes from the file contents, and from the filename when the contents are ambiguous. See [Supported Reports](./supported-reports.md). -With no config, gatecheck uses the default: every rule disabled, coverage thresholds `0`. Grype, CycloneDX, Trivy, osv-scanner, SARIF, Semgrep, Gitleaks, coverage, and bundle reports pass under that default. Syft JSON passes too, since the license rules are off by default. An old config with no `sarif` section leaves those limits disabled. +With no config, gatecheck warns and uses the default: every rule disabled, coverage thresholds `0`. Grype, CycloneDX, Trivy, osv-scanner, SARIF, Semgrep, Gitleaks, coverage, and bundle reports pass under that default. Syft JSON passes too, since the license rules are off by default. An old config with no `sarif` section leaves those limits disabled. ## Exit status - `0`: the report passed. - `1`: a threshold failed. The error text starts with `validation failure:`. -- `255`: the report or config could not be opened, the config extension is not supported, or the command line was rejected. +- `2`: the report, config, VEX, EPSS, or KEV file could not be opened or decoded, the report type is not supported, the config extension is not supported, or the command line was rejected. +- `3`: EPSS or KEV data could not be downloaded or read. -`--audit` (`-a`) prints whatever error the check returns and exits 0. That covers a failed threshold, an unknown report, a Syft file, a decode error, and a failed EPSS or KEV fetch. Opening the report, the config, and any `--epss-filename` or `--kev-filename` happens before the check. A missing file still exits 255. +`--audit` (`-a`) prints a threshold failure and exits 0. It does not hide anything else: those errors still exit 2 or 3. `GATECHECK_AUDIT=true` is the same setting, and `--audit=false` overrides it. ## Grype, CycloneDX, Trivy, and osv-scanner @@ -30,9 +37,9 @@ Rules run in this order. A failure returns immediately, except where a rule only 1. **CVE limit.** `cveLimit`, when enabled, fails if any listed id is in the report. Ids are compared without regard to case. 2. **Disabled Grype, Trivy, and osv-scanner severities.** Grype, Trivy, and osv-scanner drop findings whose severity limit is disabled. If the EPSS limit is also enabled, a finding at a disabled severity stays in the report when it has an EPSS score greater than or equal to that limit. CycloneDX leaves findings at a disabled severity in the report, so they still go through the KEV and EPSS rules. 3. **CVE risk acceptance and VEX.** Matching ids are removed and skip the remaining rules. Findings that a VEX file passed with `--vex`, `GATECHECK_VEX`, or `vex.files` marks `not_affected`, `fixed`, `false_positive`, or `resolved` are removed too. See [VEX](./vex.md). -4. **KEV limit.** When `kevLimitEnabled` is true, a CVE that is in the catalog fails the report. The catalog is `--kev-filename` or, with no file, the CISA feed. `GATECHECK_KEV_URL` overrides the feed. There is no `--kev-url` flag on `validate`. +4. **KEV limit.** When `kevLimitEnabled` is true, a CVE that is in the catalog fails the report. The catalog is `--kev-filename` (`GATECHECK_KEV_FILENAME`) or, with no file, the CISA feed. `--kev-url` (`GATECHECK_KEV_URL`) changes the feed. Grype ids are compared without regard to case, and a Grype match's related CVE ids are checked too. 5. **EPSS risk acceptance.** A CVE is removed when the configured `score` is greater than that CVE's EPSS score. A CVE with no EPSS row is kept. A CVE whose score is equal to the configured score is kept. -6. **EPSS limit.** A CVE fails when its EPSS score is greater than `score`. A CVE with no EPSS row passes this rule. A score equal to the limit passes. Data comes from `--epss-filename` or `GATECHECK_EPSS_FILENAME`, or from the API. `GATECHECK_EPSS_URL` overrides the API. There is no `--epss-url` flag on `validate`. +6. **EPSS limit.** A CVE fails when its EPSS score is greater than `score`. A CVE with no EPSS row passes this rule. A score equal to the limit passes. Data comes from `--epss-filename` or `GATECHECK_EPSS_FILENAME`, or from the API. `--epss-url` (`GATECHECK_EPSS_URL`) changes the API. 7. **Severity limit.** For each enabled severity, the report fails when the count is greater than `limit`. `limit: 0` allows none. Counts that are equal to the limit pass. Grype, CycloneDX, Trivy, and osv-scanner severities are `critical`, `high`, `medium`, and `low`. `negligible` and `unknown` have no limit field. Any CycloneDX JSON BOM uses the `cyclonedx` rules, including a BOM from Grype, Trivy, Syft, or another tool. The severity is the highest rating. A rating with a score and no severity word uses CVSS ranges. A CVSS v2 method does not produce critical. `important` counts as high, and `moderate` counts as medium. `negligible` counts as none. Empty ratings use a top-level `severity` string when the producer set one, otherwise `unknown`. `unknown`, `none`, and `info` are not counted by the critical, high, medium, or low limits. The id is the vulnerability `id`, or the `bom-ref` when `id` is empty. @@ -72,7 +79,7 @@ When `limitEnabled` is true, any finding in the report fails validation. There i Line, function, and branch coverage are each `covered / total`. The config thresholds are those ratios, from 0 to 1. The check fails when the report's ratio is less than the threshold. A ratio equal to the threshold passes. All three checks run, and each failure is reported. A report with no records of a kind, such as LCOV without branch records, has no ratio for it. `list` prints `N/A`, and `validate` skips that threshold with a warning. -`0.8` means 80 percent. `80.0` fails a normal report, because `0.8 < 80`. +`0.8` means 80 percent. A threshold over 1 is read as a percent, so `80` means `0.8`, and a warning is logged. `list` prints coverage as a percent. The config value stays a ratio. diff --git a/docs/vex.md b/docs/vex.md index d5d2dab..6160717 100644 --- a/docs/vex.md +++ b/docs/vex.md @@ -21,7 +21,7 @@ vex: - .vex/app.openvex.json ``` -Relative paths are read from the working directory. A file that is missing, is not JSON, or is neither format is an error, and `validate` exits 255 without checking the report. +Relative paths are read from the working directory. A file that is missing, is not JSON, or is neither format is an error, and `validate` exits 2 without checking the report, even with `--audit`. ## Which statuses skip a finding diff --git a/go.mod b/go.mod index 3ca6f82..369c177 100644 --- a/go.mod +++ b/go.mod @@ -7,12 +7,11 @@ toolchain go1.26.10 require ( github.com/dustin/go-humanize v1.1.0 github.com/easy-up/go-coverage v0.0.0-20241018034313-3de592d59a78 - github.com/gatecheckdev/configkit v0.0.0-20240517005856-da14389dd06a github.com/lmittmann/tint v1.2.1 + github.com/olekukonko/ll v0.1.6 github.com/olekukonko/tablewriter v1.1.5 github.com/pelletier/go-toml/v2 v2.4.3 github.com/spf13/cobra v1.10.2 - github.com/spf13/viper v1.20.1 gopkg.in/yaml.v3 v3.0.1 ) @@ -21,24 +20,16 @@ require ( github.com/clipperhouse/displaywidth v0.10.0 // indirect github.com/clipperhouse/uax29/v2 v2.6.0 // indirect github.com/fatih/color v1.18.0 // indirect - github.com/fsnotify/fsnotify v1.9.0 // indirect - github.com/go-viper/mapstructure/v2 v2.4.0 // indirect github.com/inconshreveable/mousetrap v1.1.0 // indirect + github.com/kr/pretty v0.3.1 // indirect github.com/mattn/go-colorable v0.1.14 // indirect github.com/mattn/go-isatty v0.0.20 // indirect github.com/mattn/go-runewidth v0.0.19 // indirect github.com/olekukonko/cat v0.0.0-20250911104152-50322a0618f6 // indirect github.com/olekukonko/errors v1.2.0 // indirect - github.com/olekukonko/ll v0.1.6 // indirect github.com/rogpeppe/go-internal v1.12.0 // indirect - github.com/sagikazarmark/locafero v0.9.0 // indirect - github.com/sourcegraph/conc v0.3.0 // indirect - github.com/spf13/afero v1.14.0 // indirect - github.com/spf13/cast v1.7.1 // indirect github.com/spf13/pflag v1.0.9 // indirect - github.com/subosito/gotenv v1.6.0 // indirect - go.uber.org/multierr v1.11.0 // indirect + github.com/stretchr/testify v1.10.0 // indirect golang.org/x/sys v0.32.0 // indirect - golang.org/x/text v0.24.0 // indirect gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect ) diff --git a/go.sum b/go.sum index d2633bb..0999eb4 100644 --- a/go.sum +++ b/go.sum @@ -5,6 +5,7 @@ github.com/clipperhouse/displaywidth v0.10.0/go.mod h1:XqJajYsaiEwkxOj4bowCTMcT1 github.com/clipperhouse/uax29/v2 v2.6.0 h1:z0cDbUV+aPASdFb2/ndFnS9ts/WNXgTNNGFoKXuhpos= github.com/clipperhouse/uax29/v2 v2.6.0/go.mod h1:Wn1g7MK6OoeDT0vL+Q0SQLDz/KpfsVRgg6W7ihQeh4g= github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= +github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/dustin/go-humanize v1.1.0 h1:dbKTrvD0klcbBV/h4AWJdMuZogJACoMlvWIWZ5b2xWg= @@ -13,16 +14,6 @@ github.com/easy-up/go-coverage v0.0.0-20241018034313-3de592d59a78 h1:e2x+TfIgebN github.com/easy-up/go-coverage v0.0.0-20241018034313-3de592d59a78/go.mod h1:fsSINOc273zPnsBaKNjNffZXZpicAArpv/cTiFYgPys= github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM= github.com/fatih/color v1.18.0/go.mod h1:4FelSpRwEGDpQ12mAdzqdOukCy4u8WUtOY6lkT/6HfU= -github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8= -github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0= -github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k= -github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0= -github.com/gatecheckdev/configkit v0.0.0-20240517005856-da14389dd06a h1:SHelO0R65cDxh2CiLHvnvvLi1fkBkO0fpo1g3/eRerQ= -github.com/gatecheckdev/configkit v0.0.0-20240517005856-da14389dd06a/go.mod h1:bS1zFCUnYr3X/8Fd4qWKRnpeD/wawvfQo+HpzVbiX4A= -github.com/go-viper/mapstructure/v2 v2.4.0 h1:EBsztssimR/CONLSZZ04E8qAkxNYq4Qp9LvH92wZUgs= -github.com/go-viper/mapstructure/v2 v2.4.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM= -github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI= -github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI= @@ -50,37 +41,23 @@ github.com/olekukonko/tablewriter v1.1.5 h1:4LoZSfMySpMQY3PT8RWJsJeuEuMIoo9xGRgv github.com/olekukonko/tablewriter v1.1.5/go.mod h1:+kedxuyTtgoZLwif3P1Em4hARJs+mVnzKxmsCL/C5RY= github.com/pelletier/go-toml/v2 v2.4.3 h1:GTRvJQutkOSftxIFD5xw9aepkYNuPWmVJpffdDPYVpY= github.com/pelletier/go-toml/v2 v2.4.3/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY= +github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs= github.com/rogpeppe/go-internal v1.12.0 h1:exVL4IDcn6na9z1rAb56Vxr+CgyK3nn3O+epU5NdKM8= github.com/rogpeppe/go-internal v1.12.0/go.mod h1:E+RYuTGaKKdloAfM02xzb0FW3Paa99yedzYV+kq4uf4= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= -github.com/sagikazarmark/locafero v0.9.0 h1:GbgQGNtTrEmddYDSAH9QLRyfAHY12md+8YFTqyMTC9k= -github.com/sagikazarmark/locafero v0.9.0/go.mod h1:UBUyz37V+EdMS3hDF3QWIiVr/2dPrx49OMO0Bn0hJqk= -github.com/sourcegraph/conc v0.3.0 h1:OQTbbt6P72L20UqAkXXuLOj79LfEanQ+YQFNpLA9ySo= -github.com/sourcegraph/conc v0.3.0/go.mod h1:Sdozi7LEKbFPqYX2/J+iBAM6HpqSLTASQIKqDmF7Mt0= -github.com/spf13/afero v1.14.0 h1:9tH6MapGnn/j0eb0yIXiLjERO8RB6xIVZRDCX7PtqWA= -github.com/spf13/afero v1.14.0/go.mod h1:acJQ8t0ohCGuMN3O+Pv0V0hgMxNYDlvdk+VTfyZmbYo= -github.com/spf13/cast v1.7.1 h1:cuNEagBQEHWN1FnbGEjCXL2szYEXqfJPbP2HNUaca9Y= -github.com/spf13/cast v1.7.1/go.mod h1:ancEpBxwJDODSW/UG4rDrAqiKolqNNh2DX3mk86cAdo= github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU= github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4= github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY= github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= -github.com/spf13/viper v1.20.1 h1:ZMi+z/lvLyPSCoNtFCpqjy0S4kPbirhpTMwl8BkW9X4= -github.com/spf13/viper v1.20.1/go.mod h1:P9Mdzt1zoHIG8m2eZQinpiBjo6kCmZSKBClNNqjJvu4= github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA= github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= -github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8= -github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU= -go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0= -go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y= go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg= golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.32.0 h1:s77OFDvIQeibCmezSnk/q6iAfkdiQaJi4VzroCFrN20= golang.org/x/sys v0.32.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k= -golang.org/x/text v0.24.0 h1:dd5Bzh4yt5KYA8f9CJHCP4FB4D51c2c6JvN37xJJkJ0= -golang.org/x/text v0.24.0/go.mod h1:L8rBsPeo2pSS+xqN0d5u2ikmjtmoJbDBT1b7nHvFCdU= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q= diff --git a/pkg/epss/epss.go b/pkg/epss/epss.go index 69e57d2..56925ea 100644 --- a/pkg/epss/epss.go +++ b/pkg/epss/epss.go @@ -179,7 +179,12 @@ func ParseEPSSDataCSV(r io.Reader, data *Data) error { slog.Warn("data model does not match supported model", "want", dataModel, "got", data.ModelVersion) } - scoreDate, err := time.Parse(modelDateLayout, strings.ReplaceAll(parts[1], "score_date:", "")) + rawDate := strings.ReplaceAll(parts[1], "score_date:", "") + scoreDate, err := time.Parse(modelDateLayout, rawDate) + if err != nil { + // Older FIRST files write the offset as +0000. + scoreDate, err = time.Parse("2006-01-02T15:04:05-0700", rawDate) + } if err != nil { return fmt.Errorf("failed to parse EPSS CSV, invalid date format in metadata header '%s'", scanner.Text()) } diff --git a/pkg/format/json.go b/pkg/format/json.go new file mode 100644 index 0000000..d6ab013 --- /dev/null +++ b/pkg/format/json.go @@ -0,0 +1,93 @@ +package format + +import ( + "encoding/json" + "fmt" + "io" + + "github.com/olekukonko/ll" + "github.com/olekukonko/tablewriter" + "github.com/olekukonko/tablewriter/tw" +) + +// TableJSON is the JSON form of a table. Each row is an object keyed by the +// column header. +type TableJSON struct { + Columns []string `json:"columns"` + Rows []map[string]string `json:"rows"` + Footer map[string]string `json:"footer,omitempty"` +} + +// NewJSONTable returns a table that writes TableJSON instead of drawing a grid. +// Cells are not wrapped or padded. +func NewJSONTable(w io.Writer) *tablewriter.Table { + return tablewriter.NewTable(w, + tablewriter.WithRenderer(&jsonRenderer{}), + tablewriter.WithRowAutoWrap(tw.WrapNone), + tablewriter.WithHeaderAutoFormat(tw.Off), + tablewriter.WithFooterAutoFormat(tw.Off), + tablewriter.WithPadding(tw.Padding{Overwrite: true}), + ) +} + +// WriteEmptyJSON writes a TableJSON with no rows and a message. +func WriteEmptyJSON(w io.Writer, message string) error { + enc := json.NewEncoder(w) + enc.SetIndent("", " ") + return enc.Encode(struct { + Columns []string `json:"columns"` + Rows []map[string]string `json:"rows"` + Message string `json:"message"` + }{Columns: []string{}, Rows: []map[string]string{}, Message: message}) +} + +type jsonRenderer struct { + w io.Writer + out TableJSON +} + +func (r *jsonRenderer) Start(w io.Writer) error { + r.w = w + r.out = TableJSON{Columns: []string{}, Rows: []map[string]string{}} + return nil +} + +func (r *jsonRenderer) Header(headers [][]string, _ tw.Formatting) { + if len(headers) > 0 { + r.out.Columns = append([]string(nil), headers[0]...) + } +} + +func (r *jsonRenderer) Row(row []string, _ tw.Formatting) { + r.out.Rows = append(r.out.Rows, r.keyed(row)) +} + +func (r *jsonRenderer) Footer(footers [][]string, _ tw.Formatting) { + if len(footers) > 0 { + r.out.Footer = r.keyed(footers[0]) + } +} + +func (r *jsonRenderer) keyed(cells []string) map[string]string { + m := make(map[string]string, len(cells)) + for i, cell := range cells { + key := "" + if i < len(r.out.Columns) { + key = r.out.Columns[i] + } + if key == "" { + key = fmt.Sprintf("column%d", i+1) + } + m[key] = cell + } + return m +} + +func (r *jsonRenderer) Line(tw.Formatting) {} +func (r *jsonRenderer) Config() tw.Rendition { return tw.Rendition{} } +func (r *jsonRenderer) Logger(*ll.Logger) {} +func (r *jsonRenderer) Close() error { + enc := json.NewEncoder(r.w) + enc.SetIndent("", " ") + return enc.Encode(r.out) +} diff --git a/pkg/gatecheck/bundle.go b/pkg/gatecheck/bundle.go index 35db33e..a44dbea 100644 --- a/pkg/gatecheck/bundle.go +++ b/pkg/gatecheck/bundle.go @@ -1,12 +1,17 @@ package gatecheck import ( + "errors" + "fmt" "io" "log/slog" "github.com/gatecheckdev/gatecheck/pkg/archive" ) +// ErrBundleLabelNotFound means RemoveFromBundle was asked for a label the bundle does not have. +var ErrBundleLabelNotFound = errors.New("bundle has no file with label") + // CreateBundle create a new bundle with a file // // If the bundle already exist, use CreateBundle. @@ -72,6 +77,9 @@ func RemoveFromBundle(bundleRWS io.ReadWriteSeeker, label string) error { if err := archive.UntarGzipBundle(bundleRWS, bundle); err != nil { return err } + if _, ok := bundle.Manifest().Files[label]; !ok { + return fmt.Errorf("%w: %q", ErrBundleLabelNotFound, label) + } bundle.Remove(label) // Seek errors are unlikely so just capture for edge cases _, seekErr := bundleRWS.Seek(0, io.SeekStart) diff --git a/pkg/gatecheck/config.go b/pkg/gatecheck/config.go index 2564b89..bc342eb 100644 --- a/pkg/gatecheck/config.go +++ b/pkg/gatecheck/config.go @@ -9,11 +9,12 @@ import ( "log/slog" "os" "path" + "sort" + "strings" "github.com/gatecheckdev/gatecheck/pkg/format" "github.com/gatecheckdev/gatecheck/pkg/vex" "github.com/pelletier/go-toml/v2" - "github.com/spf13/viper" "gopkg.in/yaml.v3" ) @@ -42,17 +43,21 @@ type Config struct { func (c *Config) String() string { buf := new(bytes.Buffer) _ = json.NewEncoder(buf).Encode(c) - - v := viper.New() - v.SetConfigType("json") - _ = v.ReadConfig(buf) + var tree map[string]any + _ = json.Unmarshal(buf.Bytes(), &tree) + rows := map[string]string{} + flattenConfig("", tree, rows) + keys := make([]string, 0, len(rows)) + for key := range rows { + keys = append(keys, key) + } + sort.Strings(keys) contentBuf := new(bytes.Buffer) table := format.NewTable(contentBuf) table.Header([]string{"config key", "value"}) - - for _, key := range v.AllKeys() { - if err := table.Append([]string{key, fmt.Sprintf("%v", v.Get(key))}); err != nil { + for _, key := range keys { + if err := table.Append([]string{key, rows[key]}); err != nil { slog.Error("append config row", "error", err) return contentBuf.String() } @@ -63,6 +68,21 @@ func (c *Config) String() string { return contentBuf.String() } +func flattenConfig(prefix string, value any, out map[string]string) { + switch v := value.(type) { + case map[string]any: + for key, child := range v { + name := strings.ToLower(key) + if prefix != "" { + name = prefix + "." + name + } + flattenConfig(name, child, out) + } + default: + out[prefix] = fmt.Sprintf("%v", v) + } +} + type configCoverageReport struct { LineThreshold float32 `json:"lineThreshold" toml:"lineThreshold" yaml:"lineThreshold"` FunctionThreshold float32 `json:"functionThreshold" toml:"functionThreshold" yaml:"functionThreshold"` @@ -156,7 +176,7 @@ type configCVE struct { ID string `json:"id" toml:"id" yaml:"id"` Metadata struct { Tags []string `json:"tags" toml:"tags" yaml:"tags"` - } + } `json:"metadata" toml:"metadata" yaml:"metadata"` } type configLimit struct { @@ -253,102 +273,155 @@ func NewDefaultConfig() *Config { } } +// WriteDefaultConfig writes the default config, tagged as generated. func WriteDefaultConfig(w io.Writer, format string) error { config := NewDefaultConfig() config.Metadata.Tags = append(config.Metadata.Tags, "auto generated from CLI") return EncodeConfigTo(w, config, format) } -func EncodeConfigTo(w io.Writer, config *Config, format string) error { - var encoder interface { - Encode(any) error +// ConfigFormat returns the canonical config format for a name or extension: +// "json", "yaml", or "toml". "yml" and a leading dot are accepted. +func ConfigFormat(name string) (string, error) { + switch strings.ToLower(strings.TrimPrefix(strings.TrimSpace(name), ".")) { + case "json": + return "json", nil + case "yaml", "yml": + return "yaml", nil + case "toml": + return "toml", nil + default: + return "", fmt.Errorf("unsupported config format %q, must be json, toml, yaml, or yml", name) } +} - slog.Debug("encode config file", "format", format) - switch format { +// EncodeConfigTo writes config in format (json, yaml, yml, or toml, with or +// without a leading dot). JSON and YAML are indented by two spaces. +func EncodeConfigTo(w io.Writer, config *Config, format string) error { + canonical, err := ConfigFormat(format) + if err != nil { + return err + } + slog.Debug("encode config file", "format", canonical) + switch canonical { case "json": enc := json.NewEncoder(w) enc.SetIndent("", " ") - encoder = enc - case "yaml", "yml": + return enc.Encode(config) + case "yaml": enc := yaml.NewEncoder(w) enc.SetIndent(2) - encoder = enc - case "toml": - encoder = toml.NewEncoder(w) + if err := enc.Encode(config); err != nil { + return err + } + return enc.Close() default: - return fmt.Errorf("unsupported format '%s'", format) + enc := toml.NewEncoder(w) + enc.SetIndentTables(true) + return enc.Encode(config) } - - return encoder.Encode(config) } +// ConfigEncoder writes a config in the format named by a file extension. type ConfigEncoder struct { writer io.Writer ext string } +// NewConfigEncoder takes ".json", ".yaml", ".yml", or ".toml". The dot is optional. func NewConfigEncoder(w io.Writer, ext string) *ConfigEncoder { - return &ConfigEncoder{ - writer: w, - ext: ext, - } + return &ConfigEncoder{writer: w, ext: ext} } func (e *ConfigEncoder) Encode(config *Config) error { - var encoder interface { - Encode(any) error - } - - switch e.ext { - case ".json": - encoder = json.NewEncoder(e.writer) - case ".toml": - encoder = toml.NewEncoder(e.writer) - case ".yaml", ".yml": - encoder = yaml.NewEncoder(e.writer) - default: - return errors.New("invalid file extension, only json, toml, yaml or yml supported") - } - - return encoder.Encode(config) - + return EncodeConfigTo(e.writer, config, e.ext) } +// ConfigDecoder reads a config file. The extension picks the format. type ConfigDecoder struct { filename string } func NewConfigDecoder(filename string) *ConfigDecoder { - return &ConfigDecoder{ - filename: filename, - } + return &ConfigDecoder{filename: filename} } -func (d *ConfigDecoder) Decode(config *Config) error { - ext := path.Ext(d.filename) +// ErrUnknownConfigKeys means a config file has keys gatecheck does not read. +var ErrUnknownConfigKeys = errors.New("config has unknown keys") - slog.Debug("decode", "filename", d.filename, "extension", ext) - f, err := os.Open(d.filename) +// Decode reads the file into config. Keys gatecheck does not know are +// skipped. When there are any, Decode fills config and then returns an error +// wrapping ErrUnknownConfigKeys, so the caller can warn and go on. +func (d *ConfigDecoder) Decode(config *Config) error { + slog.Debug("decode config", "filename", d.filename) + canonical, err := ConfigFormat(path.Ext(d.filename)) + if err != nil { + return fmt.Errorf("%s: %w", d.filename, err) + } + content, err := os.ReadFile(d.filename) if err != nil { return err } - defer func() { _ = f.Close() }() + return DecodeConfig(content, canonical, config) +} - var decoder interface { - Decode(any) error +// DecodeConfig reads content in format into config. See ConfigDecoder.Decode +// for how unknown keys are reported. +func DecodeConfig(content []byte, format string, config *Config) error { + canonical, err := ConfigFormat(format) + if err != nil { + return err } - - switch ext { - case ".json": - decoder = json.NewDecoder(f) - case ".toml": - decoder = toml.NewDecoder(f) - case ".yaml", ".yml": - decoder = yaml.NewDecoder(f) + var loose error + switch canonical { + case "json": + loose = json.Unmarshal(content, config) + case "yaml": + loose = yaml.Unmarshal(content, config) default: - return errors.New("invalid file extension, only json, toml, yaml or yml supported") + loose = toml.Unmarshal(content, config) + } + if loose != nil { + return loose } + if unknown := unknownConfigKeys(content, canonical); unknown != "" { + return fmt.Errorf("%w: %s", ErrUnknownConfigKeys, unknown) + } + return nil +} - return decoder.Decode(config) +// unknownConfigKeys decodes content strictly into a scratch config and returns +// the decoder's description of the unknown keys, or "". +func unknownConfigKeys(content []byte, format string) string { + scratch := &Config{} + var err error + switch format { + case "json": + dec := json.NewDecoder(bytes.NewReader(content)) + dec.DisallowUnknownFields() + err = dec.Decode(scratch) + case "yaml": + dec := yaml.NewDecoder(bytes.NewReader(content)) + dec.KnownFields(true) + err = dec.Decode(scratch) + if errors.Is(err, io.EOF) { + err = nil + } + default: + dec := toml.NewDecoder(bytes.NewReader(content)) + dec.DisallowUnknownFields() + err = dec.Decode(scratch) + var strict *toml.StrictMissingError + if errors.As(err, &strict) { + keys := make([]string, 0, len(strict.Errors)) + for _, e := range strict.Errors { + keys = append(keys, strings.Join(e.Key(), ".")) + } + return strings.Join(keys, ", ") + } + } + if err == nil { + return "" + } + return strings.TrimSpace(err.Error()) } diff --git a/pkg/gatecheck/config_test.go b/pkg/gatecheck/config_test.go new file mode 100644 index 0000000..53085f2 --- /dev/null +++ b/pkg/gatecheck/config_test.go @@ -0,0 +1,91 @@ +package gatecheck + +import ( + "bytes" + "errors" + "os" + "path/filepath" + "strings" + "testing" +) + +func TestConfigRoundTripEveryFormat(t *testing.T) { + for _, format := range []string{"json", ".json", "yaml", "yml", ".yaml", "toml"} { + t.Run(format, func(t *testing.T) { + want := NewDefaultConfig() + want.Grype.SeverityLimit.Critical = configLimit{Enabled: true, Limit: 2} + want.License.Deny = []string{"GPL-*"} + cve := configCVE{ID: "CVE-2026-1"} + cve.Metadata.Tags = []string{"accepted"} + want.Grype.CVERiskAcceptance.CVEs = []configCVE{cve} + var buf bytes.Buffer + if err := EncodeConfigTo(&buf, want, format); err != nil { + t.Fatal(err) + } + canonical, _ := ConfigFormat(format) + got := &Config{} + if err := DecodeConfig(buf.Bytes(), canonical, got); err != nil { + t.Fatalf("decode: %v\n%s", err, buf.String()) + } + if got.String() != want.String() { + t.Fatalf("round trip changed the config:\n%s", buf.String()) + } + if canonical != "toml" && !strings.Contains(buf.String(), "\n ") { + t.Fatalf("%s output is not indented:\n%s", format, buf.String()) + } + }) + } + if _, err := ConfigFormat("xml"); err == nil { + t.Fatal("xml should be rejected") + } +} + +func TestConfigUnknownKeys(t *testing.T) { + cases := map[string]string{ + "gatecheck.yaml": "version: \"1\"\ngrype:\n severityLimit:\n critical:\n enabled: true\n severityLimt: {}\nbogus: 1\n", + "gatecheck.json": `{"version":"1","grype":{"severityLimit":{"critical":{"enabled":true}}},"bogus":1}`, + "gatecheck.toml": "version = \"1\"\nbogus = 1\n[grype.severityLimit.critical]\nenabled = true\n", + } + for name, body := range cases { + t.Run(name, func(t *testing.T) { + file := filepath.Join(t.TempDir(), name) + if err := os.WriteFile(file, []byte(body), 0o600); err != nil { + t.Fatal(err) + } + config := NewDefaultConfig() + err := NewConfigDecoder(file).Decode(config) + if !errors.Is(err, ErrUnknownConfigKeys) || !strings.Contains(err.Error(), "bogus") { + t.Fatalf("want unknown keys error naming bogus, got %v", err) + } + if !config.Grype.SeverityLimit.Critical.Enabled { + t.Fatal("known keys should still be decoded") + } + }) + } + clean := filepath.Join(t.TempDir(), "gatecheck.yml") + if err := os.WriteFile(clean, []byte("version: \"1\"\n"), 0o600); err != nil { + t.Fatal(err) + } + if err := NewConfigDecoder(clean).Decode(NewDefaultConfig()); err != nil { + t.Fatal(err) + } + empty := filepath.Join(t.TempDir(), "gatecheck.yaml") + if err := os.WriteFile(empty, nil, 0o600); err != nil { + t.Fatal(err) + } + if err := NewConfigDecoder(empty).Decode(NewDefaultConfig()); err != nil { + t.Fatalf("empty yaml: %v", err) + } +} + +func TestCoverageThresholdPercent(t *testing.T) { + if got := coverageThreshold("line", 80); got != 0.8 { + t.Fatalf("80 -> %v", got) + } + if got := coverageThreshold("line", 0.8); got != 0.8 { + t.Fatalf("0.8 -> %v", got) + } + if got := coverageThreshold("line", 1); got != 1 { + t.Fatalf("1 -> %v", got) + } +} diff --git a/pkg/gatecheck/download.go b/pkg/gatecheck/download.go index ce37dc0..588e784 100644 --- a/pkg/gatecheck/download.go +++ b/pkg/gatecheck/download.go @@ -1,6 +1,7 @@ package gatecheck import ( + "fmt" "io" "net/http" "os" @@ -131,7 +132,10 @@ func DownloadEPSS(w io.Writer, optionFuncs ...optionFunc) error { f(options) } - return epss.DownloadData(w, options.epssDownloadOptions()...) + if err := epss.DownloadData(w, options.epssDownloadOptions()...); err != nil { + return fmt.Errorf("%w: %w", ErrExternalData, err) + } + return nil } func DownloadKEV(w io.Writer, optionFuncs ...optionFunc) error { @@ -140,5 +144,8 @@ func DownloadKEV(w io.Writer, optionFuncs ...optionFunc) error { f(options) } - return kev.DownloadData(w, kev.WithClient(options.kevClient), kev.WithURL(options.kevURL)) + if err := kev.DownloadData(w, kev.WithClient(options.kevClient), kev.WithURL(options.kevURL)); err != nil { + return fmt.Errorf("%w: %w", ErrExternalData, err) + } + return nil } diff --git a/pkg/gatecheck/list.go b/pkg/gatecheck/list.go index 54b93a9..de01872 100644 --- a/pkg/gatecheck/list.go +++ b/pkg/gatecheck/list.go @@ -55,22 +55,43 @@ func WithEPSS(epssFile *os.File, epssURL string, optionFuncs ...optionFunc) (fun } if epssFile == nil { - err := epss.FetchData(data, options.epssDownloadOptions()...) - return f, err + if err := epss.FetchData(data, options.epssDownloadOptions()...); err != nil { + return f, fmt.Errorf("%w: %w", ErrExternalData, err) + } + return f, nil + } + + if err := epss.ParseEPSSDataCSV(epssFile, data); err != nil { + return f, fmt.Errorf("%w: %w", ErrExternalData, err) } + return f, nil +} - err := epss.ParseEPSSDataCSV(epssFile, data) +// ListFormats are the values WithDisplayFormat accepts. "" and "ascii" are the table. +var ListFormats = []string{"table", "markdown", "json"} - return f, err +func normalizeDisplayFormat(name string) string { + switch strings.ToLower(strings.TrimSpace(name)) { + case "markdown", "md": + return "markdown" + case "json": + return "json" + default: + return "table" + } } func List(dst io.Writer, src io.Reader, inputFilename string, options ...ListOptionFunc) error { - table := format.NewTable(dst) var err error o := &listOptions{} for _, f := range options { f(o) } + displayFormat := normalizeDisplayFormat(o.displayFormat) + table := format.NewTable(dst) + if displayFormat == "json" { + table = format.NewJSONTable(dst) + } content, err := readReport(src) if err != nil { @@ -126,6 +147,11 @@ func List(dst io.Writer, src io.Reader, inputFilename string, options ...ListOpt if err = archive.UntarGzipBundle(src, bundle); err != nil { return err } + if displayFormat == "json" { + enc := json.NewEncoder(dst) + enc.SetIndent("", " ") + return enc.Encode(bundle.Manifest()) + } _, err = fmt.Fprintln(dst, bundle.Content()) return err @@ -139,14 +165,16 @@ func List(dst io.Writer, src io.Reader, inputFilename string, options ...ListOpt if err != nil { var empty emptyReport if errors.As(err, &empty) { + if displayFormat == "json" { + return format.WriteEmptyJSON(dst, string(empty)) + } _, err = fmt.Fprintln(dst, string(empty)) return err } return err } - switch strings.ToLower(strings.TrimSpace(o.displayFormat)) { - case "markdown", "md": + if displayFormat == "markdown" { format.SetMarkdown(table) } diff --git a/pkg/gatecheck/osv.go b/pkg/gatecheck/osv.go index a544cd1..d55c249 100644 --- a/pkg/gatecheck/osv.go +++ b/pkg/gatecheck/osv.go @@ -3,6 +3,7 @@ package gatecheck import ( "encoding/json" "errors" + "fmt" "io" "log/slog" "slices" @@ -83,7 +84,7 @@ func validateOSVReportWithFetch(r io.Reader, config *Config, options *fetchOptio epssData := new(epss.Data) if err := LoadCatalogAndData(config, catalog, epssData, options); err != nil { slog.Error("validate osv-scanner report: load epss data from file or api", "error", err) - return errors.New("cannot run osv-scanner validation: Cannot load external validation data, see log for details") + return fmt.Errorf("%w: osv-scanner validation: %w", ErrExternalData, err) } return validateOSVFrom(r, config, catalog, epssData) } diff --git a/pkg/gatecheck/trivy.go b/pkg/gatecheck/trivy.go index bc2f5e4..46db4fe 100644 --- a/pkg/gatecheck/trivy.go +++ b/pkg/gatecheck/trivy.go @@ -3,6 +3,7 @@ package gatecheck import ( "encoding/json" "errors" + "fmt" "io" "log/slog" "slices" @@ -83,7 +84,7 @@ func validateTrivyReportWithFetch(r io.Reader, config *Config, options *fetchOpt epssData := new(epss.Data) if err := LoadCatalogAndData(config, catalog, epssData, options); err != nil { slog.Error("validate trivy report: load epss data from file or api", "error", err) - return errors.New("cannot run Trivy validation: Cannot load external validation data, see log for details") + return fmt.Errorf("%w: Trivy validation: %w", ErrExternalData, err) } return validateTrivyFrom(r, config, catalog, epssData) } diff --git a/pkg/gatecheck/validate.go b/pkg/gatecheck/validate.go index 2996ff0..43fd75b 100644 --- a/pkg/gatecheck/validate.go +++ b/pkg/gatecheck/validate.go @@ -21,6 +21,9 @@ import ( var ErrValidationFailure = errors.New("validation failure") +// ErrExternalData means EPSS or KEV data could not be downloaded or read. +var ErrExternalData = errors.New("cannot load EPSS or KEV data") + func newValidationErr(details string) error { return fmt.Errorf("%w: %s", ErrValidationFailure, details) } @@ -274,7 +277,7 @@ func ruleGrypeKEVLimit(config *Config, report *artifacts.GrypeReportMin, catalog // Check if vulnerability is in the KEV Catalog for _, vulnerability := range report.Matches { inKEVCatalog := slices.ContainsFunc(catalog.Vulnerabilities, func(kevVul kev.Vulnerability) bool { - return kevVul.CveID == vulnerability.Vulnerability.ID + return slices.ContainsFunc(vulnerability.IDs(), func(id string) bool { return strings.EqualFold(kevVul.CveID, id) }) }) if inKEVCatalog { badCVEs = append(badCVEs, vulnerability.Vulnerability.ID) @@ -646,7 +649,7 @@ func validateGrypeReportWithFetch(r io.Reader, config *Config, options *fetchOpt if err := LoadCatalogAndData(config, catalog, epssData, options); err != nil { slog.Error("validate grype report: load epss data from file or api", "error", err) - return errors.New("cannot run Grype validation: Cannot load external validation data, see log for details") + return fmt.Errorf("%w: Grype validation: %w", ErrExternalData, err) } return validateGrypeFrom(r, config, catalog, epssData) @@ -671,7 +674,7 @@ func validateCyclonedxReportWithFetch(r io.Reader, config *Config, options *fetc if err := LoadCatalogAndData(config, catalog, epssData, options); err != nil { slog.Error("validate cyclonedx report: load epss data from file or api", "error", err) - return errors.New("cannot run Cyclonedx validation: Cannot load external validation data, See log for details") + return fmt.Errorf("%w: Cyclonedx validation: %w", ErrExternalData, err) } return validateCyclonedxFrom(r, config, catalog, epssData) } @@ -733,6 +736,7 @@ func validateCoverage(src io.Reader, kind artifacts.ReportKind, targetFilename s var errs error for _, check := range checks { + check.threshold = coverageThreshold(check.name, check.threshold) ratio, ok := coverageRatio(check.covered, check.total) if !ok { if check.threshold > 0 { @@ -751,6 +755,16 @@ func validateCoverage(src io.Reader, kind artifacts.ReportKind, targetFilename s return errs } +// coverageThreshold reads a threshold over 1 as a percent, so 80 means 0.8. +func coverageThreshold(name string, threshold float32) float32 { + if threshold <= 1 { + return threshold + } + ratio := threshold / 100 + slog.Warn("coverage threshold is over 1, reading it as a percent", "kind", name, "threshold", threshold, "ratio", ratio) + return ratio +} + // coverageRatio returns false when total is zero, so a report with no records // of a kind is not applicable rather than NaN. func coverageRatio(covered, total int) (float32, bool) { @@ -772,8 +786,8 @@ func validateBundle(r io.Reader, config *Config, options *fetchOptions) error { epssData := new(epss.Data) if err := LoadCatalogAndData(config, catalog, epssData, options); err != nil { - slog.Error("validate cyclonedx report: load epss data from file or api", "error", err) - return errors.New("cannot run Cyclonedx validation: Cannot load external validation data, See log for details") + slog.Error("validate bundle: load epss data from file or api", "error", err) + return fmt.Errorf("%w: bundle validation: %w", ErrExternalData, err) } var errs error diff --git a/website/llms-full.txt b/website/llms-full.txt index dd10da1..77b5847 100644 --- a/website/llms-full.txt +++ b/website/llms-full.txt @@ -19,7 +19,7 @@ Logs go to stderr. Tables, `config init`, downloads, and this guide go to stdout - `completion bash|fish|powershell|zsh` prints a shell completion script. - `help [command]` prints the same text as ` --help`. -Global flags, on every command: `-v` / `--verbose` (debug logs) and `--silent` (errors only). They cannot be set together. `-h` / `--help` is also global. The scanner commands pass every argument through, including `--help`, so `gatecheck grype --help` is Grype's help. +Global flags, on every command: `-v` / `--verbose` (debug logs), `--silent` (warnings and errors), `--log-level debug|info|warn|error` (default `info`), and `--log-format text|json` (default `text`). Only one of `--verbose`, `--silent`, and `--log-level` can be set. `-h` / `--help` is also global. The scanner commands pass every argument through, including `--help`, so `gatecheck grype --help` is Grype's help. ## Scanners @@ -50,9 +50,9 @@ gatecheck zizmor --format sarif .github/workflows > zizmor.sarif `gatecheck semgrep scan` and `gatecheck osemgrep scan` insert `--experimental` after `scan` when that flag is absent. Other osemgrep commands need `--experimental` from the caller. `gatecheck semgrep --experimental --version` prints the osemgrep version. When the program that runs is the Python `semgrep` on `PATH`, the flag is left alone. `gatecheck osemgrep` looks for the managed binary, then `osemgrep` on `PATH`. -The managed binary wins when it is present. `gatecheck grype`, `gatecheck syft`, `gatecheck gitleaks`, `gatecheck trivy`, `gatecheck osv-scanner`, `gatecheck gosec`, `gatecheck hadolint`, and `gatecheck zizmor` otherwise run that name on `PATH`. `gatecheck semgrep` tries `semgrep` and then `osemgrep` on `PATH`. If none exist, the command prints `gatecheck: is not installed; run `gatecheck bootstrap`` and exits 255. A scanner's own exit status is returned as-is. +The managed binary wins when it is present. `gatecheck grype`, `gatecheck syft`, `gatecheck gitleaks`, `gatecheck trivy`, `gatecheck osv-scanner`, `gatecheck gosec`, `gatecheck hadolint`, and `gatecheck zizmor` otherwise run that name on `PATH`. `gatecheck semgrep` tries `semgrep` and then `osemgrep` on `PATH`. If none exist, the command prints `gatecheck: is not installed; run `gatecheck bootstrap`` and exits 2. A scanner's own exit status is returned as-is. -A platform with no release asset for a requested GitHub-hosted tool fails that tool and the command exits 255. A platform with no semgrep wheel prints a skip message on stderr and continues. Current pins are Grype `0.121.0`, Syft `1.55.0`, Gitleaks `8.30.1`, semgrep `1.182.1`, Trivy `0.76.1`, osv-scanner `2.7.0`, gosec `2.30.0`, hadolint `2.15.1`, and zizmor `1.32.0`, in `internal/bootstrap/versions.go`. +A platform with no release asset for a requested GitHub-hosted tool fails that tool and the command exits 2. A platform with no semgrep wheel prints a skip message on stderr and continues. Current pins are Grype `0.121.0`, Syft `1.55.0`, Gitleaks `8.30.1`, semgrep `1.182.1`, Trivy `0.76.1`, osv-scanner `2.7.0`, gosec `2.30.0`, hadolint `2.15.1`, and zizmor `1.32.0`, in `internal/bootstrap/versions.go`. Syft is installed so it can write CycloneDX (`syft -o cyclonedx-json`). That BOM is listed and validated as CycloneDX. Native Syft JSON is recognized from `descriptor.name` or the schema URL. `list` prints its packages and licenses, and `validate` runs the license rules on it. CycloneDX is a report format, and coverage tools are left to the language toolchain. @@ -112,7 +112,7 @@ gatecheck config convert --file gatecheck.yaml --output toml `config convert` reads `-f` / `--file` (default `gatecheck.yaml`). The extension selects the decoder: `.yaml`, `.yml`, `.json`, or `.toml`. -A partial file is fine. Omitted fields keep the default. Unknown keys are ignored. With no config, `validate` uses the built-in default: every rule disabled, coverage thresholds `0`. Grype, CycloneDX, Trivy, osv-scanner, SARIF, Semgrep, Gitleaks, coverage, and bundle reports pass under that default. Syft JSON passes too, since the license rules are off by default. An old config with no `sarif` section leaves those limits disabled. +A partial file is fine. Omitted fields keep the default. Unknown keys, such as a misspelled `severityLimt`, are named in a warning on stderr, and the rest of the file is still used. With no config, `validate` uses the built-in default: every rule disabled, coverage thresholds `0`. Grype, CycloneDX, Trivy, osv-scanner, SARIF, Semgrep, Gitleaks, coverage, and bundle reports pass under that default. Syft JSON passes too, since the license rules are off by default. An old config with no `sarif` section leaves those limits disabled. `GATECHECK_CONFIG_FILENAME` is the same setting as `validate --config` / `-f`. @@ -139,7 +139,7 @@ Field names below are the ones `config init` emits. In YAML they are case sensit `vex.files` lists OpenVEX or CycloneDX VEX documents, read along with `--vex`. -`coverage.lineThreshold`, `functionThreshold`, and `branchThreshold` are ratios from 0 to 1: covered lines, functions, or branches divided by the total. The report fails when its ratio is less than the threshold. A ratio equal to the threshold passes. `0.8` is 80 percent. `80` fails a report whose real line coverage is 0.8, because 0.8 is less than 80. There is no `enabled` flag. The default `0` allows any coverage, because a ratio is never less than 0. `list` prints these numbers as percents in the table footer. The config still wants the ratio. A report with no records of a kind, such as LCOV without branch records, has no ratio for it. `list` prints `N/A`, and `validate` skips that threshold with a warning. +`coverage.lineThreshold`, `functionThreshold`, and `branchThreshold` are ratios from 0 to 1: covered lines, functions, or branches divided by the total. The report fails when its ratio is less than the threshold. A ratio equal to the threshold passes. `0.8` is 80 percent. A threshold over 1 is read as a percent, so `80` means `0.8`, and a warning says so. There is no `enabled` flag. The default `0` allows any coverage, because a ratio is never less than 0. `list` prints these numbers as percents in the table footer. The config still wants the ratio. A report with no records of a kind, such as LCOV without branch records, has no ratio for it. `list` prints `N/A`, and `validate` skips that threshold with a warning. Grype, CycloneDX, Trivy, and osv-scanner rules run in this order. A failure returns immediately, except where a rule only removes findings. Trivy counts vulnerability entries only. osv-scanner counts one finding per group. @@ -173,17 +173,18 @@ gatecheck validate --config gatecheck.yaml grype-report.json gatecheck validate --audit --config gatecheck.yaml gatecheck-bundle.tar.gz ``` -The report path is the only positional argument, and it is required. Pass the config with `--config` or `-f`. +The report path is the positional argument. With no path, `--input-type` is required and the report is read from stdin. Pass the config with `--config` or `-f`. With no config, a warning says every rule is disabled. -Exit status: +Exit status, for `validate` and every other gatecheck command: -- `0`: the report passed. With `--audit` / `-a`, a check error is printed and the process also exits 0. +- `0`: success. With `--audit` / `-a`, a threshold failure is printed to stderr and the process still exits 0. - `1`: a threshold failed and `--audit` is off. The error text starts with `validation failure:`. -- `255`: the report or config could not be opened, the config extension is not supported, the command line was rejected, or another check error occurred with `--audit` off. +- `2`: usage error, a file that could not be opened or written, or a report, config, or VEX file that could not be decoded. `--audit` does not change this. +- `3`: EPSS or KEV data could not be downloaded or read. `--audit` does not change this. -Opening the report, the config, and any `--epss-filename` or `--kev-filename` happens before the audit check. A missing file still exits 255 when `--audit` is set. +`--format table|markdown|json` also prints the result to stdout. JSON is `{"report": "...", "passed": false, "failures": ["Grype: Severity Limit Exceeded"]}`, plus `"error"` when the check stopped on something else. Without `--format`, stdout is empty. -`--epss-filename` is the EPSS CSV used when an EPSS rule is enabled. `--kev-filename` is the CISA KEV JSON used when `kevLimitEnabled` is true. `--epss-cache-dir` and `--epss-no-cache` apply when that CSV is downloaded. `validate` has no `--epss-url` or `--kev-url` flag. `GATECHECK_EPSS_URL` and `GATECHECK_KEV_URL` still override those APIs when the matching file is not set. The defaults are the same URLs `download` uses. +`--epss-filename` is the EPSS CSV used when an EPSS rule is enabled. `--kev-filename` is the CISA KEV JSON used when `kevLimitEnabled` is true. `--epss-url` and `--kev-url` change the feeds. `--epss-cache-dir` and `--epss-no-cache` apply when that CSV is downloaded. `--vex FILE` (repeatable), `GATECHECK_VEX` (comma-separated, used when the flag is absent), and the config's `vex.files` name OpenVEX or CycloneDX VEX documents. Grype, CycloneDX, Trivy, and osv-scanner findings that a VEX file marks `not_affected` or `fixed` (OpenVEX), or `not_affected`, `false_positive`, `resolved`, or `resolved_with_pedigree` (CycloneDX `analysis.state`), are removed right after the `cveLimit` deny list, so they skip the KEV, EPSS, and severity rules. Ids match the finding's id or aliases. A statement that lists subcomponents or `affects` refs matches only those package URLs. The OpenVEX product itself is not checked. When several statements match, the latest timestamp wins. @@ -193,14 +194,15 @@ EPSS data is loaded only when an EPSS limit or EPSS risk acceptance rule is enab ```shell gatecheck list grype-report.json -gatecheck list --markdown --epss grype-report.json +gatecheck list --format markdown --epss grype-report.json +gatecheck list --format json trivy-report.json grype image:tag -o json | gatecheck ls --input-type grype gatecheck list-all grype-report.json semgrep-report.json ``` -`list` opens the first filename only. Further filenames are ignored. `--markdown` prints a markdown table. A Grype, CycloneDX, SARIF, Semgrep, Gitleaks, Trivy, or osv-scanner report with no findings prints one sentence and no table, with or without `--markdown`: `No grype vulnerabilities`, `No cyclonedx vulnerabilities`, `No sarif findings`, `No semgrep findings`, `No gitleaks findings`, `No trivy vulnerabilities`, or `No osv-scanner vulnerabilities`. `--epss` adds EPSS score and percentile columns for Grype, CycloneDX, Trivy, and osv-scanner. Other report types still list, and those columns are omitted. `--epss-url` empty uses `https://epss.cyentia.com`. `--epss-filename` reads that CSV instead of calling the API. +`list` takes one filename, or stdin with `--input-type`. `--format table|markdown|json` picks the output, and `--markdown` is the same as `--format markdown`. JSON is `{"columns": [...], "rows": [{column: value}], "footer": {...}}`. A Grype, CycloneDX, SARIF, Semgrep, Gitleaks, Trivy, osv-scanner, or Syft report with nothing in it prints one sentence and no table: `No grype vulnerabilities`, `No cyclonedx vulnerabilities`, `No sarif findings`, `No semgrep findings`, `No gitleaks findings`, `No trivy vulnerabilities`, `No osv-scanner vulnerabilities`, or `No syft packages`. In JSON that is `{"columns": [], "rows": [], "message": "..."}`. Syft JSON lists package, version, type, and licenses. `--epss` adds EPSS score and percentile columns for Grype, CycloneDX, Trivy, and osv-scanner. Other report types still list, and those columns are omitted. `--epss-url` empty uses `https://epss.cyentia.com`. `--epss-filename` reads that CSV instead of calling the API. -`list-all` prints each filename, then its table, or that sentence when the report has no findings. A file whose contents and name are not a supported `list-all` type is skipped with a warning. A missing file is skipped. A list error is logged and the command continues. The command exits 0. `--epss` adds EPSS data for Grype, CycloneDX, Trivy, and osv-scanner, including a file whose name does not contain those words when the contents do. There is no `--epss-filename` flag, and `GATECHECK_EPSS_FILENAME` is not read. `GATECHECK_EPSS_URL` overrides the API. `--epss-cache-dir` and `--epss-no-cache` are accepted. +`list-all` prints each filename, then its table, or that sentence when the report has nothing in it. With `--format json` it prints one array of `{"file": ..., "report": ...}`. A file whose contents and name are not a supported `list-all` type is skipped with a warning. A file that cannot be read or listed is logged, the rest are still listed, and the command then exits 2. `--epss` adds EPSS data for Grype, CycloneDX, Trivy, and osv-scanner, loaded once per run. `--epss-filename`, `--epss-url`, `--epss-cache-dir`, and `--epss-no-cache` work as on `list`. ## bundle @@ -213,7 +215,7 @@ gatecheck bundle remove gatecheck-bundle.tar.gz semgrep-report.json gatecheck list gatecheck-bundle.tar.gz ``` -The stored label is the base name of the target file (`reports/grype-report.json` is stored as `grype-report.json`). Later validation uses the file contents to pick the type, and the label when the contents are ambiguous. Repeat `-t` / `--tag` for more than one tag. When the flag is omitted, `GATECHECK_BUNDLE_TAG` is read as a comma-separated list. `bundle add` requires an existing bundle. `bundle remove` takes the label, not a path that is opened. A label that is not in the bundle is logged and the command exits 0. There is no `bundle list` subcommand. `gatecheck list` prints label, SHA-256 digest, tags, and size. +The stored label is the base name of the target file (`reports/grype-report.json` is stored as `grype-report.json`). Later validation uses the file contents to pick the type, and the label when the contents are ambiguous. Repeat `-t` / `--tag` for more than one tag. When the flag is omitted, `GATECHECK_BUNDLE_TAG` is read as a comma-separated list. `bundle create` replaces an existing file. `bundle add` requires an existing bundle. `bundle remove` takes the label, not a path that is opened. A label that is not in the bundle exits 2 and leaves the bundle unchanged. There is no `bundle list` subcommand. `gatecheck list` prints label, SHA-256 digest, tags, and size. ## download @@ -230,23 +232,25 @@ EPSS requests send a User-Agent with the gatecheck version and `https://github.c ## Environment variables -A non-empty flag wins. An empty flag falls through to the environment variable, then to the default. - | Variable | Commands | Same as | | --- | --- | --- | | `GATECHECK_CONFIG_FILENAME` | `validate` | `--config` | +| `GATECHECK_AUDIT` | `validate` | `--audit` | | `GATECHECK_VEX` | `validate` | `--vex`, comma-separated | -| `GATECHECK_EPSS_FILENAME` | `list`, `validate` | `--epss-filename` | -| `GATECHECK_EPSS_URL` | `download epss`, `list`, `list-all`, `validate` | `--epss-url` on commands that have that flag | +| `GATECHECK_EPSS_FILENAME` | `list`, `list-all`, `validate` | `--epss-filename` | +| `GATECHECK_EPSS_URL` | `download epss`, `list`, `list-all`, `validate` | `--epss-url` | | `GATECHECK_EPSS_CACHE_DIR` | `download epss`, `list`, `list-all`, `validate` | `--epss-cache-dir` | | `GATECHECK_EPSS_CACHE` | `download epss`, `list`, `list-all`, `validate` | `--epss-no-cache` when the value is `off` | -| `GATECHECK_KEV_URL` | `download kev`, `validate` | `--kev-url` on `download kev` | +| `GATECHECK_KEV_FILENAME` | `validate` | `--kev-filename` | +| `GATECHECK_KEV_URL` | `download kev`, `validate` | `--kev-url` | | `GATECHECK_BUNDLE_TAG` | `bundle create`, `bundle add` | `--tag`, as a comma-separated list | +| `GATECHECK_VERBOSE` | every command | `--verbose` | +| `GATECHECK_SILENT` | every command | `--silent` | +| `GATECHECK_LOG_LEVEL` | every command | `--log-level` | +| `GATECHECK_LOG_FORMAT` | every command | `--log-format` | | `GATECHECK_HOME` | `bootstrap`, `grype`, `syft`, `gitleaks`, `semgrep`, `osemgrep`, `trivy`, `osv-scanner`, `gosec`, `hadolint`, `zizmor` | data directory; binaries are in `bin` under it | -`GATECHECK_EPSS_CACHE` also disables the cache for `0`, `false`, `no`, `disabled`, `disable`, and `none`. - -`GATECHECK_EPSS_FILE`, `GATECHECK_KEV_FILE`, and `GATECHECK_CLI_AUDIT` are not read. There is no `GATECHECK_KEV_FILENAME`. The KEV filename setting is bound to `GATECHECK_EPSS_FILENAME`, so that variable also selects the KEV file. Pass a local catalog with `--kev-filename`. `GATECHECK_VERBOSE`, `GATECHECK_SILENT`, and `GATECHECK_AUDIT` are not parsed as booleans. Use `--verbose`, `--silent`, and `--audit`. A non-empty value in those three variables can panic. +A flag on the command line wins over its variable. An empty variable counts as unset. `GATECHECK_AUDIT`, `GATECHECK_VERBOSE`, and `GATECHECK_SILENT` take `true`, `false`, `1`, `0`, `t`, or `f`, and any other value exits 2. `GATECHECK_EPSS_CACHE` also disables the cache for `0`, `false`, `no`, `disabled`, `disable`, and `none`. ## Minimal CI @@ -260,10 +264,10 @@ Create the config with `gatecheck config init > gatecheck.yaml` and set real thr ## Common mistakes - The contents do not identify a type and the filename has no lowercase type word (`scan.json`, `Grype.json`). A real bundle named `project.gcb` is still recognized from its contents. An empty document such as `{"matches":[]}` still needs a name such as `grype-report.json`, or `--input-type grype` on standard input. -- Coverage thresholds are ratios. Set `coverage.lineThreshold` to `0.8` for 80 percent, not `80` or `80.0`. +- Coverage thresholds are ratios. Set `coverage.lineThreshold` to `0.8` for 80 percent. A value over 1, such as `80`, is read as a percent with a warning. - `validate` takes the report as its positional argument. The config is `--config` / `-f`. `gatecheck validate gatecheck.yaml grype-report.json` tries to open the config as a report. `config convert` uses `--file` / `-f`, which is a different flag. -- `list` on a pipe needs `--input-type`. Clear contents still win over that flag. `validate` needs a filesystem path. -- `list` ignores every filename after the first. Use `list-all` for several files. `list-all` skips coverage files such as `lcov.info`. List those with `gatecheck list lcov.info`. +- `list` and `validate` on a pipe need `--input-type`. Clear contents still win over that flag. +- `list` takes one filename, and a second one exits 2. Use `list-all` for several files. `list-all` skips coverage files such as `lcov.info`. List those with `gatecheck list lcov.info`. - Native Syft JSON gets only the license rules. Use CycloneDX output when you also want vulnerabilities scored. That BOM is CycloneDX even when the filename contains `syft`. - `gatecheck semgrep --version` reaches osemgrep without `--experimental`, and osemgrep then tries to run `pysemgrep`. Pass the flag: `gatecheck semgrep --experimental --version`. -- `--audit` still exits 255 when the report, the config, or a named EPSS or KEV file cannot be opened. +- `--audit` only hides threshold failures. It still exits 2 when the report, the config, or a named EPSS, KEV, or VEX file cannot be opened, and 3 when EPSS or KEV data cannot be loaded.