Vulnivore

Vulnivore is GitHub issue creator from vulnerability scan results for private repositories.

Vulnivore is a vulnerability management tool designed specifically for GitHub private repositories. It has the ability to convert security scan results into GitHub issues. Vulnivore supports SARIF format and Trivy json output format. This tool is particularly beneficial for those who wish to manage vulnerabilities within private repositories without the need for GitHub Advanced Security.

Key Features

Ability to customize the issue body template
Prevents duplication of issues
Offers a customizable policy in Rego for the creation of issues, labels, and assignees

Quick Start Guide

Warning

This quick start guide is intended for trial purposes only. It is not recommended for use in a production environment. For production use, please refer to the Configuring your GitHub App section.

1. Installing the GitHub App

Navigate to the GitHub App page and click on the "Configure" button.
Select the organization or user account you wish to install the app on.
Choose the repositories for installation and click on the "Install" button.
You'll be redirected to a configuration page with a URL similar to https://github.com/settings/installations/XXXX. Copy the XXXX part of the URL, which is your INSTALLATION_ID.

2. Adding the GitHub Actions Workflow

Add a .github/workflows/vulnivore.yml file to your repository. This step assumes your repository contains a Dockerfile to build an image.

name: Build and Scan

on:
  push:
    branch:
      main

env:
  TAG_NAME: your-repo-name:${{ github.sha }}

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write # Need to authenticate for vulnivore
    steps:
      - name: checkout
        uses: actions/checkout@v4
      - name: Set up Docker buildx
        uses: docker/setup-buildx-action@v2
      - name: Build Docker image
        run: docker build . -t ${{ env.TAG_NAME }}
      - name: Run Trivy
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: "image"
          image-ref: ${{ env.TAG_NAME }}
          format: "json"
          output: "trivy-results.json"

      - name: Upload Trivy results to Vulnivore
        uses: m-mizutani/vulnivore-upload@main
        with:
          filepath: trivy-results.json
          url: https://vulnivore-j47o6xodla-an.a.run.app/webhook/github/action/trivy
          installation_id: "XXXX" # Put your INSTALLATION_ID

After a successful vulnerability detection, you can locate the identified issues within the 'Issues' section of your GitHub repository.

Configuration your GitHub App

1. Creating a GitHub App

To create a GitHub App, follow these steps:

Visit the GitHub App page and click on the "New GitHub App" button.
Enter the necessary information into the required fields. This includes the GitHub App name and Homepage URL.
Adjust the permissions for "Issue" to "Read & Write" and then click on the "Create GitHub App" button.

Once the GitHub App is created, make sure to note down the following information:

The GitHub App ID (For example, it could be something like 123456)
The private key. This can be generated by clicking on the "Generate a private key" button. Once generated, it will be automatically downloaded.

2. Deploying Vulnivore

Vulnivore, which operates as an HTTP server, needs to be deployed and made accessible from GitHub. You can either deploy it in your own environment or use a service like Google Cloud Run.

For an example on how to deploy Vulnivore on Google Cloud Run, you can refer to this sample repository: vulnivore-deploy.

During deployment, you'll need to set the following environment variables:

Environment Variables Required

VULNIVORE_ADDR: This is the address where Vulnivore listens. Example: 0.0.0.0:8192.
VULNIVORE_GITHUB_APP_ID: This is the ID of the GitHub App you created. Example: 417839.
VULNIVORE_GITHUB_APP_INSTALLATION_ID: This is the default installation ID of your GitHub App. Example: 43608677.
VULNIVORE_FIRESTORE_PROJECT_ID: This is the ID of your Google Cloud Project.
VULNIVORE_FIRESTORE_COLLECTION: This is the name of your Firestore collection. Example: vulnivore.

Optional Environment Variables

VULNIVORE_POLICY_DIR: This variable specifies the policy directory. Vulnivore will import all *.rego files from this directory. For more information, refer to the Policy in Rego section.
VULNIVORE_LOG_FORMAT: This variable specifies the log format. The default format is json, but you can also set it to text for a more human-readable log format.

Command

For the deployed app, you need to specify the serve subcommand, as shown in this example.

3. Configuring GitHub Actions

To configure GitHub Actions, you'll need to add a workflow file to your repository. This file will be used to build your Docker image and scan it for vulnerabilities. Once the scan is complete, the results will be uploaded to Vulnivore.

GitHub Actions can be configured by adding a .github/workflows/vulnivore.yml file to your repository. Action configuration is same with one described in the Quick Start Guide section.

Policy in Rego

Input

The input data, often referred to as input in Rego, varies depending on the format of the received data. Here are some examples:

Trivy:
- Metadata: This refers to the .Metadata field in the Trivy JSON output.
- Result: This refers to inspecting one of the results in the .Results field in the Trivy JSON output.
- Vuln: This refers to inspecting one of the vulnerabilities in the .Results[].Vulnerabilities field in the Trivy JSON output.
SARIF:
- Report: This refers to the entire SARIF data set.
- Run: This refers to inspecting one of the runs in the .runs field in the SARIF data.
- Result: This refers to inspecting one of the results in the .runs[].results field in the SARIF data.
- Location: This refers to inspecting one of the locations in the .runs[].results[].locations field in the SARIF data.

Output

The output schema is standardized across all input formats. Here's what it includes:

action (string): This field indicates the action to be taken. It can be either create or ignore. If set to create, an issue will be created. If set to ignore, no action will be taken. By default, this field is set to create.
labels (set of string): This field allows you to set labels for the issue. By default, no labels are set and this field is empty.
assignees (set of string): This field allows you to assign the issue to specific individuals. By default, no individual is assigned and this field is empty.

License

Apache License 2.0

m-mizutani / vulnivore