Expose structured BGP parse diagnostics for application-level malformed-message investigation

[digizeph]

Problem

Applications such as BGPKIT Monocle need to detect, classify, display, and optionally retain malformed BGP UPDATE messages.

Today, bgpkit-parser has the underlying signals, but they are not application-friendly:

• Fatal parser failures are skipped by default iterators.
• Fallible iterators expose ParserErrorWithBytes, but body-parse failures currently do not retain the offending raw MRT record.
• Recoverable RFC 7606 violations are retained in Attributes::validation_warnings(), but require callers to manually inspect parsed updates.
• BgpElem intentionally discards attribute-validation context.

A CLI report mode could be built later, but the parser should first provide a stable structured diagnostic API that Monocle and other applications can consume.

Proposed solution

Add a library-level diagnostic iterator/API that preserves parsing progress and yields both successfully parsed records and malformed-data diagnostics.

Diagnostics should distinguish:

1. Fatal record/message parse errors

   • ParserError
   • MRT common header, when available
   • Original raw MRT record bytes, when available
   • Enough context to identify the source record and export it

2. Recoverable validation findings

   • Parsed record/update context
   • One or more BgpValidationWarning values
   • Original raw MRT record bytes, or a way to access them without re-encoding
   • Peer, timestamp, and announced/withdrawn prefixes when parsing reached them

The API should continue scanning after an individual malformed record where recovery is possible.

Possible API shape

The exact naming is open, but a stream of structured events would let applications process both categories uniformly:

for event in BgpkitParser::new(input)?.into_diagnostic_iter() {
    match event {
        DiagnosticEvent::Record(record) => {
            // Valid record with no validation findings.
        }
        DiagnosticEvent::Validation {
            record,
            warnings,
            raw_record,
        } => {
            // Parsed UPDATE, but RFC 7606 validation findings exist.
        }
        DiagnosticEvent::ParseError {
            error,
            common_header,
            raw_bytes,
        } => {
            // A record or embedded BGP message could not be parsed.
        }
    }
}

The API should avoid requiring applications to parse the input twice or reconstruct raw bytes by re-encoding parsed models.

Acceptance criteria

• Applications can discover fatal malformed NLRI/prefix and attribute parse failures without relying on logs or enable_core_dump().
• Applications can discover recoverable BgpValidationWarning findings, including invalid flags/lengths, duplicate or missing mandatory attributes, malformed AS_PATH, and invalid ORIGIN/NEXT_HOP.
• Diagnostics carry original MRT bytes when the full record was read successfully.
• The iterator continues after recoverable failures.
• Existing default and fallible iterator behavior remains backward compatible.
• Add fixture-based tests for invalid/truncated NLRI, malformed attribute encoding, invalid attribute flags or length, missing/duplicate mandatory attributes, malformed AS_PATH, raw-byte preservation, and continued iteration.

Follow-up

Once this API exists, Monocle can implement UI/API reporting, filtering, aggregation, and record export without parser-specific workarounds. A parser CLI reporting mode can then be a thin consumer of the same API.