nano SIEM
Agents & MCPDetection-as-Code

Authoring Detections

Supported in:Self-hosted

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 under detections/credential_access/.

The agent will:

  1. Read 2–3 existing rules in persistence-ocsf/ for shape
  2. Look up the OCSF fields the CloudTrail parser emits (API Activity, class_uid=6003: api.operation, actor.user.name, src_endpoint.ip), from parsers-ocsf/aws_cloudtrail/ or the OCSF field reference
  3. 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_cloudtrail parser actually populates. Search a few events to confirm.
  • mode: should be staging for any new detection; live is reserved for reviewed and tuned rules
  • risk score= in the pipeline body: the entity= argument should be the entity that's actually risky (often src_endpoint.ip or actor.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 validate

Fix 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.yaml

Or 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 where clauses

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 high appropriate, or should this be medium?

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              # apply

The 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_techniques blindly. 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: alerting on first commit. Start in staging, bake in live and 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

On this page