Crafting Searches
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
statsaggregations make the result useful - Where to use
prevalence,dedup, orevalto 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_sourcevalue, for examplewindows_sysmonoraws_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 -spawnsReview for:
- Field accuracy: in OCSF Process Activity (
class_uid=1007) the parent isactor.process, and the new process isprocess. 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()vsstats dc()(distinct count) vstimechartmake 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
prevalenceto 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 Xdepending 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 10while 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_uidand 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
- Search Commands reference: full nPL command list
- Quick Reference: every command at a glance
- Authoring detections: promote a hunt to a scheduled detection