Every detection rule is a YAML document. This page covers the rule structure, required fields, and how to organize your rules.
File Structure
A rule file contains reusable components (lists and macros) followed by rules. Components are defined first, then rules reference them:
# 1. Reusable components (defined at file level, before rules)
- list: monitored_addresses
items:
- "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
- macro: is_high_value
condition: tx.value > 100 ether
# 2. Rules (reference components defined above)
- rule: High Value Transfer to Monitored Address
desc: Detects large transfers to monitored addresses
tags: ["security", "high-value"]
condition: >
is_high_value and tx.to in (monitored_addresses)
output: >
High value transfer detected: %tx.value_eth ETH to %tx.to
priority: WARNING
chain: ["ethereum"]
enabled: true
Important: lists and macros are NOT fields within a rule. They are separate components defined at the file level (before rules) that can be reused by multiple rules in the same file. See Lists & Macros for details. Required Fields
Every rule must include these fields:
| Field | Type | Description | Example |
|---|
rule | string | Unique rule name | High Value Transfer |
desc | string | Human-readable description | Detects transfers over 100 ETH |
condition | string | Detection condition expression | tx.value > 100 ether |
output | string | Alert message with placeholders | Large transfer: %tx.value_eth ETH |
priority | string | Alert priority: NOTICE, WARNING, or CRITICAL | WARNING |
enabled | boolean | Whether rule is active | true |
Optional Fields
| Field | Type | Description | Example |
|---|
tags | array | Tags for categorization | ["security", "high-value"] |
chain | array | Target blockchain(s). If not specified, applies to all enabled chains | ["ethereum", "polygon"] |
references | array | URLs to threat intelligence, blog posts, or documentation | ["https://rekt.news/..."] |
Recommended Field Order
For consistency, follow this field order within each rule:
rule - Rule identifierdesc - Descriptionreferences - Threat intelligence links (optional)tags - Categorization tags (optional)condition - Detection logicoutput - Alert messagepriority - Severity levelchain - Target networks (optional)enabled - Activation status
The validator will warn if fields are out of order, but won’t block validation. This helps maintain consistency across your rule base.
References Field
The references field allows you to document threat intelligence sources, blog posts, exploit analyses, or any relevant context for your detection rule.
Example
- rule: Euler Finance Exploit Pattern
desc: Detects donation attack pattern similar to Euler Finance hack (March 2023)
references:
- "https://rekt.news/euler-finance-rekt/"
- "https://twitter.com/BlockSecTeam/status/1635527807996932096"
tags: ["defi", "flash-loan", "exploit"]
condition: >
tx.logs.any(event_name == "Donate") and
tx.value > 10 ether
output: >
Potential donation attack detected - Value: %tx.value_eth ETH
priority: CRITICAL
chain: ["ethereum"]
enabled: true
dry-run, the references will be displayed in the output.
Next Steps
