octovy

README

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

License

Octovy is licensed under the Apache License 2.0. Copyright 2023 Masayoshi Mizutani mizutani@hey.com