Octovy

A standalone Trivy-to-BigQuery export tool

Overview

Trivy is a powerful open-source vulnerability scanner and SBOM generator. Octovy exports Trivy scan results to BigQuery, enabling you to build a centralized SBOM and vulnerability repository for your entire organization—a comprehensive inventory of all dependencies, versions, and known vulnerabilities across repositories, searchable via SQL.

It provides three core functions:

• Insert existing Trivy results (insert): Import Trivy JSON output files into BigQuery
• Scan and insert (scan): Run Trivy on a local directory and insert results into BigQuery
• GitHub App webhook server (serve): Scan repositories automatically on push and pull_request events

These functions can be used with GitHub Actions or deployed as a GitHub App. Storing results in BigQuery enables organization-wide vulnerability management:

• Measure vulnerability exposure: Query how many packages with known vulnerabilities exist across all repositories in your organization
• Rapid incident response: When a critical vulnerability is announced, search for affected packages by name or version across your organization immediately—before vulnerability databases or scanners are updated
• Continuous monitoring: Set up scheduled queries to check for specific critical vulnerabilities periodically

Prerequisites

Before using Octovy, you need to set up BigQuery and configure Google Cloud authentication.

1. Create BigQuery Dataset

bq mk --dataset your-project-id:octovy

2. Configure Authentication

gcloud auth application-default login

For detailed setup instructions (service accounts, IAM permissions, etc.), see BigQuery Setup Guide.

Commands

scan - Scan and Insert

Scans repositories with Trivy and inserts results into BigQuery. Has two subcommands:

scan local - Scan Local Directory

Scans a local directory. Auto-detects git metadata (owner, repo, commit) from the local repository.

# Scan current directory
octovy scan local --bigquery-project-id your-project-id

# Scan specific directory
octovy scan local --dir /path/to/code --bigquery-project-id your-project-id

# With explicit metadata
octovy scan local \
  --bigquery-project-id your-project-id \
  --github-owner myorg \
  --github-repo myrepo \
  --github-commit-id abc123

scan remote - Scan GitHub Repository

Scans a GitHub repository remotely via GitHub App API. Requires GitHub App configuration.

# Scan a specific repository
octovy scan remote \
  --bigquery-project-id your-project-id \
  --github-owner myorg \
  --github-repo myrepo \
  --github-app-id 12345 \
  --github-app-private-key "$(cat private-key.pem)"

# Scan all repositories for an organization
octovy scan remote \
  --bigquery-project-id your-project-id \
  --github-owner myorg \
  --all \
  --github-app-id 12345 \
  --github-app-private-key "$(cat private-key.pem)"

Full documentation →

insert - Insert Existing Results

Inserts Trivy scan result JSON files into BigQuery. Useful when you already have Trivy workflows or want to decouple scanning from insertion.

# Generate Trivy result and insert
trivy fs --format json --output results.json .
octovy insert -f results.json --bigquery-project-id your-project-id

# Insert with explicit metadata
octovy insert -f results.json \
  --bigquery-project-id your-project-id \
  --github-owner myorg \
  --github-repo myrepo

Full documentation →

serve - GitHub App Server

Runs an HTTP server that receives GitHub webhooks and automatically scans repositories on push and pull_request events.

octovy serve \
  --addr :8080 \
  --bigquery-project-id your-project-id \
  --github-app-id 12345 \
  --github-app-private-key "$(cat private-key.pem)" \
  --github-app-secret your-webhook-secret

Full documentation →

BigQuery Queries

Once scan results are in BigQuery, you can run powerful queries for vulnerability management.

Find All Critical Vulnerabilities

SELECT
  github.owner,
  github.repo_name,
  github.commit_id,
  vuln.VulnerabilityID,
  vuln.PkgName,
  vuln.InstalledVersion,
  vuln.Severity
FROM `your-project.octovy.scans`
CROSS JOIN UNNEST(report.Results) AS result
CROSS JOIN UNNEST(result.Vulnerabilities) AS vuln
WHERE vuln.Severity = 'CRITICAL'
ORDER BY timestamp DESC

Search for a Specific Package (e.g., Log4j)

When a critical vulnerability like Log4Shell is announced, immediately find all affected repositories:

SELECT DISTINCT
  github.owner,
  github.repo_name,
  pkg.Name,
  pkg.Version
FROM `your-project.octovy.scans`
CROSS JOIN UNNEST(report.Results) AS result
CROSS JOIN UNNEST(result.Packages) AS pkg
WHERE LOWER(pkg.Name) LIKE '%log4j%'
ORDER BY github.owner, github.repo_name

For more query examples and detailed schema documentation, see BigQuery Schema Reference.

Setup Guides

Required Setup

• BigQuery Setup - Required for all commands

Optional Setup

• GitHub App Setup - Required for serve and scan remote commands
• Firestore Setup - Optional for real-time metadata tracking

Documentation

See docs/README.md for:

• Detailed command documentation
• Setup guides for all services
• Common workflows and examples
• Troubleshooting guides
• FAQ

License

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