A detection engineer raises a rule's threshold from 10 to 20. The change is stored locally, imported to a SIEM, and possibly even committed to a git repo. However, the underlying “why?” remains confined to DMs, tickets, and the engineer's memory. That critical context frequently vanishes due to operational churn or leaves with the engineer’s departure, leaving the next teammate to decode version diffs, if they exist, wondering why 20 and not 10.
Scaled across hundreds of rules and a few years of turnover, you have the standard state of most contemporary detection programs: version-controlled logic, but unrecorded reasoning.
The missing context costs more as AI-assisted workflows become the norm in detection work. An agent reading a bare rule has the same problem as the new hire: it sees the rule logic and nothing about why. With the journal beside the rule, that agent becomes the fast path to context, surfacing the relevant history in seconds and grounding its guidance in what the team actually decided. It drafts the next entry too, continuing the record over time.
To solve the missing context problem, we are introducing ADEF , the Agentic Detection Engineering Framework, an open source project designed to bridge this gap.
What is ADEF? Operating as a non-intrusive layer above your current detection infrastructure rather than a fork, ADEF interacts with your existing rules in a read-only manner, regardless of their native format. It complements every rule with a companion markdown journal that logs its purpose, characterization, tuning history, and scheduled review dates.
This documentation is driven by a structured five-stage lifecycle known as FORGE:
Find : Identify a coverage gap, threat intelligence report, or hunt result that requires codification.Observe : Analyze baseline telemetry to establish a normal operational profile before defining anomalous behavior.Refine : Validate the logic using backtesting, similarity matches, and overlap checks.Govern : Control deployments through quality gates, defined ownership, and structured review cycles.Evolve : Adapt the rule over time by tuning, deprecating, or replacing it as necessary.Fig. 1 - The FORGE lifecycle: Find, Observe, Refine, Govern, Evolve, with a return loop from Evolve back to Observe.
The journals are not just documentation but part of the ADEF workspace. ADEF provides a queryable catalog of your entire detection inventory. adef detection list --tactic credential-access filters it, adef detection show D-0042 renders a rule alongside its full stage history, and adef detection search "credential dumping" ranks detections by journal reasoning and rule metadata together, so proposed work is checked against existing coverage before it becomes a duplicate rule and duplicate noise.
Agents and agentic support is built into each phase of the lifecycle.
During the Find stage, an agent builds the initial hypothesis and log entries directly from a CTI report. In the Refine stage, executing adef detection refine initiates a three-agent sequence to check for duplicate logic, trigger overlaps, and schema compliance, and saves these findings directly to the rule's journal. Finally, the Evolve stage uses a recommender agent to suggest whether a rule should be maintained, tuned, or retired based on its real-world performance metrics. This setup maintains a clear separation of responsibilities: the journals preserve institutional memory, the lifecycle standardizes the documentation workflow, the agents generate drafts, and human engineers make the final decisions.
Scope and limitations ADEF does not address a lack of functional query options; tools like SQL, KQL, SPL are all perfectly good at expressing detection logic. It also does not aim to replace existing SIEM features or act as a basic metrics dashboard for tracking coverage maps. Instead, it specifically confronts a lifecycle and retention challenge: the absence of a structured, permanent ledger detailing why a specific rule was created, how its logic was verified, and when it requires re-evaluation.
To directly tackle this core challenge, ADEF relies on your existing rule engines rather than introducing another rule format. Rules stay in their native language, and what ADEF stores beside each rule is its own metadata sidecar: a catalog record that captures tagging, cataloging, and enrichment (MITRE, platform, status), and a journal that captures the reasoning, all without ever rewriting the rule itself.
The initial rollout is restricted to a CLI and an MCP server. It doesn’t ship vendor connectors, never connects to your SIEM, and never writes to your rule repo. The system enforces a strict human-in-the-loop control model where autonomous agents function exclusively to provide recommendations for final engineer approval.
Three onboarding paths, regardless of where your rules reside 1. You have an existing detection repo. Point ADEF at your current repository without modifying your original files:
adef catalog /path/to/rules It natively supports Splunk, Sigma, Panther, and raw KQL/SQL/CQL. Proprietary or custom formats can be supported via a simple YAML extraction profile without any custom code. An agent drafts it from your examples, the engine validates it, and you approve it.
2. Your rules live directly within your SIEM or platform. Generate a one-time export (such as a savedsearches.conf, a Sentinel analytics export, or a folder of rule files) and catalog that export. The resulting workspace of records and journals serves as your initial version-controlled detection inventory.
3. You are building a detection program completely from scratch. Author new rules directly inside ADEF using your defined data schema. The workspace serves as your official system of record going forward or until you choose to transition to a dedicated repository.
Teach ADEF your data model; Validate against your data Detections are only as reliable as your knowledge of the data they query. ADEF eliminates the need to connect directly to your SIEM. Simply run a single export, and the framework takes care of the rest. Using built-in ADEF CLI, new detections can utilize an existing data model with the following flow:
Using adef schema recipe prints the exact field-export query required for your specific platform, e.g., Splunk, Sentinel, Elastic, Chronicle, Sumo Logic, or QRadar. From there, adef schema reshape transforms that raw export into a clear, reviewable schema declaration. Finally, adef schema check answers a crucial question that engineering teams struggle with: Do the fields targeted by your detection rules actually exist in your data ? The failure mode this catches is quieter than a syntax error. For instance, in Splunk, a single logon failure event might contain both a raw field and its CIM-normalized counterpart:
Status = 0xc000006d raw field, NTSTATUS codes
status = failure normalized field If a rule queries Status=failure, the syntax is perfectly valid, yet it will fail to return any matches indefinitely. ADEF addresses this during the reshape step by merging these related pairs into a unified declared field complete with aliases. It flags questionable merges where the values of the two distinct spellings share no common ground, while schema check highlights every single rule referencing a field that your environment simply lacks.
This same level of integrity is applied to your coverage tracking. The adef coverage command avoids providing a superficial “vanity” heatmap. Instead, it distinguishes techniques backed by multiple reviewed detections from fragile ones that rely on a single rule or unverified inferences. It exposes techniques dependent on a single log source and uncovers inaccurate or fictional coverage where mapped technique IDs do not exist within ATT&CK at all. Every single mapping, including sub-techniques like T1547.001, is verified against an embedded ATT&CK snapshot, allowing the entire report to be exported as a scored MITRE Navigator layer.
Skills: the conversational layer over the CLI Everything above is deliberately a CLI command. The commands are the scriptable, auditable contracts that do the real work. But a first-time user still faces a question: which command, with which flags, against a repo ADEF may not recognize?
Skills answer it by teaching an AI assistant (Claude Code, Codex, or any MCP client) to drive ADEF rather than just describe it. Without them, an assistant can tell you about adef catalog; with them, one plain-English request runs the whole loop and ends at your approval.
ADEF ships eight skills, each fronting a step you've already met in this post:
Skill Fronts What it does for you
catalog-onboarding adef catalog Walks a repo in; drafts and validates an extraction profile for unknown formats before you approve it
schema-declaration adef schema reshape Turns one SIEM field export into a reviewable schema, and helps you make the merge calls a machine can't
detection-author adef detection new Interviews you for the intent and known false positives an AI can't infer, then scaffolds a schema-grounded draft
coverage-review adef coverage Turns the coverage report into a work plan: the gaps, the single points of failure, what to build next
Four more (catalog-sync, forge-stage, detection-explorer, and mitre-tagger) cover reconciling, lifecycle transitions, browsing, and ATT&CK tagging. You can read more about them in the skills folder of the repo.
The same “agents propose, humans approve” principle still stands. A skill orchestrates the same deterministic CLI you could run by hand, then stops at the decision that needs a human who understands the data.
adef install-skills copies the skills into a .claude/ (or .agents/ for Codex) directory, so a team can commit them into their shared repo and everyone gets them on clone. Solo Claude Code users can instead /plugin install to bundle the skills and wire the adef-mcp server in one step.
ADEF and ATHF, paired siblings If you're familiar with the Agentic Threat Hunting Framework (ATHF), the shape of ADEF will look familiar. This structural parallel is deliberate. While ATHF utilizes the LOCK lifecycle to establish baseline visibility and ask "Is this active in our environment?, ” ADEF employs the FORGE lifecycle to transform that insight into production alerts by answering "How do we codify this to alert our security team? "
Fig 2. - ATHF and ADEF side-by-side: lifecycle, unit-of-work, output, and the planned hunt-promote bridge between them. Author note: The hunt-promote bridge is a design preview in this release; see “What's next” below for its current status.
Getting started with an adoption path Get started by installing from source today; PyPI packaging is delivered alongside the official release.
pip install agentic-detection-engineering-framework The quickstart guide provides a self-contained demonstration with sample rules and data.
We recommend a pragmatic four-week adoption strategy to integrate the framework into your workflow:
Week 1 : Install the tool and manually document a single production rule in the journal OR catalog your existing repository Import and reshape your existing SIEM or vendor data schema Week 2 : Cataloging in week 1 paired every rule with a skeleton journal. Count how many are still blank to measure the scale of your context gap, then work the enrichment queue (adef detection list --needs-review no_mitre) and run a first adef coverage for a baseline.Week 3 : Make it part of your routine. Initialize new rules using adef detection new and log every notable tuning choice in the Evolve history.Week 4 : Link adef-mcp to your IDE to query existing detection memory before submitting a rule PR. Claude Code users can deploy the entire surface, the MCP server plus its skills, through a single plugin install from the repository; Codex users get the same skills via adef install-skills --agent codex. Each skill pairs with a step you have already met by this point in the ramp: catalog-onboarding with adef catalog (Week 1)schema-declaration with adef schema reshape (Week 1)forge-stage with adef detection observe through evolve (Week 3)coverage-review with adef coverage.Fig. 3 - The four-week adoption path, from first install to searchable detection memory. What's next The next phase of this project will focus on building additional functionality as we learn more from the ADEF community.
Two elements of the architecture are currently design previews rather than features:
ATHF Hunt >> ADEF Detection Promotion: When a hunt uncovers a resilient, repeatable signal, adef hunt-promote H-0042 graduates it to a formal detection, preserving the hunt's journal lineage inside the detection's Find phase. Because both frameworks share a CLI and MCP foundation, analysts and agents can move between hunting and detection engineering without a learning curve.Exporting ADEF-authored rules back to your repo: Rules created natively within ADEF remain in its internal catalog for now; writing them back to an external repository is deferred until teams explicitly need that migration.The nearest work to be completed, with the first two items exposed by schema checking itself:
Value-aware schema checking : When a platform exposes the same fact under two field spellings, each spelling matches only its own values, and a folded field keeps only the canonical spelling's values today. A query written against the other spelling (Status=failure, in the Splunk example above) is legal per schema yet never matches. The next release keeps values per spelling and catches this class of silent failure at check time.Abstracted field layers as schema sources : Some rules query fields that exist only in a platform's normalized or accelerated data layer, never in a raw field export (in Splunk's data models, Processes.process_name; roughly 39 percent of ESCU's 2,113 active detections). Declaring those layers as schema sources closes the blind spot.Staleness warnings when the catalog falls behind the rule repo. Fuzzy matching for renamed rules : Today a renamed rule surfaces as new; a wrong automatic match is worse than a manual merge.A detection stats seam feeding false-positive and volume data into Evolve decision Looking further ahead, our long-term target remains the improvement of the ADEF automated flow. adef detection new --from-intel <url> will draft a backtested, documented detection straight from a threat intelligence report. Throughout these iterations, our core operational principle holds: agents propose, but humans approve.
Find ADEF on Github ADEF is MIT-licensed and on GitHub , with the full FORGE methodology in docs/methodology.md .
As with any open source project, the work is never done. We look forward to continually improving this project with the detection community. If you deploy this release against your detection repository and encounter unexpected behavior, please file an issue .
Thank you to early contributors and reviewers: Chris Witter , Lauren Proehl , Alex Hurtado , and others.
.webp)
.webp)