Getting Started

1. Put your detection rules in a Git repository

We recommend creating a new GitHub repository in your organization for Scanner detection rules. However, any Git host works for the user-pushed flow below — GitHub is only required if you want Scanner to poll the repository for you.

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

2. Choose a sync mode

Scanner supports two ways to bring rules from a repository into your tenant. Both run the same validate / test / materialize pipeline, so the synced rules look the same either way — pick whichever matches how your team manages rules.

• GitHub-polled — Scanner pulls from a GitHub.com repository connected through the Scanner GitHub App, every ~5 minutes. Use this when your rules live in GitHub.com and the App can be granted read access. Continue with GitHub-polled sync below.
• User-pushed — your CI (or you, locally) pushes the repository to Scanner, typically via the Scanner GitHub Action or directly via scanner-cli. Use this when your rules live outside GitHub.com — for example on GitLab, Bitbucket, or a self-hosted GitHub Enterprise Server — when the Scanner GitHub App can't be granted access, or when sync should run from CI. Skip ahead to user-pushed sync.

Set up GitHub-polled sync

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.

Add a polled 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

Set up user-pushed sync

Add a push sync source

Go to Detections > Synced Repositories on your Scanner instance and add a new push sync source. You'll be asked to choose two things:

• A push key — a per-tenant identifier you'll use to target this source on every push. Pick something short and stable (e.g. the repo's slug).
• A branch that the source tracks (typically your default branch). The source must be registered for the same branch you'll push from — for example, a GitHub Action triggered on push: branches: [main] needs a source registered for main, and a scanner-cli sync-git-repo run from a main checkout works the same way. To sync from more than one branch, register a separate push sync source per branch.

Add a push sync source

Detection rules can reference event-sink keys (see Writing Detection Rules). Unlike the GitHub-polled flow, the event-sink assignment step in the UI only becomes available after your first push — Scanner discovers which keys exist by reading the uploaded rules. You'll come back to this step after running the sync the first time.

Push from your rules repository

You have two options for invoking the sync. Both end up running the same scanner-cli sync-git-repo upload under the hood — the server validates, tests, and materializes the rules in exactly the same way.

GitHub Action (recommended for GitHub.com / GHES)

Use the scanner-inc/sync-detection-rules Action. It installs scanner-cli, runs the sync against the checked-out tree, and surfaces per-file failures and warnings as PR / check annotations on the offending YAML files.

name: Sync Detection Rules
on:
  push:
    branches: [main]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: scanner-inc/sync-detection-rules@v0.1.0
        with:
          scanner_api_url: ${{ vars.SCANNER_API_URL }}
          scanner_api_key: ${{ secrets.SCANNER_API_KEY }}
          push_key: ${{ vars.SCANNER_PUSH_KEY }}

scanner_api_key is the only sensitive value — store it as a repository secret. scanner_api_url (from Settings > API Keys in Scanner) and push_key (the identifier you picked on the push sync source) aren't credentials — uploads are authorized by the API key — so configure them as repository variables instead. Variables are visible in workflow logs, which makes debugging easier.

Run scanner-cli directly

Assign event sinks (after the first push)

Scanner can only discover the event-sink keys your rules reference by reading rules that have actually been uploaded, so event-sink assignment happens after your first successful push — regardless of which option above you used.

If you set up the GitHub Action, trigger it at least once (push a commit to the configured branch, or run the workflow manually from the Actions tab) so Scanner has rules to discover keys from.

Then, in Detections > Synced Repositories, open the sync source you created. Scanner now lists the event-sink keys your rules reference — assign one or more event sinks to each key. See Writing Detection Rules for how the keys are declared in rule YAML.

Until you do, rules referencing unassigned keys will sync, but won't deliver alerts to any sink.

Check the status of your sync

The sync source detail page shows the same information regardless of mode — the last sync attempt, the detection rules that were included, and any failures or warnings. Open it from Detections > Synced Repositories (or by clicking on the connected repository, for GitHub-polled sync).

Last sync status and included rules

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 tag identifying the sync source.

Synced detection rule

If any rule fails to validate or its tests fail, the sync does not proceed and the failure list shows which files were rejected and why. After fixing the files:

• GitHub-polled — check in the changes; the next scheduled sync will pick them up, or kick off a sync manually from the Detections page.
• User-pushed — trigger the GitHub Action again (or re-run scanner-cli sync-git-repo).