Detection-as-Code
Manage nano detections as version-controlled YAML and ship them with the nanodac CLI and MCP server
Manage your detections as YAML files in Git to review changes and reproduce deployments. Use nanodac to validate files, test queries against your data, and sync rules to nano; its MCP server exposes the same operations to a coding agent.
These pages describe @nano-rs/dac-cli and @nano-rs/dac-mcp-server 0.1.0.
Why Detection-as-Code
| UI-based editing | Detection-as-Code |
|---|---|
| Changes tracked in the audit log | Full git history with author and rationale |
| No built-in review gate | Pull-request approval before deploy |
| Manual deployment | CI validates and syncs |
| Rollback by hand | git revert, then sync |
A detection moves through modes as it earns trust:
| Mode | Purpose | Output |
|---|---|---|
staging | Development; not executed | None |
live | Bake-in: runs and records matches | Findings, no alerts |
alerting | Production | Alerts |
paused | Temporarily stopped | None |
With or without pivt
nano Self-run includes pivt, which drafts detections from a description and tunes them against your data inside the product. The open-core build doesn't include pivt. There, a coding agent (Claude Code, Codex, Cursor) fills the gap by reading the reference repositories and authoring the same files.
| With pivt | With a coding agent |
|---|---|
| Generate a parser from a pasted sample | The agent reads parsers-ocsf/ examples, drafts parser.yaml, and you validate it |
| Draft a detection from "alert me when…" | The agent reads rules/ examples and drafts YAML; nanodac validate checks it |
| Turn a question into nPL | The agent reads the search commands docs and drafts the query |
| AI rule tuning | Review matches with nanodac test, iterate by pull request |
The agent runs on your machine or in your CI, so samples and detection logic stay in your environment. You can use both approaches on any deployment.
Reference repositories
| Repository | Purpose |
|---|---|
nano-rs/parsers | Parsers (parser.yaml with VRL). main holds the OCSF 1.9 parsers under parsers-ocsf/. |
nano-rs/rules | Detection rules by MITRE tactic. On main, rules are in the *-ocsf/ folders, such as credential_access-ocsf/. Licensed DRL 1.1. |
nano-rs/nanodac | The CLI, MCP server and GitHub Action |
When nano syncs nano-rs/parsers or nano-rs/rules itself, it follows the main branch. A repository still registered on the retired ocsf-1.9 branch is moved to main automatically.
nanodac essentials
Install
npm install -g @nano-rs/dac-cli # puts `nanodac` on your PATH
npx @nano-rs/dac-cli --help # or run without installingCreate a detections repository:
mkdir my-detections && cd my-detections
git init
nanodac initinit writes two files: nanodac.config.yaml and detections/example_detection.yaml. It doesn't create a CI workflow; see CI.
Configure
nanodac finds nanodac.config.yaml (or nanodac.config.yml, or nanodac.yaml) by searching up from the current directory.
apiUrl: https://nano.example.com # your nano base URL
detectionsDir: ./detections # relative to this file
sync:
deleteOrphans: false # delete remote rules with no local file
confirmDestructive: true # stop before updates or deletes unless --force| Key | Meaning |
|---|---|
apiUrl | nano API base URL |
searchUrl | Search service URL, only when it isn't behind apiUrl (split services) |
detectionsDir | Where detection files live |
repoUrl | This repository's URL, sent with each rule as provenance. Not in the published 0.1.0 package, which ignores it. |
sync.deleteOrphans | true deletes remote rules that have no local file. Default false. |
sync.confirmDestructive | true (default) stops a sync that would update or delete rules unless you pass --force |
defaultSeverity, defaultMode and defaultDetectionMode are accepted in the file but not used by any command.
Set the API key in the environment (never in the config file):
export NANOSIEM_API_KEY=your-api-key.env and .env.local files are also read. See Setup for the permissions the key needs.
Detection file format
A detection is YAML frontmatter followed by the nPL query. This is credential_access-ocsf/kerberoasting.yml from nano-rs/rules:
---
title: kerberoasting_activity
description: Detects Kerberos service ticket requests (TGS) for multiple SPNs, indicative of Kerberoasting attacks.
author: nano.rs
severity: high
mode: live
detection_mode: scheduled
schedule: "*/3 * * * *"
lookback: 15m
folder: identity
mitre_tactics:
- TA0006
mitre_techniques:
- T1558.003
tags:
- kerberos
- kerberoasting
- active_directory
ai_triage_hints:
ignore_when:
- "Service account performing legitimate ticket requests"
- "Known vulnerability scanner activity"
suspicious_when:
- "Single user requesting many service tickets"
- "Tickets requested with RC4 encryption"
---
metadata.log_source IN ("windows_event", "windows_security", "auth_logs") class_uid=3002
| where metadata.event_code="4769" OR activity_id=4
| stats count, dc(dst_endpoint.hostname) as unique_targets, values(unmapped.service_name) as services, min(time) as time by user.name, src_endpoint.ip
| where count > 10 AND unique_targets > 5
| eval esc_likely_kerberoasting=(unique_targets > 15)
| risk score=min(100, 75 + if(esc_likely_kerberoasting, 15, 0)) entity=user.name factor=concat("Multiple TGS requests", if(esc_likely_kerberoasting, "; Likely Kerberoasting", ""))
| table time, user.name, src_endpoint.ip, services, count, unique_targets, risk_score, risk_factorsRequired fields:
| Field | Values |
|---|---|
title | Snake_case identifier. sync matches local and remote rules by title. |
severity | critical, high, medium, low, informational |
mode | staging, live, alerting, paused |
detection_mode | scheduled or realtime. In a rule file, any other value (including real-time, the API's spelling) imports as a scheduled rule |
| query body | nPL after the frontmatter |
Optional fields:
| Field | Meaning |
|---|---|
description, author | Free text |
schedule | Cron expression (scheduled rules) |
lookback | Search window, for example 15m, 1h, 24h |
folder | Grouping in the rules list |
mitre_tactics, mitre_techniques | ATT&CK ids (TA####, T#### or T####.###) |
tags | List of tags |
alert_mode | grouped (one alert for all matches) or per_event |
ai_triage_hints | ignore_when, suspicious_when and context for analysts and AI triage |
reference_url | Link to background on the technique |
realtime_enabled | Run as a real-time rule |
auto_tuning | enabled, min_confidence, critical, mode |
requires | fields and source names the rule depends on |
case_visibility, case_groups | Who can see cases the rule creates |
playbook, playbook_id, playbook_selector_mode | Response playbook to attach |
Risk isn't set in frontmatter. Score an entity in the query with the risk command:
class_uid=3002 status_id=2 | stats count by user.name | where count > 20 | risk score=80 entity=user.name factor="Repeated failed logins"CLI commands
| Command | Purpose | Flags |
|---|---|---|
nanodac init | Scaffold config and an example rule | -d, --directory |
nanodac validate [files…] | Check frontmatter, required fields, MITRE ids, cron and lookback. Runs locally, no API call. | --strict (warnings fail) |
nanodac test <file> | Run the rule's query against your data and show matches | -d, --days (7), -H, --hours, -l, --limit (3), -a, --all, -f, --fields, -c, --compact |
nanodac diff | Compare local files with the rules in nano | -v, --verbose |
nanodac sync | Create, update and (with sync.deleteOrphans) delete rules to match local files | --dry-run, --force, --env |
nanodac pull | git pull the base branch, stashing local changes first | -b, --branch (main), --no-stash |
nanodac issue create / issue list | GitHub issues for detection work (uses the gh CLI) | see --help |
nanodac repo list / add / sync / browse / import | Manage rule repositories connected to nano and import rules from them | see --help |
There is no --delete-orphans flag; set sync.deleteOrphans: true in the config.
CI with GitHub Actions
The nanodac repository ships a GitHub Action (packages/github-action) and example workflows in examples/workflows/ (detection-sync.yml, detection-pr-review.yml, detection-full-sync.yml). To use them, copy the action directory into your repository as .github/actions/nanodac and a workflow into .github/workflows/.
detection-sync.yml validates on pull requests and deploys on push to main:
name: Detection Sync
on:
push:
branches: [main]
paths: ['detections/**']
pull_request:
paths: ['detections/**']
jobs:
validate:
runs-on: ubuntu-latest
if: github.event_name == 'pull_request'
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
- uses: ./.github/actions/nanodac
with:
nanosiem-url: ${{ secrets.NANOSIEM_URL }}
api-key: ${{ secrets.NANOSIEM_API_KEY }}
action: validate
github-token: ${{ secrets.GITHUB_TOKEN }}
deploy:
runs-on: ubuntu-latest
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
steps:
- uses: actions/checkout@v4
- uses: ./.github/actions/nanodac
with:
nanosiem-url: ${{ secrets.NANOSIEM_URL }}
api-key: ${{ secrets.NANOSIEM_API_KEY }}
action: deployAction inputs: nanosiem-url, api-key, search-url, detections-dir (default detections), action (validate, deploy or both), strict, dry-run, delete-orphans (default false) and github-token.
Add NANOSIEM_URL and NANOSIEM_API_KEY as repository secrets. New rules land in the mode their file sets; keep new rules in staging until an analyst promotes them.
Troubleshoot
Need help with these checks? Contact support with the request ID and time with timezone.
A sync stops before changing rules
With sync.confirmDestructive enabled, updates and deletes require --force. Review nanodac sync --dry-run before applying the change.
Remote rules disappear during sync
Check sync.deleteOrphans. When enabled, sync deletes remote rules with no matching local file.
What's next
- Setup: reference repositories, the nanodac MCP server, agent instructions and key permissions
- Authoring parsers: draft an OCSF parser from a log sample
- Authoring detections: draft, validate, test and ship a rule
- Crafting searches: turn hunting questions into nPL
For the operations side, see Investigator.