Detection Metadata That Makes Rules Operable

Stable identity lets the detection survive change

A title can change. A file can move. A rule can be translated into several platforms. A stable identifier connects versions, tests, deployments, alerts, exceptions, metrics, incidents, and retirement records across those changes.

Use a globally or repository-unique content identity and separate version or revision. Record status, created and modified time, authors, owner, reviewers, changelog, and replacement relationships. Do not reuse an identifier for a new behavior after retirement.

Alerts should preserve the detection identity and executable artifact version that produced them. Without it, an investigator cannot know which logic and assumptions applied to historical evidence.

Describe the behavior claim before the implementation

Metadata should state the threat or misuse behavior, scope, consumer, decision, and limits in plain language. Framework mappings, tactics, techniques, and tags organize this claim; they do not replace it.

Record actor, action, target, necessary context, expected result, and alternative explanations. State which platforms, tenants, identity types, and populations are in and out of scope.

This description allows reviewers to compare source intent with generated backend logic. It also prevents a broad title such as credential theft from making a narrow session-reuse analytic appear more complete than it is.

Make evidence and dependencies machine-readable

List required log sources, event classes, fields, time semantics, identity resolution, enrichment, lookback, state, converter, backend features, schedules, routing, and case integrations. Human explanation and structured dependency identifiers serve different purposes; keep both.

Attach tests to the requirement and dependency they exercise. Record last validated version and environment, current health, and known gaps. An ATT&CK mapping without local evidence state should never display as validated coverage.

The detection dependencies graph lets change systems identify affected content when a parser, schema, field map, or shared component changes.

Define the output contract and operating policy

State whether the analytic creates enrichment, risk, a hunt result, an alert, a case, or a response request. Record severity, confidence, priority logic, deduplication, suppression, evidence fields, routing, consumer, and service expectation.

Keep analytic severity, evidence confidence, asset consequence, and response priority separate. A moderate-confidence event on a break-glass identity can deserve urgent review. A high-confidence benign policy test may not.

Link exceptions and filters with owner and expiry. The content record should show effective scope rather than the unfiltered source claim. Runtime deployment and enablement state also belong beside repository state.

Use metadata as a living assurance record

Review metadata after incidents, source changes, mapping changes, tests, filters, deployment moves, ownership changes, and service degradation. Automate freshness checks, but do not let a recent timestamp substitute for substantive review.

Retirement metadata should identify reason, final version, disabled deployments, consumers notified, historical identifier preservation, replacement, and residual risk. Historical alerts must still resolve to the retired content and evidence contract.

Good metadata reduces memory dependence. A new engineer or analyst can understand why the detection exists, what evidence it needs, where it runs, what it produces, how confidence was earned, and what would make the claim no longer true.

Metadata quality should be tested like content quality. Reject missing owners, unresolved dependencies, invalid identities, expired reviews, unsupported mappings, and output contracts that omit required evidence. Automation can enforce presence and consistency; human review must still decide whether the descriptions are accurate and useful.