Detection Rule Documentation Template: ADS fields, response steps and review records

A detection rule that nobody can explain is a liability: analysts cannot triage it, engineers cannot tune it, and nobody knows when it silently stops working. This template gives every production detection a standard record, built on the Alerting and Detection Strategy (ADS) format published by Palantir and extended with the response, validation and review fields a SOC needs. Each numbered section below is one block of the record, with fill-in fields marked [like this]. It is written for detection engineers, SOC leads and incident responders who maintain rule libraries in a SIEM, EDR or data lake, and it pairs with a Sigma or vendor rule file stored in version control. For the wider discipline see the Detection Engineering Guide.

How to use this template

Create one record per detection, named after the single behaviour it detects. Palantir's ADS guidance asks for titles that target a singular event, such as "Non-SA Bastion Logon", rather than a family of events. Store the record next to the rule logic (for example rules/windows/proc_creation_lsass_access.yml and docs/proc_creation_lsass_access.md) so that a pull request changes both together. See the Detection as Code Guide for the pipeline that enforces this.

• Required before production: sections 1, 2, 3, 4 and 8, plus a passing true positive validation. ADS treats validation as mandatory: if you cannot generate a true positive, the alert may need to be broken down, refactored or discarded.
• Required within 30 days of go-live: sections 5 to 7, populated from the first real triage cases.
• Owner: every record names an accountable engineer and a backup. Orphaned rules are the first to rot.
• Status: reuse the Sigma status values so the record and rule agree: experimental, test, stable, deprecated, unsupported.

1. Scope and triggers

• Detection name: [Short, singular behaviour, for example "Non-system process opening LSASS with read access"]
• Rule ID: [UUID, identical to the Sigma id] Version: [semantic version] Status: [experimental | test | stable | deprecated | unsupported]
• Goal: [One plain sentence on the behaviour you are trying to detect and why it matters to [Organisation].]
• ATT&CK mapping: [Tactic / technique / sub-technique, for example Credential Access / T1003 OS Credential Dumping / T1003.001 LSASS Memory]. ADS asks for both parent and child category.
• Threat context: [Actors, campaigns or incidents that motivated the rule, with intelligence references.]
• Assets in scope: [Platforms, OS versions, tenants, business units. State exclusions explicitly.]
• Blind spots and assumptions: [Where the rule will not fire: for example, telemetry not collected on servers in [segment], attacker uses a signed driver, renamed binary, alternative technique such as T1059.001 PowerShell-based dumping without the monitored API call.]
• Detection type: [Atomic indicator | behavioural | threshold or aggregation | correlation across sources | anomaly or model-based | building block that feeds other rules]. The type tells reviewers what tuning and validation to expect: a correlation rule needs every input tested, an anomaly rule needs a baseline period stated.
• Identities involved: [Which account types can trigger the rule: human admins, service accounts, workload identities, CI runners, AI agents.] Non-human identities often run the same tools attackers use, so state how the rule tells them apart, for example by expected host, parent process or credential type. See the NHI Detection Engineering Guide.
• Log source dependencies: [Exact source and setting, for example Sysmon Event ID 10 with a ProcessAccess filter including lsass.exe; Windows audit policy setting; cloud audit category.] If the source stops, this rule is blind.

2. Roles and contacts

3. Detection and triage

• Strategy abstract: [How the rule works in four or five sentences: data sources, the condition, enrichment (asset criticality, identity context, threat intelligence) and any false positive suppression.]
• Technical context: [What a responder needs without being the subject expert: what normal looks like, how the attack works, which fields matter. ADS describes this as a self-contained reference for the judgement call.]
• Query location: [Repository path and commit] Schedule: [real time | every N minutes, look-back window] Platform: [SIEM / EDR / data lake]
• Priority criteria: [Map to Sigma levels and your queue severity. Sigma defines high as an event that should trigger an internal alert and prompt review, and critical for cases where probability borders on certainty.] Example: critical when the host is a domain controller; high otherwise.
• Known false positives: [Defining characteristics of each benign source: backup agent [name] on [hosts], EDR self-scans, admin tooling. Record the suppression and who approved it.]
• Triage questions (answer in order):
  1. Is the source process expected on this host, signed, and in its usual path?
  2. Which account ran it, and is that account human, service or machine? Check recent authentication for the account.
  3. What happened in the 30 minutes before and after on the host (process tree, network connections, file writes)?
  4. Does the same indicator appear on other hosts in the last [N] days?
  5. Does this meet the incident criteria in [IR plan reference]? NIST SP 800-61 Rev. 3 recommends applying incident criteria while accounting for known false positives (DE.AE-08).
• Evidence to capture at triage: [Alert ID, raw events, process tree export, host and account identifiers, timestamps in UTC. Note anything that will age out quickly, such as EDR telemetry kept for a limited period.]
• Triage SLA: [Critical: 15 minutes; high: 1 hour; medium: 1 business day.]

4. Containment

Record the containment options a responder may use for this alert, who may approve each, and what to check first. Containment for a credential theft rule is very different from one for a noisy reconnaissance rule, and the record should say so.

NIST SP 800-61 Rev. 3 recommends letting handlers select containment manually in addition to or instead of automated measures, and considering automatic containment for some threats such as quarantining malware. See the Incident Scoping and Containment Strategy Guide for when to hold back.

5. Eradication

• Typical root causes for this alert: [Malware dropped by phishing, compromised admin credential, vulnerable service.]
• Eradication steps to consider: [Remove persistence, reimage, rotate exposed credentials, patch the entry point.]
• Credential follow-up: [If secrets or tokens may have been exposed, list which classes to rotate and link the procedure.] See the Leaked Credential Response Playbook.
• Scope check: [Query to find the same behaviour across the estate before declaring eradication complete.]

6. Recovery

• Return to service criteria: [Host reimaged or verified clean, credentials rotated, monitoring confirmed working.]
• Heightened monitoring: [Temporary lower threshold or watchlist on affected hosts and accounts for [N] days.]
• Rule health after the incident: [Confirm the log source still flows from recovered hosts; reimaged builds sometimes lose agents or audit policy.]

7. Communication and notification

• Internal notification: [Who is told at each priority: SOC lead, IR lead, asset owner, CISO.]
• Ticket and case fields: [Rule ID and version, ATT&CK tags, triage outcome code: true positive, benign true positive, false positive, inconclusive.]
• External or regulatory route: [If a confirmed true positive could be reportable, link the incident communication plan rather than duplicating it.] See the Incident Communication Plan Template.

8. Post-incident review

This section holds validation evidence and the change history. It turns the record into something a reviewer or auditor can trust.

• True positive validation: [Test case reference, for example an Atomic Red Team test mapped to the technique, or a recorded lab procedure. Date run, environment, result, alert ID produced.] ADS describes validation as similar to a unit test.
• Last validated: [Date] Next due: [Date, for example quarterly for critical rules and after any log source change.]
• Performance record: [Alerts in last 90 days, true positive rate, median time to triage, suppressions added.]
• Lessons from incidents: [Each incident where this rule fired, missed or fired late, with the change made.]
• Change log: [Version, date, author, reviewer, what changed and why. Mirror the Sigma modified date.]
• Retirement: [If deprecated, the replacing rule ID, using Sigma related types such as obsolete or merged.]

Implementation guidance

1. Start with the top 20 rules by alert volume and by severity. Document those first: they generate most analyst time and most risk.
2. Make the record a merge requirement. In CI, fail any pull request that adds or changes a rule without a matching record containing goal, ATT&CK tags, blind spots, false positives and a validation reference.
3. Pilot with one team for a month. Measure triage time on documented versus undocumented rules, then adjust fields that analysts never use.
4. Schedule validation. Run the true positive test on a cadence and after every change to the rule or its log source. A failed test opens a ticket to the owner.
5. Review quarterly. Retire rules with no true positives and no threat justification; demote noisy rules to test rather than suppressing them silently.
6. Roll back safely. Keep the previous rule version deployable. If a change floods the queue, revert the commit, not the record.

Metrics to track: percentage of production rules with a complete record; percentage validated in the last 90 days; true positive rate per rule; median time to triage for documented rules; number of rules with an unnamed owner (target zero). For maturity benchmarking see the Detection Engineering Maturity Model.

Common failure patterns: blind spots left blank because nobody wants to admit them; false positive suppressions added in the SIEM but not in the record; validation done once at creation and never again; records stored in a wiki that drifts from the rule in the repository; priority set by gut feel instead of written criteria.

Standards and references: Palantir: Alerting and Detection Strategy Framework · SigmaHQ: Sigma Rules Specification · SigmaHQ: pySigma · NIST: SP 800-61 Rev. 3 Incident Response Recommendations · Red Canary: Atomic Red Team · MITRE ATT&CK: LSASS Memory

Related NHI Mgmt Group resources: Detection Engineering Guide · Sigma Rules Guide · SOC Runbook Template · Detection Validation and Testing Guide