nano SIEM
Agents & MCPInvestigator

Build parsers

Supported in:Self-hosted

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:

  1. Read the VRL reference resource
  2. list_log_sources, so it doesn't duplicate an existing source type
  3. Draft a parser for the whole source, not just the sample
  4. validate_vrl: compile-check; fix every diagnostic and re-run until valid
  5. test_parse_sample: run the VRL against the sample and inspect the output
  6. create_log_source: save a working copy (validated, not live)
  7. publish_log_source: promote the working copy so it goes live
  8. get_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_vrl compiles the VRL and returns { valid, errors, diagnostics }. Diagnostics carry line, column and a code (such as E651 or E203), so the agent can fix the exact spot.
  • test_parse_sample runs the VRL against one raw line and returns the parsed output plus extracted_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_source saves a working copy. The server validates and stores it, but it isn't live. update_log_source edits a working copy the same way.
  • publish_log_source promotes the working copy to a new active version and rolls it out. This is the step that makes an edit live.
  • deploy_log_source re-pushes the already-published version without promoting anything. Use it to retry a failed rollout, not after editing VRL.
  • undeploy_log_source takes 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-Type header, 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_types lists the transport drivers and their match-field presets.
    • list_source_configs lists configured transports.
    • check_rule_reachability checks 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_rule maps 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_repositories lists connected repositories and their sync status.
  • sync_parser_repository refreshes the cached copy from upstream.
  • list_repository_parsers browses the available parsers.
  • import_parser imports one as a working copy, either linked (tracks upstream updates, the default) or forked. 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.

What's next

On this page