nano SIEM
Agents & MCPDetection-as-Code

Authoring Parsers

Supported in:Self-hosted

Use a coding agent to draft an OCSF 1.9 parser from a sample log, validate it, and ship it

Draft an OCSF 1.9 parser from sample logs with a coding agent, then validate it before deployment. You can use this repository workflow on any build; Self-run also offers sample-based generation with pivt.

This page assumes you've completed Setup and cloned parsers to ~/nano-workspace/parsers/.

Parser file shape

OCSF 1.9 parsers live under parsers-ocsf/<name>/ on the main branch of the parsers repository (66 parsers). Use it as reference:

parsers-ocsf/myapp/
├── parser.yaml
└── samples/
    ├── login_success.json
    ├── login_failure.json
    └── malformed.json

parser.yaml:

name: myapp_ocsf
display_name: MyApp
version: "1.0.0"
ocsf_version: "1.9.0"
description: "Parses MyApp login and logout events as OCSF Authentication"
match_values:
  - myapp            # the source type senders declare; one value
category: application
vendor: "Example Corp"
product: "MyApp"
parser_vrl: |
  raw_log = string!(.message)
  parsed = object(parse_json(raw_log) ?? {}) ?? {}
  ocsf = {
    "class_uid": 3002, "category_uid": 3, "activity_id": 1, "type_uid": 300201,
    "time": to_unix_timestamp(parse_timestamp(parsed.ts, "%+") ?? now(), unit: "milliseconds"),
    "severity_id": 1,
    "metadata": {"version": "1.9.0", "product": {"name": "MyApp", "vendor_name": "Example Corp"}},
    "user": {"name": parsed.user},
    "src_endpoint": {"ip": parsed.src},
    "raw_data": raw_log
  }
  . = ocsf

The contract:

  • Emit the full OCSF object on the root (. = ocsf). Set class_uid, activity_id, type_uid (class_uid * 100 + activity_id), category_uid, severity_id, time and metadata.version = "1.9.0".
  • Keep the original line in raw_data, as a string.
  • Put fields with no OCSF home under unmapped. The OCSF parsers in the repository end with a generated block that spills unconsumed source fields there automatically.
  • Use OCSF paths, not invented ones: src_endpoint.ip, actor.user.name or user.name (depends on the class), time, metadata.uid. See OCSF schema and OCSF field reference.
  • When no class fits, use Base Event (class_uid 0) rather than forcing a security class.
  • One source type per source. It names what the log is, not its encoding, and you deploy exactly one parser per source type.

Good templates: parsers-ocsf/okta/ (JSON identity events) and parsers-ocsf/windows_event/ (many event IDs, several classes).

Workflow: from sample log to live parser

Step 1: Capture samples

Save representative events, one file per branch the parser handles, plus one malformed line:

mkdir -p parsers-ocsf/myapp/samples
echo '{"ts":"2026-05-09T10:00:00Z","action":"login","user":"alice","src":"10.0.0.5","status":"ok"}' > parsers-ocsf/myapp/samples/login_success.json
echo '{"ts":"2026-05-09T10:00:01Z","action":"login","user":"bob","src":"10.0.0.6","status":"failed","reason":"bad_password"}' > parsers-ocsf/myapp/samples/login_failure.json
echo 'not json at all' > parsers-ocsf/myapp/samples/malformed.json

Step 2: Ask the agent to draft the parser

Name the source, point at the samples and at a similar reference parser, and state the classes:

Write an OCSF 1.9 parser for "myapp" in parsers-ocsf/myapp/parser.yaml. Samples are in parsers-ocsf/myapp/samples/. Use parsers-ocsf/okta/parser.yaml as the structural reference. Logins and logouts are Authentication (3002); map status to status_id (1 success, 2 failure) and reason to status_detail. Everything else goes under unmapped.

Review the VRL. Agents get the skeleton right but sometimes invent VRL functions; check anything unfamiliar against the VRL function reference.

Step 3: Validate

The parsers repository validates OCSF parsers with one script:

scripts/validate-ocsf.sh parsers-ocsf/myapp/parser.yaml

It runs two gates on every sample:

  1. VRL: vector vrl compiles and runs the program. A runtime abort is a failure, because that parser would drop every event it touches.
  2. OCSF: the emitted event is checked against nano's OCSF 1.9 contract (needs nano's ocsf_event_validate binary on PATH or in OCSF_VALIDATOR), plus: metadata.version matches ocsf_version, the type_uid formula holds, no legacy output fields, the class isn't deprecated, and every path is either a queryable OCSF path or under unmapped.

A parser with no samples/ directory is reported as UNVALIDATED.

Spot-check the output:

  • class_uid, activity_id and type_uid are set on every event
  • time is correct (epoch milliseconds)
  • IPs are under src_endpoint / dst_endpoint, not left in unmapped
  • Nothing important landed in unmapped that has an OCSF home

Step 4: Add it to nano

  • Contribute upstream: open a pull request against nano-rs/parsers. CI runs both validation scripts.
  • Keep it private: put it in your own parser repository and connect that under Ingestion → Repositories, then import it. Imports land as draft log sources; review, publish and roll out from Log Sources.

You can also paste the VRL into a log source in the parser editor and publish it there. See Parser extensions.

Tips

  • Always name one or two reference parsers in the prompt. A generic "write me a parser" produces generic output.
  • Spell out the class and the important mappings. The agent can't tell which fields matter to your analysts.
  • Validate every iteration. A parser that looks right can silently drop fields.
  • Let the long tail go to unmapped. It's still searchable as unmapped.<key>.

Troubleshoot

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

VRL fails to compile

Check fallible calls such as to_int(...). Handle errors with ?? or an if err == null block and rerun validation.

Validation reports UNVALIDATED

Add a samples/ directory with representative events and a malformed line, then rerun the validation script.

What's next

On this page