GitHub Bot

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. By default, only one instance the bot can be deployed to a region. To deploy more than one instance of GitHub bot to the same region, contact Customer Support.

Integration Environment Variables

Name

Required

Description

Valid Values

Default

GITHUB_APP_ID

Yes

GitHub app id

 

 

CHECK_POLICY

Yes

If Spectral finds issues in a PR - how should we handle the PR check? The policies are based on the Spectral issue severity - critical, high, medium, low, and informational

  • Fail on any issue

  • Fail on low and above

  • Fail on medium and above

  • Fail on high and above

  • Fail on critical only

  • Always Pass

 

SPECTRAL_TAGS

No

Include detectors by tag, separated by comma

secrets / iac / oss

 

SPECTRAL_ENGINES

No

Engines list to run Spectral with, separated by commas

 

 

SPECTRAL_DSN

No

Your Spectral DSN retrieved from SpectralOps (leave empty if you are using vault)

 

 

GITHUB_WEBHOOK_SECRET

No

The GitHub app webhook secret, any strong secret would be fine (leave empty if you are using vault)

 

 

GITHUB_PRIVATE_KEY

No

GitHub app private key base64 encoded (leave blank if stored in vault)

 

 

SECRETS_VAULT

No

The vault you're storing your secrets in

aws_secrets_manager

 

VAULT_KEY_SPECTRAL_DSN

No

The key in the vault where the Spectral DSN is stored. should be in the format of Spectral_Dsn-*

 

 

VAULT_KEY_GITHUB_WEBHOOK_SECRET

No

The key in the vault where the GitHub webhook secret is stored. should be in the format of Spectral_GithubBot_WebhookSecret-*

 

 

VAULT_KEY_GITHUB_PRIVATE_KEY

No

The key in the vault where the GitHub private key is stored. should be in the format of Spectral_GithubBot_PrivateKey-*

 

 

CUSTOM_COMMENT

No

Add a custom text to the pull request comment and check summary - Markdown format

 

 

SHOULD_SKIP_INGEST

No

If set to true - findings won't be sent to SpectralOps and won't be seen in your dashboard

true / false

false

GITHUB_SHOULD_POST_REVIEW_COMMENTS

No

Should review comments be posted on PR files where Spectral has identified issues

true / false

false

GITHUB_SHOULD_SKIP_CHECK

No

Disable GitHub check creation

true /false

false

S3_BLACK_LIST_BUCKET_NAME

No

Name of the bucket containing the blacklist file

 

 

S3_BLACK_LIST_OBJECT_KEY

No

Blacklist file S3 object key

true /false

false

STRICT_MODE

No

If set to true - issues from changed files in the PR will fail the check even if the issues are in lines that hasn't been modified

 

 

HOME

No

If the environment does not automatically set this variable, specify a path to an existing location that has write permissions. For example, in AWS LambdaClosed A serverless compute service that lets you run code without provisioning or managing servers, creating workload-aware cluster scaling logic, maintaining event integrations, or managing runtimes., where this variable is not preset, assign it the value /tmp

 

 

GITHUB_SELF_HOSTED_DOMAIN

No

Provide the domain if you're running a self-hosted Github (for example: https://my-github-domain.com).

 

 

CUSTOM_SSL_CERTIFICATE

No

The SSL certificate content for on-prem Github. Use this variable if not using AWSClosed Amazon® Web Services. Public cloud platform that offers global compute, storage, database, application and other cloud services. Secrets Manager for the certificate.

 

 

VAULT_KEY_CUSTOM_SSL_CERTIFICATE

No

The vault key to retrieve the custom SSL certificate.

 

Spectral_custom_ssl_certificate

Configuring Code Security Github Bot

  1. Create a new GitHub app:

    • To install the app on an organizational account, use this link.

    • To install the app on a personal account, use this link.

  2. Select on which depositories to install the app:

    • All repositories (applies to all current and future repositories owned by the resource owner)

    • Only select repositories

  3. Use one of these methods to deploy the bot:

    Method

    How to Deploy

    Cloud Formation

    Prerequisite

    These permissions are required in your AWS account:

     

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

    Procedure

    1. In AWS, launch the stack.

    2. In the settings of your new GitHubb app, generate a private key.

    3. Encode the private key in base64 without line breaks. Example OpenSSL command:

      openssl base64 -A -in YOUR-PRIVATE-KEY.pem

    4. In AWS > GITHUB_PRIVATE_KEY field, enter the private key that you created in the previous step.

    5. For Check Policy, select one of these:

      • 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

    6. Set the value of the STRICT_MODE parameter. If this parameter is true, the status check runs on all issues. If this parameter is set to false, the status check runs only for new issues.

    TerraformClosed An infrastructure as code tool that lets you define both cloud and on-prem resources in human-readable configuration files that you can version, reuse, and share.

    Terraform - Deploy AWS resources using the Code Security Terraform module. Set the value of the integration_type parameter to github).

    Note: The Terraform deployment is supported starting from GitHub bot 2.x versions.

    DockerClosed Docker (specifically, Docker Engine) is a software technology providing operating-system-level virtualization also known as containers.

    Follow the deployment instructions in the Code Security DockerHub repo.

  4. Go to the GitHub app settings page.

  5. In the Webhook section, enter these values:

    • Webhook URL

    • Webhook secret

    Note - In AWS Lambda, to generate the webhook URL, append /api/github/event to the ServiceEndpoint output from this stack:

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

    Note - In Docker, to generate the webhook URL, append /events/github to the URL for your container:

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

  6. In the Webhook section, set the Webhook to active.

Using a Vault

We recommend to store your secrets in a vault instead of directly in the configuration of your Lambda. Only AWS Secret Manager is supported.

To use AWS Secret Manager to store your secrets:

  1. In Code Security, set the value of the SECRETS_VAULT environment variable to aws_secrets_manager.

  2. In your vault, set these secrets:

    Secret

    Value

    GITHUB_PRIVATE_KEY

    Spectral_GithubBot_PrivateKey

    GITHUB_WEBHOOK_SECRET

    Spectral_GithubBot_WebhookSecret

    SPECTRAL_DSN

    Spectral_Dsn

Using Custom Vault Keys

Use these Code Security integration environment variables to create custom secret vault keys:

Note - If you use AWS Secrets Manager with a CloudFormation or Terraform deployment, the role you created for the Lambda functions gives permission to perform the action only for the default secrets.

Integration Environment Variable

Description

VAULT_KEY_SPECTRAL_DSN

Spectral DSN key name, in this format: Spectral_Dsn-*

VAULT_KEY_GITHUB_WEBHOOK_SECRET

GitHub app webhook secret, in this format:
Spectral_GithubBot_WebhookSecret-*

VAULT_KEY_GITHUB_PRIVATE_KEY

Private key, in this format:

Spectral_GithubBot_PrivateKey-*

VAULT_KEY_CUSTOM_SSL_CERTIFICATE

Optional - This is a key for a vault that contains a self-signed certificate. Default value:
Spectral_custom_ssl_certificate

Advanced Configuration: Excluding Repositories

To exclude specific repositories from the scan, add them to an exclusion list of repo URLs.

  1. Create a text file containing a list of full URLs of repositories to exclude (for example: https://github.com/expressjs/express). Put each URL on a new line in the file.

  2. In Code Security, define these integration environment variables:

    Integration Environment Variable

    Description

    S3_BLACK_LIST_BUCKET_NAME

    The name of the bucket containing the exclusion list file

    S3_BLACK_LIST_OBJECT_KEY

    The object key of the exclusion list file

Advanced Configuration: Configuring Multiple GitHub Apps with a Single Instance of Code Security Bot

To configure mutliple GitHub apps with a single instance of Code Security bot, configure a multi_app.json file in the root directory and add it to the frontend and backend Lambda functions.

The GitHub object is a dictionary containing all of the GitHub Apps. For each app, you must set the private_key, which is a base64-encoded string of the GitHub App's private key. In the <app_id>

Procedure

  1. In the AWS Lambda deployment, in the root directory, open the multi_app.json file.

  2. In the <app_id> section, enter the GitHub App ID to configure a specific application.

  3. Optional - Configure one or more of these optional parameters:

    Parameter

    Description

    check_failure_policy

    Determines the failure policy for scans from this specific GitHub App. If not set, it defaults to CHECK_POLICY. Refer to the table above for possible values.

    spectral_dsn

    Allows splitting scans using a different DSN for this GitHub App. It defaults to SPECTRAL_DSN.

    webhook_token

    Allows using a webhook secret for this GitHub App. It defaults to GITHUB_WEBHOOK_SECRET.

    secret_vault

    Enables storing secrets (webhook secret, app private key, spectral DSN) in a vault at the app level. When using a vault, you must specify all the keys for the webhook secret, GitHub App private key, and optional spectral DSN.

    self_hosted_domain

    Allows self hosted domain for this GitHub App. It defaults to GITHUB_SELF_HOSTED_DOMAIN.

Example multi_app.json Configuration File

Copy 
{
  "github": {
    "<app_id>": {
      "private_key": "",
      "spectral_dsn": "",
      "webhook_token": "",
      "self_hosted_domain": "",
      "secret_vault": {
        "name": "aws_secrets_manager",
        "key_webhook_secret": "",
        "key_private_key": "",
        "key_spectral_dsn": "",
        "key_ssl_certificate": "",
      }
    }
  }
}

  1. Download and unzip the Lambda code:

    1. Download the Lambda code as a .zip file.

    2. Unzip the downloaded file.

  2. Add the multi_app.json configuration file you edited in Step 1 to the unzipped directory.

  3. Re-zip the configuration file and upload it to the Lambda:

    1. Select all of the files in the unzipped directory.

    2. Zip the files.

    3. Upload the new .zip file to AWS Lambda. Make sure that the multi_app.json configuration file is in the .zip file.

Monitoring Code Security Github Bot with CloudWatch alarms

We recommend to monitor GitHub Bot errors using CloudWatch alarms in AWS Lambda. Follow this procedure in CloudWatch:

  1. Click Create Alarm.

  2. Click Select Metric.

  3. Select the Errors metric for the Lambda.

  4. Click Select Metric.

  5. Set the statistic to Sum and select the required period to measure the threshold.

  6. In the Conditions section:

    1. For threshold, select static.

    2. Select Greater.

    3. Set the threshold value to 1 or a greater number.

    4. Click Next.

  7. Add the email addresses to receive the alarm.

  8. Click Next.

  9. Enter a name for the alarm.

  10. Click Next.

  11. Read the summary. If the configuration is correct, click OK.

Upgrading the Github Bot

The Code Security GitHub bot is versioned.

To upgrade the l GitHub bot with Lambda:

In Lambda, in the Code tab, upload a new .zip file of the Github bot. Upload the new version to the frontend Lambda and to the backend Lambda.

To upgrade the GitHub bot with Docker:

Deploy a new GitHub bot image from the docker hub.