Manage nano detections as version-controlled YAML with @nano-rs/dac-cli — validate, test, diff, and sync detection rules from your terminal or CI

nanodac CLI

@nano-rs/dac-cli (nanodac) brings GitOps to detection engineering. Detection rules live as YAML files in a git repo — so you get version control, peer review, and CI/CD — and nanodac validates them, tests them against historical data, and syncs them to your nano deployment.

npx @nano-rs/dac-cli init

Why detection-as-code

A UI rule editor tracks changes in an audit log but offers no review gate and no easy rollback. Managing detections as code closes both gaps: every change carries git history and author rationale, ships behind PR approval, and reverts with git revert. New rules land in staging and graduate to alerting only once an analyst has validated them.

Install

# Global — puts `nanodac` on your PATH
npm install -g @nano-rs/dac-cli

# …or run any command without installing
npx @nano-rs/dac-cli <command>

Quick start

# Scaffold a detections repo (config + detections/ + CI workflow)
nanodac init

# Point nanodac.config.yaml at your deployment, then set the key
export NANOSIEM_API_KEY="your-api-key"

# Author a detection under detections/, then:
nanodac validate              # schema + nPL + MITRE + cron checks
nanodac test detections/brute_force_ssh.yaml   # preview matches on real data
nanodac diff                  # what would change on the deployment
nanodac sync --dry-run        # preview the sync plan
nanodac sync                  # push to nano

The API key authenticates with the X-API-Key header and carries an explicit permission list — no role inheritance. Scope it to least privilege: read/validate/test needs detections:view + search:execute; authoring and sync add detections:create/detections:edit/detections:promote. The full matrix is in Setup → API key permissions.

Detection file format

YAML frontmatter (metadata) followed by the nPL query body:

---
title: brute_force_ssh
description: Detects SSH brute force from a single source IP
severity: high
mode: staging
schedule: "*/5 * * * *"
lookback: 15m
mitre_tactics: TA0006
mitre_techniques: T1110
ai_triage_hints:
  ignore_when: ["Source IP is a known security scanner"]
  suspicious_when: ["Multiple usernames targeted from same IP"]
---
source_type="ssh_logs" event_type="login_failed"
| stats count() as attempts by src_ip
| where attempts > 10
| risk score=70 entity=src_ip factor="SSH brute force"

CI/CD

nanodac init scaffolds a GitHub Actions workflow that runs nanodac validate on pull requests and nanodac sync on merge to main. New rules deploy in staging until an analyst promotes them. The companion MCP server (@nano-rs/dac-mcp-server) lets a coding agent author and sync detections for you.

Next steps

Detection-as-Code overview — the full workflow, file format, and CLI reference
Setup — reference repos, the MCP server, and agent instructions
Authoring detections — first end-to-end detection walkthrough

nanodac CLI

nanodac CLI

Why detection-as-code

Install

Quick start

Detection file format

CI/CD

Next steps

On this page