Clone the nano reference repositories and wire up your coding agent with the nanodac MCP server

Setup

To make a coding agent useful against nano, give it three things:

Reference material — local clones of the parsers, rules, and nanodac repositories so the agent has real examples to learn from
A way to talk to nano — the nanodac MCP server, which exposes detection sync, validation, and search as agent-callable tools
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 all three repos as siblings. The exact layout doesn't matter — the agent will discover 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/nanos-sh/parsers.git
git clone https://github.com/nanos-sh/rules.git
git clone https://github.com/nanos-sh/nanodac.git

You should end up with:

~/nano-workspace/
├── parsers/        # 60+ sample parser.yaml files
├── rules/          # Detection corpus organized by MITRE tactic
└── nanodac/        # CLI + MCP server source

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.

cd ~/nano-workspace/nanodac
pnpm install
pnpm build

# Make the CLI and MCP server runnable from anywhere
pnpm link --global

Verify:

nanodac --help
nanodac-mcp --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 scaffolds:

my-detections/
├── nanodac.config.yaml      # API endpoints + sync defaults
├── detections/              # Your YAML detections live here
└── .github/workflows/       # Optional CI for validate + sync

Edit nanodac.config.yaml to point at your nano deployment:

apiUrl: https://your-nano.example.com:3001
searchUrl: https://your-nano.example.com:3002
detectionsDir: ./detections
defaultSeverity: medium
defaultMode: staging
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"

Generate the key from your nano deployment under Settings → API Keys.

Step 4: Wire up the nanodac MCP server

The MCP server gives your agent direct, typed access to nano: it can list detections, run validation, fetch search results, and trigger syncs without you copy-pasting CLI output.

Drop this into .mcp.json (or mcp-config.json for Cursor) at the root of your detections repo:

{
  "mcpServers": {
    "nanodac": {
      "command": "nanodac-mcp",
      "env": {
        "NANOSIEM_API_URL": "https://your-nano.example.com:3001",
        "NANOSIEM_API_KEY": "${NANOSIEM_API_KEY}",
        "NANOSIEM_SEARCH_URL": "https://your-nano.example.com:3002"
      }
    }
  }
}

This is the same mcp-config.json shape nanodac ships in its own repo. The ${NANOSIEM_API_KEY} reference reads from the shell environment at agent startup — your API key never gets written to disk.

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/` — sample parsers in YAML+VRL format
- `~/nano-workspace/rules/` — sample detections organized by MITRE tactic
- `~/nano-workspace/nanodac/examples/` — canonical detection examples
- `/coding-agents/parsers`, `/coding-agents/detections`, `/coding-agents/search` in nano docs

Always read at least 2 existing examples before drafting a new one.

## Detection conventions

- 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` (via the MCP `validate` tool)
3. Run `nanodac test <file>` 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.

Verify the full setup

Ask your agent:

List the detections currently configured in nano.

If MCP is wired correctly, the agent will call the nanodac MCP server's list tool and return a real list 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.

What's next

Authoring parsers — first end-to-end parser walkthrough
Authoring detections — first end-to-end detection walkthrough
Crafting searches — natural-language hunting

Setup

On this page