nano SIEM
Agents & MCPDetection-as-Code

Setup

Supported in:Self-hosted

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:

  1. Reference material: local clones of the parsers and rules repositories so the agent has real examples to learn from
  2. A way to talk to nano: the nanodac CLI and its MCP server, which expose detection sync, validation, and search as agent-callable tools
  3. Repo-specific instructions: a CLAUDE.md (or AGENTS.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.git

You 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/ folders

The 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-cli

Or skip the install and run any command through npx @nano-rs/dac-cli <command>.

Verify:

nanodac --help

Step 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 init

nanodac 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: true

Set 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 deploy

Tune this to your team. The agent will read it on every session start.

MCP tools

The server registers 26 tools:

GroupTools
Detectionslist_detections, get_detection, create_detection, update_detection, validate_detection (local), validate_query (server-side), test_detection
Lifecyclepromote_detection, demote_detection, trigger_detection
Search and helpsearch, get_schema (the detection file format), generate_hints (placeholder: points you to the UI)
Git and GitHubcreate_branch, write_detection_file, commit_and_push, create_pull_request, get_current_branch, sync_repo, create_issue, list_issues
Rule repositorieslist_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 your gh CLI 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.
CapabilityTools and commandsPermission
Read ruleslist_detections, get_detection, nanodac diffdetections:view
Check a queryvalidate_querydetections:view
Test against your datatest_detection, nanodac testdetections:create
Create rulescreate_detection, nanodac syncdetections:create
Update rulesupdate_detection, nanodac syncdetections:edit
Delete orphaned rulesnanodac sync with deleteOrphansdetections:delete
Change mode, run nowpromote_detection, demote_detection, trigger_detectiondetections:promote
Searchsearchsearch:execute
Rule repositorieslist_repositories, browse_repository, get_coveragerule_repositories:view
Rule repositories: writesync_repository, import_rulerule_repositories:sync, rule_repositories:import
Register a rule repositorynanodac repo addrule_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

On this page