GitHub Action

Table of contents

OSV-Scanner is offered as a GitHub Action. We currently have two different GitHub Actions:

  1. An action that triggers a scan with each pull request and will only report new vulnerabilities introduced through the pull request.
  2. An action that performs a full vulnerability scan, which can be configured to scan on a regular schedule. The full vulnerability scan can also be configured to run on release to prevent releasing with known vulnerabilities in dependencies.

Scan on pull request

Scanning your project on each pull request can help you keep vulnerabilities out of your project. This GitHub Action compares a vulnerability scan of the target branch to a vulnerability scan of the feature branch, and will fail if there are new vulnerabilities introduced through the feature branch. You may choose to prevent merging if new vulnerabilities are introduced, but by default the check will only warn users.

Instructions

In your project repository, create a new file .github/workflows/osv-scanner-pr.yml and include the following:

name: OSV-Scanner PR Scan

# Change "main" to your default branch if you use a different name, i.e. "master"
on:
  pull_request:
    branches: [main]
  merge_group:
    branches: [main]

permissions:
  # Require writing security events to upload SARIF file to security tab
  security-events: write
  # Only need to read contents
  contents: read

jobs:
  scan-pr:
    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@v1.5.0"

View results

Results may be viewed by clicking on the details of the failed action, either from your project’s actions tab or directly on the PR. Results are also included in GitHub annotations on the “Files changed” tab for the PR.

Scheduled scans

Regularly scanning your project for vulnerabilities can alert you to new vulnerabilities in your dependency tree. This GitHub Action will scan your project on a set schedule and report all known vulnerabilities. If vulnerabilities are found the action will return a failed status.

Instructions

In your project repository, create a new file .github/workflows/osv-scanner-scheduled.yml and include the following:

name: OSV-Scanner Scheduled Scan

on:
  schedule:
    - cron: "30 12 * * 1"
  # Change "main" to your default branch if you use a different name, i.e. "master"
  push:
    branches: [main]

permissions:
  # Require writing security events to upload SARIF file to security tab
  security-events: write
  # Only need to read contents
  contents: read

jobs:
  scan-scheduled:
    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@v1.5.0"

As written, the scanner will run on 12:30 pm UTC every Monday, and also on every push to the main branch. You can change the schedule by following the instructions here.

View results

Maintainers can review results of the scan by navigating to their project’s security > code scanning tab. Vulnerability details can also be viewed by clicking on the details of the failed action.

Scan on release

Here is a example of blocking on release, though the actual implementation will heavily depend on your specific release process.

name: Go Release Process

on:
  push:
    tags:
      - "*" # triggers only if push new tag version, like `0.8.4` or else

permissions:
  contents: read # to fetch code (actions/checkout)

jobs:
  osv-scan:
    uses: google/osv-scanner/.github/workflows/osv-scanner-reusable.yml
    with:
      # Only scan the top level go.mod file without recursively scanning directories since
      # this is pipeline is about releasing the go module and binary
      scan-args: |-
        --skip-git
        ./
    permissions:
      # Require writing security events to upload SARIF file to security tab
      security-events: write
  tests:
    name: Run unit tests
    ...
  release:
    needs: # Needs both tests and osv-scan to pass
      - tests
      - osv-scan
    # Your actual release steps
    steps:
      ...

View results

Results may be viewed by clicking on the details of the failed release action from the action tab.

Customization

The GitHub Actions have the following optional inputs:

  • scan-args: This value is passed to osv-scanner CLI after being split by each line. See the usage page for the available options. The --format and --output flags are already set by the reusable workflow and should not be overridden here. Default: 
      --recursive # Recursively scan subdirectories
  --skip-git=true # Skip commit scanning to focus on dependencies
  ./ # Start the scan from the root of the repository
  • results-file-name: This is the name of the final SARIF file uploaded to Github. Default: results.sarif
  • download-artifact: Optional artifact to download for scanning. Can be used if you need to do some preprocessing to prepare the lockfiles for scanning. If the file names in the artifact are not standard lockfile names, make sure to add custom scan-args to specify the lockfile type and path (see specify lockfiles).
  • upload-sarif: Whether to upload the results to Security > Code Scanning. Defaults to true.
Examples

Scan specific lockfiles 

jobs:
  scan-pr:
    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@v1.5.0"
    with:
      scan-args: |-
        --lockfile=./path/to/lockfile1
        --lockfile=requirements.txt:./path/to/python-lockfile2.txt

Default arguments 

jobs:
  scan-pr:
    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@v1.5.0"
    with:
      scan-args: |-
        --recursive
        --skip-git=true
        ./

Using download-artifact input to support preprocessing 

jobs:
  extract-deps:
    name: Extract Dependencies
    # ...
    steps:
      # ... Steps to extract your dependencies
      - name: "upload osv-scanner deps" # Upload the deps
        uses: actions/upload-artifact@v4
        with:
          name: converted-OSV-Scanner-deps
          path: osv-scanner-deps.json
          retention-days: 2
  vuln-scan:
    name: Vulnerability scanning
    # makes sure the extraction step is completed before running the scanner
    needs: extract-deps
    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@v1.5.0"
    with:
      # Download the artifact uploaded in extract-deps step
      download-artifact: converted-OSV-Scanner-deps
      # Scan only the file inside the uploaded artifact
      scan-args: |-
        --lockfile=osv-scanner:osv-scanner-deps.json
    permissions:
      # Needed to upload the SARIF results to code-scanning dashboard.
      security-events: write
      contents: read