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

m-mizutani/octovy