Authoring Parsers
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.jsonparser.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
}
. = ocsfThe contract:
- Emit the full OCSF object on the root (
. = ocsf). Setclass_uid,activity_id,type_uid(class_uid * 100 + activity_id),category_uid,severity_id,timeandmetadata.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.nameoruser.name(depends on the class),time,metadata.uid. See OCSF schema and OCSF field reference. - When no class fits, use Base Event (
class_uid0) 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.jsonStep 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 inparsers-ocsf/myapp/samples/. Useparsers-ocsf/okta/parser.yamlas the structural reference. Logins and logouts are Authentication (3002); mapstatustostatus_id(1 success, 2 failure) andreasontostatus_detail. Everything else goes underunmapped.
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.yamlIt runs two gates on every sample:
- VRL:
vector vrlcompiles and runs the program. A runtime abort is a failure, because that parser would drop every event it touches. - OCSF: the emitted event is checked against nano's OCSF 1.9 contract (needs nano's
ocsf_event_validatebinary onPATHor inOCSF_VALIDATOR), plus:metadata.versionmatchesocsf_version, thetype_uidformula holds, no legacy output fields, the class isn't deprecated, and every path is either a queryable OCSF path or underunmapped.
A parser with no samples/ directory is reported as UNVALIDATED.
Spot-check the output:
class_uid,activity_idandtype_uidare set on every eventtimeis correct (epoch milliseconds)- IPs are under
src_endpoint/dst_endpoint, not left inunmapped - Nothing important landed in
unmappedthat 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 asunmapped.<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
- Authoring detections: write detections against the parsed data
- Build parsers: the interactive parser workflow over MCP
- OCSF field reference