nano SIEM
User Guide

Detection Rules & Threat Hunting

Supported in:Self-hosted

Write, test and promote nPL detection rules over OCSF events — lifecycle, scheduling, real-time rules, alert modes and findings.

Write an nPL detection rule to check your OCSF 1.9 events on a schedule. nano records findings when the rule matches and creates alerts when the rule is in Alerting mode.

Rules live under Rules (/rules). From there you can also open MITRE Coverage, AI Tuning, Repositories (detection-as-code), Lookup Tables and IOC Lists.

Rule lifecycle

A rule moves through modes as you gain confidence in it:

ModeRuns?Creates alerts?Use it for
StagingNoNoWriting and editing. New rules start here
LiveYesNoBake-in. Matches are recorded as findings and counted, but no alert is raised
AlertingYesYesProduction. Matches create alerts for triage
PausedNoNoTemporarily stopping an alerting rule without losing its settings

Move rules Staging → Live → Alerting. Leave a rule in Live long enough to see its match volume and false positives against real data, then promote it.

Writing a rule

Open Rules → New Rule. The editor has a form view and a YAML (code) view that round-trip. The main fields:

Field (YAML key)Meaning
Rule name (title)snake_case; used as the alert title
Description, Author, TagsShown in alerts and the rule catalog
Severity (severity)critical, high, medium, low, informational
Mode (mode)staging, live, alerting, paused
QueryThe nPL body
Cron expression (schedule)Five fields: minute hour day-of-month month day-of-week
Lookback (lookback)The window each evaluation reads, from 1 minute to 7 days
Alert mode (alert_mode)grouped or per_event (below)
Tactics, Techniques (mitre_tactics, mitre_techniques)MITRE ATT&CK IDs, e.g. TA0002, T1059.001

Rule queries use OCSF paths. For example, encoded PowerShell on Windows endpoints:

class_uid=1007 process.name="powershell.exe" process.cmd_line="*-enc*"

A threshold rule — many failed sign-ins from one source:

class_uid=3002 status_id=2 | stats count, dc(user.name) as users by src_endpoint.ip | where count > 20

A new process whose hash is rare in your environment:

class_uid=1007 | prevalence hash_prevalence < 5 window=7d

See the nPL command reference and the OCSF field reference for paths such as actor.user.name, device.hostname and file.hashes.value.

Create a rule through the API

POST /api/rules takes JSON with an API key in X-API-Key. Create the key under Settings → Access Control → API keys with the detections:create permission (see API keys and the permissions the detection tools need). name, query and severity are required. A new rule starts in staging unless you set mode. The full request schema is at /api-docs/openapi.json on your nano once you sign in.

curl -sS -X POST "https://nano.example.com/api/rules" \
  -H "X-API-Key: $NANO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "failed_signins_burst",
    "description": "Many failed sign-ins from one source",
    "query": "class_uid=3002 status_id=2 | stats count by src_endpoint.ip | where count > 20",
    "severity": "high",
    "mode": "alerting",
    "detection_mode": "scheduled",
    "schedule_cron": "*/5 * * * *",
    "lookback_minutes": 15,
    "alert_mode": "grouped",
    "mitre_tactics": ["TA0006"],
    "mitre_techniques": ["T1110"]
  }'
JSON fieldValues
severitycritical, high, medium, low, informational
modestaging, live, alerting
detection_modescheduled or real-time (the API spelling, with a hyphen)
alert_modegrouped or per_event
mitre_tactics, mitre_techniquesSet both or neither. One without the other is refused: "MITRE tactics and techniques must either both be empty or both be provided"

The full request schema is at /api-docs/openapi.json on your nano once you sign in.

Generating and testing rules

  • Generate with pivt. Describe the behavior in plain language, and pivt's detection wizard drafts the rule, its MITRE mapping and triage hints. In pivt, @detection opens the same wizard. Review the draft before you save it.
  • Test before you promote. The editor's test runs the query over historical data and shows what it would have matched.
  • Run now. POST /api/rules/{id}/trigger queues a one-off run. The scheduler picks it up within seconds.

Alert modes

alert_modeBehaviorUse it for
grouped (default)All matches from one run become one alertMost rules, especially aggregations
per_eventEach matched event becomes its own alertVendor pass-through (one EDR detection = one alert), IOC matches

max_events_per_alert (default 100) caps how many alerts one per_event run can create.

Set alert_cooldown_minutes to stop the same rule re-alerting on the same entity within that many minutes. The cooldown is time-based and survives restarts.

---
title: crowdstrike_pass_through
mode: alerting
alert_mode: per_event
schedule: "*/1 * * * *"
lookback: 5m
---
metadata.log_source="crowdstrike_falcon" class_uid=2004

Scheduling

Every rule runs on a cron schedule over its lookback window. Typical choices:

Rule typeScheduleLookback
IOC and single-event matchesevery 1–5 minutes5–15 minutes
Behavioral thresholdsevery 15–30 minutes1–4 hours
Baselines and rarityhourly or daily1–7 days

Each rule's start is offset by a fixed amount derived from the rule's ID, so a large rule set spreads across the interval instead of firing on the same second.

Real-time rules

A rule in Real-time detection mode runs as a ClickHouse materialized view: each new batch of events is checked as it is written, so matches arrive within about 10–30 seconds instead of on the next scheduled run.

How to ask for it depends on where the rule comes from:

WhereWrite
The API (POST /api/rules)"detection_mode": "real-time", or "realtime_enabled": true
A rule file imported from a rule repositorydetection_mode: realtime (no hyphen). Any other value imports as a scheduled rule

Real-time mode is for simple filter rules, such as IOC and single-event matches. A rule can't run in real time if it uses:

  • piped commands (stats, where, lookup and so on);
  • a bare keyword search (except a *keyword* wildcard);
  • an IN [ ... ] subsearch or the ioc term;
  • an arithmetic where-style predicate;
  • the spans or metrics dataset.

Saving such a rule in real-time mode is refused with a message that names the reason. Use a scheduled rule instead.

Bounds per run

A scheduled run keeps its memory bounded, so one noisy rule can't take down the service that runs detections.

  • Event rules. For a rule whose results are matching events (a search with where, eval or rex), a run that matches more than DETECTION_MAX_MATCHES_PER_RUN events (default 2,000) evaluates the newest 2,000 events plus the newest event for every distinct value of each field the rule groups alerts by. Grouping, dedup and cooldown then work per entity as usual, so a flood from one host can't hide a quiet one. The run is marked PARTIAL in rule health.
  • Coverage incomplete. If one field has too many distinct values to cover, the run raises a DETECTION COVERAGE INCOMPLETE alert at the rule's severity. Narrow the rule or split it.
  • Other rules. Aggregations (stats, timechart and so on), | risk, prevalence and other commands always read their full input, because a cut would change what they detect.
  • Stored matches. Each stored match row holds at most 512 KiB of events, newest first. The match count stays exact, and GET /api/rules/{id}/matches reports events_truncated when events were left out.
  • Crashes. A rule that keeps crashing the jobs service shows as failing in rule health and retries after a growing delay, from 5 minutes up to 6 hours. A rule that was only running alongside a crash reruns on its own a few minutes later and isn't counted as failing.

DETECTION_MAX_MATCHES_PER_RUN is an environment variable on the service that runs detections (nano-jobs).

Findings: every match is searchable

Every match is written back to your data as an OCSF Detection Finding (class_uid=2004) with metadata.log_source="findings". Live-mode matches are findings with finding_info.types="detection_match"; Alerting-mode matches are "alert". The rule's mode is in finding_info.analytic.state: Active (alerting), Experimental (live) or Suppressed (paused).

Every time a rule fired:

metadata.log_source="findings" finding_info.analytic.name="suspicious_powershell_encoded_execution" | table time, finding_info.analytic.state, risk_score, severity

Which rules fire most:

metadata.log_source="findings" | stats count by finding_info.analytic.name, finding_info.analytic.state | sort -count

Findings also carry the MITRE mapping (finding_info.attacks.technique.uid), the scored entity (resources) and native risk_score / risk_level. Use them for tuning reviews, dashboards and meta-detections — rules over findings. See Risk-Based Alerting.

Rules after a nano-side stage

If a rule uses prevalence, lookup, inputlookup, resolve_identity, ai or lateral, the commands after it run in post-processing, where only where, head, tail, sort, table, stats, dedup, rename, fields, top, rare, fillnull, eval, timechart, rex, risk, reverse and tree are supported. See post-processing after nano-side stages.

AI tuning

Rules → AI Tuning reviews how a rule performs and proposes threshold changes and exclusions. Per rule you can:

  • turn auto-tuning on or off and set the minimum confidence a proposal needs (0.0–1.0);
  • mark a rule critical, which excludes it from auto-tuning;
  • review the version history and revert a change. A revert pauses auto-tuning for that rule for 7 days.

For a rule managed in a detection-as-code repository, tuning changes are proposed as pull requests against the rule's file. pivt's @tune command opens the same tuning wizard.

MITRE ATT&CK coverage

Tag rules with tactic (TA…) and technique (T…) IDs. Rules → MITRE Coverage shows which techniques your rules cover and where the gaps are. The mapping is also stamped on each finding.

Troubleshoot

Need help with these checks? Contact support with the affected deployment, request ID and time with timezone.

SymptomCheck
A Live rule never matchesRun the query in Search over the same lookback, and check that metadata.log_source in the query matches the source your events arrive under. A keyword matches whole tokens only, so "canary" doesn't match canary123; use *canary* or a field match. See Keywords match whole tokens
"Unknown canonical OCSF field"The query uses a name that isn't an OCSF 1.9 path. See Migrating legacy field names
Rule refused on saveRead the message: a query that doesn't parse, an unknown field, a command after a nano-side stage that post-processing can't run, or a real-time rule that isn't a simple filter
Too many alertsRaise thresholds, add exclusions, use grouped alerts or alert_cooldown_minutes, or add a prevalence filter

What's next

On this page