# DetectionRule

A Guardian alert rule: a detection run on a schedule over the tenant's logs, raising alerts. Fields, YAML, HCL and CLI samples, and how apply treats it.

A Guardian alert rule: a detection run on a schedule over the tenant's logs, raising alerts. Name exactly one of body, file, searchRef, countermeasure, sigmahq or ioc. body and file are the tenant's own rule; the others run a rule Guardian already has, which can be tuned (level, threshold, suppressions, timing) but not edited. A rule whose detection does not compile, or names a log source Guardian has no table for, is stored turned off. The plan caps how many rules run at once. Deleting one that an AlertTrigger still uses is refused.

| | |
|---|---|
| `apiVersion` | `vulnetix.com/v1` |
| `kind` | `DetectionRule` |
| Group | [SIEM](/platform-iac/kinds/catalogue.md#siem) |
| Status | **Served.** The [config engine](/platform-iac/reference/engine.md) plans and applies it. |
| Objects per tenant | many, keyed by `metadata.name` |
| Token and role | An owner, or a service account with the developer role, or an Authentik access token for either. The kind is written in Guardian, which the Vulnesis API vouches to for the caller; a member can read it but not change it. See [Credentials for automation](/platform-iac/reference/config-api.md#credentials-for-automation). |
| Applied after | [`SavedSearch`](/platform-iac/kinds/saved-search.md), [`MessagingConnection`](/platform-iac/kinds/messaging-connection.md) (deleted before them) |
| Terraform resource | [`vulnetix_detection_rule`](/platform-iac/terraform/resources.md#vulnetix_detection_rule), imported by name (see [Terraform and OpenTofu](#terraform-and-opentofu)) |
| CLI | [`vulnetix config apply`](/platform-iac/cli/apply.md), CLI v3.165.1 and later. |
| Pinned schema | [`v1.19.1/DetectionRule.schema.json`](https://github.com/Vulnesis/config-schemas/releases/download/v1.19.1/DetectionRule.schema.json) |
| Newest schema | [`latest/DetectionRule.schema.json`](https://github.com/Vulnesis/config-schemas/releases/latest/download/DetectionRule.schema.json) |
| First released in | [`v1.3.0`](https://github.com/Vulnesis/config-schemas/releases/tag/v1.3.0) |
| Print the built-in copy | `vulnetix config schema DetectionRule` |

## Minimal

Only the fields the kind requires. From `examples/DetectionRule/minimal.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/DetectionRule.schema.json
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: sigmahq-aws-root-login
spec:
  sigmahq: rules/cloud/aws/cloudtrail/aws_root_account_usage.yml
```

**HCL** (resource `vulnetix_detection_rule`)

```hcl
# Only the arguments the kind requires. From config-schemas examples/DetectionRule/minimal.yaml.

resource "vulnetix_detection_rule" "sigmahq_aws_root_login" {
  name    = "sigmahq-aws-root-login"
  sigmahq = "rules/cloud/aws/cloudtrail/aws_root_account_usage.yml"
}
```

Every field that has a schema default, set to that default: [`terraform/detection_rule.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/detection_rule.tf) and [`yaml/DetectionRule.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/DetectionRule.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/DetectionRule.schema.json
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: sigmahq-aws-root-login
spec:
  sigmahq: rules/cloud/aws/cloudtrail/aws_root_account_usage.yml
EOF
```

## Advanced

Every field the kind supports, with a `when` expression where it takes one. From `examples/DetectionRule/advanced.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/DetectionRule.schema.json
# A rule names exactly one of body, file, searchRef, countermeasure, sigmahq
# or ioc, so each form has its own document.
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: dynamic-dns
  labels:
    team: secops
    mitre-tactic: command-and-control
  annotations:
    runbook: https://wiki.example.com/secops/dynamic-dns
spec:
  displayName: Dynamic DNS lookup
  language: sigma
  body: |
    title: Dynamic DNS lookup
    id: 6f3e0c52-0d4b-4c8e-9a51-2a6b9a0e7d10
    level: medium
    logsource:
      category: dns_query
    detection:
      selection:
        QueryName|endswith:
          - .duckdns.org
          - .no-ip.org
      condition: selection
  enabled: true
  level: medium
  severityOverride: warning
  intervalSec: 120
  latenessSec: 300
  suppressSec: 1800
  maxAlertsPerRun: 50
  threshold:
    count: 5
    windowSec: 600
    by: [src_ip]
  suppressions:
    - field: QueryName
      value: updates.duckdns.org
      until: "2026-12-31"
    - field: src_ip
      value: 10.20.0.15
  target:
    connections: [secops-slack]
    emails: [secops@example.com]
---
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: brute-force-file
spec:
  displayName: SSH brute force
  language: sigma
  file: siem/rules/brute-force.yml
  enabled: false
  level: high
---
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: dns-search-rule
spec:
  searchRef: dynamic-dns-lookups
  level: low
  intervalSec: 600
---
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: log4shell-countermeasure
spec:
  countermeasure: 3b1f8a62-7d2e-4c41-9a0b-5e6f7c8d9e01
  severityOverride: critical
  intervalSec: 300
  target:
    connections: [secops-slack]
---
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: sigmahq-aws-root-login
spec:
  sigmahq: rules/cloud/aws/cloudtrail/aws_root_account_usage.yml
  level: high
  suppressSec: 3600
---
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: indicator-domains
spec:
  displayName: Indicator domain resolved
  ioc: ioc-dns
  maxAlertsPerRun: 100
  latenessSec: 120
```

**HCL** (resource `vulnetix_detection_rule`)

```hcl
# Every argument the kind supports. From config-schemas examples/DetectionRule/advanced.yaml.

resource "vulnetix_detection_rule" "dynamic_dns" {
  name               = "dynamic-dns"
  body               = "title: Dynamic DNS lookup\nid: 6f3e0c52-0d4b-4c8e-9a51-2a6b9a0e7d10\nlevel: medium\nlogsource:\n  category: dns_query\ndetection:\n  selection:\n    QueryName|endswith:\n      - .duckdns.org\n      - .no-ip.org\n  condition: selection\n"
  display_name       = "Dynamic DNS lookup"
  enabled            = true
  interval_sec       = 120
  language           = "sigma"
  lateness_sec       = 300
  level              = "medium"
  max_alerts_per_run = 50
  severity_override  = "warning"
  suppress_sec       = 1800
  suppressions = [
    {
      field = "QueryName"
      until = "2026-12-31"
      value = "updates.duckdns.org"
    },
    {
      field = "src_ip"
      value = "10.20.0.15"
    },
  ]
  target = {
    connections = ["secops-slack"]
    emails      = ["secops@example.com"]
  }
  threshold = {
    by         = ["src_ip"]
    count      = 5
    window_sec = 600
  }
  labels = {
    mitre-tactic = "command-and-control"
    team         = "secops"
  }
  annotations = {
    runbook = "https://wiki.example.com/secops/dynamic-dns"
  }
}

resource "vulnetix_detection_rule" "brute_force_file" {
  name         = "brute-force-file"
  display_name = "SSH brute force"
  enabled      = false
  file         = "siem/rules/brute-force.yml"
  language     = "sigma"
  level        = "high"
}

resource "vulnetix_detection_rule" "dns_search_rule" {
  name         = "dns-search-rule"
  interval_sec = 600
  level        = "low"
  search_ref   = "dynamic-dns-lookups"
}

resource "vulnetix_detection_rule" "log4shell_countermeasure" {
  name              = "log4shell-countermeasure"
  countermeasure    = "3b1f8a62-7d2e-4c41-9a0b-5e6f7c8d9e01"
  interval_sec      = 300
  severity_override = "critical"
  target = {
    connections = ["secops-slack"]
  }
}

resource "vulnetix_detection_rule" "sigmahq_aws_root_login" {
  name         = "sigmahq-aws-root-login"
  level        = "high"
  sigmahq      = "rules/cloud/aws/cloudtrail/aws_root_account_usage.yml"
  suppress_sec = 3600
}

resource "vulnetix_detection_rule" "indicator_domains" {
  name               = "indicator-domains"
  display_name       = "Indicator domain resolved"
  ioc                = "ioc-dns"
  lateness_sec       = 120
  max_alerts_per_run = 100
}
```

Every field that has a schema default, set to that default: [`terraform/detection_rule.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/detection_rule.tf) and [`yaml/DetectionRule.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/DetectionRule.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/DetectionRule.schema.json
# A rule names exactly one of body, file, searchRef, countermeasure, sigmahq
# or ioc, so each form has its own document.
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: dynamic-dns
  labels:
    team: secops
    mitre-tactic: command-and-control
  annotations:
    runbook: https://wiki.example.com/secops/dynamic-dns
spec:
  displayName: Dynamic DNS lookup
  language: sigma
  body: |
    title: Dynamic DNS lookup
    id: 6f3e0c52-0d4b-4c8e-9a51-2a6b9a0e7d10
    level: medium
    logsource:
      category: dns_query
    detection:
      selection:
        QueryName|endswith:
          - .duckdns.org
          - .no-ip.org
      condition: selection
  enabled: true
  level: medium
  severityOverride: warning
  intervalSec: 120
  latenessSec: 300
  suppressSec: 1800
  maxAlertsPerRun: 50
  threshold:
    count: 5
    windowSec: 600
    by: [src_ip]
  suppressions:
    - field: QueryName
      value: updates.duckdns.org
      until: "2026-12-31"
    - field: src_ip
      value: 10.20.0.15
  target:
    connections: [secops-slack]
    emails: [secops@example.com]
---
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: brute-force-file
spec:
  displayName: SSH brute force
  language: sigma
  file: siem/rules/brute-force.yml
  enabled: false
  level: high
---
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: dns-search-rule
spec:
  searchRef: dynamic-dns-lookups
  level: low
  intervalSec: 600
---
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: log4shell-countermeasure
spec:
  countermeasure: 3b1f8a62-7d2e-4c41-9a0b-5e6f7c8d9e01
  severityOverride: critical
  intervalSec: 300
  target:
    connections: [secops-slack]
---
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: sigmahq-aws-root-login
spec:
  sigmahq: rules/cloud/aws/cloudtrail/aws_root_account_usage.yml
  level: high
  suppressSec: 3600
---
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: indicator-domains
spec:
  displayName: Indicator domain resolved
  ioc: ioc-dns
  maxAlertsPerRun: 100
  latenessSec: 120
EOF
```

## Fields

Paths use dots for nesting and `[]` for the items of a list. **Required** means required whenever the parent object is present. A default is what the server uses when the field is left out.

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| <span id="apiVersion"></span>`apiVersion` | string | yes |  | exactly `vulnetix.com/v1` | The document format version. Every kind in this release is vulnetix.com/v1. |
| <span id="kind"></span>`kind` | string | yes |  | exactly `DetectionRule` | Always DetectionRule. |
| <span id="metadata"></span>`metadata` | object | yes |  | no other keys |  |
| <span id="metadata-name"></span>`metadata.name` | string | yes |  | pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$` | The object's name, unique per kind within a tenant. It is the natural key: plan, apply, export and the Terraform provider all address an object by kind and name. |
| <span id="metadata-org"></span>`metadata.org` | string | no |  | format `uuid` | The tenant (organization UUID) the document belongs to. When set, plan and apply refuse to run against any other tenant. |
| <span id="metadata-labels"></span>`metadata.labels` | object | no |  | map of string to string (length 0 to 256); keys match `^[a-z0-9]([a-z0-9._/-]{0,61}[a-z0-9])?$` | Free key/value labels. Stored with the object, never interpreted by the server. |
| <span id="metadata-annotations"></span>`metadata.annotations` | object | no |  | map of string to string (length 0 to 4096) | Free key/value notes for people and tools, such as a ticket link. |
| <span id="spec"></span>`spec` | object | yes |  | no other keys |  |
| <span id="spec-displayName"></span>`spec.displayName` | string | no |  | length 1 to 200 | The name the console shows. Defaults to the Sigma rule's title, or the saved search's, countermeasure's or built-in rule's name. |
| <span id="spec-language"></span>`spec.language` | string | no |  | `sigma`, `dsl` | The language of body or file. sigma: a Sigma rule, or several in one multi-document YAML with one correlation rule, which is the one that alerts. dsl: the Guardian search language. Guardian keeps a DSL rule only as a copy of a saved search today, so a dsl body or file has no direct write path yet; use searchRef until Guardian takes DSL rule text. |
| <span id="spec-body"></span>`spec.body` | string | no |  | length 1 to 262144 | The rule text, at most 256 KiB. |
| <span id="spec-file"></span>`spec.file` | string | no |  | length 1 to 1024 | A file holding the rule text, the same as body. |
| <span id="spec-searchRef"></span>`spec.searchRef` | string | no |  | pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$` | The metadata.name of a SavedSearch whose text the rule runs. Its text is copied when the rule is created: editing the search later does not change the rule. |
| <span id="spec-countermeasure"></span>`spec.countermeasure` | string | no |  | format `uuid` | A Vulnesis countermeasure of kind SIGMA, by uuid: the virtual patching lane's detection for a vulnerability. |
| <span id="spec-sigmahq"></span>`spec.sigmahq` | string | no |  | pattern `^[A-Za-z0-9_./-]+\.ya?ml$` | A rule from the SigmaHQ catalogue Guardian imports weekly, by its path in the SigmaHQ repository. Only rules that compile are offered. |
| <span id="spec-ioc"></span>`spec.ioc` | string | no |  | `ioc-dns`, `ioc-net` | A built-in indicator rule. ioc-dns: a domain on an indicator list resolved. ioc-net: a connection to an indicator address. |
| <span id="spec-enabled"></span>`spec.enabled` | boolean | no | `true` |  | Whether the rule runs. A rule that cannot compile is never on, whatever this says. |
| <span id="spec-level"></span>`spec.level` | string | no |  | `informational`, `low`, `medium`, `high`, `critical` | The Sigma level. Defaults to the rule's own level, or medium. |
| <span id="spec-severityOverride"></span>`spec.severityOverride` | string | no |  | `info`, `notice`, `warning`, `critical` | The alert severity, instead of the one the level maps to (informational to info, low to notice, medium to warning, high and critical to critical). |
| <span id="spec-intervalSec"></span>`spec.intervalSec` | integer | no | `60` | 60 to 3600 | Seconds between runs. |
| <span id="spec-latenessSec"></span>`spec.latenessSec` | integer | no | `300` | 0 to 3600 | How long a run waits for late rows before it reads a window, in seconds. |
| <span id="spec-suppressSec"></span>`spec.suppressSec` | integer | no | `900` | 0 to 604800 | Seconds during which a repeat of the same alert is merged into the open one instead of raising another. |
| <span id="spec-maxAlertsPerRun"></span>`spec.maxAlertsPerRun` | integer | no | `50` | 1 to 1000 | Alerts one run may raise. Beyond it, one overflow alert says how many more matched. |
| <span id="spec-threshold"></span>`spec.threshold` | object | no |  | no other keys | Alert only when at least count rows match within windowSec, counted per the by fields. Wraps the detection as a Sigma event_count correlation. |
| <span id="spec-threshold-count"></span>`spec.threshold.count` | integer | yes |  | 1 to 1000000 |  |
| <span id="spec-threshold-windowSec"></span>`spec.threshold.windowSec` | integer | yes |  | 60 to 86400 |  |
| <span id="spec-threshold-by"></span>`spec.threshold.by` | array of string | no |  | 0 to 5 items; each item: length 1 to 80 |  |
| <span id="spec-suppressions"></span>`spec.suppressions` | array of object | no |  | 0 to 50 items | Values that never alert. Each adds a filter on field equal to value to the rule's detection until it lapses. |
| <span id="spec-suppressions-field"></span>`spec.suppressions[].field` | string | yes |  | pattern `^[A-Za-z0-9_.-]{1,80}$` |  |
| <span id="spec-suppressions-value"></span>`spec.suppressions[].value` | string | yes |  | length 1 to 512 |  |
| <span id="spec-suppressions-until"></span>`spec.suppressions[].until` | string | no |  | format `date` | The last day it applies is the day before this date (UTC). Left out, it never lapses. |
| <span id="spec-target"></span>`spec.target` | object | no |  | no other keys | Where the rule's alerts are sent, beyond the Guardian alerts list. |
| <span id="spec-target-connections"></span>`spec.target.connections` | array of string | no |  | 0 to 10 items; items unique; each item: pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$` |  |
| <span id="spec-target-emails"></span>`spec.target.emails` | array of string | no |  | 0 to 20 items; items unique; each item: format `email`; length 0 to 254 |  |

## Rules

Conditions the schema enforces beyond each field's own type. `vulnetix config validate` and the engine's plan report a document that breaks one.

| On | Rule |
|---|---|
| `spec` | When : `language` is required. Otherwise: `language` is not allowed. |
| `spec` | Exactly one of `body`, `file`, `searchRef`, `countermeasure`, `sigmahq` or `ioc` is set. |

## Applying this kind

- **Command.** `vulnetix config apply -f <file>`; the CLI line above says from which release. Plan first with [`vulnetix config plan`](/platform-iac/cli/plan.md): it shows each object as create, update, delete or no change, with a `planHash` that apply then holds to. Apply writes in one transaction, except for the second phase below.
- **Manager.** Each object records the manager that applied it (`terraform`, `console` or `gitops:<repo>`). `--prune` deletes only objects its own manager owns. See [The manager](/platform-iac/cli/plan.md#the-manager) and the [config engine](/platform-iac/reference/engine.md).
- **Order.** Applied after [`SavedSearch`](/platform-iac/kinds/saved-search.md) and [`MessagingConnection`](/platform-iac/kinds/messaging-connection.md), so a document that refers to one by `metadata.name` can be in the same apply. Deleted before them.
- **Second phase.** This kind is not written inside the apply transaction. The other kinds apply and commit first, then each DetectionRule is written on its own, in Guardian. One that fails reports `status.phase: Failed` and a `message`, and nothing is recorded for it. The others stay applied and the apply answers 207. Plan again to see what is left. A single `PUT` from the Terraform provider answers 502 `external_failed` instead.
- **Status.** A failed second-phase write reports phase `Failed` with a `message`. The phases the engine reports are explained under [status phases](/platform-iac/reference/engine.md#status-phases).

## How apply treats it

Written in Guardian, in the second phase; see [SIEM kinds](/platform-iac/reference/engine.md#siem-kinds-written-in-guardian).

- Levers, threshold, target, suppressions, level, display name and a Sigma `body` change in place.
- The source (`searchRef`, `countermeasure`, `sigmahq`, `ioc`, or a body versus another form) cannot move. The plan blocks it: declare the new rule under a new name.
- `sigmahq` is resolved by path through Guardian's catalogue.
- `file` is refused, because the server never reads a path. Send the text as `body`.
- A `dsl` body is refused, because Guardian keeps a DSL rule only as a copy of a saved search. Use `searchRef`.
- A rule Guardian cannot compile stays off whatever `enabled` says, so `enabled` is not a change for it and the plan warns with the compile error.
- `displayName` and `level` default to Guardian's choice, so they are compared only when the document sets them.

## Terraform and OpenTofu

The resource is `vulnetix_detection_rule` in the `vulnetix/resolve` provider. Its arguments are the `spec` in snake case, beside `name`, `labels` and `annotations` from `metadata`. The Minimal and Advanced HCL are above. The provider's own reference is [vulnetix_detection_rule](https://registry.terraform.io/providers/vulnetix/resolve/latest/docs/resources/detection_rule).

Import an object that already exists by its name:

```shell
# Import an existing DetectionRule by its name (metadata.name).
terraform import vulnetix_detection_rule.sigmahq_aws_root_login sigmahq-aws-root-login
```

Install, authentication and how state is read: [Terraform and OpenTofu](/platform-iac/terraform.md).

## More examples

`examples/DetectionRule/rules.yaml` from `Vulnesis/config-schemas`:

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/DetectionRule.schema.json
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: dynamic-dns
spec:
  language: sigma
  body: |
    title: Dynamic DNS lookup
    id: 6f3e0c52-0d4b-4c8e-9a51-2a6b9a0e7d10
    level: medium
    logsource:
      category: dns_query
    detection:
      selection:
        QueryName|endswith:
          - .duckdns.org
          - .no-ip.org
      condition: selection
  threshold: { count: 5, windowSec: 600, by: [src_ip] }
  suppressions:
    - field: QueryName
      value: updates.duckdns.org
      until: "2026-12-31"
  target:
    connections: [secops-slack]
---
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: brute-force-file
spec:
  language: sigma
  file: siem/rules/brute-force.yml
  enabled: false
---
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: log4shell-countermeasure
spec:
  countermeasure: 3b1f8a62-7d2e-4c41-9a0b-5e6f7c8d9e01
  severityOverride: critical
  intervalSec: 300
---
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: sigmahq-aws-root-login
spec:
  sigmahq: rules/cloud/aws/cloudtrail/aws_root_account_usage.yml
  level: high
---
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: indicator-domains
spec:
  ioc: ioc-dns
  maxAlertsPerRun: 100
---
apiVersion: vulnetix.com/v1
kind: DetectionRule
metadata:
  name: dns-search-rule
spec:
  searchRef: dynamic-dns-lookups
  level: low
```

Check a file with `vulnetix config validate -f <file>`. See [Validate documents](/platform-iac/cli/validate.md). In an editor, start the file with the [schema comment](/platform-iac/schemas/editors.md).
