Setup
Install the nanodac CLI from npm and wire up your coding agent with the nanodac MCP server
Set up nanodac and its MCP server so your coding agent can validate detections, search data, and sync rules to nano. Give the agent reference repositories and project instructions before you ask it to author rules.
Prepare these three parts:
- Reference material: local clones of the
parsersandrulesrepositories so the agent has real examples to learn from - A way to talk to nano: the
nanodacCLI and its MCP server, which expose detection sync, validation, and search as agent-callable tools - Repo-specific instructions: a
CLAUDE.md(orAGENTS.md) file that tells the agent your conventions
This page walks through all three.
Step 1: Clone the reference repositories
Pick a workspace directory and clone both reference repos as siblings. The exact layout doesn't matter (the agent discovers them by path), but keeping them as siblings of your detections repo is the convention used in these docs.
mkdir -p ~/nano-workspace && cd ~/nano-workspace
git clone https://github.com/nano-rs/parsers.git
git clone https://github.com/nano-rs/rules.gitYou should end up with:
~/nano-workspace/
├── parsers/ # parser.yaml files; OCSF 1.9 parsers are under parsers-ocsf/
└── rules/ # Detection rules by MITRE tactic; OCSF rules are in *-ocsf/ foldersThe main branch of both holds the OCSF 1.9 parsers and rules. Pull these regularly: the upstream repos are where new vendor support and detection coverage lands first.
Step 2: Install nanodac
nanodac is the CLI that validates detections, syncs them to your nano deployment, and exposes those operations to your agent over MCP. It's published to npm as @nano-rs/dac-cli — no clone or build. Install it globally so the nanodac command is on your PATH:
npm install -g @nano-rs/dac-cliOr skip the install and run any command through npx @nano-rs/dac-cli <command>.
Verify:
nanodac --helpStep 3: Create your detections repo
This is where your agent will write. Keep it separate from the reference repos so updates don't conflict with your work.
cd ~/nano-workspace
mkdir my-detections && cd my-detections
git init
nanodac initnanodac init writes nanodac.config.yaml and detections/example_detection.yaml. It doesn't create a CI workflow; copy one from the nanodac repository if you want it (see CI).
Edit nanodac.config.yaml to point at your nano deployment:
apiUrl: https://nano.example.com # your nano base URL
detectionsDir: ./detections
sync:
deleteOrphans: false
confirmDestructive: trueSet the API key in your shell environment (do not commit it):
export NANOSIEM_API_KEY="your-api-key-here"Create the key in nano under Settings → API Keys, scoped to the permissions in API key permissions below.
Step 4: Wire up the nanodac MCP server
The MCP server (nanodac-mcp) gives your agent direct access to nano and to your detections repository: it can list and test detections, run searches, write detection files, open branches and pull requests, and import rules from rule repositories.
Drop this into .mcp.json (or mcp-config.json for Cursor) at the root of your detections repo:
{
"mcpServers": {
"nanodac": {
"command": "npx",
"args": ["-y", "@nano-rs/dac-mcp-server"],
"env": {
"NANOSIEM_API_URL": "https://nano.example.com",
"NANOSIEM_API_KEY": "${NANOSIEM_API_KEY}"
}
}
}
}Restart your agent. In Claude Code, run /mcp to confirm nanodac shows as connected. In Cursor, the MCP panel will list it under Available Servers.
Step 5: Give the agent your conventions
Without instructions, an agent will produce plausible-looking output that drifts from your team's style. A short instructions file fixes this.
Create CLAUDE.md (or AGENTS.md, or both; they can be identical) at the root of your detections repo:
# Detection Engineering — agent instructions
## Reference repositories
When asked to author or modify detections, parsers, or searches, consult:
- `~/nano-workspace/parsers/parsers-ocsf/` — OCSF 1.9 parsers in YAML+VRL format
- `~/nano-workspace/rules/*-ocsf/` — OCSF detections organized by MITRE tactic
- https://github.com/nano-rs/nanodac/tree/main/examples — canonical detection examples
- `/agents/detection-as-code/parsers`, `/agents/detection-as-code/detections`, `/agents/detection-as-code/search` in nano docs
Always read at least 2 existing examples before drafting a new one.
## Detection conventions
- Fields are OCSF 1.9 paths (`src_endpoint.ip`, `user.name`, `device.hostname`, `process.cmd_line`, `metadata.log_source`). Never invent field names; check https://nano.rs/docs/reference/ocsf-fields/
- New detections start with `mode: staging` — never `live` until reviewed
- Always include `mitre_tactics` and `mitre_techniques`
- Always include `ai_triage_hints` with `ignore_when` and `suspicious_when` lists
- Use `risk score=` instead of bare `where` for severity tuning
- File goes under `detections/<tactic>/<descriptive_name>.yaml`
## Workflow
1. Draft the detection in a new branch
2. Run `nanodac validate` (or the MCP `validate_detection` tool)
3. Run `nanodac test <file>` (or `test_detection`) to sanity-check against historical data
4. Open a PR — never push to main directly
5. After merge, CI runs `nanodac sync` to deployTune this to your team. The agent will read it on every session start.
MCP tools
The server registers 26 tools:
| Group | Tools |
|---|---|
| Detections | list_detections, get_detection, create_detection, update_detection, validate_detection (local), validate_query (server-side), test_detection |
| Lifecycle | promote_detection, demote_detection, trigger_detection |
| Search and help | search, get_schema (the detection file format), generate_hints (placeholder: points you to the UI) |
| Git and GitHub | create_branch, write_detection_file, commit_and_push, create_pull_request, get_current_branch, sync_repo, create_issue, list_issues |
| Rule repositories | list_repositories, sync_repository, browse_repository, import_rule, get_coverage |
And five prompts: new_detection_workflow, generate_detection, tune_detection, explain_detection and suggest_hints.
API key permissions
nanodac sends the key in NANOSIEM_API_KEY as the X-API-Key header. A nano key carries an explicit permission list; it doesn't inherit a role. Scope it to what you use:
- nano API tools need the permissions below.
- GitHub tools (
create_issue,list_issues,create_pull_request) use yourghCLI login, not a nano permission. - Local tools (
create_branch,write_detection_file,commit_and_push,get_current_branch,sync_repo,get_schema,validate_detection) need no permission.
| Capability | Tools and commands | Permission |
|---|---|---|
| Read rules | list_detections, get_detection, nanodac diff | detections:view |
| Check a query | validate_query | detections:view |
| Test against your data | test_detection, nanodac test | detections:create |
| Create rules | create_detection, nanodac sync | detections:create |
| Update rules | update_detection, nanodac sync | detections:edit |
| Delete orphaned rules | nanodac sync with deleteOrphans | detections:delete |
| Change mode, run now | promote_detection, demote_detection, trigger_detection | detections:promote |
| Search | search | search:execute |
| Rule repositories | list_repositories, browse_repository, get_coverage | rule_repositories:view |
| Rule repositories: write | sync_repository, import_rule | rule_repositories:sync, rule_repositories:import |
| Register a rule repository | nanodac repo add | rule_repositories:manage |
Minimal vs full key
Validate, test and read (a typical review or CI key):
[ "detections:view", "detections:create", "search:execute" ]detections:create is there because testing a query uses the rule-test endpoint, which needs it.
Full detection-as-code:
[
"detections:view", "detections:create", "detections:edit", "detections:delete",
"detections:promote", "search:execute",
"rule_repositories:view", "rule_repositories:sync", "rule_repositories:import"
]Drop detections:delete if you keep sync.deleteOrphans: false.
API keys can call every rule and rule-repository route nanodac uses, with the permissions above. That includes updating a rule (PUT /api/rules/{id}, detections:edit).
Create a scoped key
Under Settings → API Keys, create a key with the permissions above. You can only grant permissions your own account holds.
Verify the full setup
Ask your agent:
List the detections currently configured in nano.
If MCP is wired correctly, the agent calls list_detections and returns the rules from your deployment. If it asks you to run a CLI command instead, the MCP connection isn't live: re-check .mcp.json and that NANOSIEM_API_KEY is exported in the shell that launched the agent.
Troubleshoot
Need help with these checks? Contact support with the request ID and time with timezone.
The agent cannot list detections
Confirm the MCP connection, NANOSIEM_API_URL, and the API key in the environment used to launch the agent. The key needs detections:view to list rules.
What's next
- Authoring parsers: first end-to-end parser walkthrough
- Authoring detections: first end-to-end detection walkthrough
- Crafting searches: natural-language hunting