> For the complete documentation index, see [llms.txt](https://docs.scanner.dev/scanner/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scanner.dev/scanner/using-scanner-complete-feature-reference/detections-and-alerting/detection-rules/detection-rules-as-code.md).

# Detection Rules as Code

## 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](/scanner/what-and-why/how-it-works/detection-rule-engine.md).

To get started, see [Getting Started](/scanner/using-scanner-complete-feature-reference/detections-and-alerting/detection-rules/detection-rules-as-code/getting-started.md).

## How syncing works

When a sync is triggered, Scanner reads the current state of the repository, then [validates](/scanner/using-scanner-complete-feature-reference/detections-and-alerting/detection-rules/detection-rules-as-code/writing-detection-rules.md#schema) and [runs tests](/scanner/using-scanner-complete-feature-reference/detections-and-alerting/detection-rules/detection-rules-as-code/writing-detection-rules.md#detection-rule-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](https://github.com/scanner-inc/sync-detection-rules), or directly via [`scanner-cli`](/scanner/using-scanner-complete-feature-reference/detections-and-alerting/detection-rules/detection-rules-as-code/cli.md). 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](/scanner/using-scanner-complete-feature-reference/detections-and-alerting/detection-rules/detection-rules-as-code/getting-started.md) to set up either mode.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.scanner.dev/scanner/using-scanner-complete-feature-reference/detections-and-alerting/detection-rules/detection-rules-as-code.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.