GHAS Reviewer App

Overview

GitHub Advanced Security (GHAS) Reviewer App allows security teams to enforces a reviewer to approve and dismiss alerts. This allows security experts to provide 4-eyes principle over all security alerts generated in GitHub.

Caution

The public GitHub App will be sent security data and is only used for testing purposes. It is recommended to deploy your own instance of the app for production use.

Public GitHub App

✨ Features

• Re-open closed alerts if an unapproved users changes the alert
• Notifies Security Team for vulneraiblities found in PR and assigns them as reviewers. Requires security team to be repository collaborators.
• GitHub Advanced Security Features
  • Code Scanning alerts
  • Secret Scanning alerts
  • Dependabot alerts

⚡️ Requirements

• Python +3.9
• GitHub Application Setup
  • Permissions
• [optional] Docker / Docker Compose

Usage

GHAS Reviewer is a Python based web application which primarily uses Docker for easy deployment.

GitHub Application Configuration

Checkout how to setup a GitHub App here.

Store the App key so the service can read it from the path provided along with the other environment variables or cli arguments.

Environment Variable:

Create a .env file in the root of the project with the following environment variables.

# Application ID
GITHUB_APP_ID=123456
# Path to the App private key
GITHUB_APP_KEY_PATH=./config/key.pem
# or use the private key directly
GITHUB_APP_KEY=-----BEGIN PRIVATE KEY-----\n...
# Webhook Secret
GITHUB_APP_SECRET=123456789012345678901234567890
GITHUB_APP_ENDPOINT=/
GITHUB_GHAS_TEAM="sec_team"

You can also use the following CLI arguments to pass the configuration.

If you choose to pass the private key via a file just store the key in a file and pass the path to the file. In our case, we store the key in ./config/key.pem. You will later mount this file into the container.

Permissions

The GitHub App requires the following permissions:

• Repository

  • Code scanning alerts: Read & Write
  • Dependabot alerts: Read & Write
  • Secrets scanning alerts: Read & Write
  • Issues: Read & Write
  • Pull requests: Read & Write

• Webhook events

  • Code scanning alerts
  • Dependabot alerts
  • Secret scanning alerts

Container / Docker

The application is designed to be run in a container, this allows for easy deployment and scaling.

Pull / Download image:

# Pull latest (or a release)
docker pull ghcr.io/advanced-security/ghas-reviewer-app:main

Or Build From Source:

docker build -t advanced-security/ghas-reviewer-app .

or build locally

docker build -t advanced-security/ghas-reviewer-app .

Run Docker Image:

docker run \
    --env-file=.env \
    -v ./config:/ghasreview/config \
    -p 9000:9000 \
    ghcr.io/advanced-security/ghas-reviewer-app:main

or run it locally

docker run \
    --env-file=.env \
    -v ./config:/ghasreview/config \
    -p 9000:9000 \
    advanced-security/ghas-reviewer-app

**Run

Docker Compose

If you are testing the GitHub App you can quickly use Docker Compose to spin-up the container.

docker-compose build
docker-compose up -d

Local Development

If you want to run the application locally you can use the following the same steps as abouve meaning you need to creeate an GitHub App, store the private key and set the environment variables.

After you have set the environment variables you can run the application using the following commands.

# We are using Pipenv for dependency management
pip install pipenv

# Install dependencies
pipenv install --dev

# Run the application
pipenv run develop

Limitations

• Pull Request require team approval. The security team needs to be repository collaborator.

Maintainers / Contributors

• @GeekMasher - Author / Core Maintainer
• @theztefan - Contributor

Support

Please create GitHub Issues if there are bugs or feature requests.

This project uses Sematic Versioning (v2) and with major releases, breaking changes will occur.

License

This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.