Connecting GitHub Code Scanning Alerts to Slack

TLDR: Right now, code_scanning_alerts are not supported by GitHub Actions events. This means we cannot use GitHub Actions for this use case. Once code_scanning_alerts are supported, a GitHub Action will be created for teams who do not want to deploy a custom solution.

Overview

A solution that enables organizations to filter GitHub Code Scanning alerts into Slack channels. Specifically whenever an alert has been:

• Created
• Fixed
• Manually Closed by a User

The solution has been designed to be configurable to the end-users preferences when it comes to being notified. Code Scanning can be noisy, so the solution ensures you can configure when you get notified.

This solution is deployed to AWS.

How this works

Whenever a new code scanning alert is: created, fixed or closed_by_user, a webhook from a GitHub App will be sent to an API Gateway within AWS. The API's first step is passing the context of the payload to a Lambda Authorizer, ensuring the Webhook has come from GitHub. If valid, the API will pass the event payload (from the webhook) to a Lambda for processing. The first step this Lambda does is validate the GitHub Secret is correct. If valid, the Lambda will destructure the payload, find the event type (created, fixed or closed_by_user) and, based on the event, send a specific message to a Slack App Incoming Webhook URL. The Slack App will then forward the message to the specific channels configured on the Slack App.

At any point, if the webhook IP or secret sent do not match or are not valid, an unauthorized response will be sent to the client.

Technologies Used

The following technologies are used throughout this solution:

• AWS
  • Lambda is used for compute power.
  • Cloud Formation is used as our IaC (Infrastructure as Code).
  • HTTP API Gateway is used for ingress into AWS.
  • Cloud Watch is used for logging and monitoring.
  • IAM is used to connect resources and allow deployments into AWS from GitHub Actions
  • S3 is used by AWS SAM to deploy the stack, and therefore deploy it into the AWS ecosystem using Cloud Formation.
  • AWS Systems Manager Parameter Store is used to store parameters.
• Slack
  • Slack App is used as our ingress method into Slack.
• GitHub
  • GitHub App is used as our egress method out of GitHub.
  • GitHub Actions is used to deploy the solution into AWS.

AWS SAM is used for the Lambda & HTTP API Gateway resources.

Note: Even though this solution is deployed to AWS, the code can be changed to work with the likes of Azure and GCP (Azure Function, Google Functions, etc.).

Architecture

https://i.ibb.co/MnJ60KZ/Example.png

Pre-Req's

1. Access to an AWS environment.
2. Access to a Slack environment.
3. Access to a GitHub environment.
4. A repository where the code for this solution is going to live.

Getting Started

The below steps show the path of least resistance way of deploying this solution into AWS. There are many ways to do this. Every organization likely has different processes (especially with deploying into AWS), meaning you may have to pivot during these steps to accommodate organization-specific processes. This is okay. Please treat these instructions as an example and reference; if they work end-to-end, great; if not, please adjust to your company policies.

If you get an error you cannot get around, please log an issue on this repository.

Step One: Create IAM User

Create an IAM User. The IAM User will need to have the capability to do the following:

• CRUD access over S3 Resources.
• CRUD access over IAM Resources.
• CRUD access over API Gateway Resources.
• CRUD acess over Lambda Resources.
• CRUD access over CloudWatch Resources.

From that user, create an AWS Access key and secret. Once you have both, create a GitHub Enviroment called main and within that environment create two secrets AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY with the relevant information from AWS in. Set the environment to only deploy from the main branch. (This can be changed later at any time).

NOTE: If your organization doesn't allow the use of IAM Users, this isn't a problem. We use the official configure-aws-credentials GitHub action. Meaning you can head to the .github/workflows/deploy.yaml file and swap out the AWS User method to assuming an AWS Role. Or, if you have a custom GitHub Action which authenticates into AWS, remove the configure-AWS-credentials action and swap it out for your custom one.

Step Two: Create and Configure Slack App

Create a Slack Application. You will need to be an administrator of your Slack organization to do this. When you create the Slack application, add the channel(s) you would like the Code Scanning results to be posted to.

Instructions on doing this can be found here: Webhooks: Getting Started.

You should end up with a URL that looks like this: https://hooks.slack.com/services/******/******/****** (I have redacted the values for ***).

NOTE: Don't share this URL with anyone; keep it private.

Step Three: Create and Configure GitHub App

Create a GitHub Application. You will need to be an administrator of your GitHub organization to do this. During the creation of the application, you only need to enter:

1. GitHub App Name: GitHub Code Scanning Alerts to Slack
2. Homepage URL: https://donotknowthisurlyet.com
3. Webhook URL: https://donotknowthisurlyet.com
4. Webhook Secret: enter secret of your choice - keep this value secret but note it down for later
5. Permissions:
   • Security event
6. Subscribe to events:
   • Code scanning alert
7. Where can this integration be installed: Only on this account

The rest of the fields you do not need to enter. Right now, you don't know what the URL's are going to be, so put any value in there.

Once the application is created, you need to install the GitHub App on your organization and then add the repositories you want Code Scanning events to be sent to Slack. Follow the instructions here: Installing your private GitHub App on your repository.

NOTE: When you install the GitHub App on your GitHub Organisation, I would advise you do not have it connected to every repository. It will get very noisy. Only install it on the repositories you are interested in.

Once it's installed, we need to collect some information:

1. GitHub App Private Key. Follow the instructions here: Generating a private key to do that.
2. Client Secret: Just above where you generated the private key, there will be an option for you to generate a client secret. Click the Generate a new Client Secret button and note down the secret.
3. Client ID: Just above where you generated the client secret, you will see the Client ID; take a note of the id.
4. App ID: Just above where you generated the client secret, you will see the App ID; take a note of the id.
5. Installation ID: The Installation ID is in a different location; head to your Organizations GitHub App's page (https://github.com/organizations/${orgName}/settings/installations). Click Configure next to the GitHub App you created. If you look at the URL, at the end of the URL, you will see a number. It should be after the installations/ part of the URL. Copy down that number.

Step Four: Create Parameters within AWS Systems Manager (Parameter Store)

Log into AWS, head to AWS Systems Manager, then AWS Parameter Store. In total, you will need to create seven parameters.

1. /code scanning/APP_CLIENT_ID: The GitHub App Client ID you got from Step Three.
2. /code scanning/APP_CLIENT_SECRET: The GitHub App Client Secret you got from Step Three.
3. /code scanning/APP_ID: The GitHub App ID you got from Step Three.
4. /code scanning/APP_INSTALLATION_ID: The GitHub App Installation ID you got from Step Three.
5. /code scanning/APP_PRIVATE_KEY: The GitHub App Private Key you got from Step Three.
6. /code scanning/GITHUB_WEBHOOKS_SECRET: The GitHub App Private Key you got from Step Three. (The first part when you created the GitHub App)
7. /code scanning/SLACK_WEBHOOK_URL: The Slack Webhook URL you got at the end of Step Two.

NOTE: It is recommended you make the: /codescanning/APP_CLIENT_SECRET, /codescanning/APP_PRIVATE_KEY, /codescanning/GITHUB_WEBHOOKS_SECRET and /codescanning/SLACK_WEBHOOK_URL values SecureString within Parameter Store. The rest can be simply String types.

Step five: Deployment into AWS

Second to last step! Before we do this, let's check