go-vuln-gate

go-vuln-gate

A CI/CD gate that filters govulncheck results by CVSS score threshold. Only fail your pipeline when high-severity vulnerabilities are detected.

Table of Contents

• Features
• Quick Start
  • GitHub Action
  • CLI
• CLI Installation
  • Docker
• CLI Usage
• GitHub Action Usage
  • Using Docker Image
• NVD API
• Output Examples
• How It Works

Features

• CVSS Score Filtering: Only detect vulnerabilities above a threshold (default: 7.0)
• Called Vulnerabilities Only: By default, only checks vulnerabilities actually called by your code
• Age Filter: Filter vulnerabilities published within the last N years
• Multiple CVSS Versions: Supports CVSS v2, v3, and v4
• NVD API Integration: Automatically fetches CVSS scores from NVD API
• Parallel Processing: Concurrent CVSS score fetching with API key
• Auto Retry: Exponential backoff retry on rate limits
• Multiple Output Formats: text, JSON, and SARIF formats
• GitHub Action: Easy integration into CI/CD pipelines

Quick Start

GitHub Action (Quick Start)

- uses: anies1212/go-vuln-gate@v1
  with:
    cvss-threshold: '7.0'

Note: The GitHub Action automatically installs govulncheck - no manual setup required.

CLI (Quick Start)

# 1. Install govulncheck (required)
go install golang.org/x/vuln/cmd/govulncheck@latest

# 2. Install go-vuln-gate
go install github.com/anies1212/go-vuln-gate/cmd/go-vuln-gate@latest

# 3. Run
go-vuln-gate --threshold 7.0 ./...

CLI Installation

Prerequisites

• Go 1.22 or later
• govulncheck (must be installed separately)

Step 1: Install govulncheck

go-vuln-gate requires govulncheck to be installed and available in your PATH.

go install golang.org/x/vuln/cmd/govulncheck@latest

Step 2: Install go-vuln-gate

go install github.com/anies1212/go-vuln-gate/cmd/go-vuln-gate@latest

Verify Installation

# Check govulncheck is installed
govulncheck -version

# Check go-vuln-gate is installed
go-vuln-gate --help

Pre-built Binaries

Pre-built binaries are available on the Releases page.

Note: Even when using pre-built binaries, you still need to install govulncheck separately.

Docker

A Docker image with govulncheck pre-installed is available:

# Pull the image
docker pull ghcr.io/anies1212/go-vuln-gate:latest

# Run on your project
docker run --rm -v $(pwd):/workspace ghcr.io/anies1212/go-vuln-gate:latest --threshold 7.0 ./...

CLI Usage

Basic

# Scan current directory (threshold: 7.0)
go-vuln-gate ./...

# Custom threshold
go-vuln-gate --threshold 9.0 ./...

# Only check vulnerabilities from the last 3 years
go-vuln-gate --max-age 3 ./...

# Include all vulnerabilities (not just called ones)
go-vuln-gate --include-all ./...

# Use NVD API key (faster with parallel requests)
go-vuln-gate --nvd-api-key $NVD_API_KEY ./...

# JSON output
go-vuln-gate --output json ./...

# SARIF output (for GitHub Code Scanning)
go-vuln-gate --output sarif ./...

Options

Environment Variables

• NVD_API_KEY: NVD API key (alternative to --nvd-api-key)

GitHub Action Usage

Basic

name: Security Scan

on: [push, pull_request]

jobs:
  vuln-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run go-vuln-gate
        uses: anies1212/go-vuln-gate@v1
        with:
          cvss-threshold: '7.0'
          max-age: '3'  # Only last 3 years
          nvd-api-key: ${{ secrets.NVD_API_KEY }}

SARIF Output with Code Scanning

name: Security Scan

on: [push, pull_request]

jobs:
  vuln-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run go-vuln-gate
        uses: anies1212/go-vuln-gate@v1
        with:
          cvss-threshold: '7.0'
          output-format: 'sarif'
          nvd-api-key: ${{ secrets.NVD_API_KEY }}
        continue-on-error: true

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Using Docker Image in GitHub Actions

If your CI runs in a Docker container or you prefer using the Docker image directly:

name: Security Scan

on: [push, pull_request]

jobs:
  vuln-check:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/anies1212/go-vuln-gate:latest
    steps:
      - uses: actions/checkout@v4

      - name: Run go-vuln-gate
        run: go-vuln-gate --threshold 7.0 ./...
        env:
          NVD_API_KEY: ${{ secrets.NVD_API_KEY }}

Or use the Docker image directly without the composite action:

- name: Run go-vuln-gate
  run: |
    docker run --rm \
      -v ${{ github.workspace }}:/workspace \
      -e NVD_API_KEY=${{ secrets.NVD_API_KEY }} \
      ghcr.io/anies1212/go-vuln-gate:latest \
      --threshold 7.0 ./...

Input Parameters

Outputs

CVSS Score Threshold Guide

NVD API

Rate Limits

The NVD API has rate limits:

• Without API key: 1 request per 6 seconds (concurrency: 1)
• With API key: 1 request per 0.6 seconds (concurrency: 5)

For scanning many vulnerabilities, we recommend obtaining an API key.

Request an NVD API Key

Auto Retry

When rate limited (429 error), the tool automatically retries with exponential backoff:

• 1st retry: after 10 seconds
• 2nd retry: after 20 seconds
• 3rd retry: after 40 seconds (max 60 seconds)

Output Examples

Text Format

Running govulncheck on ./......
Found 2 called vulnerabilities (out of 10 total), fetching CVSS scores...

=== go-vuln-gate Report ===

Threshold: 7.0 (CVSS v31)
Total vulnerabilities found: 2
Vulnerabilities above threshold: 1
Highest CVSS score: 9.8 (CRITICAL)

--- Vulnerabilities Above Threshold ---

  GO-2024-1234
    CVE: CVE-2024-1234
    CVSS: 9.8 (CRITICAL, v31)
    Summary: Remote code execution vulnerability
    Affected: example.com/vulnerable-lib
    Fixed in: v1.2.3

[FAIL] Found 1 vulnerabilities above threshold 7.0

JSON Format

{
  "summary": {
    "threshold": 7.0,
    "cvss_version": "v31",
    "total_vulnerabilities": 2,
    "filtered_vulnerabilities": 1,
    "highest_score": 9.8,
    "should_fail": true
  },
  "vulnerabilities": [
    {
      "osv_id": "GO-2024-1234",
      "cve_ids": ["CVE-2024-1234"],
      "summary": "Remote code execution vulnerability",
      "cvss_score": 9.8,
      "severity": "CRITICAL",
      "affected_modules": ["example.com/vulnerable-lib"],
      "fixed_version": "v1.2.3"
    }
  ]
}

How It Works

1. Runs govulncheck with JSON output
2. By default, filters to only vulnerabilities that are actually called by your code
3. Fetches CVSS scores from NVD API for each CVE
4. Filters vulnerabilities by CVSS threshold
5. Outputs results and exits with code 1 if vulnerabilities exceed threshold

License

MIT License