Detection rule (MDR)

This revision adds optional metadata.reviewed. rule-1.0.md (rule::1.0) stays normative. A rule opts in by setting metadata.schema. Platform blocks and every other field match rule::1.0.

Requirements

• The document MUST declare metadata.schema: rule::1.1.
• name, metadata, and description MUST be present.
• metadata.reviewed MAY be omitted. Omitted means no recorded review.
• When metadata.reviewed is present, it MUST be an ISO 8601 date (YYYY-MM-DD) or datetime string, coerced to string on load, using the same forms as metadata.created and metadata.modified. A date-only value denotes 00:00:00Z on that date.
• Implementations MUST NOT write metadata.reviewed during validate, deploy, share, or template generation. Authors set it when a person reviews the rule.
• Consumers MUST NOT treat metadata.created or metadata.modified as a review time. Updating reviewed does not require a change to metadata.version or metadata.modified.
• status MUST be a valid deployment status from deployment.md (default: STAGING).
• severity MUST be a value of the alert_severity vocabulary (pin alert_severity::1.0: Informational, Low, Medium, High, Critical; default: Informational). It is the rule's own severity, distinct from a threat's severity, which uses the severity (Threat Severity) incident scale.
• techniques MUST be a list of ATT&CK technique ids from vocabulary att&ck (pin att&ck::1.2). The list MAY be empty.
• platforms or configurations MUST contain at least one enabled platform block for deployable rules.
• detection_model when present MUST reference either a valid objective UUID or the UUID of a signal defined under an objective (objective::1.0 or objective::1.1). A rule implements a whole objective or one of its signals; both are referenceable by design. A signal reference implements that signal, and the rule's objective is the signal's owning objective. Indirect coverage of other objectives is derived from signal bindings on objective::1.1 (objective-1.1.md, draft). A rule has a single detection_model.
• Platform blocks MUST validate against the platform schema identifier declared in each block's schema field.
• references MAY be omitted.
• Registry-backed methods (deploy, validate, document) require a bound opentide registry at runtime — not part of static YAML validation.

Definition

Top level (DetectionRule)

Review staleness

Evaluated at instant T, for a positive duration W supplied by the consumer, a detection rule is unreviewed when any of the following holds:

1. metadata.schema is rule::1.0 (that revision has no review field).
2. metadata.schema is rule::1.1 and metadata.reviewed is absent.
3. metadata.schema is rule::1.1 and the reviewed instant is strictly earlier than T − W.

A reviewed instant equal to T − W or later is not unreviewed. W is not a field on the rule. The predicate is a read and MUST NOT modify the rule.

response (RuleResponse)

procedure (ResponseProcedure)

searches[] (ResponseSearch)

language names the query language when system alone does not. With system: elastic it MUST be one of the names elastic-1.0 uses: kuery (KQL), lucene, eql, or esql (ES|QL). language MUST NOT be set with any other system, because the system alone names the language: sentinel and defender_for_endpoint are KQL, splunk is SPL, and no other system has a language in this revision. With system: elastic, an omitted language (or an empty one, YAML null) means the language is unknown and the query is not analysed, as before the field existed.

Platform block (PlatformConfigBase)

Shared fields on every platform configuration:

configurations (RuleConfigurations)

Typed optional blocks keyed by platform identifier:

Shared block fields and the capability matrix are in platforms/index.md. Each link above is the field contract for that block.

Relationships

• metadata.md — identity, schema routing, and metadata.reviewed
• rule-1.0.md — previous MDR revision; still valid; no metadata.reviewed
• objective-1.0.md — linked via detection_model (the objective, or one of its signals)
• objective-1.1.md — same link; reuse bindings add indirect coverage (draft)
• deployment.md — status lifecycle and promotion
• platforms/index.md — platform blocks and deploy/validate capabilities
• validation.md — schema, vocabulary, and query validation
• Vocabularies: severity, alert_severity, att&ck, deployment statuses

Defaults & overrides

Vocabulary files are canonical in vocabularies/ — not overridable. See configuration.md.

Examples

name: Sentinel KQL Rule
metadata:
  uuid: 00000000-0000-4000-8003-000000000101
  schema: rule::1.1
  version: 1
  created: "2026-01-01"
  modified: "2026-01-02"
  reviewed: "2026-09-01"                 # optional; omit when nobody has reviewed the rule
  tlp: clear
description: Detects credential access via suspicious process creation
status: STAGING
severity: High
techniques: [T1059]
detection_model: 00000000-0000-4000-8002-000000000001   # → objective UUID, or a signal UUID under one
response:
  alert_severity: High
configurations:
  sentinel:
    enabled: true
    name: Sentinel KQL Rule
    status: STAGING
    query: |
      SecurityEvent
      | where EventID == 4688
      | take 1
    scheduling:
      frequency: PT1H
      lookback: PT2H
    alert:
      title: Sentinel KQL Rule
      suppression: false

Valid fixtures

Invalid fixtures

History