nano SIEM
Search Commands

Syntax

Supported in:Self-hosted

nPL search syntax: keywords, field comparisons, wildcards, regex, IN lists, CIDR ranges, ioc terms, precedence, comments, time modifiers and query limits.

Use this reference to write your nPL search expression and connect it to pipeline commands. An nPL query contains a search expression followed by zero or more piped commands:

<search expression> | <command> | <command> ...

The search expression selects events. Each command transforms the rows that the previous stage produced. This page covers the search expression and the rules that apply to the whole query. Each command has its own page; see the command list or the quick reference.

Fields are OCSF 1.9 dotted paths such as src_endpoint.ip or actor.user.name. See OCSF schema and the OCSF field reference.

Keywords

A bare word is a token search over the event's message and raw_data. Several words must all match. Quote a phrase to match the words together.

mimikatz
failed password
"access denied"
  • * alone matches every event.
  • A wildcard keyword such as *svchost* is a case-insensitive substring match on message and raw_data.
  • Keyword matching is case-insensitive.
  • A field filter is faster and more precise than a keyword. Prefer process.name=mimikatz.exe over mimikatz when you know the field.

Field comparisons

user.name=administrator
http_response.code>=500
dst_endpoint.port!=443
severity_id>=4
OperatorMeaning
= / !=Equal / not equal. String comparisons are case-insensitive.
> < >= <=Numeric (or time) comparison

Quote values that contain spaces or special characters: process.file.path="C:\Program Files\app.exe". Inside quotes a backslash never escapes the closing quote, so a Windows path ending in \ works. Use single quotes to match a literal ".

Unquoted values may contain letters, digits and _ - . * ? / : @ \ +, so URLs, paths and IPv6 addresses can usually be written without quotes.

Wildcards

* matches any run of characters and ? matches one character. With = or != a wildcard value is a case-insensitive pattern match.

user.name=adm*
process.name=*.ps1
user.name=adm?n

Existence: field=*

field=* matches events where the field is present and not empty. It is not "match all". field!=* matches events where the field is missing or empty.

class_uid=3002 user.name=*
class_uid=4002 http_request.user_agent!=*

Regular expressions

Write a regex between slashes, or use the =~ / !~ operators. Regex matching is unanchored and case-insensitive.

process.cmd_line=/-enc(odedcommand)?\s+[A-Za-z0-9+\/=]{40,}/
process.cmd_line =~ "-enc"
http_request.url.hostname !~ "\.(com|net|org)$"

IN lists

class_uid IN (3002, 3003)
user.name IN ("administrator", "root", "admin")
dst_endpoint.port NOT IN (80, 443)

CIDR ranges

An IP field compared with a CIDR matches addresses in the range. IN CIDR(...) takes a list.

src_endpoint.ip=10.0.0.0/8
src_endpoint.ip!=10.0.0.0/8
dst_endpoint.ip IN CIDR("10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16")
dst_endpoint.ip NOT IN CIDR("10.0.0.0/8", "192.168.0.0/16")

Word operators

OperatorExample
LIKE (% and _ wildcards)process.name LIKE "%.exe"
CONTAINSprocess.cmd_line CONTAINS "downloadstring"
STARTSWITHhttp_request.url.hostname STARTSWITH "login."
ENDSWITHfile.name ENDSWITH ".lnk"

Each also takes NOT, for example process.name NOT LIKE "%.exe".

Functions in a filter

A function can sit on the left of a comparison, and several boolean functions work as a filter on their own:

lower(user.name)="administrator"
len(user.name) < 3
is_public_ip(src_endpoint.ip) class_uid=3002
cidr_match(dst_endpoint.ip, "10.0.0.0/8")
isnotnull(actor.process.cmd_line)

The boolean functions allowed on their own are isnull, isnotnull, like, match, cidr_match, is_private_ip, is_public_ip, has, in, isnum, isint, isstr, isbool, and searchmatch. See Functions for the full list.

Indicators: ioc

ioc matches an indicator in whichever observable field it could appear in, so you don't have to name the field. nano picks the fields from the value's type: an IP checks src_endpoint.ip and dst_endpoint.ip, a hash checks file.hashes.value, process.file.hashes.value and actor.process.file.hashes.value, and a domain checks the HTTP, URL, DNS and destination host names.

ioc=203.0.113.50
ioc=44d88612fea8a8f36de82e1278abb02f
ioc in [203.0.113.50, evil.example]
ioc=203.0.113.50 | stats count by metadata.log_source, class_name

ioc also accepts a threat feed (ioc in feed("name"), or a feed function such as threatfox(...)), a lookup table (ioc in lookup("table", "column")) or an inline table (ioc in [inputlookup table]). Pair it with retro to sweep history.

Boolean logic and precedence

Terms separated by spaces are ANDed. AND/&&, OR/|| and NOT combine them, and parentheses group.

The precedence differs between the search expression and where / eval:

WherePrecedence (tightest first)a b OR c means
Search expression and piped searchNOT, then OR, then ANDa AND (b OR c)
where and evalNOT, then AND, then ORn/a: x OR y AND z means x OR (y AND z)

The search rule follows the common SIEM convention. When in doubt, add parentheses.

class_uid=3002 (user.name=administrator OR user.name=root) status_id=2
class_uid=1007 NOT process.name=svchost.exe
* | where (user.name="administrator" OR user.name="root") AND status_id=2

Pipes and commands

Each | starts a command that receives the previous stage's rows. Command names and keywords are case-insensitive.

class_uid=3002 status_id=2 | stats count by user.name, src_endpoint.ip | where count > 20 | sort -count

Starting with a command

A query can start with a pipe. The search expression is then *:

| stats count by metadata.log_source

You can also leave out the pipe for these commands: stats, chart, timechart, streamstats, eventstats, top, rare and inputlookup. The command must take arguments and use the whole segment.

stats count by class_name
top dst_endpoint.port

To search for those words as keywords instead, quote them ("top user") or start with the search keyword (search top user). A leading search keyword is otherwise optional: search class_uid=3002 is the same as class_uid=3002.

Comments

Use // for a comment to the end of the line and /* ... */ for a block. Text inside quotes is never treated as a comment. # is not a comment character and causes a syntax error.

class_uid=3002 status_id=2 // failed logons only
/* brute force */ class_uid=3002 status_id=2 | stats count by src_endpoint.ip

Newlines are treated as spaces, so you can break a long query across lines.

Time range

The time picker sets the search window. You can also set it in the query with earliest= and latest=. Units are s, m, h, d, w, M (months) and y.

class_uid=3002 status_id=2 earliest=-24h
metadata.log_source=aws_cloudtrail earliest=-7d latest=-1d

Snap-to modifiers such as @d are not supported. Don't add them: earliest=-7d@d uses a plain 7-day offset (not midnight), and the leftover @d is searched as a keyword, which silently drops most events.

Filter on time with the time picker or earliest=/latest=. A BETWEEN clause is not part of nPL: time BETWEEN 1 AND 2 is read as four keywords, not a range.

Subsearches

A subsearch in square brackets supplies values to the outer query. Use it with IN, join and append:

class_uid=1007 device.hostname IN [search class_uid=3002 status_id=2 | return device.hostname]

An IN [...] subsearch may contain only a search expression and an optional return of one field. It supplies up to 10,000 distinct values; a count on return is ignored here. To filter on aggregates first, use join.

A subsearch can read another dataset: start it with dataset=spans or dataset=metrics (for example IN [dataset=spans ...] or join ... [dataset=metrics ...]) to match against OpenTelemetry traces or metrics. Without dataset=, a subsearch reads the same dataset as the outer search.

Post-processing after nano-side stages

lookup, prevalence, inputlookup, resolve_identity, ai and lateral run in nano itself, after ClickHouse returns rows. Everything after the first of these stages runs in post-processing, where only these commands work: where, head, tail, sort, table, stats, dedup, rename, fields, top, rare, fillnull, eval, timechart, rex, risk, reverse, and tree. Put every other command before the first such stage.

Limits

LimitValue
Piped commands per query25
Nesting depth (parentheses and subsearches)50
Terms in one AND/OR chain1,024
Query length1 MiB

Search admission, concurrency and execution limits are deployment settings; see Settings → Search.

What's next

  • Functions: eval and where functions, aggregations
  • where: filter rows with expressions
  • search: apply search syntax later in the pipeline
  • Best practices: writing fast hunts

On this page