Github Bot

Suggest Edits

Monitor, alert, and discover sensitive data in your code for each commit. Get instant feedback on any commit you push to your repository. Spectral Bot can be installed directly on organizations and user accounts and grant access to specific repositories.

Setup Github App

First you will need to create a new GitHub app.

  • If you are installing on an organization account use this link.
  • If you are installing on your personal GitHub account use this link.

You then have to choose between installing on

  • All repositories
    This applies to all current and future repositories owned by the resource owner.

  • Only select repositories

Confirm your choice and move on to deploy the bot. After the bot is deployed you will need to return to the GitHub app settings and complete the setup. See the "Complete the GitHub App Setup" section below for details.

Deploy the bot

Deploy using one of the following two methods:

With AWS Lambda

Next we'll deploy the lambda to your AWS account. These permissions are required: 

lambda:GetAccountSettings
cloudformation:DescribeStacks
iam:CreateRole
iam:DeleteRole
apigateway:POST
logs:CreateLogGroup
iam:PutRolePolicy

Go ahead and launch the stack

  • To fill in the PRIVATE_KEY field, you'll need to generate a private key in your new GitHub app's settings and encode it with base64 without linebreaks:openssl base64 -A -in your-private-key.pem

  • The options for the "Check Policy" field are

    • "Fail on any issue"
    • "Fail on critical only"
    • "Fail on high and above"
    • "Fail on medium and above"
    • "Fail on low and above"
    • "Always pass".

    This is for reference if you want to change it after deployment.

  • If STRICT_MODE is set to true the status check considers on all issues found in the modified files, even if the issues are old. Otherwise, only new issues will be counted for the status.

With Docker

Follow the deployment instructions on our DockerHub repo for the GitHub scanner.

Using vault

Instead of storing your secrets directly on the configuration of your Lambda, it is recommended for you to use a vault instead.

In order to use a vault, it is needed to set another environment variable called SECRETS_VAULT which contains the type of the vault you are using.

Available values:

  • AWS secrets manager - aws_secrets_manager

Currently, we are supporting AWS secret manager, but in the future we are planning to support more vaults.

In your vault, make sure you set the following 3 secrets in your vault:

  • Spectral_GithubBot_PrivateKey (for PRIVATE_KEY)
  • Spectral_GithubBot_WebhookSecret (for WEBHOOK_SECRET)
  • Spectral_Dsn (for SPECTRAL_DSN)

Overriding vault keys

To set up custom secret vault keys, use the following environment variables:

  • SPECTRAL_DSN_VAULT_KEY - Spectral DSN key name, should be in the format of Spectral_Dsn-*
  • WEBHOOK_SECRET_VAULT_KEY - GitHub app webhook secret, should be in the format of Spectral_GithubBot_WebhookSecret-*
  • PRIVATE_KEY_VAULT_KEY - Private key, should be in the format of Spectral_GithubBot_PrivateKey-*

AWS Secrets Manager

If you are deploying using CloudFormation, notice that the role created for the lambdas would give permission to perform secretsmanager:GetSecretValue action only for those 3 secrets.

Exclude repositories

To prevent the bot from scanning specific repositories you can supply the bot with the list of these "blacklisted" repo URLs.
To supply such list, you'll need to define two new environment variables:

  1. REPOS_BLACKLIST_BUCKET_NAME - the name of the bucket containing the blacklist file
  2. REPOS_BLACKLIST_OBJECT_KEY - the object key of the blacklist file

The blacklist file should be a text file containing a list of full URLs of repositories that has to be excluded (such as https://github.com/expressjs/express), with line breaks separating between them (each URL in a new line).

When the bot notices that the repo needed to be scanned is contained in the blacklist it would stop the execution and a check wouldn't be created.

If a problem occurs while fetching the blacklist, a failed check is created with an appropriate log in order to be able to know that a given push has not been scanned.

NOTE: Only single instance of the bot can be deployed to a region, if you wish to deploy several bot instances to the same region please contact customer support.

Complete the GitHub App Setup

After deployment is completed, go back to the GitHub app settings page.
In the Webhook section configure the Webhook URL, Webhook secret, and set the Webhook to active.

AWS Lambda

To build the webhook URL append /api/github/event to the ServiceEndpoint output from the stack:

https://<id>.execute-api.<region>.amazonaws.com/prod/api/github/event

Docker

To build the webhook URL append /events/github to the URL for your container:

https://<container-domain>/events/github

Save your changes to complete the process.

Monitoring

It is highly recommended monitoring the bot errors. It can be done easily if the bot is hosted using AWS lambda through CloudWatch alarms.

To create an alarm do the following:

  1. In Cloudwatch, click on Create Alarm, and then Select Metric.
  2. Select the Errors metric for the lambda and click on Select Metric.
  3. Set the statistic to be Sum and select the required period for the threshold measuring.
  4. Under conditions, choose static threshold, choose Greater, and set the threshold value to at least 1. Click Next.
  5. Insert to Emails be to be alarmed. Click Next, name the alarm and click Next again.
  6. Go over the summary, and if everything makes sense to you - click OK.

That's it 💪

Now all commits for the selected repositories are protected!

Updated 6 days ago