Getting Started

1. Create a new GitHub repository for detection rules

We recommend creating a new GitHub repository in your organization for Scanner detection rules.

Add detection rule YAML files to your new repository. See Writing Detection Rulesfor information on how to write detection rules.

2. Connect to the Scanner GitHub App

Go to Settings > Integrations on your Scanner instance to connect your GitHub account.

Integrations page

Choose which account to connect to and which repositories the Scanner GitHub App can access. The App will only have read access to code and metadata in the selected repositories.

You will need to be logged into GitHub and have appropriate permissions on the selected repositories in order to complete this process.

Allow access to select repositories

If you want to connect multiple accounts, click on Connect again to select another account.

You will be able to configure repositories after connecting to the GitHub App, if you want to give the Scanner App access to more repositories or revoke access to repositories later.

3. Add a sync source

After connecting your GitHub account, go to Detection Rule: GitHub Settings.

GitHub integration options

On this page, you will see all connected GitHub accounts and sync sources.

GitHub settings page

To add a new sync source, click Add Repository. Select the repository and branch that you would like to sync from.

Add a sync source

You will be prompted to assign event sinks to each key in this sync source. You can select one or more event sinks to assign to each key (or leave it blank). These keys are defined in the detection rules themselves; see the Writing Detection Rules section for more information.

Assign event sinks

A sync will automatically kick off after you add a sync source. Syncs happen every 5 minutes (if there have been new commits since the last attempted sync). They can be kicked off manually on the Detections page or via API.

Kick off a GitHub sync

4. Check the status of your sync

Click on the connected repository to check the sync status. On this page, you will see information on the last sync status and the detection rules that were included.

Last sync status and included rules

You can also change the branch or update permissions on this page.

If there are no errors or failing tests, the detection rules will be synced and you will see them on the Detections page with a GitHub tag.

Synced detection rule

If there are any errors or failing tests, the sync does not proceed. You will be able to see which files had errors or failing tests. After fixing the files and checking in the changes, you can wait for a new sync to kickoff or kickoff a sync from the Detections page.