prevalence

Filter or enrich events based on artifact prevalence. Identify rare or suspicious indicators.

Description

The prevalence command leverages nano's prevalence tracking to filter events based on how common artifacts are across your environment. This is powerful for detecting rare file hashes, newly seen domains, or unusual patterns.

Prevalence data tracks how many hosts have observed each artifact and when it was first seen.

Syntax

Filter mode:

... | prevalence <field> <operator> <value> [<field> <operator> <value> ...] [window=<duration>]

Enrich mode:

... | prevalence enrich=true [window=<duration>]

Filter Fields

Used with filter mode (prevalence <field> <operator> <value>):

Enrichment Fields

When using enrich=true, the following fields are added to each event. These can be used in downstream commands like where, sort, stats, and table.

Optional Arguments

window
Syntax: window=<duration>
Description: Time window for prevalence calculation
Default: 30d

enrich
Syntax: enrich=true
Description: Add prevalence fields without filtering

Examples

Rare file hashes

file_hash=*
| prevalence hash_prevalence < 5

Newly seen domains

* | prevalence domain_first_seen > now() - INTERVAL 24 HOUR

Combined conditions

* | prevalence hash_prevalence < 3 AND hash_first_seen > now() - INTERVAL 7 DAY window=30d

Enrich with prevalence data

* | prevalence enrich=true
  | table file_hash, hash_prevalence, hash_first_seen

Rare process execution

process_name=*
| prevalence hash_prevalence <= 10 window=7d
| table timestamp, process_name, file_hash, hash_prevalence, src_host

New domain connections

dest_domain=*
| prevalence domain_first_seen > now() - INTERVAL 1 DAY
| stats count() by dest_domain, domain_first_seen

Suspicious downloads

action=file_download
| prevalence hash_prevalence < 5 AND domain_prevalence < 10

Rare and new

* | prevalence hash_prevalence < 3 AND hash_first_seen > now() - INTERVAL 3 DAY
  | where bytes > 1000000

Enrich and filter by host count

* | prevalence enrich=true
  | where host_count < 5

Find rare artifacts

sourcetype=squid_proxy
| prevalence enrich=true
  | where is_rare=1
  | table timestamp, user, prevalence_artifact, prevalence_type, host_count, prevalence_score

Recently seen artifacts sorted by rarity

* | prevalence enrich=true
  | where prevalence_first_seen > "2026-01-01"
  | sort prevalence_score

Aggregate by artifact

sourcetype=squid_proxy
| prevalence enrich=true
  | where host_count < 3
  | stats count by prevalence_artifact, prevalence_type, host_count, prevalence_first_seen

Prevalence Scoring

The prevalence_score field is a 0-100 score that reflects how common an artifact is across your environment. It's calculated relative to your rarity threshold setting (default: 3 hosts).

Within each band, the score scales linearly. For example, with a rarity threshold of 5:

Configuring the rarity threshold

The rarity threshold controls where the scoring bands start. A higher threshold means more artifacts are classified as rare. You can configure it in Settings > Prevalence or via API:

curl -X PUT https://your-instance/api/settings/prevalence \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"rarity_threshold": 5}'

See Prevalence Settings for all configuration options.

Usage Notes

Automatic calculation: Prevalence is calculated automatically from your log data.

Window parameter: Adjusts the time range for prevalence calculation. Shorter windows are more sensitive.

Performance: Prevalence queries are optimized but may be slower on very large datasets.

Enrichment mode: Use enrich=true to add prevalence fields without filtering.

Multiple conditions: All conditions must be satisfied (AND logic).

Known Limitations

When using enrich=true, commands after prevalence are applied in post-processing.

Commands that work after prevalence enrich

Commands that don't work after prevalence enrich

Note: Filter mode (prevalence hash_prevalence < 5) uses optimized SQL JOINs and doesn't have these limitations.

Related Commands

• where - Additional filtering after prevalence
• stats - Aggregate prevalence results
• lookup - Enrich with other data sources