nano SIEM
User Guide

Risk-Based Alerting

Supported in:Self-hosted

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.

Score detection findings and accumulate risk on a user, host, IP, email address, or cloud account. Use a risk rule to alert on the accumulated score so related low-confidence signals can lead to one actionable alert.

The flow:

  1. A detection rule fires and writes a finding with a risk score (0–100) attributed to an entity.
  2. nano accumulates each entity's findings over 24 hours and 7 days, with older findings decaying.
  3. A risk rule — a detection rule over the risk dataset — alerts when an entity's accumulated score crosses a threshold.

Score findings

Every detection rule has a base risk score. To score from the data instead, add the | risk command to the rule's query:

risk score=<0-100 | expression> [entity=<field>] [factor=<expression>] [weight=<0.0-1.0>]
ParameterMeaning
scoreA literal 0–100, or an eval expression. Computed scores are clamped to 0–100.
entity (alias field)The field whose value receives the risk. Defaults to src_endpoint.ip.
factor (alias type)A label saying why the score was added.
weightMultiplier for this command (0.0–1.0). Overrides the global risk weight.

Parameters can come in any order. Full syntax: risk.

A static score on the host where PowerShell ran:

class_uid=1007 process.name="powershell.exe" | risk score=75 entity=device.hostname factor="PowerShell execution"

A score that grows with the number of failed logons:

class_uid=3002 status_id=2 | stats count as attempts by src_endpoint.ip | risk score=if(attempts > 50, 90, if(attempts > 10, 70, 40)) entity=src_endpoint.ip factor="Failed logins"

A conditional score:

class_uid=3002 | risk score=if(cidr_match("10.0.0.0/8", src_endpoint.ip), 40, 80) entity=user.name factor="Admin login"

A down-weighted score while you tune a noisy rule:

class_uid=4001 | risk score=30 entity=src_endpoint.ip factor="Network" weight=0.5

Stack scores

Several | risk commands in one query add up (capped at 100). Each adds its factor to risk_factors, and you can filter on the running risk_score:

class_uid=3002 | risk score=10 entity=user.name factor="Login attempt" | where status_id=2 | risk score=20 factor="Failed login" | where NOT is_private_ip(src_endpoint.ip) | risk score=25 factor="External IP" | where risk_score >= 30 | table time, user.name, src_endpoint.ip, status, risk_score, risk_factors

| risk also works after a nano-side stage such as prevalence or lookup.

Choose the entity

Pick the field that names who or what should carry the risk. Common choices, by class:

EntityPath
User (authentication subject)user.name
User (who did it)actor.user.name
Host (endpoint events)device.hostname
Source / destination IPsrc_endpoint.ip, dst_endpoint.ip
Email addressactor.user.email_addr, user.email_addr

Which path a class populates differs; see OCSF schema → Paths depend on the class and OCSF field reference.

nano types each entity from its value: an IPv4 address is ip, a value with @ is email, a value containing a dot is hostname, anything else is user. Cloud account entities are typed cloud_account.

Findings in your data

Each finding is an OCSF Detection Finding (class_uid=2004) with metadata.log_source=findings. Search them like any other events:

PathMeaning
risk_score, risk_level, risk_level_id, risk_detailsThe finding's risk
finding_info.analytic.name, finding_info.analytic.uidThe rule that fired
finding_info.attacks.tactic.name, finding_info.attacks.technique.uidMITRE ATT&CK mapping
resources.name, resources.typeThe entity the risk was attributed to
observables.name, observables.valueEntities seen in the matched events
evidencesThe matched events

Risk by rule:

metadata.log_source="findings" | stats count, sum(risk_score) as total_risk by finding_info.analytic.name | sort -total_risk

High and critical findings:

metadata.log_source="findings" risk_level_id>=4 | table time, finding_info.title, risk_score, risk_level, resources.name

Daily risk trend:

metadata.log_source="findings" | timechart span=1d sum(risk_score) by risk_level

See OCSF field reference → Findings, risk and observables.

Accumulated risk and decay

nano adds up each entity's findings over two windows, 24 hours and 7 days. Recent findings count more than older ones:

Finding ageDefault factor
0–24 hours1.0
1–3 days0.7
3–5 days0.4
5–7 days0.2
Older than 7 daysExcluded

Example: an entity with findings scored 50 (2 hours ago), 30 (12 hours), 80 (2 days), 60 (4 days) and 40 (6 days):

WindowRaw scoreDecayed score
24h50 + 30 = 8050 + 30 = 80
7d26050 + 30 + 56 + 24 + 8 = 168

Accumulated scores are not capped at 100: they're sums. The 7-day score is always at least the 24-hour score.

Change the factors in Settings → Risk Scoring (see Risk Scoring Settings).

Risk rules: the risk dataset

Accumulated risk is an nPL dataset, risk, with one row per entity:

ColumnMeaning
entity, entity_typeThe entity and its type
score_24h, score_7dDecayed accumulated risk
raw_score_24h, raw_score_7dAccumulated risk without decay
findings_24h, findings_7dContributing findings
distinct_rules_24h, distinct_rules_7dDistinct rules that contributed
distinct_tactics_24h, distinct_tactics_7dDistinct MITRE tactics
last_finding_at, last_rule_name, last_severityThe most recent finding

A risk rule is an ordinary scheduled detection rule with its dataset set to risk. It moves through the same Staging → Live → Alerting lifecycle as any rule.

Threshold:

* | where score_24h > 100

Breadth is a stronger signal than one noisy rule re-firing. Require several rules across several tactics:

* | where score_24h > 100 AND distinct_tactics_24h >= 3 AND distinct_rules_24h >= 2

Slow burn over a week:

* | where score_7d > 300 AND distinct_rules_7d >= 3 | table entity, entity_type, score_7d, distinct_rules_7d, last_rule_name

Rules for a risk rule:

  • It can't add risk itself: its risk score must be 0, and its query can't contain | risk. nano refuses to save or run a risk rule that breaks either, because its findings would feed its own input.
  • Use the rule's alert cooldown so an entity that stays above the threshold doesn't alert on every run.
  • Cleared entities (see below) stop matching.

Risk rules read the same decay settings and clear state as the Risk page.

Risk notables

Settings → Risk Scoring has a risk notables card: a 24-hour threshold (default 500), a 7-day threshold (default 1,000), a per-entity cooldown (default 240 minutes) and optional per-entity-type overrides. It's off by default.

The card edits a built-in rule, Accumulated risk threshold exceeded (score_24h > 500 or score_7d > 1000). The rule ships in Live mode, so it records matches but raises no alerts. Turning the card on moves it to Alerting.

The Risk page

Risk (/risk, permission risk:view) lists entities by accumulated risk:

  • Summary tiles for 24 hours and 7 days, and counts by entity type.
  • A table of entities with the 24h and 7d decayed scores, findings (24h / 7d), last rule and last seen. Hover a score to see the raw value.
  • Filters by entity type and score.
  • An entity's context and risk timeline.

Risk → Watchlists (/risk/watchlists, permission risk:watchlists) manages watchlists. See Risk Scoring Settings.

Risk API

EndpointPermissionPurpose
GET /api/risk/entitiesrisk:viewRisky entities. Query: window, entity_type, min_score, max_score, limit, offset.
GET /api/risk/time-windowedrisk:view24h and 7d decayed scores. Query: min_score_24h, min_score_7d, limit.
GET /api/risk/overviewrisk:viewSummary for 24h and 7d.
GET /api/risk/notable-countrisk:viewNumber of entities over the notable thresholds.
GET /api/risk/entity-activityrisk:viewDaily activity for entities. Query: entities.
GET /api/entities/{type}/{value}/contextrisk:viewContext for one entity.
GET /api/entities/{type}/{value}/risk-timelinerisk:viewRisk over time for one entity.
POST /api/risk/clearrisk:clearClear one entity's risk. Body: entity, entity_type, reason.
POST /api/risk/clear-allrisk:clearClear all risk.

To find entities over a threshold, use /api/risk/time-windowed:

curl "https://your-instance/api/risk/time-windowed?min_score_24h=100&min_score_7d=150" \
  -H "X-API-Key: $NANO_API_KEY"

/api/risk/thresholds has been retired. Use /api/risk/time-windowed, or a risk rule if you want alerts.

Clear an entity after a false positive:

curl -X POST "https://your-instance/api/risk/clear" \
  -H "X-API-Key: $NANO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity": "203.0.113.10", "entity_type": "ip", "reason": "Approved scanner"}'

Settings

Settings → Risk Scoring (permission risk:configure):

SettingDefaultAPI
Global risk weight (0.0–1.0), applied to every rule's score1.0/api/settings/risk
Decay factors1.0 / 0.7 / 0.4 / 0.2/api/settings/risk-decay
Risk notablesOff; 500 / 1,000; 240 min/api/settings/risk-notables

The final score of a finding is round(score × weight). Weight 0 turns risk scoring off.

Decay and notables aren't in the open-source edition; open core has the global weight. Details: Risk Scoring Settings.

Practices

  • Start low. Give individual rules modest scores and let accumulation do the work. Raise scores on rules that prove reliable.
  • Pick actionable entities. Users for insider and account-takeover risk, hosts for endpoint activity, IPs for network activity.
  • Alert on breadth. Conditions on distinct_rules_* and distinct_tactics_* cut false positives far more than a higher bare threshold.
  • Clear with a reason. When you close out a false positive, clear the entity with a reason so the audit trail explains why its score dropped.
  • Route risk alerts. Send risk-rule alerts to your SOAR or firewall automation through a notification channel.

Troubleshoot

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

A risk rule is refused

Set its risk score to 0 and remove | risk from the query. A risk rule cannot add risk to its own input.

Risk notables raise no alerts

The built-in Accumulated risk threshold exceeded rule ships in Live mode. Turn the risk notables card on to move it to Alerting.

What's next

On this page