nano SIEM
Agents & MCPDetection-as-Code

Detection-as-Code

Supported in:Self-hosted

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 editingDetection-as-Code
Changes tracked in the audit logFull git history with author and rationale
No built-in review gatePull-request approval before deploy
Manual deploymentCI validates and syncs
Rollback by handgit revert, then sync

A detection moves through modes as it earns trust:

ModePurposeOutput
stagingDevelopment; not executedNone
liveBake-in: runs and records matchesFindings, no alerts
alertingProductionAlerts
pausedTemporarily stoppedNone

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 pivtWith a coding agent
Generate a parser from a pasted sampleThe 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 nPLThe agent reads the search commands docs and drafts the query
AI rule tuningReview 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

RepositoryPurpose
nano-rs/parsersParsers (parser.yaml with VRL). main holds the OCSF 1.9 parsers under parsers-ocsf/.
nano-rs/rulesDetection rules by MITRE tactic. On main, rules are in the *-ocsf/ folders, such as credential_access-ocsf/. Licensed DRL 1.1.
nano-rs/nanodacThe 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 installing

Create a detections repository:

mkdir my-detections && cd my-detections
git init
nanodac init

init 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
KeyMeaning
apiUrlnano API base URL
searchUrlSearch service URL, only when it isn't behind apiUrl (split services)
detectionsDirWhere detection files live
repoUrlThis repository's URL, sent with each rule as provenance. Not in the published 0.1.0 package, which ignores it.
sync.deleteOrphanstrue deletes remote rules that have no local file. Default false.
sync.confirmDestructivetrue (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_factors

Required fields:

FieldValues
titleSnake_case identifier. sync matches local and remote rules by title.
severitycritical, high, medium, low, informational
modestaging, live, alerting, paused
detection_modescheduled or realtime. In a rule file, any other value (including real-time, the API's spelling) imports as a scheduled rule
query bodynPL after the frontmatter

Optional fields:

FieldMeaning
description, authorFree text
scheduleCron expression (scheduled rules)
lookbackSearch window, for example 15m, 1h, 24h
folderGrouping in the rules list
mitre_tactics, mitre_techniquesATT&CK ids (TA####, T#### or T####.###)
tagsList of tags
alert_modegrouped (one alert for all matches) or per_event
ai_triage_hintsignore_when, suspicious_when and context for analysts and AI triage
reference_urlLink to background on the technique
realtime_enabledRun as a real-time rule
auto_tuningenabled, min_confidence, critical, mode
requiresfields and source names the rule depends on
case_visibility, case_groupsWho can see cases the rule creates
playbook, playbook_id, playbook_selector_modeResponse 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

CommandPurposeFlags
nanodac initScaffold 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 diffCompare local files with the rules in nano-v, --verbose
nanodac syncCreate, update and (with sync.deleteOrphans) delete rules to match local files--dry-run, --force, --env
nanodac pullgit pull the base branch, stashing local changes first-b, --branch (main), --no-stash
nanodac issue create / issue listGitHub issues for detection work (uses the gh CLI)see --help
nanodac repo list / add / sync / browse / importManage rule repositories connected to nano and import rules from themsee --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: deploy

Action 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

For the operations side, see Investigator.

On this page