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.
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:
- A detection rule fires and writes a finding with a risk score (0–100) attributed to an entity.
- nano accumulates each entity's findings over 24 hours and 7 days, with older findings decaying.
- A risk rule — a detection rule over the
riskdataset — 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>]| Parameter | Meaning |
|---|---|
score | A 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. |
weight | Multiplier 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.5Stack 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:
| Entity | Path |
|---|---|
| User (authentication subject) | user.name |
| User (who did it) | actor.user.name |
| Host (endpoint events) | device.hostname |
| Source / destination IP | src_endpoint.ip, dst_endpoint.ip |
| Email address | actor.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:
| Path | Meaning |
|---|---|
risk_score, risk_level, risk_level_id, risk_details | The finding's risk |
finding_info.analytic.name, finding_info.analytic.uid | The rule that fired |
finding_info.attacks.tactic.name, finding_info.attacks.technique.uid | MITRE ATT&CK mapping |
resources.name, resources.type | The entity the risk was attributed to |
observables.name, observables.value | Entities seen in the matched events |
evidences | The matched events |
Risk by rule:
metadata.log_source="findings" | stats count, sum(risk_score) as total_risk by finding_info.analytic.name | sort -total_riskHigh and critical findings:
metadata.log_source="findings" risk_level_id>=4 | table time, finding_info.title, risk_score, risk_level, resources.nameDaily risk trend:
metadata.log_source="findings" | timechart span=1d sum(risk_score) by risk_levelSee 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 age | Default factor |
|---|---|
| 0–24 hours | 1.0 |
| 1–3 days | 0.7 |
| 3–5 days | 0.4 |
| 5–7 days | 0.2 |
| Older than 7 days | Excluded |
Example: an entity with findings scored 50 (2 hours ago), 30 (12 hours), 80 (2 days), 60 (4 days) and 40 (6 days):
| Window | Raw score | Decayed score |
|---|---|---|
| 24h | 50 + 30 = 80 | 50 + 30 = 80 |
| 7d | 260 | 50 + 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:
| Column | Meaning |
|---|---|
entity, entity_type | The entity and its type |
score_24h, score_7d | Decayed accumulated risk |
raw_score_24h, raw_score_7d | Accumulated risk without decay |
findings_24h, findings_7d | Contributing findings |
distinct_rules_24h, distinct_rules_7d | Distinct rules that contributed |
distinct_tactics_24h, distinct_tactics_7d | Distinct MITRE tactics |
last_finding_at, last_rule_name, last_severity | The 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 > 100Breadth 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 >= 2Slow burn over a week:
* | where score_7d > 300 AND distinct_rules_7d >= 3 | table entity, entity_type, score_7d, distinct_rules_7d, last_rule_nameRules 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
| Endpoint | Permission | Purpose |
|---|---|---|
GET /api/risk/entities | risk:view | Risky entities. Query: window, entity_type, min_score, max_score, limit, offset. |
GET /api/risk/time-windowed | risk:view | 24h and 7d decayed scores. Query: min_score_24h, min_score_7d, limit. |
GET /api/risk/overview | risk:view | Summary for 24h and 7d. |
GET /api/risk/notable-count | risk:view | Number of entities over the notable thresholds. |
GET /api/risk/entity-activity | risk:view | Daily activity for entities. Query: entities. |
GET /api/entities/{type}/{value}/context | risk:view | Context for one entity. |
GET /api/entities/{type}/{value}/risk-timeline | risk:view | Risk over time for one entity. |
POST /api/risk/clear | risk:clear | Clear one entity's risk. Body: entity, entity_type, reason. |
POST /api/risk/clear-all | risk:clear | Clear 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):
| Setting | Default | API |
|---|---|---|
| Global risk weight (0.0–1.0), applied to every rule's score | 1.0 | /api/settings/risk |
| Decay factors | 1.0 / 0.7 / 0.4 / 0.2 | /api/settings/risk-decay |
| Risk notables | Off; 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_*anddistinct_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
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.
Data Management
Create lookup tables from files or by hand, refresh them with scheduled URL ingestion, and use them with lookup, inputlookup and ioc in lookup().