OCSF schema
How nano models events with OCSF 1.9 — classes, log sources, class-dependent paths, unmapped fields, raw data, enrichments and fast filters.
Use OCSF field paths to search your events and write detections and dashboards across log sources. Every event in nano uses OCSF 1.9.0: parsers map source records to OCSF, and nano stores the events in ClickHouse. One table holds every OCSF version: each event keeps its own metadata.version.
This page explains the model. For a lookup table of paths by entity, see OCSF field reference.
Fields are dotted paths
OCSF events are nested objects. You query a leaf by its full dotted path:
src_endpoint.ip="10.0.4.12" dst_endpoint.port=3389
actor.user.name="bob.wilson" | stats count by class_name, activity_name
process.cmd_line="*-EncodedCommand*" | table time, device.hostname, actor.user.name, process.cmd_line-
Use the exact OCSF 1.9 path. Destination objects are spelled
dst_endpoint, neverdest_endpoint. -
Every scalar leaf in the OCSF 1.9 schema is a valid query path, even if none of your events populate it yet. A path with no data returns an empty value, not an error.
-
A name that isn't an OCSF 1.9 path is rejected:
Unknown canonical OCSF field 'foo' in query. Use an exact OCSF 1.9 path, or `unmapped.foo` for an intentionally unmapped source field -
The event time is
time. The event's unique ID ismetadata.uid.
Log source, class and activity
Three fields tell you what an event is.
| Field | Type | Meaning | Example |
|---|---|---|---|
metadata.log_source | string | The log source the event came from (lowercase). Set from the source you send to. | aws_cloudtrail, windows_sysmon, okta |
class_uid / class_name | int / string | The OCSF event class | 3002 / Authentication |
activity_id / activity_name | int / string | The action within the class | 1 / Logon |
category_uid / category_name | int / string | The class's category | 3 / Identity & Access Management |
type_uid | long | class_uid * 100 + activity_id, the most specific event type | 300201 = Authentication: Logon |
Filter by source with metadata.log_source, and by kind of event with class_uid and activity_id. The class filter works across every source that emits that class:
metadata.log_source=okta class_uid=3002 status_id=2 | stats count by user.name
class_uid=3002 status_id=2 | stats count by metadata.log_source, user.nameClass and activity values are numbers, not strings. When you port a query that filtered on an event-type string such as login, rewrite the filter as a class_uid / activity_id pair rather than renaming the field.
Common classes
class_uid | Class | class_uid | Class |
|---|---|---|---|
0 | Base Event (no better class) | 4001 | Network Activity |
1001 | File System Activity | 4002 | HTTP Activity |
1005 | Module Activity | 4003 | DNS Activity |
1006 | Scheduled Job Activity | 4004 | DHCP Activity |
1007 | Process Activity | 4009 | Email Activity |
1008 | Event Log Activity | 5001 | Device Inventory Info |
2004 | Detection Finding | 6002 | Application Lifecycle |
3002 | Authentication | 6003 | API Activity |
3003 | Authorize Session | 201001 | Registry Key Activity |
3006 | Group Management | 201002 | Registry Value Activity |
3007 | User Management | 201004 | Windows Service Activity |
OCSF 1.9 deprecates Account Change (3001) and User Access Management (3005); nano parsers emit User Management (3007) and Group Management (3006) instead. The full list is in the OCSF field reference.
Severity and status
| Field | Values |
|---|---|
severity_id | 0 Unknown, 1 Informational, 2 Low, 3 Medium, 4 High, 5 Critical, 6 Fatal |
severity | The label for severity_id |
status_id | 0 Unknown, 1 Success, 2 Failure, 99 Other |
status, status_detail | The outcome label and the source's own detail |
Paths depend on the class
OCSF puts the same real-world entity in different objects depending on the class. Pick the path for the class you're querying, or OR both.
| Entity | Where it lives |
|---|---|
| User | Authentication: the account logging on is user.*; whoever initiated it is actor.user.*. User and group management: the admin is actor.user.*, the target account is user.*. API Activity: the caller is actor.user.*. |
| Process | Process Activity (1007): the process started or stopped is process.*, and its parent is actor.process.*. Module, network, file, DNS and registry classes: the process doing the action is actor.process.*. |
| Host | Endpoint classes (process, file, registry): device.hostname. Network classes: src_endpoint.hostname / dst_endpoint.hostname. |
| URL | HTTP Activity: http_request.url.*. Network Activity and other classes: top-level url.*. |
actor.user.name="bob.wilson" OR user.name="bob.wilson" | stats count by class_name
device.hostname="ws-0142" OR src_endpoint.hostname="ws-0142" | stats count by metadata.log_sourceHashes are arrays
OCSF stores hashes as a list of fingerprint objects, each with an algorithm_id and a value. Query the .value leaf; an equality match means "any hash in the list equals this value".
file.hashes.value="44d88612fea8a8f36de82e1278abb02f"
process.file.hashes.value="275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f" OR actor.process.file.hashes.value="275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f"unmapped and raw_data
Not every source field has an OCSF home. nano keeps them instead of dropping them.
-
unmappedholds source fields the parser didn't map. Keys are flattened to dotted snake_case, so a source fieldappContext.tenantNamebecomesunmapped.app_context.tenant_name. Query them by path:metadata.log_source=json_generic unmapped.app_context.tenant_name="acme"- Keys that look like secrets (
password,secret,authorization,token) are stored as<redacted>. - Arrays that contain objects or other arrays are stored as JSON strings.
- If a key's type changes between events (for example, number then string), the later values are kept as JSON text under
unmapped.nano_coerced. - Field lists in the search UI show the
unmapped.*keys your own events have.
- Keys that look like secrets (
-
raw_dataholds the original log line, unmodified and not redacted.messageholds a readable summary. -
Keyword search (a bare term with no field) searches both
messageandraw_data:"mimikatz" | table time, metadata.log_source, device.hostname, message
When you write a parser, map what OCSF covers and let the rest spill to unmapped. See Parser extensions.
Enrichments
Context added at ingest — geolocation, threat intel matches, prevalence — is stored on the event in OCSF form:
- Endpoint attributes such as
src_endpoint.location.countryandsrc_endpoint.autonomous_system.number, where the enrichment fills a standard OCSF attribute. enrichments[], OCSF's list of enrichment records. Each record hasname(the field that was enriched),value,type,provider,short_descand adataobject. Query the record fields asenrichments.name,enrichments.value,enrichments.providerand so on. The fields underenrichments.datadepend on the feed.
IP geolocation fills the endpoint attributes: when a parser leaves src_endpoint.location.country or src_endpoint.autonomous_system.number (and their dst_endpoint twins) empty, ClickHouse fills them from the IPinfo Lite dictionary as the event is written. Threat-intel matches (ThreatFox, Tor exit nodes) are stored as enrichments.ioc_src_ip_threat_type, enrichments.ioc_dest_ip_threat_type, enrichments.ioc_domain_threat_type and enrichments.ioc_hash_threat_type.
src_endpoint.location.country=* | stats count by src_endpoint.location.country
enrichments.ioc_src_ip_threat_type=* | stats count by enrichments.ioc_src_ip_threat_type, src_endpoint.ipSee Enrichment field reference for each feed.
Events nano writes
nano writes some events itself. They're OCSF events in ClickHouse and you search them like any other source.
| Events | Filter | Class |
|---|---|---|
| Detection findings | metadata.log_source=findings | Detection Finding (2004): finding_info.*, risk_score, risk_level, evidences[], observables[] |
| Platform audit | metadata.log_source=audit | API Activity (6003): actor.user.name, api.operation, api.service.name, src_endpoint.ip, status |
metadata.log_source=findings | stats count by finding_info.analytic.name, risk_level
metadata.log_source=audit status_id=2 | table time, actor.user.name, api.operation, src_endpoint.ipFast filters
Searches read less data, and return sooner, when they filter on fields ClickHouse can use to skip data before reading events. The table is sorted by class and log source, and these fields carry skip indexes:
metadata.log_source,class_uid,type_uidsrc_endpoint.ip,dst_endpoint.ipuser.name,actor.user.name,device.hostnamefile.hashes.value,process.file.hashes.value
Practical rules:
- Narrow the time range first. Time is the biggest filter.
- Add a log source or class (
metadata.log_source=…,class_uid=…) whenever you know it. - Prefer exact matches on the fields above to wildcard or substring matches.
- Put filters in the search, before the first
|, rather than in a later| where.
metadata.log_source=windows_sysmon class_uid=1007 device.hostname="ws-0142" | table time, actor.process.name, process.cmd_lineMore in Search best practices.
Legacy field names
The earlier flat field names still resolve for compatibility, but use OCSF paths in new searches and rules. Migrating from legacy field names maps each old name to its OCSF 1.9 path.