nano SIEM
User Guide

Prevalence Tracking

Supported in:Self-hosted

Find rare hashes, domains and IPs by how many of your hosts have seen them, stamped on each event at ingest and computed on demand with prevalence.

Use prevalence to find artifacts seen by few hosts and scope an investigation. nano counts the distinct hosts that have seen each artifact, so you can compare a file hash or domain with your environment’s baseline.

nano tracks three kinds of artifact:

ArtifactTaken from (OCSF 1.9)
File hashesfile.hashes.sha256, process.file.hashes.sha256
Domainsdst_endpoint.hostname, query.hostname
IP addressessrc_endpoint.ip, dst_endpoint.ip (public addresses only; private ranges are not tracked)

The host that "saw" an artifact is identified from the event's src_endpoint.hostname, or src_endpoint.ip when it has no hostname.

You use prevalence in two ways:

Ingest-time stampprevalence command
What it measuresHow rare the artifact was when the event arrivedHow rare the artifact is now, over a window you choose
Where it livesprevalence_* columns on each eventFields added to your results
CostFree: it's already on the eventA lookup per result set
Use inAny search, detection or dashboardSearch pipelines

The ingest-time stamp is stable: two analysts reading the same event a week apart see the same number. Use the command when you need today's picture, a first-seen time, or a different window.

Prevalence on each event

When an event is written, ClickHouse looks up the artifacts on it in the prevalence baseline and stores the host count in four columns:

ColumnArtifact
prevalence_file_hashfile.hashes.sha256
prevalence_process_hashprocess.file.hashes.sha256
prevalence_dest_domaindst_endpoint.hostname (not an IP address)
prevalence_dest_ipdst_endpoint.ip (public addresses only)

Each value is the number of distinct hosts that had seen the artifact when the event arrived, with three special values:

ValueMeaning
1A new artifact: it wasn't in the baseline yet, so this event is its first sighting
9999Common: the artifact was on more hosts than nano counts individually
65535The event has no such artifact (the source field is empty)

The baseline is refreshed from your events in the background, so it trails ingest. An artifact that appears several times before the next refresh is stamped 1 each time. The stamp is never rewritten: it records how rare the artifact was when the event arrived.

Search the stamp

Rare process executions, by host:

class_uid=1007 prevalence_process_hash < 3 | stats count by process.name, device.hostname

Domains seen on fewer than three hosts when the request was made:

class_uid=4002 prevalence_dest_domain < 3 | stats count by dst_endpoint.hostname

First sightings of a file hash:

prevalence_file_hash=1 | table time, device.hostname, file.name, file.hashes.sha256

The prevalence command

| prevalence looks up current prevalence for the artifacts on your result rows. It has three forms.

Filter on host count or first-seen time. The fields are hash_prevalence, domain_prevalence, hash_first_seen and domain_first_seen:

metadata.log_source="windows_sysmon" | prevalence hash_prevalence < 5 window=7d
query.hostname=* | prevalence domain_first_seen > now() - 24h

Combine conditions with AND.

Enrich every row with its prevalence details, then keep working with the rows:

class_uid=1007 | prevalence enrich=true window=30d | table time, device.hostname, process.name, is_rare, first_seen

Name fields to look up:

class_uid=1007 | prevalence process.file.hashes.value, dst_endpoint.ip

Options:

OptionValuesNotes
window (alias interval)24h, 7d, 30dwindow=1h is rejected.
enrichtrue, falseAdds prevalence fields to every row.
thresholdrare, uncommon, commonAccepted but ignored.

Full syntax: prevalence.

Prevalence page

The Prevalence page (/prevalence) is an explorer over your prevalence data. It needs the prevalence:view permission.

  • Summary tiles: Rare artifacts, New artifacts (24h) and High-risk assets.
  • Search for one artifact, or paste several.
  • Filter by time window (24h, 7d, 30d), artifact type and risk.
  • Open an artifact to see its top hosts, top users, file names, log sources and network context, and pivot to a search.
  • Export the list (needs prevalence:export).

Prevalence API

EndpointPurpose
GET /api/prevalence/hash/{hash}One hash
GET /api/prevalence/domain/{domain}One domain
POST /api/prevalence/bulkUp to 100 artifacts in one request
GET /api/prevalence/rareRare artifacts
GET /api/prevalence/newNewly seen artifacts
GET /api/prevalence/explorer, GET /api/prevalence/explorer/detailThe explorer list and detail
POST /api/prevalence/scatterHost count against first-seen time
POST /api/prevalence/query-artifactsPrevalence of the artifacts in an nPL query's results
GET /api/prevalence/exportExport (up to 10,000 artifacts)

Bulk lookup:

curl -X POST "https://your-instance/api/prevalence/bulk" \
  -H "X-API-Key: $NANO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"artifacts": ["d41d8cd98f00b204e9800998ecf8427e", "rare-domain.example"], "time_window": "7d"}'

time_window accepts 24h (default), 7d and 30d.

POST /api/prevalence/query-artifacts takes the same nPL as search and filters with it the way search does, on UDM and OCSF data alike (from v2.0.15; in v2.0.13 a filtered query on OCSF returned no artifacts). A query it can't run answers 400 with the reason, and a failed read answers 500 or 504, never an empty list.

"Warming" on a new install. The Rarity view reads a 30-day window, so it shows host counts as unknown (not rare) until prevalence has covered all 30 days of it; the label gives the date it will. A kind of artifact you never ingest (for example, no DNS or proxy logs means no domains) stays unknown.

Rarity threshold

An artifact is rare when its host count is below the rarity threshold. The default is 3 hosts.

Change the threshold in Settings → Rarity Thresholds or with PUT /api/settings/prevalence (permission prevalence:configure).

Hunting with prevalence

  • Rare executables: class_uid=1007 prevalence_process_hash < 3, then group by device.hostname to see where a binary ran.
  • New domains: HTTP (class_uid=4002) or network events with prevalence_dest_domain=1, or | prevalence domain_first_seen > now() - 24h for DNS queries.
  • Scope an incident: look up an artifact's host count to see how far it spread, and its first-seen time to see when it arrived.
  • Cut false positives: in detection rules, skip artifacts that are common across your fleet.

Prevalence also feeds risk-based alerting and detections.

Troubleshoot

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

A brand-new deployment shows every artifact as new

The baseline is built from your own events. Until it has a few hours of data, most artifacts are stamped 1. Wait for the baseline to fill before you build rarity rules on the stamp.

window=1h is rejected

Use a supported command window: 24h, 7d, or 30d.

What's next

On this page