Configuration

validate reads YAML, JSON, or TOML. The extension selects the format: .yaml, .yml, .json, or .toml.

gatecheck config init > gatecheck.yaml

config init writes to standard output. -o / --output accepts json, .json, toml, .toml, yaml, yml, .yaml, and .yml. The default is yaml.

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 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.

Field names below are the ones config init emits. In YAML they are case sensitive. Use the lowercase names.

Default file

This is what gatecheck config init prints.

version: "1"
metadata:
  tags: []
grype:
  severityLimit:
    critical:
      enabled: false
      limit: 0
    high:
      enabled: false
      limit: 0
    medium:
      enabled: false
      limit: 0
    low:
      enabled: false
      limit: 0
  epssLimit:
    enabled: false
    score: 0
  kevLimitEnabled: false
  cveLimit:
    enabled: false
    cves: []
  epssRiskAcceptance:
    enabled: false
    score: 0
  cveRiskAcceptance:
    enabled: false
    cves: []
cyclonedx:
  severityLimit:
    critical:
      enabled: false
      limit: 0
    high:
      enabled: false
      limit: 0
    medium:
      enabled: false
      limit: 0
    low:
      enabled: false
      limit: 0
  epssLimit:
    enabled: false
    score: 0
  kevLimitEnabled: false
  cveLimit:
    enabled: false
    cves: []
  epssRiskAcceptance:
    enabled: false
    score: 0
  cveRiskAcceptance:
    enabled: false
    cves: []
trivy:
  severityLimit:
    critical:
      enabled: false
      limit: 0
    high:
      enabled: false
      limit: 0
    medium:
      enabled: false
      limit: 0
    low:
      enabled: false
      limit: 0
  epssLimit:
    enabled: false
    score: 0
  kevLimitEnabled: false
  cveLimit:
    enabled: false
    cves: []
  epssRiskAcceptance:
    enabled: false
    score: 0
  cveRiskAcceptance:
    enabled: false
    cves: []
osv-scanner:
  severityLimit:
    critical:
      enabled: false
      limit: 0
    high:
      enabled: false
      limit: 0
    medium:
      enabled: false
      limit: 0
    low:
      enabled: false
      limit: 0
  epssLimit:
    enabled: false
    score: 0
  kevLimitEnabled: false
  cveLimit:
    enabled: false
    cves: []
  epssRiskAcceptance:
    enabled: false
    score: 0
  cveRiskAcceptance:
    enabled: false
    cves: []
semgrep:
  severityLimit:
    error:
      enabled: false
      limit: 0
    warning:
      enabled: false
      limit: 0
    info:
      enabled: false
      limit: 0
  impactRiskAcceptance:
    enabled: false
    high: false
    medium: false
    low: false
gitleaks:
  limitEnabled: false
sarif:
  severityLimit:
    critical:
      enabled: false
      limit: 0
    high:
      enabled: false
      limit: 0
    medium:
      enabled: false
      limit: 0
    low:
      enabled: false
      limit: 0
  ruleLimit:
    enabled: false
    rules: []
  ruleRiskAcceptance:
    enabled: false
    rules: []
coverage:
  lineThreshold: 0
  functionThreshold: 0
  branchThreshold: 0
vex:
  files: []
license:
  enabled: false
  deny: []
  allow: []
  denyUnknown: false
  packageRiskAcceptance: []
scorecard:
  enabled: false
  minScore: 0
  checks: []
trufflehog:
  limitEnabled: false
  verifiedOnly: false

version and metadata

version is the string "1". metadata.tags is a list of strings. Neither one changes validation.

Grype, CycloneDX, Trivy, and osv-scanner

grype, cyclonedx, trivy, and osv-scanner use the same fields. Trivy scores vulnerability entries. Misconfigurations, secrets, and licenses in the Trivy JSON are ignored. A Trivy id matches VulnerabilityID and each VendorIDs entry.

osv-scanner counts one finding per vulnerability group. Aliases of that group are not counted again. License-only packages are skipped. max_severity is a CVSS base score: 9.0 and above is critical, 7.0 high, 4.0 medium, 0.1 low, and anything lower is unknown. The words CRITICAL, HIGH, MEDIUM, LOW, MODERATE, and UNKNOWN are also accepted. MODERATE is medium. A CVSS vector with no numeric score is unknown. database_specific.severity is used when max_severity is empty. Deny, allow, and KEV match the OSV id or any alias. EPSS and KEV look up the first id that starts with CVE-.

severityLimit has critical, high, medium, and low. Each has enabled and limit. limit is a count. The report fails when the number of findings at that severity is greater than limit. enabled: true and limit: 0 allows none. enabled: false skips that severity.

epssLimit.score and epssRiskAcceptance.score are EPSS ratios from 0 to 1, the same scale as the FIRST CSV. The limit fails when a CVE’s score is greater than score. Risk acceptance removes a CVE when score is greater than that CVE’s score. See Validation for the order and the equal-score cases.

kevLimitEnabled fails the report when any remaining CVE is in the CISA catalog.

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.

grype:
  cveLimit:
    enabled: true
    cves:
      - id: CVE-2024-0001
        metadata:
          tags:
            - denied
  cveRiskAcceptance:
    enabled: true
    cves:
      - id: CVE-2023-5678
        metadata:
          tags:
            - accepted

Semgrep

severityLimit has error, warning, and info. Each has enabled and limit, with the same meaning as the Grype counts.

impactRiskAcceptance has enabled, high, medium, and low. When enabled is true, a finding is removed when its impact matches a level whose value is true. high, medium, and low are separate switches.

Gitleaks

limitEnabled: true fails validation when the report contains any finding. false skips the check. There is no count.

trufflehog

trufflehog gates trufflehog --json output, a second secrets scanner next to Gitleaks.

trufflehog:
  limitEnabled: true
  verifiedOnly: false

limitEnabled: true fails validation when the report has any finding. verifiedOnly: true counts only the secrets trufflehog verified as live, so unverified matches are logged and do not fail. Secret values in the report are never decoded, listed, or logged.

Scorecard

scorecard gates an OpenSSF Scorecard report from scorecard --format json.

scorecard:
  enabled: true
  minScore: 6
  checks:
    - name: Dangerous-Workflow
      minScore: 10
    - name: Token-Permissions
      minScore: 5

Scores are 0 to 10. minScore fails the report when the aggregate score is lower. 0 lets any aggregate pass. Each checks entry fails the report when that check scores lower than its minScore. Check names are compared without regard to case. A check scored -1 (inconclusive, such as Signed-Releases on a repo with no releases) is skipped with a warning, and so is a named check that is not in the report. A score equal to the minimum passes.

SARIF

sarif is for any SARIF 2.1.0 report. Semgrep’s own JSON still uses semgrep. semgrep --sarif uses sarif.

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. The ranges are the ones GitHub code scanning uses:

  • 9.0 and above: critical
  • 7.0 to 8.9: high
  • 4.0 to 6.9: medium
  • above 0 and below 4.0: low
  • 0: none, and the severity limit does not count it

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: high
  • warning: medium
  • note: low
  • none: the result is ignored

ruleLimit is the deny list. ruleRiskAcceptance is the allow list. Each has enabled and rules. A rule entry is id plus an optional metadata.tags list. id is compared without regard to case.

sarif:
  ruleLimit:
    enabled: true
    rules:
      - id: CKV_AWS_21
        metadata:
          tags:
            - denied
  ruleRiskAcceptance:
    enabled: true
    rules:
      - id: B101
        metadata:
          tags:
            - accepted

See Validation for which results are counted and the order of the rules.

License

license gates the package licenses in Syft JSON and CycloneDX BOMs.

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.

Coverage

lineThreshold, functionThreshold, and branchThreshold are ratios from 0 to 1:

  • line coverage is covered lines divided by total lines
  • 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. 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.

gatecheck list prints these numbers as percents in the table footer. The config still wants the ratio.

A tighter file

version: "1"
metadata:
  tags:
    - ci
grype:
  severityLimit:
    critical:
      enabled: true
      limit: 0
    high:
      enabled: true
      limit: 5
  epssLimit:
    enabled: true
    score: 0.5
  kevLimitEnabled: true
semgrep:
  severityLimit:
    error:
      enabled: true
      limit: 0
    warning:
      enabled: true
      limit: 10
  impactRiskAcceptance:
    enabled: true
    high: false
    medium: true
    low: true
gitleaks:
  limitEnabled: true
coverage:
  lineThreshold: 0.8
  functionThreshold: 0.75
  branchThreshold: 0.7

Fields left out of this file keep the defaults from config init.