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.
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
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 using one of the following two methods:
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.
STRICT_MODEis 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.
Follow the deployment instructions on our DockerHub repo for the GitHub scanner.
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.
- 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:
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
WEBHOOK_SECRET_VAULT_KEY- GitHub app webhook secret, should be in the format of
PRIVATE_KEY_VAULT_KEY- Private key, should be in the format of
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.
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:
- REPOS_BLACKLIST_BUCKET_NAME - the name of the bucket containing the blacklist file
- 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.
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.
To build the webhook URL append
/api/github/event to the ServiceEndpoint output from the stack:
To build the webhook URL append
/events/github to the URL for your container:
Save your changes to complete the process.
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:
- In Cloudwatch, click on
Create Alarm, and then
- Select the
Errorsmetric for the lambda and click on
- Set the statistic to be
Sumand select the required period for the threshold measuring.
- Under conditions, choose
Greater, and set the threshold value to at least 1. Click
- Insert to Emails be to be alarmed. Click
Next, name the alarm and click
- Go over the summary, and if everything makes sense to you - click OK.
Now all commits for the selected repositories are protected!
Updated 6 days ago