Authoring Detections
Use a coding agent with the nanodac MCP server to draft, validate, and ship YAML detections to your nano deployment
Use a coding agent and the nanodac MCP server to draft, validate, test, and ship detections from your repository. This workflow works on any build, including open core; Self-run also offers in-product drafting with pivt.
This page assumes you've completed Setup: nanodac is installed, the MCP server is wired into your agent, and ~/nano-workspace/rules/ is cloned.
Detection file shape (refresher)
nanodac detections are YAML frontmatter with an nPL search body. One file per detection. Example structure:
---
title: ssh_brute_force
description: Detects SSH brute force with many failed logins from one source IP
author: security-team
severity: high
mode: staging
detection_mode: scheduled
schedule: "*/5 * * * *"
lookback: 15m
folder: identity
mitre_tactics:
- TA0006
mitre_techniques:
- T1110
tags:
- authentication
- brute_force
ai_triage_hints:
ignore_when:
- "Source IP is a known security scanner"
suspicious_when:
- "Multiple usernames targeted from the same IP"
- "Activity outside business hours"
context: "SSH brute force can trigger on legitimate password recovery attempts."
---
metadata.log_source="linux_journald" class_uid=3002 status_id=2
| stats count as attempts, dc(user.name) as users, values(user.name) as targeted_users by src_endpoint.ip
| where attempts > 10
| risk score=70 entity=src_endpoint.ip factor="SSH brute force"The rules/ repo is organized by MITRE tactic. The OCSF rules are in the *-ocsf/ folders (credential_access-ocsf/, lateral_movement-ocsf/, execution-ocsf/ and so on); the folders without the suffix hold legacy rules. Point the agent at the -ocsf folders.
End-to-end workflow
Step 1: Describe what you want to detect
Ask the agent in plain English. Include the data source, behavior, severity, schedule, and output path:
Draft a detection for AWS CloudTrail events showing an IAM user creating an access key for a different user. Use
~/nano-workspace/rules/persistence-ocsf/for tone and structure. MITRE T1098 (Account Manipulation), severity high, scheduled every 5 minutes with a 15-minute lookback. File it underdetections/credential_access/.
The agent will:
- Read 2–3 existing rules in
persistence-ocsf/for shape - Look up the OCSF fields the CloudTrail parser emits (API Activity,
class_uid=6003:api.operation,actor.user.name,src_endpoint.ip), fromparsers-ocsf/aws_cloudtrail/or the OCSF field reference - Draft
detections/credential_access/iam_access_key_for_other_user.yaml
Review the draft. Common things to fix:
- Field names: OCSF 1.9 paths that your
aws_cloudtrailparser actually populates. Search a few events to confirm. mode: should bestagingfor any new detection;liveis reserved for reviewed and tuned rulesrisk score=in the pipeline body: theentity=argument should be the entity that's actually risky (oftensrc_endpoint.iporactor.user.name)
Step 2: Validate
The nanodac MCP server has a validate_detection tool (local checks) and validate_query (server-side query check). Ask the agent:
Validate the new detection.
validate_detection and nanodac validate check the frontmatter: required fields, MITRE ids, cron and lookback. validate_query asks nano whether the query itself compiles, which catches unknown fields. If you don't have MCP wired up, run it manually:
nanodac validateFix reported errors and rerun validation before testing.
Step 3: Test against historical data
Before pushing live, dry-run the detection against real events in your nano deployment:
nanodac test detections/credential_access/iam_access_key_for_other_user.yamlOr via the agent (test_detection): "Test this detection; show me the matches it would have produced over the last 7 days."
nanodac test runs the search body against your deployment's historical data and returns the matching events. Use this to:
- Confirm the rule fires when it should (find a known-good event and verify it matches)
- Estimate noise: if the detection would have produced 500 alerts in the last week, it needs more
whereclauses
If the result looks noisy, ask the agent: "That's too many matches; most are service accounts. Exclude actor.user.name values starting with svc- and re-test."
Step 4: Open a PR
Open a pull request so another analyst can review the query before deployment:
git checkout -b detection/iam-access-key-for-other-user
git add detections/credential_access/iam_access_key_for_other_user.yaml
git commit -m "Add detection: IAM access key created for another user"
git push -u origin detection/iam-access-key-for-other-user
gh pr create --title "Detection: IAM access key for other user" --body "..."The agent can run all of these for you. A reviewer should look at:
- nPL correctness: does the search actually match the described behavior?
- Field name accuracy: do the fields exist in the parsed events?
ai_triage_hints: are the ignore/suspicious lists realistic?- Severity calibration: is
highappropriate, or should this bemedium?
Step 5: Sync to nano
Once merged, CI (or you, locally) runs nanodac sync to push the detection to nano. If you've copied the nanodac GitHub Action and detection-sync.yml workflow into your repository (CI), this happens on merge to main.
Manual sync:
git checkout main && git pull
nanodac sync --dry-run # preview
nanodac sync # applyThe detection lands in staging mode (per its frontmatter). Move it to live to start counting matches without alerting; after a few days at the expected volume, set mode: alerting, open another PR, and re-sync.
Iteration patterns
Tuning a noisy detection. Run nanodac test to get the noisy matches → paste a few false-positive events to the agent → ask it to propose additional where clauses → re-test. Loop until the false-positive rate is acceptable.
Porting an existing rule from another SIEM. Show the agent the source rule (Sigma, KQL, or another SIEM's query language) and the one or two closest nano examples from the rules/*-ocsf/ folders. Ask: "Port this rule to nano nPL format, using these examples for structure." Validate before trusting the output.
Bulk-importing a tactic. Point the agent at a MITRE technique and ask it to draft 3–5 candidate detections covering different angles. Review each candidate individually before validation and testing.
Anti-patterns
- Don't sync directly from your laptop to production. Always go through PR review. The CI-driven sync is there for a reason.
- Don't trust agent-generated
mitre_tactics/mitre_techniquesblindly. Cross-check against attack.mitre.org; agents will sometimes confidently produce technique IDs that don't map to the described behavior. - Don't set
mode: alertingon first commit. Start instaging, bake inliveand watch the match volume, then promote.
Troubleshoot
Need help with these checks? Contact support with the request ID and time with timezone.
A query matches no expected events
Inspect events from the target source and compare their populated OCSF fields with the query. Test against historical data before syncing.
A new rule sends alerts immediately
Check the file’s mode. Start with staging, review matches in live, then promote to alerting through a reviewed change.
What's next
- Crafting searches: use the agent for ad-hoc hunting, not just scheduled detections
- Detection-as-Code: full nanodac CLI reference
- Risk-Based Alerting: how
risk score=chains compose into alerts