Search & query language
nPL, nano's piped query language: how a query is built, where to start, and every command by task.
Use nPL (nano Pipe Language) to search your events, refine results, and summarize activity. Build a query from a search expression followed by piped commands that filter, reshape, and aggregate the rows:
class_uid=3002 status_id=2 | stats count by user.name, src_endpoint.ip | where count > 20 | sort -countThat query finds failed logons (OCSF Authentication, class 3002, with status_id=2), counts them per user and source address, keeps pairs with more than 20 failures, and puts the worst first.
If you know another SIEM's pipe-based query language, most of nPL will look familiar. Fields are OCSF 1.9 dotted paths, such as src_endpoint.ip, actor.user.name and process.cmd_line. Look paths up in the OCSF field reference. If you have searches written for older nano field names, see the field-name migration guide.
Before you begin
To run searches, you need search:execute. Use the OCSF field reference to identify the fields your logs populate.
Start here
- Syntax: keywords, field comparisons, wildcards, regex, CIDR ranges,
ioc, precedence, comments and limits - Functions: every
eval/wherefunction and every aggregation - Quick reference: all commands on one page
- Best practices: how to write fast, precise hunts
Run your first searches
mimikatz // keyword search over message and raw_data
metadata.log_source=windows_sysmon class_uid=1007 process.name=powershell.exe
class_uid=4002 http_response.code>=500 | stats count by http_request.url.hostname | sort -count | head 10
class_uid=1007 | timechart span=1h count by device.hostname
ioc=203.0.113.50 | stats count by metadata.log_source, class_nameCommands by task
Filter
| Command | Use it to |
|---|---|
| search | Filter later in the pipeline with search syntax |
| where | Filter with expressions, functions and field-to-field comparisons |
| regex | Keep or drop rows whose field matches a regex |
dedup (uniq) | Keep the first row per combination of values |
| head / tail | Keep the first or last N rows |
| sample | Keep a random sample |
Aggregate
| Command | Use it to |
|---|---|
| stats | Count, sum, average and more, grouped by fields |
| chart | Aggregate by one or two dimensions for a chart |
| timechart | Aggregate into time buckets |
| top / rare | Most or least common values, with percentages |
| eventstats | Add group aggregates to every row |
| streamstats | Running aggregates in event order |
bin (bucket) | Group times or numbers into buckets |
| anomaly | Keep statistical outliers |
Shape fields
| Command | Use it to |
|---|---|
| eval | Compute new fields |
| table | Choose columns and their order |
| fields | Keep or remove fields |
| rename | Rename fields |
rex (extract) | Extract fields with a regex, or edit with sed |
| spath | Extract values from JSON |
| fillnull | Replace empty values |
| mvexpand | One row per value of an array |
| sort / reverse | Order rows |
Correlate
| Command | Use it to |
|---|---|
| join | Add fields from a subsearch on matching keys |
| append | Add a subsearch's rows |
| transaction | Group related events into sessions |
| sequence | Find ordered event patterns per entity |
| funnel | Count how far entities get through ordered steps |
| lateral | Trace movement between hosts and users |
| tree | Build process or web request trees |
| return / format | Shape subsearch output |
Enrich and investigate
| Command | Use it to |
|---|---|
| lookup | Add columns from a lookup table |
| inputlookup | Read a lookup table as results |
| prevalence | Filter or enrich by how rare an artifact is in your environment |
resolve_identity (resolve-identity) | Map IPs and hosts to users |
| risk | Attach a risk score to matching events |
| retro | Sweep history for indicators |
| ai | Ask the AI to classify rows |
| asset | Open an asset dossier |
| baseline | Compare an entity's activity to its baseline |
| cloud | Summarize cloud control-plane activity |
Observability
services, service, trace and metric open the observability views for OpenTelemetry data.
Troubleshoot
Need help with these checks? Contact support with the affected deployment, request ID and time with timezone.
Your filter returns no events
Check the selected time range and confirm the field path in the OCSF field reference. Start with a broader query from Run your first searches, then add filters one at a time.
A command fails after enrichment
After lookup, prevalence, inputlookup, resolve_identity, ai or lateral, nano runs the remaining commands in post-processing. Move an unsupported command before the enrichment stage. See post-processing after nano-side stages for supported commands.
What's next
- Syntax: build search expressions
- Quick reference: choose commands by task
- Best practices: narrow searches and check results