nano SIEM
User Guide

Parser Extensions

Supported in:Self-hosted

Customize a catalog parser for one log source with a small VRL overlay that edits the OCSF event, without forking the parser.

Add a parser extension to tag events, normalize values, or fill missing fields without forking the catalog parser. The VRL overlay belongs to one log source and runs on the OCSF 1.9 event immediately after its parser.

Where an extension runs

nano's parsers write a complete OCSF event on the event root: class_uid, activity_id, metadata.*, the entity objects (src_endpoint, actor.user, process, …), raw_data, and an unmapped object for source fields with no OCSF home. The extension runs next, on that event, before it is written to ClickHouse.

So an extension reads and writes OCSF paths (.src_endpoint.ip, .actor.user.name, .cloud.account.uid) and puts anything that has no OCSF home under .unmapped. See OCSF schema and the OCSF field reference.

Common uses

GoalExample
Tag events.unmapped.team = "soc"
Normalize a value.actor.user.name = downcase(string(.actor.user.name) ?? "")
Fill a missing fieldif !exists(.device.hostname) { .device.hostname = .unmapped.computer_name }
Mask sensitive content.message = replace(string(.message) ?? "", r'\d{16}', "[REDACTED]")

What extensions are not for

  • Replacing the parser. If the catalog parser is wrong for your logs (a different format or vendor variant), build a new parser from samples instead.
  • Logic across sources. An extension belongs to one log source. Logic that spans sources belongs in detection rules or enrichment.
  • State. Extensions are stateless transforms: no aggregation, joins or lookups against other events.
  • Dropping events. An event that hits abort (or a runtime error) in an extension is not dropped. It is kept, unchanged, and marked as a parse failure, so it still counts toward the source's failure rate. To cut volume, use sampling on the Configuration tab (see Sampling).

The stub case: no catalog parser

If the log source has no parser VRL and the extension is enabled, the extension is the parser for that source. The parse step is skipped and the extension reads events straight from the router. The panel shows (stub — extension IS the parser).

In this case your extension must build the whole OCSF event on the root, the same as any parser: class_uid, activity_id, type_uid, metadata.version, raw_data and so on. See Parsers for the rules a parser follows.

Permissions

Use log_sources:view to read the source, log_sources:edit to edit its working copy, and log_sources:deploy to publish it.

Authoring an extension

  1. Open Ingestion → Log Sources and select the log source.
  2. Open the Extension tab.
  3. Write the overlay in the editor. The pivt side panel (labeled pivt) accepts plain-language edits. It is given the catalog parser as read-only context and only edits the extension.
  4. Use Test events to run the parser followed by your extension on a sample event and see the resulting OCSF event.
  5. Turn on Enabled, click Validate, then Save.
  6. Publish from the page header to make the change live.

Publishing renders a new Vector configuration and delivers it to every Vector instance. Vector reloads it, and if it rejects the new configuration the previous one keeps running. You can extend platform sources (such as aws_cloudtrail) as well as your own custom sources; the platform parser itself is never changed.

Example: tag CloudTrail by account

You run two AWS accounts and want every CloudTrail event tagged with the owning team, so dashboards and detections can filter on it.

On the aws_cloudtrail log source, Extension tab:

if .cloud.account.uid == "111111111111" {
    .unmapped.team = "platform"
} else if .cloud.account.uid == "222222222222" {
    .unmapped.team = "data"
}

Test it with a sample event, enable, save and publish. Then search on the new field:

metadata.log_source="aws_cloudtrail" unmapped.team="platform"
| stats count by api.operation

The catalog CloudTrail parser keeps running unchanged; your tag rides on top.

Example: normalize user names

A source reports user names in mixed case, which splits counts in stats and misses watchlist matches:

if exists(.actor.user.name) {
    .actor.user.name = downcase(string(.actor.user.name) ?? "")
}

Validation

Invalid extension VRL never reaches a running pipeline.

GateWhat it catches
Validate / publishThe server compiles both the parser and the extension. Syntax errors and blocked functions (get_env_var, http_request, dns_lookup and others) reject the publish. The previous version stays live and the error names the transform.
Test eventsRuns the full parser → extension chain against your sample before you publish, so a path that doesn't match what the parser emits shows up in the draft loop.
DeployVector validates the generated configuration. On a failure the previous version stays live.

The pivt panel validates every suggestion before returning it. Save stores your draft as is; the gates run when you publish.

Versions

Extensions use the same publish and version flow as the parser:

  • Each Publish snapshots both the parser VRL and the extension VRL into a new version.
  • The Versions tab diff shows changes to either.
  • Revert restores both to the chosen version's snapshot.

Sampling

Extensions run before the optional sampling step, so a value your extension sets is visible to the sampling exclude condition. For example, set a criticality tag in the extension:

.unmapped.criticality = if .src_endpoint.ip == "10.0.1.5" { "high" } else { "low" }

and exclude high-criticality events from sampling on the Configuration tab. Events marked as parse failures are never sampled out.

Limitations

  • One extension per log source. Put all your logic in a single transform.
  • VRL only. There's no declarative shorthand for simple cases such as adding a constant field; use a one-line VRL assignment.
  • No conflict lint. If your extension sets a field and a later parser update also sets it, the extension wins, because it runs second. Check the Versions diff when you take parser updates.
  • No shared library. Each log source's extension is its own artifact; copy logic between sources by hand.

Troubleshoot

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

Saved edits do not appear in new events

Save keeps a working draft. Publish the source to make the extension live, then check the source's deployment status on Ingestion → Log Sources.

A custom field fails OCSF validation

Write fields without an OCSF home under .unmapped, then test the full parser and extension chain.

A later parser update changes the result

The extension runs second and wins when both set a field. Review the Versions diff and retest representative samples.

What's next

On this page