detection-as-code

Sigma detection rules that are checked on public logs before they are merged. A rule must fire on the attack logs listed in its test cases and stay silent on normal activity. Each rule comes with a detection card that covers its blind spots, false positives and triage steps.

• Repository layout
• How a rule is checked
• Detection cards
• Quick start
• Converting rules for a SIEM
• Adding a rule
• Sources
• License

Every rule folder has the same three files:

detections/<platform>/<name>/
├── <rule>.yml    Sigma rule, file named as in SigmaHQ
├── tests.yml     test cases: log URL, sha256, what the rule must find
└── README.md     detection card

Test logs and the ATT&CK release are downloaded into .cache/ and checked against their sha256. They are not stored in the repo.

When MITRE publishes a new ATT&CK release, the weekly check opens an issue. Set VERSION and SHA256 in tools/attack.py to the new release and run the checks.

The README.md next to each rule follows the Palantir Alerting and Detection Strategy framework: Goal, Categorization, Strategy Abstract, Technical Context, Blind Spots and Assumptions, False Positives, Validation, Priority, Response, Additional Resources. Validation names an Atomic Red Team test that makes the rule fire and lists the results on the test logs. Example: LSASS memory access.

You need Python 3.12 and uv. goodlog also needs bash, curl, tar and Linux on x86-64, since it runs a Linux binary. On Windows use WSL.

git clone https://github.com/Dubwaay/detection-as-code.git
cd detection-as-code
uv sync --locked
uv run pytest
uv run python -m tools.sigma_check -i $(find detections -name '*.yml' ! -name tests.yml)

Run the rules over a clean baseline. The baseline and the checker are downloaded once into .cache/goodlog/:

tools/goodlog.sh win10-client

Baselines: win10-client, win2022-ad, win11-client, win2022-0-20348-azure, win2022-evtx.

Run the same checks on every commit:

uv tool install pre-commit
pre-commit install

Use sigma-cli with the backend for your SIEM. For Splunk:

uvx --from sigma-cli==3.1.0 --with pysigma-backend-splunk==2.1.0 --with pysigma-pipeline-sysmon==2.0.0 \
  sigma convert -t splunk -p sysmon detections/windows/lsass_memory_access/proc_access_win_lsass_memory_access.yml

The sysmon pipeline turns the Sigma log source into Sysmon event IDs. Add the index or source of your Sysmon data to the search. Backends for other SIEMs are listed in the pySigma docs.

1. Create detections/<platform>/<name>/ and put the Sigma rule there. Name the file as SigmaHQ does, for example proc_creation_win_<name>.yml.
2. Add tests.yml with at least one log the rule must fire on (min_results) and one it must stay silent on (max_results: 0). The format is defined in tools/cases.py. Logs are read by sourcetype. tools/logs.py has readers for XmlWinEventLog, the Windows event logs in splunk/attack_data, and linux_audit, a raw Linux audit.log. A log can be one file inside a zip archive: set member to its path.
3. Add README.md with the detection card. An existing card shows the expected sections.
4. Run uv run pytest, and tools/goodlog.sh for Windows rules.
5. Open a pull request. CI runs the same checks.

• Sigma specification, pySigma and sigma-cli.
• splunk/attack_data (Apache-2.0): attack logs for the test cases.
• CAM-LDS (CC BY 4.0): Linux audit logs of attack scenarios for the test cases. M. Landauer et al., CAM-LDS: Cyber Attack Manifestations for Automatic Interpretation of System Logs and Security Alerts, International Journal of Information Security, 2026.
• NextronSystems/evtx-baseline (Apache-2.0): clean Windows logs and evtx-sigma-checker for goodlog.
• SigmaHQ/sigma: tests/thor.yml, the mapping of Sigma log sources to Windows channels used by goodlog.
• Atomic Red Team (MIT): tests named in the cards to make a rule fire.
• Splunk BOTS v1, v2 and v3 (CC0): extra checks in Splunk, results are in the cards.
• Palantir ADS framework (MIT): the card format.
• MITRE ATT&CK, STIX data from attack-stix-data.

MIT, see LICENSE. Downloaded data keeps the license of its source.