Octovy

Octovy is a GitHub App that scans your repository's code for potentially vulnerable dependencies. It utilizes trivy to detect software vulnerabilities. When triggered by events like push and pull_request from GitHub, Octovy scans the repository for dependency vulnerabilities and performs the following actions:

Adds a comment to the pull request, summarizing the vulnerabilities found
Inserts the scan results into BigQuery

Octovy adds a comment to the pull request when it detects new vulnerabilities between the head of the PR and the merge destination.

Setup

1. Creating a GitHub App

Start by creating a GitHub App here. You can use any name and description you like. However, ensure you set the following configurations:

General
- Webhook URL: https://<your domain>/webhook/github
- Webhook secret: A string of your choosing (e.g. mysecret_XOIJPOIFEA)
Permissions & events
- Repository Permissions
  - Checks: Set to Read & Write
  - Contents: Set to Read-only
  - Metadata: Set to Read-only
  - Pull Requests: Set to Read & Write
- Subscribe to events
  - Pull request
  - Push

Once you have completed the setup, make sure to take note of the following information from the General section for future reference:

App ID (e.g. 123456)
Private Key: Click Generate a private key and download the key file (e.g. your-app-name.2023-08-14.private-key.pem)

2. Setting Up Cloud Resources

Cloud Storage: Create a Cloud Storage bucket dedicated to storing the scan results exclusively for Octovy's use.
BigQuery (Optional): Create a BigQuery dataset and table for storing the scan results. Octovy will automatically update the schema. The default table name should be scans.

3. Deploying Octovy

The recommended method of deploying Octovy is via a container image, available at ghcr.io/m-mizutani/octovy. This image is built using GitHub Actions and published to the GitHub Container Registry.

To run Octovy, set the following environment variables:

Required Environment Variables

OCTOVY_ADDR: The address to bind the server to (e.g. :8080)
OCTOVY_GITHUB_APP_ID: The GitHub App ID
OCTOVY_GITHUB_APP_PRIVATE_KEY: The path to the private key file
OCTOVY_GITHUB_APP_SECRET: The secret string used to verify the webhook request from GitHub
OCTOVY_CLOUD_STORAGE_BUCKET: The name of the Cloud Storage bucket

Optional Environment Variables

OCTOVY_TRIVY_PATH: The path to the trivy binary. If you uses the our container image, you don't need to set this variable.
OCTOVY_CLOUD_STORAGE_PREFIX: The prefix for the Cloud Storage object
OCTOVY_BIGQUERY_PROJECT_ID: The name of the BigQuery dataset
OCTOVY_BIGQUERY_DATASET_ID: The name of the BigQuery table
OCTOVY_BIGQUERY_TABLE_ID: The name of the BigQuery table
OCTOVY_BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT: The service account to impersonate when accessing BigQuery
OCTOVY_SENTRY_DSN: The DSN for Sentry
OCTOVY_SENTRY_ENV: The environment for Sentry

Configuration

Ignore list

The developer can ignore specific vulnerabilities by adding them to the ignore list. The config file is written in CUE. See CUE definition in pkg/domain/model/schema/ignore.cue.

The config file should be placed in .octovy directory at the root of the repository. Octovy checks all files in the .octovy directory recursively and loads them. (e.g. .octovy/ignore.cue)

The following is an example of the ignore list configuration:

package octovy

IgnoreList: [
  {
    Target: "Gemfile.lock"
    Vulns: [
      {
        ID:        "CVE-2020-8130"
        ExpiresAt: "2024-08-01T00:00:00Z"
        Comment:   "This is not used"
      },
    ]
  },
]

package name should be octovy. IgnoreList is a list of Ignore struct.

Target is the file path to ignore. That should be matched Target of trivy
Vulns is a list of IgnoreVuln struct.
- ID (required): the vulnerability ID to ignore. (e.g. CVE-2022-2202)
- ExpiresAt (required): The expiration date of the ignore. It should be in RFC3339 format. (e.g. 2023-08-01T00:00:00). The date must be in 90 days and if it's over 90 days, Octovy will ignore it.
- Comment (optional): The developer's comment

m-mizutani/octovy