Prevalence Tracking
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:
| Artifact | Taken from (OCSF 1.9) |
|---|---|
| File hashes | file.hashes.sha256, process.file.hashes.sha256 |
| Domains | dst_endpoint.hostname, query.hostname |
| IP addresses | src_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 stamp | prevalence command | |
|---|---|---|
| What it measures | How rare the artifact was when the event arrived | How rare the artifact is now, over a window you choose |
| Where it lives | prevalence_* columns on each event | Fields added to your results |
| Cost | Free: it's already on the event | A lookup per result set |
| Use in | Any search, detection or dashboard | Search 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:
| Column | Artifact |
|---|---|
prevalence_file_hash | file.hashes.sha256 |
prevalence_process_hash | process.file.hashes.sha256 |
prevalence_dest_domain | dst_endpoint.hostname (not an IP address) |
prevalence_dest_ip | dst_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:
| Value | Meaning |
|---|---|
1 | A new artifact: it wasn't in the baseline yet, so this event is its first sighting |
9999 | Common: the artifact was on more hosts than nano counts individually |
65535 | The 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.hostnameDomains seen on fewer than three hosts when the request was made:
class_uid=4002 prevalence_dest_domain < 3 | stats count by dst_endpoint.hostnameFirst sightings of a file hash:
prevalence_file_hash=1 | table time, device.hostname, file.name, file.hashes.sha256The 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() - 24hCombine 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_seenName fields to look up:
class_uid=1007 | prevalence process.file.hashes.value, dst_endpoint.ipOptions:
| Option | Values | Notes |
|---|---|---|
window (alias interval) | 24h, 7d, 30d | window=1h is rejected. |
enrich | true, false | Adds prevalence fields to every row. |
threshold | rare, uncommon, common | Accepted 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
| Endpoint | Purpose |
|---|---|
GET /api/prevalence/hash/{hash} | One hash |
GET /api/prevalence/domain/{domain} | One domain |
POST /api/prevalence/bulk | Up to 100 artifacts in one request |
GET /api/prevalence/rare | Rare artifacts |
GET /api/prevalence/new | Newly seen artifacts |
GET /api/prevalence/explorer, GET /api/prevalence/explorer/detail | The explorer list and detail |
POST /api/prevalence/scatter | Host count against first-seen time |
POST /api/prevalence/query-artifacts | Prevalence of the artifacts in an nPL query's results |
GET /api/prevalence/export | Export (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 bydevice.hostnameto see where a binary ran. - New domains: HTTP (
class_uid=4002) or network events withprevalence_dest_domain=1, or| prevalence domain_first_seen > now() - 24hfor 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
Scheduled Reports
Run a saved search or dashboard on a cron schedule and produce downloadable CSV and self-contained HTML report artifacts.
Risk-Based Alerting
Score events and entities with the risk command, track accumulated entity risk with time decay, and alert on it with risk rules over the risk dataset.