advanced-security/probot-security-alerts

Sample GitHub App which monitors and enforces rules for code scanning, Dependabot, and secret scanning alerts

Probot Security Alert Watcher

This repository contains a sample GitHub App built with Probot that demonstrates how to monitor and respond to security alert events. The application automatically re-opens any security alert which is closed by someone that is not part of a specific team. It responds to alerts from code scanning, secret scanning, and Dependabot.

Requirements

The repository contains a development container that supports Visual Studio Code or GitHub Codespaces. This container includes all of the required dependencies. The application is written in TypeScript and runs on Node.js 18. To develop the project without a development container, Node.js 18 must be installed. Running npm install will configure the other dependencies.

The application expects a team called scan-managers to exist in your organization. This team contains the users that are approved to close code scanning alerts. If the team does not exist, all requests will be rejected. Alerts closed by users that are not part of this team will be automatically reopened. The name can be changed by configuring the environment variable SECURITY_ALERT_CLOSE_TEAM.

License

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

Maintainers

The current project maintainers can be found in CODEOWNERS.

Setup and Local Development

The application will automatically create a .env as part of its setup process, but will register the App to the current user's GitHub account by default. To configure the registration to use an organization, create an initial .env file which contains the following line:

GH_ORG=your-org-name

This will ensure that your application is properly configured and registered with that organization.

To setup and configure the project, run the following commands:

# Install dependencies (if not using dev container)
npm install

# Run the application
npm start

When running inside of a dev container or Codespaces, npm install will be automatically run.

The start command starts a background process that monitors changes to the TypeScript source files. Nodemon is used to automatically restart the Node.js application when the TypeScript-generated files in dist are changed.

Open http://localhost:3000 and click Register GitHub App. This will guide you through the process of registering and configuring the application. You will need to select the repository (or repositories) you want to use with the application as part of the setup process. When the workflow is completed, the .env file will be updated to match the configuration.

GitHub Codespaces

When using Codespaces, the environment will use a private port (3000) for the app and smee.io as a proxy for public visibility. If you do not want to use SMEE, the Codespaces port will need public visibility to be reachable. There is a feature request to add support for specifying port visibility in devcontainer.json.

To configure visibility manually:

1. Ensure the Probot application has been started using npm run and that it has started listening on port 3000.
2. Open the Command Pallette using Shift + Command + P (Mac) / Ctrl + Shift + P (Windows/Linux)
3. Choose Ports: Focus on Ports View
4. Right click the line that contains the port Probot (3000)
5. Select Port Visibility and change the value to Public

Using a proxy

The GitHub App will automatically create an use an endpoint on smee.io as a proxy if the environment variable NODE_ENV is not set to production. It will create a new endpoint and add it to the .env file automatically. To manually configure the App to use Smee.io as a proxy for a private port or local development environment:

1. Go to https://smee.io/new. Copy the provided webhook URL.
2. Create (or update) a .env file. An example file (.env.example) is provided.
3. Add a line with WEBHOOK_PROXY_URL= and the URL from Step 1. For example, `WEBHOOK_PROXY_URL=https://smee.io/ABCDEF

The environment (.env) file

This file .env contains the environment settings used by the Probot application. A sample file is provided (.env.sample). The first time the application is run, the file will be created. Once the GitHub App is registered, the file will be updated with the security settings required for creating tokens. Typically, there are only two settings that may need to be configured initially:

• GH_ORG - Configure the application to register with an organization rather than the current user, specify the organization name
• WEBHOOK_PROXY_URL - Configure a proxy server that will receive all webhook messages. If not provided, this will be created automatically in non-production environments.

First launch

The first time the application is run, it will open a port (typically https://localhost:3000) and listen for incoming messages. Opening this page in the browser will start a process of configuring and registering the GitHub App. This process is called the Manifest Flow. The configuration settings in the app.yml file are used to register the application, associate it with a public webhook URL, and secure the communications. Once this process completes, the .env file will be updated based on that registration. The web page will then be changed to disable the registration process.

Removing the .env settings for the application will re-enable the process.

Known Issues

This sample application has the following known issues.

ECONN Error

When running in a development container (Visual Studio Code), the Docker environment can occasionally stop correctly proxying messages. When this occurs:

• The GitHub App and Smee.io will both report that payloads were delivered. The application will not show any activity.
• The Node.js application may occasionally log an error beginning with ECONN.

If this occurs, restart Docker Desktop. Visual Studio code can reload the window once Docker Desktop has restarted, and npm start can be used to restart the application. The connectivity issues should be resolved.

Probot Support

This sample is built using Probot and the framework it provides. The latest version of Probot does not yet fully support the new dependabot alerts.

GitHub manifest flow

The manifest flow does not currently support Dependabot alerts. The events will need to be manually selected.

Container build

A standalone image can be built using docker build. The image uses a minimal distribution, running Node.js on Alpine. It supports all Alpine-supported architectures. The image is configured to expose port 3000. For additional security, the node_modules folder is placed above the working directory with the app. When the directory is missing in the application folder, Node.js will automatically search the parent folder. This prevents the modules and their binaries from being exposed by the web service. The application is installed in /opt/probot/app, configurable at build time with the build argument APP_ROOT.

For testing and deploying outside of development environments, the GitHub App will need to be created manually. The currently required permissions and events can be found in the app.yml file.

The following environment variables need to be configured and provided to the container:

Variable	Value
NODE_ENV	production. This is preconfigured in the image.
APP_ID	The identifier for the registered app. This can be found in the App's General > About.
GH_ORG	The name of the owning GitHub organization.
PRIVATE_KEY	The text from the private key file. This can be created in General > Private keys > Generate a private key
PRIVATE_KEY_PATH	Path to the private key if it is stored on the file system or provided as a secret volume
WEBHOOK_SECRET	The GitHub App's webhook secret. A value should always be provided in General > Webhook > Webhook secret
GITHUB_CLIENT_ID	The App Client ID. This can be found in the App's General > About.
GITHUB_CLIENT_SECRET	A client secret. This can be found in the App's General > Client Secrets > Generate a new client secret
SECURITY_ALERT_CLOSE_TEAM	The name of a custom approving team if the default is not used

Note For production environments, ensure that secrets, IDs, and private keys are stored and provided securely.

Additional environment variables can be found in the Probot documentation.

Using GitHub Security Managers

It is possible to configure the approving team as a child of the team assigned to the Security Managers role. You can follow these steps to create a child team. Because this team is a child of the previous team, it is included in the Security Managers. All members of this child team will be Security Managers and able to review alerts in all repositories.

Note
The Security Managers for an organization automatically have read access to all repositories. This permission is not removed if the team is removed from the Security Managers.

probot-security-alerts's Issues

Improve standalone server support

To make it easier to use, make the server package available from Releases:

• Separate server code
• Automate creating ZIP package
• Release file: server ZIP package (requires workflow)
• Add documentation to /docs for using the image

Possible future enhancement:

• Single executable application

Bug: push protection bypass alerts are not reopened

When a user who's NOT on the SECURITY_ALERT_CLOSE_TEAM bypasses push protection for a reason that results in a closed alert, the alert is not reopened by the app.

Create Dev Container image

Build the image for amd64 and arm64 to improve dev container start times in Codespaces and with local dev containers

Issue with docker file when its running on ecs

these the docker file # syntax=docker/dockerfile:1.4

ARG NODE_VERSION=18
ARG ALPINE_VERSION=3.17

FROM node:${NODE_VERSION}-alpine${ALPINE_VERSION} as build
WORKDIR /app
COPY --link . .
RUN --mount=type=cache,target=/usr/local/share/npm-global
npm install --location=global npm@latest
&& npm ci
&& npm run build
&& npm run test

FROM node:${NODE_VERSION}-alpine${ALPINE_VERSION}
ARG APP_ROOT=/opt/probot

ENV NODE_ENV=production
ENV APP_ID=866979
ENV PRIVATE_KEY="${PRIVATE_KEY}"
ENV WEBHOOK_SECRET="${WEBHOOK_SECRET}"

WORKDIR ${APP_ROOT}
COPY --link package.json package-lock.json ./
RUN --mount=type=cache,target=/usr/local/share/npm-global
npm i --location=global npm@latest
&& npm ci --omit=dev \
&& npm cache clean --force
WORKDIR ${APP_ROOT}/app
COPY --link --from=build /app/dist/ .
EXPOSE 3000
ENTRYPOINT ["node", "main.js"]
when i'm running docker image on ECS these error
"Error: Certificate is missing, and is required to run in production mode. To resolve, ensure either the PRIVATE_KEY or PRIVATE_KEY_PATH environment variable is set and contains a valid certificate

Improve Azure Functions support

To make it easier for users to deploy the sample on Azure Functions, we need the following features:

• Separate code for the Function handler
• Automate Functions build
• Implement Feature for Dev Container with required tools
• Bicep file for deploying Function on Azure Container Apps with Key Vault
• Release image: Container image (requires workflow)
• Bicep file for deploying on Azure Functions with Key Vault
• Release image: Functions ZIP package (requires workflow)
• Add documentation for deploying to /docs folder

Stretch goals:

• Add integration tests
• Bicep files committed with built ARM templates
• Azure UI implemented to prompt user for deployment variables (APP_ID, etc.)
• "Deploy to Azure" link configuration for deploying the ARM file to Azure

Improve AWS Lamda support

To make it easier for users to deploy the sample on AWS Lambda, we need the following features:

• Separate code for the Lambda handler
• Automate Lambda build using SAM
• Implement Feature for Dev Container with required tools
• Integrate Secrets Manager
• Release image: Container image (requires workflow)
• Release file: Cloud formation template for container
• Release file: ZIP package (requires workflow)
• Release file: Cloud formation template for package
• Add documentation for deploying to /docs folder

Stretch goals:

• Add integration tests

Feature request: add a severity threshold to the .env file

Context

Many organizations' security teams are outnumbered by developers, sometimes as drastically as a 1:100 ratio. Also, different organizations have different risk appetites when it comes to dismissing security alerts (e.g. focus security review on critical & high severity alerts, over medium & low severity alerts). This makes it undesirable to review the dismissal of every alert as opposed to just those that surpass a given severity threshold.

Suggestion

Allow for an optional parameter in the .env file to specify the severity threshold that requires scan-manager dismissal. For example:
SEVERITY_THRESHOLD=high would reopen only those alerts dismissed by someone other than a scan-manager that have a severity of high or critical. Not specifying a SEVERITY_THRESHOLD would reopen alerts of any severity.

cc @kenmuse

Improve Container deployments

To make it easier to use, make the container image available from ghcr.io:

• Separate server code
• Update Dockerfile for new deployment
• Automate creating Dockerfile
• Release image: Container (requires workflow)
• Add documentation to /docs for using the image