nano SIEM
Hunts

Hunt concepts

Supported in:Self-hosted

Learn the parts of a hunt: playbooks, queries, source discovery, findings, the investigator and the reviewer, memory, rulings, and campaigns.

Learn the parts of a hunt before you write or tune one. Each term on the Hunts pages is explained below.

Playbooks

A hunt's playbook says what the hunt tests and how. It has these parts:

PartWhat it is
HypothesisOne or two sentences that say what the hunt believes and what would rule it out. Up to 4,000 characters.
PivotsUp to 12 queries that nano runs on every sweep. No AI is involved.
Risk weightA number from 1 to 10 (default 5). Among hunts that are due, higher runs first.
Default severitycritical, high, medium (default), low, or info. The reviewer can raise a finding's severity, but never lower it.
Escalation modeoff, notify (default), or case. See Escalation.
ReadoutWhether escalations of this hunt need a plain-English summary.

Here is an example hypothesis: "A macro document that starts PowerShell with an encoded command is the first stage of an intrusion. Patch management also runs encoded PowerShell every day, so the parent process and the history of the host decide it."

A playbook with a hypothesis, settings, and three pivots

Pivots

A pivot is one query in the playbook. Each pivot has a role:

  • Discovery pivots find candidates for the investigator. These are the rows that might be the attack.
  • Coverage pivots measure the normal activity around them. For example, a count of all outbound connections shows how much normal traffic surrounds a rare one.

Each pivot reads one dataset:

  • Events (the default): an nPL query over your events. nano adds the sweep's time range.
  • Signals: one SQL SELECT over detections that already fired. Use it for questions nPL can't express.

A pivot can list the source types it needs. If it doesn't, nano reads them from a source_type filter in the query. A pivot with neither runs on any source.

Scorers

A scorer flags unusual rows in a pivot's results. It doesn't use AI.

MethodFlags rows where
zscoreThe value is more than the threshold number of standard deviations from the average
iqrThe value is outside the normal range, widened by the threshold
rareThe value appears no more than the threshold number of times

Hunts created before v2.0.32

Older hunts have no pivots. nano runs their original query as one discovery pivot named primary. The hypothesis comes from the hunt's subtitle or description. The playbook shows v1 until you add pivots.

Source discovery

Each sweep starts by checking which log sources have data in its time window. This step is called discover, and it doesn't use AI. The result, the source inventory, lists each source type with its event count, when it was first and last seen, and which fields it fills in. The AI agents see this list first and use only the sources on it.

If a pivot's sources have no data, nano skips that pivot. It doesn't run and it costs nothing. If nano skips every pivot, the sweep ends as no_coverage without calling an AI model. See Troubleshoot hunts.

Sweeps

A sweep is one run of a hunt over one time window. By default, the window is the last 24 hours. To see a sweep, open the hunt and click it in Sweeps. The sweep shows:

  • the sources it found;
  • each step it ran, with the rows and AI tokens each step used;
  • how much of its budget it used;
  • every query it ran.

A completed sweep, with sources, steps, AI usage, and budget

Findings

The investigator files every candidate it looks at as a finding, not only the suspicious ones. Each finding has one of these labels:

LabelMeaningSet by
leadThe investigator couldn't rule it out. It waits for the reviewer and an analyst.Investigator, or reviewer
benignIt was tested against its most likely harmless explanation, and that explanation held.Investigator, or reviewer
duplicateIt matched something already known: a suppression, a baseline, an earlier finding, or a detection that already fired.Investigator
escalatedThe reviewer escalated it, and it met the escalation bar.Reviewer only

The Findings page opens on Leads, which shows leads and escalated findings. Click Benign, Duplicate, or All to see what the hunt filtered out and why.

The Findings page, filtered to leads

To act on a finding, open it and click one of these:

  • Promote to case: opens a new case for the finding.
  • Dismiss: records why you dismissed it and adds a suppression. You choose whether the suppression applies to this hunt or every hunt, and whether it lasts 30 days, 90 days, or never expires.
  • File under campaign: links the finding to a known attacker.
  • Open in Search: opens the evidence events in Search.

The investigator and the reviewer

Two AI agents look at each sweep. They have different jobs, and you can assign each one its own model.

The investigator:

  1. Reads what earlier runs and your analysts recorded: suppressions, baselines, notes, the last 30 days of findings, rulings, and known attackers.
  2. Reads the pivot results and the detections that fired on the same hosts, users, and IPs.
  3. Runs more read-only queries if it needs them, within the sweep's budget.
  4. Tests each candidate against its most likely harmless explanation.
  5. Labels each candidate lead, benign, or duplicate.
  6. Records what it learned, with the evidence for it.

The investigator can't escalate a finding.

The reviewer checks each lead separately:

  1. It reads the claim and the evidence events. It doesn't see the investigator's reasoning yet.
  2. It checks how common the activity is, the host or user's last 14 days, known-good activity, related alerts, and earlier decisions about the same host or user.
  3. It records a verdict, escalated or benign, with its confidence and the events it relied on.
  4. Only then can it read the investigator's reasoning. It can change its verdict once. nano keeps both verdicts.

nano checks each verdict before it applies it. The reviewer must cite events it actually read, including at least one of the finding's own events. If it doesn't, the finding stays a lead. An escalation must also meet the escalation bar.

A finding the reviewer escalated

If a review fails, the finding stays a lead. To review it again, click Re-review. You need hunts:manage.

Memory

Hunts learn from earlier runs. What they learn is called memory, and you can review it on the Memory page.

TypeWhat it holdsApplies toWritten by
BaselinesNormal behavior of one host, user, or IP, such as known automationOne host, user, or IPInvestigator or analyst
Hunt notesTips and known false positives for one huntOne huntInvestigator or analyst
Environment notesFacts that apply to every huntEvery huntInvestigator or analyst
SuppressionsA harmless pattern that repeatsOne hunt, or every huntAnalyst, or investigator

Memory, showing a baseline the investigator learned

Each row shows who wrote it, how confident they were, the evidence, and when it expires. To stop a row being used, click Revoke. nano keeps revoked rows so a later run can't learn the same thing again.

These rules stop an AI agent from hiding real activity:

  • A suppression that the investigator writes lasts at most 30 days.
  • The investigator can only write a suppression for a pattern it labeled benign in the same run.
  • A suppression that stops matching for 60 days expires early.
  • A finding that an investigator's suppression marks as a duplicate still appears on the Findings page, under Suppressed by the agent. Only an analyst's suppression hides a finding from the default view.

Rulings

A ruling is an analyst's decision about a finding: true_positive, false_positive, benign, duplicate, or not_actionable. nano records a ruling when you:

  • dismiss a finding;
  • close the case that a finding was promoted to;
  • acknowledge an escalation;
  • record a ruling on the finding by hand.

Every later run reads the 50 most recent rulings for its hunt. The reviewer also reads the 20 most recent rulings about the same host, user, or IP. Rulings also measure how accurate the reviewer is. See The case gate.

Campaigns

A campaign tracks one known attacker. It has a name, other names the attacker uses, a description, and up to 8 trip conditions. A trip condition is a query that would show the attacker is back.

BehaviorWhat happens
RecheckEach sweep of a linked hunt checks the campaign when it's due. By default that's every 24 hours. If the trip conditions return no rows, the result is quiet, with no AI call. Otherwise a small AI model decides whether they fired.
Firednano files a finding linked to the campaign. The reviewer checks it like any other lead.
DormantTwo quiet rechecks in a row make the campaign dormant. After 90 days dormant, nano closes it.
Attempts on internet-facing systemsAn attack attempt on an internet-facing system, with no sign that it succeeded, stays a lead and is suggested for a campaign. Scanning doesn't page anyone.
Suggested campaignsThe investigator can suggest a new campaign. It starts dormant and does nothing until an analyst activates it.

To link a campaign to a hunt, open the campaign. Active campaigns raise the hunt's priority.

Detections in hunts

Hunts use your detection rules as evidence:

  • After each events pivot, the investigator sees the detections that fired on the same hosts, users, and IPs.
  • If a detection already covers a finding, the finding is labeled a duplicate and names the rule.
  • The reviewer sees recent detections on the finding's host, user, or IP.
  • The built-in template Detection signals clustering on one entity looks for several different quiet detections firing on the same host, user, or IP.

Rule ideas

When analysts keep promoting the same kind of finding, nano suggests it under Rule ideas. nano suggests an idea only after the pattern appears in 3 sweeps and analysts promote it twice. Click Send to record that you took it to detection as code, or Reject to keep hunting for it instead. A hunt never writes a detection rule itself. Both actions need hunts:manage.

What's next

On this page