Detection Rules as Code

Collaborate on, review, and continuously test detection rules.

What is detection rules as code?

Users can define detection rules in YAML files and use GitHub to manage detection rules. This allows teams to collaborate on detection rules and review changes.

Scanner provides a GitHub integration for syncing detection rules. Users can connect their GitHub repositories to Scanner and Scanner will automatically sync detection rules from GitHub.

Scanner's detection rules as code feature also allows for tests to be specified in the YAML files. The tests are run in Scanner and must pass before detection rules are synced.

Architecture: To understand how Scanner's detection engine works under the hood and why it can efficiently run hundreds of detection rules simultaneously, see Detection Rule Engine.

To get started, see Getting Started.

How syncing works

When a sync is triggered, Scanner reads the current state of the repository, then validates and runs tests for all rules. Then:

• If all rules pass, Scanner will create, update, or delete managed detection rules to match the current state of the YAML files in the repository.
• If any rule fails, Scanner will not sync any changes (including those that passed) and will notify the user with an error.

Sync modes

Scanner supports two ways to get detection rules from a repository into your tenant. Both feed the same validate / test / materialize pipeline above, so the result is identical — pick whichever matches how your team manages rules.

• GitHub-polled. Connect the Scanner GitHub App to a GitHub.com repository and Scanner pulls from it on a schedule (roughly every 5 minutes). Use this when your detection rules live in GitHub.com and the App can be granted read access on the repository.
• User-pushed. Your CI (or you, locally) pushes the working tree 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 granting Scanner GitHub App access isn't possible, or when you want sync to run from your own CI on commit / merge.

See Getting Started to set up either mode.