Gatecheck

Gatecheck automates report validation in a CI/CD Pipeline by comparing security findings to pre-determined thresholds. It also provides report aggregation, artifact integrity, and deployment validation. Gatecheck is stateless so self-hosting and provisioning servers is not required.

Getting Started

The fastest way to get started with Gatecheck is to download the pre-built binaries for your target system.

cd <target install dir>
curl -L <OS Specific Release>.tar.gz | tar xz
./gatecheck
./gatecheck --help

The Gatecheck CLI supports --help for every command for more detail usage.

Generate a configuration file with the default thresholds set

gatecheck config init > gatecheck.yaml

Summarize Reports with List

gatechec ls --help

List with EPSS Scores is support for Grype and Cyclondex reports

Validation

List with EPSS Scores is support for Grype and Cyclondex reports

Bundling Artifacts

Bundling Artifacts produces a gzipped tarball with an associated manifest for metadata.

Installation

Prerequisites

Before installing Gatecheck, make sure your system meets the following requirements:

• Operating System: Windows, macOS, or Linux.
• Go: Version 1.22.0 or newer (only required if you plan to build the application from source).

Installation Options

Gatecheck can be installed either by downloading the pre-compiled binary for your operating system or by compiling the source code.

Option 1: Installing from Binary

1. Download the Binary: Visit the Gatecheck GitHub releases page at https://github.com/gatecheckdev/gatecheck/releases and download the latest version for your operating system.

2. Unpack the Binary (if necessary): For Windows and Linux, you may need to unpack the .zip or .tar.gz file.

3. Move the Binary to a Bin Directory:

   • Windows: Move gatecheck.exe to a directory within your PATH, such as C:\Windows.
   • macOS/Linux: Move gatecheck to a location in your PATH, such as /usr/local/bin. You can use the command mv gatecheck /usr/local/bin in the terminal.

4. Verify Installation: Open a terminal or command prompt and type gatecheck --version to ensure the application is installed correctly.

Option 2: Building from Source

1. Clone the Repository: Clone the Gatecheck repository to your local machine using Git:

   git clone https://github.com/gatecheckdev/gatecheck
   

2. Navigate to the Repository Directory:

   cd gatecheck
   

3. Build the Application: Run the following command to compile Gatecheck with appropriate load flags:

    go build -ldflags="-X 'main.cliVersion=$(git describe --tags)' -X 'main.gitCommit=$(git rev-parse HEAD)' -X 'main.buildDate=$(date -u +%Y-%m-%dT%H:%M:%SZ)' -X 'main.gitDescription=$(git log -1 --pretty=%B)'" -o ./bin ./cmd/gatecheck
   

4. Move the Binary to a Bin Directory (as described in Option 1, step 3).

5. Verify Installation: Check the application version to confirm successful installation:

   ./gatecheck --version
   

Option 3: Use Just Recipe

Just Command Runner

git clone https://github.com/gatecheckdev/gatecheck
cd gatecheck
just install 

Will default to /usr/local/bin as the install directory, but this can be changed.

INSTALL_DIR='custom/location/bin' just install

Post-Installation Steps

After installing Gatecheck, you can begin using it by typing gatecheck followed by the necessary commands and options in your terminal or command prompt. For a list of available commands and their descriptions, use:

gatecheck --help

Troubleshooting

If you encounter any issues during the installation process, ensure that you have the correct permissions to install software on your system and that your Go environment is properly configured. For further assistance, please visit the Gatecheck GitHub issues page or contact support.

For more information on using Gatecheck, refer to the user documentation or the GitHub repository for examples and advanced usage.

Usage

Gatecheck is designed as a lightweight CLI utility first with configuration flexibility to work in any environment.

Developers can use it on the command line to summarize lengthy reports for a quick view or run an audit locally before pushing code to be handed off to CI/CD.

It simplifies cross-referencing with FIRST’s Exploit Prediction Scoring System (EPSS) API to match CVEs to vulnerability scores that provide more context than just ‘critical, high, medium, etc.’.

Gatecheck also has some additional features to make bundling reports for attestation and archiving easy.

Gatecheck Refactor

Package Updates

The Async Decoder is no longer used for a number of reasons, mostly for code readability. The user experience improvements and performance improvements were not enough to justify the complexity of the code required to keep it.

Config Updates

The new configuration file is more expressive than the original with the ability the selectively enable/disable certain rules.

See the (Configuration Guide)[./configuration.md] for details.

New CLI

Gatecheck is currently going through a refactor which will give the CLI some much-needed love. The more streamlined CLI will reduce the complexity with usage and provide a clear use case for every command.

Deprecation Schedule

The existing Gatecheck CLI is now considered deprecated however, users can still access the legacy CLI by setting the environment variable GATECHECK_FF_LEGACY_CLI_ENABLED=1 as of version 0.4.0.

This Legacy CLI and packages are scheduled to be removed after version 0.5.0.

List Reports

Most scanning tools have options to display a formatted report. Take Grype for example:

grype bkimminich/juice-shop:latest -o table

The report can be printed in a formatted table instead of 6k line JSON file.

JSON can be piped directly into gatecheck for supported reports.

grype bkimminich/juice-shop:latest -o json | gatecheck ls -i grype

Or from an existing report

gatecheck ls grype-scan-report.json

Using the --all or -a flag will do a full listing, cross-referencing with FIRST EPSS API

grype bkimminich/juice-shop:latest -o json | gatecheck ls --all -i grype

Gatecheck Bundle

in progress

Validation

Rules Order of Precedence

1. CVE Limit: Any Matching vulnerabilities will fail validation
2. CVE Risk Acceptance: Any Matching vulnerabilities will remove the CVE from subsequent rules, risk accepted
3. KEV Limit: Any Matching vulnerabilities will fail validation
4. EPSS Risk Acceptance: Any matching vulnerabilities that are below the risk acceptance will be removed from subsequent rules, risk accepted
5. EPSS Limit: Any matching vulnerabilities that exceed the limit will fail validation
6. Severity Limit: A count of severities that exceed the limit in any severity category will fail validation

Supported Reports

Configuration

Header

# The configuration version, reserved for future use but not required in v1
version: "1"
# Option metadata for the config that doesn't impact functionality
metadata:
  tags:
    - auto generated from CLI

Grype Configuration

grype:
  # Severity Limit Rule sets a limit for how many vulnerabilities are allowed in a report
  # each severity level can have a different limit
  severityLimit:
    critical:
      enabled: false
      limit: 0
    high:
      enabled: false
      limit: 0
    medium:
      enabled: false
      limit: 0
    low:
      enabled: false
      limit: 0
  # EPSS Limit Rule sets a limit for the max score allowed for each vulnerability
  epssLimit:
    enabled: false
    score: 0
  # KEV Limit Rule fails validation if any vulnerability matches to the 
  # Known Exploited Vulnerability Catalog
  kevLimitEnabled: false
  # CVE Limit Rule fails validation if any vulnerability ID matches
  # to any CVE in this list
  cveLimit:
    enabled: false
    cves: 
      - ID: CVE-example-2024-1
        Metadata:
          Tags:
            - Some example tag
  # EPSS Risk Acceptance Rule skips validation for vulnerabilities with 
  # EPSS score less than this score limit
  epssRiskAcceptance:
    enabled: false
    score: 0
  # CVE Risk Acceptance Rule skips validation for vulnerability ID that matches
  cveRiskAcceptance:
    enabled: false
    cves: 
      - ID: CVE-example-2024-2
        Metadata:
          Tags:
            - Some example tag

Cyclonedx Configuration

cyclonedx:
  # Severity Limit Rule sets a limit for how many vulnerabilities are allowed in a report
  # each severity level can have a different limit
  severityLimit:
    critical:
      enabled: false
      limit: 0
    high:
      enabled: false
      limit: 0
    medium:
      enabled: false
      limit: 0
    low:
      enabled: false
      limit: 0
  # EPSS Limit Rule sets a limit for the max score allowed for each vulnerability
  epssLimit:
    enabled: false
    score: 0
  # KEV Limit Rule fails validation if any vulnerability matches to the 
  # Known Exploited Vulnerability Catalog
  kevLimitEnabled: false
  # CVE Limit Rule fails validation if any vulnerability ID matches
  # to any CVE in this list
  cveLimit:
    enabled: false
    cves: []
  # EPSS Risk Acceptance Rule skips validation for vulnerabilities with 
  # EPSS score less than this score limit
  epssRiskAcceptance:
    enabled: false
    score: 0
  # CVE Risk Acceptance Rule skips validation for vulnerability ID that matches
  cveRiskAcceptance:
    enabled: false
    cves: []

Semgrep Configuration

semgrep:
  # Severity Limits can be applied for each level
  # if there are findings than the limit permits,
  # It will result in validation failure
  severityLimit:
    error:
      enabled: false
      limit: 0
    warning:
      enabled: false
      limit: 0
    info:
      enabled: false
      limit: 0
  # Impact Risk Acceptance premits findings based
  # on their impact level
  impactRiskAcceptance:
    enabled: false
    high: false
    medium: false
    low: false

GitLeaks Configuration

GitLeaks secrets detection validation can be turned on or off. When the limit is enabled, the presence of any non-ignored finding will result in a validation failure.

gitleaks:
  limitEnabled: false