Detection Rules & Threat Hunting
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:
| Mode | Runs? | Creates alerts? | Use it for |
|---|---|---|---|
| Staging | No | No | Writing and editing. New rules start here |
| Live | Yes | No | Bake-in. Matches are recorded as findings and counted, but no alert is raised |
| Alerting | Yes | Yes | Production. Matches create alerts for triage |
| Paused | No | No | Temporarily 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, Tags | Shown in alerts and the rule catalog |
Severity (severity) | critical, high, medium, low, informational |
Mode (mode) | staging, live, alerting, paused |
| Query | The 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 > 20A new process whose hash is rare in your environment:
class_uid=1007 | prevalence hash_prevalence < 5 window=7dSee 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 field | Values |
|---|---|
severity | critical, high, medium, low, informational |
mode | staging, live, alerting |
detection_mode | scheduled or real-time (the API spelling, with a hyphen) |
alert_mode | grouped or per_event |
mitre_tactics, mitre_techniques | Set 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,
@detectionopens 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}/triggerqueues a one-off run. The scheduler picks it up within seconds.
Alert modes
alert_mode | Behavior | Use it for |
|---|---|---|
grouped (default) | All matches from one run become one alert | Most rules, especially aggregations |
per_event | Each matched event becomes its own alert | Vendor 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=2004Scheduling
Every rule runs on a cron schedule over its lookback window. Typical choices:
| Rule type | Schedule | Lookback |
|---|---|---|
| IOC and single-event matches | every 1–5 minutes | 5–15 minutes |
| Behavioral thresholds | every 15–30 minutes | 1–4 hours |
| Baselines and rarity | hourly or daily | 1–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:
| Where | Write |
|---|---|
The API (POST /api/rules) | "detection_mode": "real-time", or "realtime_enabled": true |
| A rule file imported from a rule repository | detection_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,lookupand so on); - a bare keyword search (except a
*keyword*wildcard); - an
IN [ ... ]subsearch or theiocterm; - an arithmetic
where-style predicate; - the
spansormetricsdataset.
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,evalorrex), a run that matches more thanDETECTION_MAX_MATCHES_PER_RUNevents (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,timechartand 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}/matchesreportsevents_truncatedwhen 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, severityWhich rules fire most:
metadata.log_source="findings" | stats count by finding_info.analytic.name, finding_info.analytic.state | sort -countFindings 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.
| Symptom | Check |
|---|---|
| A Live rule never matches | Run 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 save | Read 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 alerts | Raise thresholds, add exclusions, use grouped alerts or alert_cooldown_minutes, or add a prevalence filter |
What's next
- Auto Retro-Hunt: run new threat-intel indicators against historical data.
- Alerts: triage what Alerting rules raise.
- Prevalence and Risk-Based Alerting: cut noise with rarity and accumulated entity risk.