Build parsers
Author, validate, test and publish log-source parsers (VRL that emits OCSF 1.9) over MCP with the build_parser prompt
Use the nano-investigator parser tools to write, test, save, and publish a log-source parser from your agent. The parser is a VRL program that turns raw log lines into OCSF 1.9 events.
This is the interactive way to author a parser: you work against a live deployment and the server validates and tests for you. The version-controlled way is Authoring parsers, where you draft a parser.yaml in a repository and ship it by pull request or import.
The build_parser prompt
build_parser takes the log's source type name (required) and a sample_log (optional, strongly recommended). It scripts a validate-first loop, so the agent never publishes VRL it hasn't compiled and tested:
- Read the VRL reference resource
list_log_sources, so it doesn't duplicate an existing source type- Draft a parser for the whole source, not just the sample
validate_vrl: compile-check; fix every diagnostic and re-run until validtest_parse_sample: run the VRL against the sample and inspect the outputcreate_log_source: save a working copy (validated, not live)publish_log_source: promote the working copy so it goes liveget_log_source_health: confirm events are flowing
The agent shows the VRL and the test output before saving, and asks before publishing.
Validate and test before saving
Two tools run a parser without changing anything saved:
validate_vrlcompiles the VRL and returns{ valid, errors, diagnostics }. Diagnostics carry line, column and a code (such asE651orE203), so the agent can fix the exact spot.test_parse_sampleruns the VRL against one raw line and returns the parsed output plusextracted_field_count. nano also checks the output against the OCSF 1.9 contract; an event that isn't valid OCSF fails the test.
For a source that's already ingesting, test_parse_live takes recent real events and parses them with both the new VRL and the currently published version, side by side. Use it when refining a parser rather than writing one.
> build a parser for source type "acme_fw". sample:
ts=2026-06-01T10:15:00Z src=10.1.1.5 dst=8.8.8.8 act=deny proto=udp dpt=53
Emit OCSF 1.9 Network Activity on the root; use parsers-ocsf/palo_alto as the template.
Running build_parser (acme_fw)...
list_log_sources: no existing parser for acme_fw. Drafting.
validate_vrl: valid=false — E651 at 7:34 (`??` on to_string).
Fixed. validate_vrl: valid=true.
test_parse_sample: success=true
class_uid = 4001
activity_id = 6 (Traffic)
action_id = 2 (Denied)
time = 1780308900000
src_endpoint.ip = "10.1.1.5"
dst_endpoint.ip = "8.8.8.8"
dst_endpoint.port = 53
connection_info.protocol_name = "udp"
raw_data = "ts=2026-06-01T10:15:00Z src=10.1.1.5 ..."
Save this as a working copy for acme_fw? (won't go live yet)Save, then publish
Saving and publishing are separate, as in the web UI.
create_log_sourcesaves a working copy. The server validates and stores it, but it isn't live.update_log_sourceedits a working copy the same way.publish_log_sourcepromotes the working copy to a new active version and rolls it out. This is the step that makes an edit live.deploy_log_sourcere-pushes the already-published version without promoting anything. Use it to retry a failed rollout, not after editing VRL.undeploy_log_sourcetakes a parser offline.
Don't trust a success response alone. Wait a minute and call get_log_source_health. It reports 24-hour and last-hour event counts, freshness, and a health_status of healthy, stale, no_data, disabled or error. get_log_source_deployments shows the rollout history and any error.
Parsing happens at ingest and isn't retroactive. Judge a change only on events that arrived after it went live.
Versions and rollout
Publishing creates a new version and delivers the updated Vector configuration to every Vector instance, and you can revert from Log Sources. See Parser extensions. The key needs log_sources:view, log_sources:create, log_sources:edit and log_sources:deploy.
Route events to the parser
A published parser only sees events that are routed to its source type.
- HTTPS JSON and HEC senders name the source type themselves: the
X-Source-Typeheader, or the source type field of the HEC event. A parser whose source type matches is reachable as soon as it's live. See Ingest data. - Pull sources (Kafka, AWS S3/SQS, GCP Pub/Sub) use source configurations and routing rules:
list_source_config_typeslists the transport drivers and their match-field presets.list_source_configslists configured transports.check_rule_reachabilitychecks a planned rule: the source config is enabled and deployed, a parser exists for the target, and (for Kafka) a broker is reachable.create_routing_rulemaps matching events to a parser's source type.
Start from a prebuilt parser
nano can import parsers from a repository such as nano-rs/parsers:
list_parser_repositorieslists connected repositories and their sync status.sync_parser_repositoryrefreshes the cached copy from upstream.list_repository_parsersbrowses the available parsers.import_parserimports one as a working copy, eitherlinked(tracks upstream updates, the default) orforked. Publish it like any other.
Troubleshoot
Need help with these checks? Contact support with the request ID and time with timezone.
Deploy succeeds but the edit is missing
deploy_log_source sends the already-published parser. Use publish_log_source to promote the working copy, then check draft status and deployment history.
Sample output fails OCSF validation
The 0.1.16 prompt teaches the UDM shape. Give the agent the OCSF 1.9 root-object contract above and rerun the sample test.