nano SIEM
Agents & MCPDetection-as-Code

Crafting Searches

Supported in:Self-hosted

Use a coding agent to translate natural-language hunting questions into nPL search queries

Turn a hunting question into nPL with a coding agent and the search command reference. You can paste the result into Search or run it through the nanodac MCP server on any build; Self-run also offers pivt in the product.

This page assumes you've completed Setup.

Why an agent helps here

nPL is small and consistent: piped syntax, a few dozen commands, predictable behavior. But writing a good hunting query still requires knowing:

  • Which OCSF fields to filter on, and which let ClickHouse skip data (see Fast filters)
  • Which stats aggregations make the result useful
  • Where to use prevalence, dedup, or eval to cut noise
  • How to chain risk score= for layered scoring

An agent that has read the search-commands docs and the OCSF field reference can apply all of that to a question phrased in English.

Workflow

Step 1: Point the agent at the references

If you followed Setup, your CLAUDE.md (or AGENTS.md) already tells the agent to consult the search-commands docs and the rules/ repo. If not, mention them in the prompt:

When writing nPL, use the Search Commands reference and ~/nano-workspace/rules/ for syntax patterns.

Step 2: Ask the question in English

Be specific about:

  • The data source (metadata.log_source value, for example windows_sysmon or aws_cloudtrail)
  • The time window (last 24h, last 7d)
  • The fields you want in the output

Example:

Hunt for PowerShell processes spawned by Office applications in the last 24h. Source is windows_sysmon (metadata.log_source). Show me the parent process, command line, host, and user. Group by parent process so I can see the worst offenders first.

Step 3: The agent drafts nPL

The output should look something like:

metadata.log_source=windows_sysmon class_uid=1007 activity_id=1 process.name IN ("powershell.exe", "pwsh.exe") actor.process.name IN ("winword.exe", "excel.exe", "outlook.exe", "powerpnt.exe") | stats count as spawns, values(process.cmd_line) as commands, values(device.hostname) as hosts, values(actor.user.name) as users by actor.process.name | sort -spawns

Review for:

  • Field accuracy: in OCSF Process Activity (class_uid=1007) the parent is actor.process, and the new process is process. Check a few events to confirm your parser populates the paths.
  • Time range: set it in the time picker (or the tool's start and end); agents sometimes add SQL-style time comparisons by mistake
  • Aggregation choice: stats count() vs stats dc() (distinct count) vs timechart make different result shapes; make sure the agent picked what you actually want

Step 4: Run it

Paste into the nano search bar in the UI, or, if the nanodac MCP server is wired up, ask the agent to run it directly:

Run that query and show me the top 5 results.

The MCP server calls the nano search API and the agent summarizes the results. This "ask, query, review, refine" loop is the open-core stand-in for pivt's natural-language search.

Step 5: Iterate

Review the first result and refine the query:

  • Too noisy? Add filters, or use prevalence to focus on rare artifacts
  • Too narrow? Loosen the field filter; double-check field name casing
  • Wrong shape? Switch stats by X ↔ timechart span=1h ↔ top X depending on what you're trying to see

Give the agent the result and describe the next refinement.

Promoting a hunt to a detection

When a hunting query consistently surfaces real attacker behavior, it's a candidate for a scheduled detection. Ask the agent:

Take that query and convert it into a nanodac detection file. Severity high, MITRE T1059.001, scheduled every 5 minutes with a 15-minute lookback. Save it to detections/execution/.

This is the bridge from ad-hoc search to detection-as-code. See Authoring detections for the full workflow once the YAML exists.

Tips

  • Tell the agent the schema. Point it at the OCSF field reference, and list any unmapped.* fields your sources carry. Otherwise it guesses legacy names.
  • Use | head 10 while iterating. Cheap to run, fast to review. Drop it once the shape looks right.
  • Save reusable hunts. Save a query you keep asking for as a saved search and rerun it directly.
  • Filter early. Put metadata.log_source, class_uid and exact entity matches before the first |; see Search best practices.

Troubleshoot

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

A query is too noisy

Add source and entity filters before the first pipe. Check populated OCSF fields and use prevalence when rarity helps narrow the hunt.

The output has the wrong shape

Review whether you need grouped stats, a timechart, or top. Set the intended time range before rerunning.

What's next

On this page