MCP Tools - NormB/sipnab GitHub Wiki

Every tool the MCP server exposes, what it answers, and what it returns.

This is lookup material, not reading material.

• MCP server — what MCP is, and a first working example.
• MCP deployment — the deployment shapes.
• MCP protocol — the wire contract, security model and error semantics.

The v0.5 sipnab MCP tool surface. No tool edits the analysis in place, and every response carries a ceiling. That ceiling defaults to 1000 rows and is an operator setting, not a build-time fact: --mcp-max-rows N, or [limits] mcp_max_rows in the config file, with the flag winning. The right value belongs to the consumer — a model with a small context window wants far fewer, a batch client piping to a file wants far more. Note this is a DIFFERENT limit from dialog_limit, which bounds dialogs tracked over the whole run and defaults 100x higher. One tool replaces the analysis outright — open_capture, off unless you enable it — and it mints a new capture identity so the replacement cannot reach a consumer as an ordinary update.

Survey — what is in this capture

Find — narrow to the calls that matter

Diagnose one call

Conformance and rules

Security

The peer this needs. These read TFPS through its tfps_ctl program in JSON mode, the --json flag. TFPS gained that mode in sippulse/tfps#6, merged on 2026-09-18, and no tagged release carries it yet: v0.2.1, the newest, rejects --json. Until the next release, build TFPS from its master branch. To check the tfps_ctl you have, run tfps_ctl status --json. One line of JSON means it is ready, and unknown option: --json means it predates the mode. Against an older tfps_ctl these answer with that error and name what to install.

tfps_dropped is the exception: it needs a dropped subcommand that no TFPS build has, released or on master, so it answers with TFPS's own unknown command: dropped and says so.

Evidence and provenance

Export and handoff

Capture control (opt-in, off by default)

Six rules hold across the whole surface. Each tool section below states only what it does differently, so read these once and skip them afterwards.

A required parameter has no default. Leave one out, or send the wrong JSON type, and the call fails with invalid_params (-32602) before the tool runs. Optional parameters carry a ? in every table on this page, and each row says what the tool does when you omit that one.

A limit of 0 means the default, not "no rows". limit defaults to 50 everywhere it appears. The server clamps anything larger to --mcp-max-rows (1000 unless the operator lowered it) and returns the clamped page without an error. Both edges bite the same caller: a client that computes limit from "rows I still want" asks for 50 when it meant to ask for none, and a client that asks for 5000 to "get everything" receives 1000 and no complaint. Read returned rather than the length you asked for.

Pass a cursor back exactly as it arrived. next_cursor pairs a timestamp with an identity — <RFC 3339>|<Call-ID> for dialogs, and <RFC 3339>|0xSSRC@src>dst for the rtp_stats sweep. A hand-rebuilt bare timestamp still parses, so rebuilding one costs rows instead of raising an error. next_cursor: null marks the final page.

Every list-style tool answers with a page object, never a bare array. The rows sit under a named key — dialogs, hits, streams, findings — beside returned and total_matched, so counting the rows is never necessary and never right. search_messages and security_findings carry the page fields too. tail_dialogs is the one page object with no total, because a tail cannot have one. Response bounding tabulates it.

Every answer says how much of the capture is behind it. Two booleans ride on every response object: source_exhausted, true once sipnab has read the source to its end, and source_stopped_early, true when a read ended before the source did — a truncated dump file, a file that would not open, a read error part-way through. The answer is the WHOLE answer only when source_exhausted is true and source_stopped_early is false, and one response tells you that much, so nothing has to call capture_status to interpret it.

Until then the response omits truncated: false entirely. That value claims outright that the page holds every match, and a caller reading only that field deserves no claim rather than a wrong one — JSON absence and false are different values. The response still says truncated: true whenever the row cap really did keep matches out, because that fact holds whatever the load state. complete, where a tool has one, likewise never reads true over a partial read.

A file source loads on a background thread, so an agent's first call lands inside a window a human client never sees: on a 921 MB capture, list_dialogs answered with 6 of 18,241 dialogs. tail_dialogs and capture_status have always carried source_exhausted. Now every tool that answers from the capture does. Seventeen tools are the exception, because their answer cannot move with the load. Nine read something other than the capture store — explain_response_code, explain_rule, decode_evidence, decode_ng, show_evidence, list_captures, list_tls_libraries, server_capabilities and compare_captures, which reads two files and never the loaded capture. The other eight ask another process: query_relay and relay_stats put the question to the media relay, and tfps_status, tfps_banned, tfps_dropped, tfps_labels, tfps_ban and tfps_unban put it to the toll-fraud prevention peer. How much of the capture sipnab has read says nothing about what those hold. The tools that answer with a rendered document — render_ladder, and get_capture_report / get_dialog_report in markdown and text — have no object to put a field in, so they say it in prose instead: a document drawn over a capture that is still loading, or over one whose read stopped before its end, ends with the same INCOMPLETE RUN block --report appends, naming each reason. A document drawn over a capture read in full says nothing extra, because a caveat on every answer is a caveat nobody reads. Every other tool answers with a JSON object, so the two booleans sit in the object beside the tool's own fields — timeline was the last one returning a bare array, and it now wraps its rows in an object for exactly this reason.

Capture text arrives fenced, and identifiers do not. Free text an endpoint wrote — display names, User-Agent, SDP, whole messages — comes wrapped in ⟦untrusted-capture-data⟧ … ⟦/untrusted-capture-data⟧, and the tools that emit it append a provenance note as the LAST content block. Call-IDs, cursors, addresses and timestamps stay verbatim so they pass straight into the next call. Untrusted capture text gives the per-tool breakdown. Every JSON sample below shows the markers where the server really emits them.

Each tool section names the capture its example ran against. Start a server on that capture, then call the tool. These two cover most of the page:

# The paging examples: 1334 dialogs, no RTP.
sipnab -N --mcp --mcp-transport http --mcp-bind 127.0.0.1:8731 \
       --mcp-file-root tests/pcap-samples \
       -I tests/pcap-samples/sipp-branch-scenario.pcapng

# The media examples: one completed call, two RTP streams.
sipnab -N --mcp --mcp-transport http --mcp-bind 127.0.0.1:8731 \
       --mcp-file-root tests/pcap-samples \
       -I tests/pcap-samples/sip-rtp-g711.pcap

Drive either one with the raw HTTP test on the deployment page, or point a client at http://127.0.0.1:8731/mcp. A loopback bind needs no token.

Numbers in the samples are what those captures produce. Jitter and MOS come out byte-identical run to run, because a file replay reads packet timestamps rather than arrival times, so a value that fails to match points at a real change rather than at timing noise.

Start here when you have a capture and no particular suspect. These answer "what is in it", "how much", and "is the server even seeing traffic".

Ask this first. It answers what the server is actually attached to — a live interface or a replayed file — which nothing else on this surface reveals.

No parameters. Returns:

{
  "schema_version": 2,           // 2 absorbed the counters the old stats tool returned
  "source": "live",              // "live" | "file" | "unknown"
  "name": "eth0",                // interface, or file path
  "uptime_sec": 3612,
  "dialog_count": 128,
  "stream_count": 64,
  "orphaned_stream_count": 3,    // streams no dialog claims
  "active_dialog_count": 12,     // any non-terminal state
  "active_call_count": 9,        // InCall only — narrower, hence the version bump
  "capture_quality": {
    "kernel_dropped_packets": 0,
    "interface_dropped_packets": 0,
    "invalid_timestamps": 0,
    "undecodable_frames": 0,
    "degraded": false
  },
  "caveats": {
    "media_creating_commands": 0  // relay commands seen and NOT attributed
  },
  "source_exhausted": false,     // true once a file is read to the end
  "source_stopped_early": false, // true when a read ended before the file did
  "writing_to": null,            // path packets are being saved to, if any
  "unsaved": true,               // stopping now would lose packets
  "capture_identity": {
    "node": "capture01",
    "instance": "1f4a17c8e2b91d40-1",
    "dialog_generation": 412,
    "stream_generation": 96
  },
  "unanalysed_sip_messages": 0,  // SIP that --portrange excluded
  "unanalysed_busiest_ports": [],
  "unanalysed_websocket_messages": 0,  // SIP-over-WebSocket the WS port set excluded
  "unanalysed_websocket_ports": [],    // pass these to --ws-portrange
  "load": null                   // an open_capture load in flight, if any
}

unsaved is the field that matters. It is true only for a live capture with no output file — packets held in memory and nowhere else. A file replay is already on disk, so it is never unsaved.

source: "unknown" means nobody gave the server capture context. It reports that rather than guessing, because a wrong "live" would be worse than an admission of ignorance.

capture_identity says which capture this is and how many times its stores have changed. Compare it across calls: a higher generation on the same instance means the capture grew, and a different instance means open_capture loaded a different file and every cursor you hold is void. The same object appears on capture_status, list_dialogs, find_problems, tail_dialogs, find_correlated, save_findings, open_capture and the capture-wide rtp_stats sweep. node names the box that answered, which decides whose capture a fact came from once an agent holds several servers at once.

load is null except while an open_capture read runs. During one:

"load": {
  "filename": "outage-0722.pcap",
  "instance": "1f4a17c8e2b91d40-2",
  "packets": 184320,             // climbing
  "elapsed_sec": 4,
  "done": false,
  "error": null                  // set when a load stopped early
}

The stores fill as the read goes, so dialogs appear before done. Wait for done before concluding anything about how many calls the capture holds — a partial answer looks exactly like a complete one.

Read the two unanalysed_ pairs before reading anything into dialog_count. They report SIP that sipnab recognized and did not analyze, and they are the only way to tell a capture that holds no calls from one whose calls fell outside a port setting. They count different losses with different remedies, so a non-zero figure names its own flag:

• unanalysed_sip_messages / unanalysed_busiest_ports — plain SIP signaling with both ports outside --portrange. Re-run with a range that covers the ports listed.
• unanalysed_websocket_messages / unanalysed_websocket_ports — SIP-over-WebSocket (RFC 7118) on a port outside the WebSocket set. Re-run with --ws-portrange covering the ports listed; widening --portrange recovers none of it. This is the common case on a WSS listener behind a reverse proxy, and on Kamailio, OpenSIPS and Janus, which all default outside sipnab's shipped 80/443/8080/8443.

Both are zero on a live capture, where BPF filtered before the pipeline saw anything and there is nothing to under-report.

Asterisk's Manager Interface speaks a line protocol on TCP/5038, and a login is four lines of plain text: Action: login, Username:, Secret:. AMI can originate calls, read configuration and run shell commands, so the credential is worth strictly more than the SIP digest --digest-leak already reports.

Reported here because this is where the misleading zero was. unanalysed_sip_messages: 0 was the complete answer for a capture full of AMI, and the zero is honest — AMI is not SIP, so there was no unparsed SIP message to count. Every detector sipnab had ran on parsed SIP messages, and this traffic never became one.

The secret is never recorded. sipnab writes findings to logs, exports them in containers and hands them to an agent's context, so the Secret: line becomes the fact that a credential crossed the wire and nothing more.

Not a decoder. It matches a banner and a login line and records where they were. No session tracking, no response following, nothing else the protocol carries.

The port is an observation, not a filter. An interface moved off 5038 is still reported, with default_port: false — a deployment that moved the service is the one most likely to think nobody can find it, and a rule keyed on the default would agree.

No arming needed, unlike the detectors behind security_findings. It costs two literal prefix tests on payloads that have already failed the SIP check, so there is no cost to gate against. A login with an AuthType: MD5 challenge and no Secret: line reports secret_present: false, so it never counts as a cleartext password.

Sightings aggregate per address pair, so one session reconnecting in a loop is one row with a count. The account is deliberately outside that key: this path runs before authentication, so the field is attacker-chosen.

Always present, and empty when there is nothing to report. sipnab omits every other optional block on this surface because it may never have run the check at all. It runs this one on every capture, so [] means "looked, found none" — a stronger answer than a missing key.

capture_quality above counts what the capture lost. caveats counts what sipnab chose not to do, which is a different thing and is not a defect.

Those commands create media belonging to a call without being one of its two legs. Decoding one as an ordinary leg would make a two-party call report three streams, after which the analysis that judges one-way audio and asymmetry answers a question nobody asked — so sipnab counts them instead.

Read this before reasoning about a stream count. A call with a recording fork has media on the wire that no rtp_stats row explains, and this number is how you know that is a decision rather than a gap. Zero is a real answer and the key is always present.

Absent when nobody supplied keys, which is not a decryption failure. When a decryptor ran, the block carries keylog_entries, sessions_with_keys, app_data_records, decrypted_records, undecrypted_records, late_recovered, late_evicted and read_nothing.

Act on read_nothing, never on the arithmetic. A TLS handshake carries records sipnab never loads keys for, so app_data_records > decrypted_records is not by itself a failure — an agent deriving a verdict from the two counts reports a working capture as broken and sends an operator after keys that already work. read_nothing is true only when application data arrived and none of it opened.

That case is why the block exists. A capture holding ciphertext nobody can open produces a dialog listing identical to one from a quiet network. If you are about to answer "there was no SIP on this capture", check this field first: server_capabilities.can_decrypt says whether the BUILD can decrypt, and this says whether this RUN did.

GET /v1/stats carries the same block under the same name.

What sipnab is doing, and what it is costing the host it runs on.

sipnab exports 32 Prometheus metrics, and the listener that serves them is off by default — so on most deployments those numbers exist inside the process and nothing can read them. An agent asked "is this server healthy" could not enable a listener to find out. This answers without one.

Starts no capture. Every field below answers instantly. The one optional parameter, sample_seconds, buys a rate at the cost of a wait that long.

// runtime_stats {}
{
  "schema_version": 1,
  "process": {
    "rss_bytes": 36831232, "virtual_bytes": 1276391424,
    "threads": 3, "open_fds": 10, "cpu_seconds": 0.01
  },
  "host": {
    "memory_total_bytes": 131881889792,
    "memory_available_bytes": 121499242496,
    "cpus": 14, "basis": "host"
  },
  "impact": {
    "memory_pct": 0.0279, "significant": false,
    "note": "sipnab holds 0.0% of the host memory total; the threshold for load-bearing is 10.0%"
  },
  "interfaces": [],
  "dialogs": { "used": 1, "capacity": 100000, "pct": 0.001 },
  "streams": { "used": 2, "capacity": 10000, "pct": 0.02 },
  "capture_packets_total": 852,
  "capture_queue_depth_packets": 0,
  "capture_backpressure_blocks_total": 0,
  "uptime_seconds": 41
}

An absent field means "not readable here", never zero. Every value under process and host is optional, because the sources are platform-specific. A field reported as 0 on a platform where it was never read is worse than one that says it does not know.

host.basis names the denominator. Inside a container the real limits are the control group's limits rather than the machine's, so the basis reads cgroup and the totals come from memory.max. A percentage against the wrong total is worse than no percentage, because a reader believes it.

impact.significant is a verdict. A capture that is itself the reason a proxy started dropping calls is the worst failure this tool can have, and it used to be invisible. note carries the threshold, so you can disagree with the setting rather than with the finding.

interfaces reads the interface, not the capture handle. sipnab's own counters describe what reached sipnab. These describe what reached the NIC. The pair separates the two remedies — ps_ifdrop climbing with rx_missed_errors is hardware that cannot keep up, and the fix is ring size, coalescing or RSS. ps_drop climbing alone is sipnab's read loop falling behind, and the fix is --buffer or a tighter filter. The handle counter alone cannot tell you which.

The capture-queue fields are absent without a capture. A run replaying a file through the API owns no capture meter, so capture_queue_depth_packets and capture_backpressure_blocks_total do not appear at all, rather than appearing as 0. Zero there would read as "the queue is clear", which is the one thing a saturated pipeline must never say.

Occupancy, not just counts. dialogs.used alone is a number. Beside capacity it is a decision. An operator who cannot see occupancy learns about eviction by noticing that calls have gone missing.

Rates cost a wait, so ask for one explicitly. Every counter above is cumulative, and "1,284,301 messages" answers a different question from "312 messages/second, of which 190 are OPTIONS". Send sample_seconds to read the counters twice across that window:

runtime_stats { "sample_seconds": 5 }
// ... the same envelope, plus:
{
  "rates": {
    "window_seconds": 5,
    "packets_per_second": 412.6,
    "calls_per_second": 3.4,
    "calls_per_second_by_method": [["OPTIONS", 2.8], ["INVITE", 0.6]]
  }
}

The breakdown is the point: a rate that does not separate INVITE from OPTIONS describes whatever the deployment does most, which in the field is the keepalive plane rather than the calls.

window_seconds is the window sipnab applied. sipnab caps a long window at 30 seconds so one tool call cannot outlive the client's own deadline, and rejects sample_seconds: 0 rather than answering it — an empty window returns zero deltas, and zero deltas is exactly what a healthy quiet capture reports.

The REST endpoint GET /v1/runtime returns the same envelope from the same derivation — including the same refusal and the same cap — so the two surfaces cannot disagree about one process.

Reads the capture counters, waits, and reads them again. The response carries the run totals and the change across that window, which turns a pile of monotonic counters into a rate.

sample_seconds is required — this tool has no default window, because a rate without a stated interval is not a rate. The call blocks for that long:

capture_health { "sample_seconds": 1 }

capture_status tells you what the counters say right now. capture_health tells you what they did over a window you chose, which is the difference between "this process has dropped 4 million packets since Tuesday" and "this process is dropping packets now".

Three questions it answers on a busy production server:

1. Does the capture path drop packets under load? Read in_window.kernel_dropped and in_window.interface_dropped. They stay apart because their fixes disagree — a bigger ring buffer cures the first and does nothing for the second.
2. What is on this wire that sipnab cannot decode? Read undecodable_by_reason. Each entry names the reason as a code and carries the number that identifies it: the link type, the EtherType, or the IP protocol.
3. What does the encapsulation-aware capture filter cost? Run the same window twice, once with --capture-tunnels and once without, and compare in_window.packets against the two drop counters.

The call blocks for the whole window, so a client with a short request timeout should ask for a few seconds rather than 30.

Returns:

{
  "schema_version": 1,
  "attachment": 2,
  "window": {
    "requested_seconds": 10,
    "applied_seconds": 10,
    "observed_ms": 10003
  },
  "totals": {
    "packets": 8412990,
    "kernel_dropped": 1204,
    "interface_dropped": 0,
    "invalid_timestamps": 0,
    "undecodable_frames": 2103247
  },
  "in_window": {
    "packets": 94318,
    "kernel_dropped": 17,
    "interface_dropped": 0,
    "invalid_timestamps": 0,
    "undecodable_frames": 23610
  },
  "undecoded_fraction": 0.24999999,
  "undecoded_fraction_in_window": 0.2503,
  "undecodable_by_reason": [
    { "reason": 2, "number": 34887, "frames": 2061109, "frames_in_window": 23140 },
    { "reason": 3, "number": 47,    "frames": 41022,   "frames_in_window": 465 },
    { "reason": 4, "number": null,  "frames": 1116,    "frames_in_window": 5 }
  ],
  "undecodable_reasons_dropped": 0,
  "dialogs_tracked": 2411,
  "streams_tracked": 4802,
  "clock": {
    "synchronized": true,
    "max_error_us": 238000,
    "est_error_us": 0,
    "available": true
  },
  "source_exhausted": true,
  "source_stopped_early": false
}

source_stopped_early answers the question this tool usually gets: did the whole capture arrive? It reads true when a file's read ended before the file did — libpcap error: truncated dump file, a file that would not open, a read that hit an error part-way through — which is the normal state of a ring buffer's newest member and otherwise stays invisible here. Until this field landed, that condition reached stderr as 0 of 1 file(s) read in full, 1 stopped early and reached this response not at all, so an agent asking whether a capture was sound got no answer either way. Both fields are booleans, so the response type stays free of strings.

This tool starts no capture. With --mcp attached to a live interface, the counters already accumulate, so a rate costs two reads and a wait. That is not only the cheap design, it is the safe one: the handler opens no device, names no interface, and writes no file, so no path leads from an MCP call to a capture that transmits or records anything.

No value in this response is a string. The response type holds integers, codes, two proportions and the clock's booleans, and it has no string field anywhere in it or in anything nested inside it. A type that cannot represent packet content cannot leak packet content, which is why the reasons below travel as codes and their labels live on this page instead of on the wire. The test a_populated_capture_health_response_carries_no_string_value_anywhere serializes a full response and fails on any string value at any depth.

Code 1 exists so that a server with nothing to read says so. A row of zeros from a tool that never had a capture looks exactly like a healthy quiet wire, and no code is 0, so a defaulted or truncated response can never pass for a real answer.

The number is the whole point of the entry. "Unsupported link type" names no action, and "unsupported link type 0" names three. frames counts the whole run, frames_in_window counts the sample, and an entry whose frames_in_window is 0 describes a problem that has already stopped.

undecodable_reasons_dropped counts frames whose specific number did not fit the fixed-slot tables behind these counters. A non-zero value means the breakdown adds up to less than totals.undecodable_frames, and the field exists so that nobody has to discover the shortfall by subtracting.

An MCP tool call blocks the agent that made it. The handler holds a request slot for the whole window, and clients cancel a call that has not answered — 60 seconds is the common default. A window that can run for minutes turns a diagnostic into a denial of service against the agent that asked for it.

Thirty seconds keeps the whole call inside half of that budget and still buys a window worth having. A trunk at 10,000 packets per second puts 300,000 packets through it, which is enough for a drop rate to mean something. For a longer view, call the tool repeatedly and read totals.

Divide by window.observed_ms, never by sample_seconds. A loaded runtime wakes the handler late, and the response reports the wall clock precisely so that a rate does not inherit that error.

Clock discipline. The response carries a clock object — synchronized, max_error_us, est_error_us, available — read from adjtimex(2) at report time rather than cached at startup, since a host can lose its time source while sipnab runs.

It is irrelevant to a single capture, where one clock stamped every packet and a constant offset cancels out of every interval. It matters the moment you correlate across NODES: find_correlated's timing_heuristic matches dialogs that started within the leg-correlation window of each other — two seconds unless --leg-correlation-window says otherwise — and that is smaller than the skew an undisciplined host accumulates in a day. A clock three seconds fast fails to correlate legs that belong together, and a slow one pulls unrelated legs inside the window. Widening the window to reach a B2BUA that dips a database before placing the outbound leg widens this exposure with it. Read clock from both servers before trusting a time-based match, and prefer any of the six identifier strategies — session_id, x_call_id, charging_vector_related_icid, sdp_origin, charging_vector_icid or via_branch — none of which care what time anyone thinks it is.

available: false means the platform gave no answer — NOT that the clock is bad. The two are different facts and only one of them is a problem.

The whole-capture analysis, the one --report prints. Backed by analysis::analyze and rendered by output::analysis_report.

get_dialog_report and render_ladder both answer for ONE Call-ID, so everything the report says about the capture as a whole had no MCP path: orphaned media, STUN, ICMP errors quoting SIP or RTP, and what the retention caps shed. capture_status could hand an agent a count, and no tool could expand it.

Frames read comes from the same process-global counter the Prometheus scrape reports (sipnab_capture_packets_total), so the denominator here is the one every other number in the run measures against.

A capture with no findings still answers with the clean line rather than an empty body, because silence is indistinguishable from the tool not having run:

// get_capture_report { "format": "text" }
// A capture with findings names each one; a clean capture says so outright.
"Capture analysis: 2 finding(s) across 1 dialog(s), 2 stream(s), 535000 frame(s) read."

json is the default and returns an OBJECT, serialized from the analysis itself — findings, dialogs_examined, streams_examined, frames_read and complete.

Each findings row is one ranked problem, worst first:

An evidence row carries call_id, endpoints (most specific first), at, counts (named integers such as rtp_packets and streams) and note. sipnab leaves out any of the five that does not apply rather than sending null. A capture-level finding that belongs to no call, such as a STUN probe or an undecodable frame, simply has no call_id.

// get_capture_report { "format": "json" } — one findings row, against
// tests/pcap-samples/sip-rtp-g711.pcap
{
  "kind": "one_way_audio",
  "severity": "critical",
  "occurrences": 2,
  "unit": "call",
  "evidence": [
    {
      "call_id": "[email protected]",
      "endpoints": ["10.0.2.20:5060 -> 10.0.2.15", "SDP 10.0.2.20"],
      "at": "2016-11-26T14:52:59.666393Z",
      "counts": { "rtp_packets": 425, "streams": 1 },
      "note": "10.0.2.15:27942 -> 10.0.2.20:6000 carried 425 packet(s); nothing came back the other way"
    }
  ],
  "evidence_omitted": 0
}

Read complete before the findings: it is false when the capture lost packets, hit a retention cap, or held frames no decoder could read, and a findings list from such a capture is a floor, not a total.

complete also reads false while the load runs, and for a source whose read stopped before its end. It answers "did sipnab read all of its input", so a file still arriving cannot satisfy it. Until this gate landed it ignored the load entirely and read backwards during one: on a 100 MB capture the same tool in the same session answered complete: true at frames_read: 312 and complete: false at frames_read: 365747 — true over 0.09% of the file, false once the whole file had arrived. The field keeps its name and its meaning. What changed is that the two facts under it, source_exhausted and source_stopped_early, now gate it and travel beside it.

markdown and text answer with a rendered document, which has no envelope to carry either flag, so the document states the fact itself. A report drawn while the capture is still loading, or over one whose read stopped before its end, ends with an INCOMPLETE RUN block naming each reason — the same block --report appends, and for the same reason: the reader of a rendered report has no $? and no JSON in front of them, and a partial report looks exactly like a whole one. A capture read in full adds nothing and the report ends where it always did. Ask for json when you want the two booleans as fields.

Before 0.5.125 this default returned the TEXT rendering. format chooses between markdown headings and plain text inside the renderer and never had a JSON arm, so the tool asked for JSON, got prose, and fell back to a text block. An agent that called it with no argument received prose and nothing to say the structure it asked for was never there.

GET /v1/report answers the same question over REST.

Capture files in the configured root, with their sizes and the instant each one's first packet arrived.

Parameters: none.

It lists .pcap and .pcapng only, matched case-insensitively, and skips directories. That is narrower than what open_capture accepts, which is any readable capture the name resolves to — a .cap file sitting in the root opens fine and never appears here, so an agent that treats this listing as the whole set it may open misses it. Ask the operator, or try the name.

list_captures {}

Without --mcp-file-root the whole file-tool group is off, and this answers with a refusal rather than an empty list — "no directory configured" and "the directory is empty" are different facts:

{ "code": -32602,
  "message": "file tools are disabled: start sipnab with --mcp-file-root <DIR>" }

Otherwise it answers with captures sorted by filename, plus schema_version. Running it against tests/pcap-samples returns 30 of the directory's 36 entries. The six it leaves out are five .cap captures and one file carrying no extension at all:

// list_captures {}
{
  "schema_version": 1,
  "captures": [
    { "filename": "Asterisk_ZFONE_XLITE.pcap", "bytes": 255581,
      "first_packet": "2010-09-27T07:12:49+00:00" },
    { "filename": "DTMFsipinfo.pcap", "bytes": 25429,
      "first_packet": "2011-04-27T08:14:29+00:00" },
    { "filename": "b2bua-asterisk.pcapng", "bytes": 114952,
      "first_packet": "2016-05-18T18:23:03+00:00" }
    // ... 27 more
  ]
}

first_packet is what turns a listing into a choice. It is the timestamp on the first record of the file, read whole seconds, so forty rotated captures narrow to the two that could hold a call from 14:02 without opening each one in turn. Opening one is not free: open_capture replaces the loaded capture and voids every cursor and Call-ID an agent is holding. The key reads null whenever sipnab got no first packet out of the file — a rotated capture that never received one, or a file it could not open — so treat null as "unknown", not as "empty". sipnab reports neither a dialog count nor a last-packet time here, because both need the whole file parsed and a listing that costs a full read of every capture in the root is a listing nobody runs.

Which of these files holds the call, asked without giving up the one you are working in.

list_captures narrows forty rotated files to the two that could hold a call, by time. That is a filter, not an answer. The question an operator actually has — "which of these holds Call-ID X" — had no tool at all: the only way inside another file is open_capture, documented Destructive, which replaces every dialog and stream and mints a new capture_identity that voids every cursor you hold.

This sweeps instead: a scratch store per file, the filter applied, the loaded capture untouched.

// find_in_captures { "filter": "call_id == \"[email protected]\"" }
{
  "schema_version": 1,
  "sweep": {
    "matches": [
      { "filename": "rotated-03.pcap", "dialogs_matched": 1,
        "first_call_id": "[email protected]" }
    ],
    "files_examined": 12,
    "files_total": 12,
    "unreadable": [],
    "complete": true
  }
}

A sweep runs under bounds, and one that reports no matches has not shown the call is absent — only that it did not find it in what it managed to read. complete is true in exactly one case: every candidate examined, and every one of them readable.

It is false when the sweep stopped early — stopped_because says max-files or deadline — and false when the sweep could not open some file. unreadable names each of those, with its reason, and never skips one silently: the file nobody could look in is exactly the one that might hold the call. A reason comes from the OS and from libpcap, so sipnab strips control characters and keeps the first MAX_REASON_CHARS (200).

A match does not excuse an incomplete sweep either. On a rotated spool a call that spans a rotation is in two files, so finding it in one says nothing about the other.

max_files makes the cost predictable. deadline_ms is the one that matters: a file's cost is its size, which the caller cannot see, so twenty small files and twenty 2 GB files are the same max_files and a very different wait. The sweep tests the deadline before each file rather than after: a deadline tested only afterwards is one the last file can overrun by its whole read.

There is no cancel. A tool call has no channel to interrupt it, so the sweep bounds itself and always returns with an account of what it covered.

Returns one page of dialog summaries from the live capture store.

Returns — a page object, not a bare array:

Each DialogSummary row carries call_id, state, method, from_user, to_user, msg_count, duration_sec, created_at, updated_at, a timing object (pdd_ms, setup_ms, retransmits, duration_ms, each null when the capture never showed it) and a frame pointer for show_evidence. from_user and to_user arrive fenced, because an endpoint chose them.

Two more keys appear when sipnab knows them, and are left out rather than sent as null when it does not, so an absent key means "not known here":

• final_status_code — the final response the call reached. state collapses every release cause into one word, so 403, 404, 408, 486, 503 and 603 all read as Failed, and this is the field that tells them apart. Absent while a call is still in progress, never 0.
• input_origin — which capture source delivered the message that OPENED the dialog: wire, hep or uprobe. It is what keeps frame honest, because a uprobe pointer (uprobe:opensips/954#3) has the same shape as a capture offset and only one of the two leads to bytes on disk.

The example below runs against tests/pcap-samples/sipp-branch-scenario.pcapng, which holds 1334 dialogs. limit: 2 therefore reports 2 of 1334 — and says so:

// list_dialogs { "limit": 2 }
{
  "schema_version": 1,
  "dialogs": [
    {
      "call_id": "[email protected]",
      "state": "Registered",
      "method": "REGISTER",
      "from_user": "⟦untrusted-capture-data⟧ua-a⟦/untrusted-capture-data⟧",
      "to_user": "⟦untrusted-capture-data⟧ua-a⟦/untrusted-capture-data⟧",
      "msg_count": 7,
      "final_status_code": 403,
      "duration_sec": 0.036,
      "created_at": "2016-11-17T21:52:35.303349+00:00",
      "updated_at": "2016-11-17T21:52:35.339349+00:00",
      "timing": {
        "pdd_ms": null,
        "setup_ms": null,
        "retransmits": 0,
        "duration_ms": null
      },
      "frame": "tests/pcap-samples/sipp-branch-scenario.pcapng#0@0f039ad14545671e",
      "input_origin": "wire"
    },
    {
      "call_id": "[email protected]",
      "state": "Registered",
      "method": "REGISTER",
      "from_user": "⟦untrusted-capture-data⟧ua-a⟦/untrusted-capture-data⟧",
      "to_user": "⟦untrusted-capture-data⟧ua-a⟦/untrusted-capture-data⟧",
      "msg_count": 7,
      "final_status_code": 403,
      "duration_sec": 0.036,
      "created_at": "2016-11-17T21:52:35.403349+00:00",
      "updated_at": "2016-11-17T21:52:35.439349+00:00",
      "timing": {
        "pdd_ms": null,
        "setup_ms": null,
        "retransmits": 0,
        "duration_ms": null
      },
      "frame": "tests/pcap-samples/sipp-branch-scenario.pcapng#7@f7951dd197e419b9",
      "input_origin": "wire"
    }
  ],
  "returned": 2,
  "total_matched": 1334,
  "by_method": [
    { "method": "REGISTER", "count": 1334 }
  ],
  "truncated": true,
  "next_cursor": "2016-11-17T21:52:35.403349+00:00|[email protected]",
  "capture_identity": {
    "node": "capture-01",
    "instance": "1ae7318cb5c11b1a306dd-1",
    "dialog_generation": 9015,
    "stream_generation": 0
  }
}

by_method is why this fixture is a fair example rather than a flattering one: the page shows two dialogs and the breakdown shows that all 1334 are REGISTER. Nothing in the rows could have told a caller that, and a client that reasoned about "the calls in this capture" from the page would have been reasoning about a registration flood.

Two fields in there catch people writing a client from this page. from_user reads ⟦untrusted-capture-data⟧ua-a⟦/untrusted-capture-data⟧, not ua-a, so a comparison against the bare name never matches — strip the markers, or match inside them. And capture_identity.node names the box that answered, which decides whose capture a fact came from once an agent holds several servers.

A bare array hides its own size. This tool returned 50 of 2311 dialogs on a production capture with nothing in the reply to mark the cut, and limit alone could not close the gap: requests above 1000 clamp to the hard cap, leaving 1311 dialogs no call could reach. An agent asked "how many calls failed?" counts the rows it holds and answers with that number, so a short list does not read as an incomplete answer — it reads as a confident wrong one. total_matched and truncated name the shortfall. cursor closes it.

next_cursor pairs a timestamp with a Call-ID for the same reason tail_dialogs does. Dialogs share a created_at routinely — a burst of registrations lands on one millisecond — and a bare timestamp forces a choice between dropping the rest of that group and serving it twice. Resuming after the (created_at, Call-ID) pair splits the group exactly where the page ended. Pass the value back unmodified. A bare RFC 3339 timestamp still parses, so rebuilding one by hand fails silently rather than erroring.

The two tools page on different clocks, deliberately. tail_dialogs follows updated_at, because reporting change is its job. list_dialogs pages on created_at, which never moves: a dialog that gains one more message mid-sweep would jump forward in an updated_at ordering, past a cursor that had already gone by, and vanish from the listing.

list_dialogs, find_problems, tail_dialogs and search_by_time take an optional fields array. This surface already bounds rows three ways -- limit, --mcp-max-rows, and cursors -- and it bounded columns not at all, so asking for a page to read two values off it still paid for every other value on every row.

// list_dialogs { "limit": 200, "fields": ["state", "final_status_code"] }
{ "call_id": "[email protected]", "state": "Completed", "final_status_code": 200 }

Three rules, each there for a reason:

• call_id always survives, listed or not. Every follow-up tool here takes a Call-ID, so a row an agent cannot address is a row it can do nothing with.
• An unknown name fails, naming both the typo and the fields the row actually carries. Silently returning rows without the field asked for reads as "no such data", which is a wrong answer rather than an error.
• The envelope is never projected. total_matched, truncated, next_cursor and capture_identity are how a caller knows what it did NOT get, and dropping them to save bytes would trade away the very thing the bounds exist to report.

A field already absent from a row stays absent rather than reappearing as null: the projection runs on the serialized page, so skip_serializing_if still decides what exists.

Call volume over time, in fixed-width buckets.

aggregate_dialogs answers "how many, grouped by what" and is blind to WHEN. A trunk that failed for ninety seconds and a trunk that fails one call in forty produce the same bucket counts, and only the shape over time separates them. This returns one row per interval so the shape is readable without fetching every dialog and bucketing them in the model's head -- the counting task language models get wrong most reliably.

Returns — an object wrapping the series, not a bare array:

There is no truncated and no cursor: this tool takes no limit and returns every bucket in the capture.

// timeline { "bucket_seconds": 60 }
{
  "schema_version": 1,
  "buckets": [
    { "start": "2026-08-28T04:00:00Z", "bucket_seconds": 60, "dialogs": 412 },
    { "start": "2026-08-28T04:01:00Z", "bucket_seconds": 60, "dialogs": 0 },
    { "start": "2026-08-28T04:02:00Z", "bucket_seconds": 60, "dialogs": 377 }
  ],
  "returned": 3,
  "bucket_seconds": 60
}

The object is the reason to read this tool's answer rather than count it. A bare array has no key to carry source_exhausted, so a series drawn while the capture was still loading looked exactly like one drawn over the whole file. Wrapping the rows gives that fact somewhere to land.

Two properties are deliberate. Buckets align to the epoch, not to the first dialog, so two captures of the same window produce identical boundaries and line up against each other. Aligning to the earliest call would instead shift every boundary whenever that call changed. The series also keeps empty buckets, as the middle row above shows -- a gap is a finding, and a series that silently drops it renders as continuous traffic on a shorter axis.

Ranks the busiest participants: IPs, user agents, or dialled prefixes.

aggregate_dialogs and group_dialogs group DIALOGS, and a dialog has two ends. Asking "who is busiest" of a dialog-shaped answer forces the caller to pick one end and ignore the other, which reports a trunk's traffic as belonging to whichever side the schema happened to name first. This counts PARTICIPANTS instead.

Returns:

Each talkers row carries key (the address, banner or prefix), dialogs, messages, invites, answered, failed, and share_pct. messages counts what sipnab credits to the row: messages SENT for an ip, messages carrying the banner for a ua, every message of the dialog for a prefix. answered and failed are subsets of invites, so a dimension carrying no INVITE dialogs reports zero for all three. share_pct is null — never 0 — when nothing matched, because a zero there would read as a talker measured to be idle.

The example runs against tests/pcap-samples/sipp-branch-scenario.pcapng, whose 1334 REGISTER dialogs run between two addresses:

// top_talkers { "by": "ip", "limit": 3 }
{
  "schema_version": 1,
  "by": "ip",
  "talkers": [
    { "key": "192.0.2.20", "dialogs": 1334, "messages": 5082,
      "invites": 0, "answered": 0, "failed": 0, "share_pct": 100.0 },
    { "key": "192.0.2.10", "dialogs": 1334, "messages": 3907,
      "invites": 0, "answered": 0, "failed": 0, "share_pct": 100.0 }
  ],
  "distinct_talkers": 2,
  "total_matched": 1334,
  "truncated": false,
  "capture_identity": {
    "node": "capture-01",
    "instance": "eb70c18d2bf4734944323-2",
    "dialog_generation": 9015,
    "stream_generation": 0
  }
}

The shares deliberately sum above 100%. One dialog counts for every talker in it, so a two-ended call adds to two rows — here both ends took part in all 1334 dialogs and both read 100%. total_matched is the number that partitions: compare a row's dialogs against it rather than against the other rows. by: "prefix" is the exception and does partition, because sipnab credits one bucket per dialog and a call has one dialled number.

sipnab orders rows by dialogs, then by messages, then by key, so two runs over one capture cannot disagree. key arrives fenced for by: "ua" alone, because a banner is a string a stranger typed. An address and a prefix bucket are values sipnab derived, and come back verbatim.

ip reads senders off the MESSAGES, not off the dialog's opening addresses: a proxy that re-originates mid-dialog is invisible in the dialog record and would otherwise never appear. ua reads User-Agent from requests and Server from responses, both sender-written and therefore fenced. prefix strips a leading + before taking digits, so +15551234 and 15551234 are one destination rather than two.

Counts dialogs grouped by one field, inside the store.

Counting is the operation a language model gets wrong most reliably, and this page documents that failure elsewhere: an agent asked "how many calls failed?" counts the rows it is holding and answers with that number. The page object fixed exactly one count — total_matched, for one filter. Every other count still meant fetching pages and tallying them in the model's head, or issuing N filtered queries with the buckets guessed in advance.

Returns group_by (echoed), buckets (each { value, count }, largest first), other_count, distinct_values, total_matched, capture_identity and schema_version.

The example runs against tests/pcap-samples/sipp-branch-scenario.pcapng, whose 1334 dialogs land in two states, with top_n: 1 asking for only the larger one:

// aggregate_dialogs { "group_by": "state", "top_n": 1 }
{
  "schema_version": 1,
  "group_by": "state",
  "buckets": [ { "value": "Registered", "count": 1207 } ],
  "other_count": 127,
  "distinct_values": 2,
  "total_matched": 1334,
  "capture_identity": {
    "node": "capture-01",
    "instance": "f078218d2bfca5995cf37-2",
    "dialog_generation": 9015,
    "stream_generation": 0
  }
}

The buckets plus other_count always equal total_matched. A truncated aggregate that does not say what it left out is a wrong total rather than a partial one, so nothing is silently dropped — including nulls, which become the literal (none): "how many dialogs carry no User-Agent" is a real question.

One dimension, and no time bucketing. That is a deliberate cap, not an unfinished feature. Two dimensions is a pivot table, a pivot table wants a UI, and positioning puts that outside what sipnab is. Narrow the window with filter instead.

Grouping by from.user, to.user or ua returns fenced values. Those are text the packet's sender wrote, and they reach a model here exactly as they would in a row. A state name, a status code, an IP or a codec is sipnab's own derivation and comes back verbatim — fencing those would tell the agent to distrust the analysis.

Carrier metrics per group, computed inside the store.

aggregate_dialogs answers "how many" and stops. Every question beginning with WHICH — which trunk is failing, which User-Agent has the worst audio, which hour it started — wants a rate, and a rate is the one thing a language model cannot recover from a page of rows: it would have to hold every dialog, classify each outcome and divide. Agents stop early and answer from the rows they happen to hold, which is how a truncated page becomes a confident verdict about a carrier. So this tool computes the rate where the dialogs live and reports the population underneath it.

// group_dialogs { "by": "next_hop", "metrics": ["count", "asr", "ner"], "top_n": 2 }
{
  "schema_version": 1,
  "group_by": "next_hop",
  "metrics": ["asr", "count", "ner"],
  "units": { "asr": "percent", "count": "dialogs", "ner": "percent" },
  "groups": [
    {
      "value": "203.0.113.9:5060",
      "count": 412,
      "metrics": { "asr": 71.6, "count": 412.0, "ner": 98.27 },
      "not_grounded": {},
      "population": {
        "dialogs": 412, "seizures": 405, "answered": 290, "delivered": 398,
        "completed_calls": 288, "pdd_measured": 401,
        "mos_grounded_dialogs": 260, "retransmits": 14
      }
    },
    {
      "value": "203.0.113.10:5060",
      "count": 77,
      "metrics": { "asr": null, "count": 77.0, "ner": null },
      "not_grounded": {
        "asr": "no INVITE in this group reached a final response, so nothing in it was a decided call attempt",
        "ner": "no INVITE in this group reached a final response, so nothing in it was a decided call attempt"
      },
      "population": {
        "dialogs": 77, "seizures": 0, "answered": 0, "delivered": 0,
        "completed_calls": 0, "pdd_measured": 0,
        "mos_grounded_dialogs": 0, "retransmits": 0
      }
    }
  ],
  "other_count": 11,
  "distinct_values": 6,
  "total_matched": 500,
  "capture_identity": { "node": "capture-01", "instance": "1d1a718cb5c33b7c52754-1",
                        "dialog_generation": 4113, "stream_generation": 902 }
}

A null metric is an answer, and not_grounded says which population went missing. The second group above holds 77 REGISTER dialogs. An ASR of 0 there would name a working registrar a dead trunk, which is a wrong answer rather than a missing one. That is the discipline mos_grounded already applies to a MOS on an unpublished codec, extended to the other seven metrics.

Every figure names its unit in the answer. An ASR of 0.65 and an ASR of 65 describe the same trunk and differ by a factor of a hundred, so units travels with the numbers rather than living on this page. asr and ner are PERCENTS here and in evaluate_expectations, which takes its thresholds in the same unit: a rule reads "value": 99, matching the number you read in a report. The two tools disagreed on this before 0.5.130 -- one percent, one a ratio -- and a threshold copied between them was wrong by a hundredfold in the direction that always passes.

The eight metrics, and what each one measures:

A seizure is an INVITE dialog that reached a final response. Both halves carry weight. A REGISTER is not a call attempt, and an INVITE still ringing when the capture ended has not failed — counting it as a failed seizure reports a live capture as an outage that looks worse the earlier you look.

NER credits the far end where ASR does not. A trunk full of 486s has an ASR of zero and works perfectly: the network delivered every call and the callee was busy, so reading the ASR alone escalates a healthy carrier. The five codes that count as delivered are 480, 486, 487, 600 and 603 — the callee unavailable, busy, busy everywhere, declining, or the CALLER hanging up on a call that had already reached the far end. 408 Request Timeout is deliberately absent. A proxy emits it both for a silent phone and for an unreachable next hop, so crediting it would credit the network for calls that may never have arrived, which is the exact misattribution NER exists to prevent.

ACD times the conversation, not the dialog. A call that rang for five seconds, talked for sixty and took one more on the BYE handshake spans 66 seconds and contributes 60. Averaging the span bills the caller for the ring-back, which is not what any carrier means by average call duration.

Percentiles use nearest rank, with no interpolation. An interpolated p95 returns a number no call experienced, and these figures get quoted back to a carrier as evidence about real calls. Every metric rounds to two decimal places, because a ratio over three dialogs is not accurate to fourteen — and the population sits beside it, so anyone wanting the exact ratio divides the two integers.

Groups rank by dialog count, largest first, ties broken by value. Ranking by the metric would answer a different question per call and could not page against other_count. That remainder carries a count and nothing else, deliberately: an ASR averaged over the groups that fell off the end is an average of averages across the smallest groups, which is the arithmetic that turns one busy trunk into a capture-wide verdict. The groups plus other_count always equal total_matched.

Three dimensions live here and not in aggregate_dialogs, and the set is a strict SUPERSET rather than an overlapping one, so an agent never has to discover per tool which vocabulary it is talking to:

Fencing follows the same rule as everywhere else. to_domain, to.user, from.user and ua arrive wrapped in ⟦untrusted-capture-data⟧ because a sender chose them. A state name, a status code, an address, a codec and next_hop come back verbatim, because they are sipnab's own derivation and telling an agent to distrust them would tell it to distrust the analysis.

Note next_hop names the peer only from the vantage point of a capture taken beside the sender, which is where a proxy's own trunk traffic gets captured.

One dimension, for the reason aggregate_dialogs gives: two is a pivot table, and a pivot table wants a UI. Narrow with filter instead. Reach for aggregate_dialogs when a bare count answers the question — it does the same walk without computing seven metrics.

What this binary can do and what this server permits. Ask before requesting decryption, HEP, a file export or a capture swap: a build without the feature, or a server without the flag, fails confusingly otherwise.

No parameters. Returns:

{
  "schema_version": 1,
  "version": "0.5.182",
  "features": ["api", "hep", "mcp", "native", "tls", "tui"],
  "can_decrypt": true,           // tls
  "can_hep": true,               // hep
  "can_plugins": false,          // plugins
  "runtime": {
    "mcp_file_root": "/var/spool/sipnab-captures",  // null when unset
    "mcp_allow_shutdown": false,
    "mcp_allow_open_capture": true,
    "mcp_allow_save_findings": false
  }
}

features comes from cfg! at compile time, so it cannot claim a feature the binary does not have. runtime is a different question — what the operator turned on — and no compile-time check can answer it. Without it an agent discovers the setup by calling a tool and collecting a refusal, and a refusal mid-investigation reads as a dead end rather than as a server it was never allowed to use that way.

An orphaned stream is media with no dialog. rtp_stats names which streams have none. This tool says why each one has none, which is the part an incident needs.

Parameters: limit (u32?) — maximum rows to return, bounded by --mcp-max-rows and defaulting to 50. There is no cursor: read total_orphans against the rows you received, and raise limit to reach the rest.

Returns orphans, total_orphans (the count before limit bit), truncated, relay_was_consulted, capture_identity and schema_version. Each orphans row carries ssrc, src, dst, named_endpoint, asserted_by, reason and note.

Three verdicts, and the difference between them is the point:

relay_was_consulted rides alongside the verdict and matters more than it looks. A never-named verdict with relay_was_consulted: false means nobody asked — an absence of evidence, not evidence of absence. It is deliberately not reported using the Unattributed vocabulary, which answers "sipnab asked the relay and it said X": this server holds no live reconciler, and claiming an answer nobody received is the failure that vocabulary exists to prevent.

The example runs against tests/pcap-samples/codec-negotiation.pcap, which carries four streams and no dialogs at all:

// reconcile_orphans { "limit": 2 }
{
  "schema_version": 1,
  "orphans": [
    {
      "ssrc": 238226163,
      "src": "127.0.0.1:5094",
      "dst": "127.0.0.1:5084",
      "named_endpoint": null,
      "asserted_by": null,
      "reason": "never-named",
      "note": "nothing in this capture named this endpoint. A relay could answer it and none was asked: that is an absence of evidence, not evidence of absence"
    },
    {
      "ssrc": 238226163,
      "src": "127.0.0.1:5084",
      "dst": "127.0.0.1:5094",
      "named_endpoint": null,
      "asserted_by": null,
      "reason": "never-named",
      "note": "nothing in this capture named this endpoint. A relay could answer it and none was asked: that is an absence of evidence, not evidence of absence"
    }
  ],
  "total_orphans": 4,
  "truncated": true,
  "relay_was_consulted": false,
  "capture_identity": {
    "node": "capture-01",
    "instance": "ece9518d2bf67680750b4-2",
    "dialog_generation": 1,
    "stream_generation": 4
  }
}

You know something is wrong but not which call. These cut a capture down to the dialogs worth reading: by symptom, by text, by time, or by relationship to a call you already have.

Convenience wrapper over list_dialogs that ORs each named alias, then ANDs the optional filter.

Returns the same page object as list_dialogs — dialogs, returned, total_matched, by_method, truncated, next_cursor, schema_version and capture_identity — with the same meanings and the same fenced from_user and to_user.

Read by_method first on this tool especially. Whatever the deployment does most dominates a problems page, and that is rarely the calls: on one real capture 98 of 110 rows carried OPTIONS, and 89 of those tripped an alias solely on retransmits > 3 — dead qualify peers, not call faults. Without the breakdown an agent had to already suspect the keepalive plane to exclude it.

filter is what makes this the triage entry point rather than a firehose. The aliases answer "is this call interesting". The filter answers "is it one of mine", so {"kinds": ["problems"], "filter": "dst.ip == '203.0.113.9'"} asks a question that previously needed a client-side join. The two AND together — ORing them would widen the sweep instead of narrowing it.

An unknown alias, or a filter that neither names an alias nor parses, returns invalid_params (-32602) naming the offending value.

// find_problems { "limit": 1, "filter": "msg_count > 5" }
{
  "schema_version": 1,
  "dialogs": [
    {
      "call_id": "[email protected]",
      "state": "Failed",
      "method": "REGISTER",
      "from_user": "⟦untrusted-capture-data⟧ua-a⟦/untrusted-capture-data⟧",
      "to_user": "⟦untrusted-capture-data⟧ua-a⟦/untrusted-capture-data⟧",
      "msg_count": 6,
      "final_status_code": 403,
      "duration_sec": 0.03,
      "created_at": "2016-11-17T21:54:34.903349+00:00",
      "updated_at": "2016-11-17T21:54:34.933349+00:00",
      "timing": {
        "pdd_ms": null,
        "setup_ms": null,
        "retransmits": 0,
        "duration_ms": null
      },
      "frame": "tests/pcap-samples/sipp-branch-scenario.pcapng#8028@42ba0f02341ca2f7",
      "input_origin": "wire"
    }
  ],
  "returned": 1,
  "total_matched": 6,
  "by_method": [
    { "method": "REGISTER", "count": 6 }
  ],
  "truncated": true,
  "next_cursor": "2016-11-17T21:54:34.903349+00:00|[email protected]",
  "capture_identity": {
    "node": "capture-01",
    "instance": "1ae7318cb5c11b1a306dd-1",
    "dialog_generation": 9015,
    "stream_generation": 0
  }
}

The same capture answers find_problems {} with total_matched: 127. Six of those 127 carry more than five messages, which is what the filter selects.

Case-insensitive substring search over method, status, From, To, User-Agent, and body across all dialogs.

Returns — the same page shape list_dialogs returns, not a bare array, plus the provenance note as a second content block:

snippet holds the whole raw message, fenced, and stops at 4 KB. Pass call_id and message_index straight to get_message for the parsed form.

Count from the fields, never from the rows. A capped result and a complete one hold the same shape, so the row count cannot tell them apart: on the sample capture below, { "query": "REGISTER" } returns 50 rows and limit: 1000 returns 1000, while 1334 messages match. total_matched is the number that answers "how many are there", truncated says whether you are seeing all of them, and next_cursor reaches the rest.

The example runs against tests/pcap-samples/sipp-branch-scenario.pcapng:

// search_messages { "query": "REGISTER", "limit": 1 }
{
  "schema_version": 1,
  "hits": [
    {
      "call_id": "[email protected]",
      "message_index": 0,
      "snippet": "⟦untrusted-capture-data⟧REGISTER sip:example.net SIP/2.0\r\n…⟦/untrusted-capture-data⟧"
    }
  ],
  "returned": 1,
  "total_matched": 1334,
  "truncated": true,
  "next_cursor": "2016-11-17T21:52:35.303349+00:00|[email protected]#0000000000",
  "capture_identity": {
    "node": "capture-01",
    "instance": "12100b18cb6971cf461cff-1",
    "dialog_generation": 9015,
    "stream_generation": 0
  }
}

Passing that next_cursor back returns [email protected] and reports the same total_matched: 1334: the total describes the store, not the page. The index half of the cursor carries leading zeros because the server compares the cursor as text — rebuild one by hand and #10 sorts before #2, which silently skips eight messages of a dialog. Pass it back exactly as it arrived.

Returns dialogs whose first message falls in the window, oldest first.

Returns { dialogs, returned, total_matched, truncated, next_cursor, capture_identity, schema_version }. Each row carries call_id, created_at, state and final_status_code — a narrower row than list_dialogs returns, with no msg_count, no from_user, no timing and no frame. No markers appear here either, because none of those four fields is free text. Feed a call_id to another tool when you need the rest.

total_matched counts every dialog in the window before limit applies, so a small answer from a quiet window reads differently from a truncated one.

filter turns "failed calls between 14:00 and 14:05" into a single call. The window narrows first and the filter runs over what survives.

The example runs against tests/pcap-samples/sipp-branch-scenario.pcapng. The same window without a filter answers total_matched: 247:

// search_by_time { "start": "2016-11-17T21:52:35Z", "end": "2016-11-17T21:53:00Z",
//                  "filter": "problems", "limit": 2 }
{
  "schema_version": 1,
  "dialogs": [
    {
      "call_id": "[email protected]",
      "created_at": "2016-11-17T21:52:36.203349+00:00",
      "final_status_code": 403,
      "state": "Failed"
    },
    {
      "call_id": "[email protected]",
      "created_at": "2016-11-17T21:52:37.703349+00:00",
      "final_status_code": 403,
      "state": "Failed"
    }
  ],
  "returned": 2,
  "total_matched": 16,
  "truncated": true,
  "next_cursor": "2016-11-17T21:52:37.703349+00:00|[email protected]",
  "capture_identity": {
    "node": "capture-01",
    "instance": "12100b18cb6971cf461cff-1",
    "dialog_generation": 9015,
    "stream_generation": 0
  }
}

truncated: true is not a dead end. Pass next_cursor back to continue through the window. total_matched keeps counting the whole window rather than the remainder, so it does not shrink as you page — without a cursor the only way past a truncated window would be to narrow it, putting every row past the 1000-row ceiling out of reach. The cursor is the same compound form list_dialogs issues, and it is opaque: pass it back exactly as it arrived.

Compiles a Filter DSL expression, counts what it selects, and returns no rows.

The DSL narrows list_dialogs, find_problems, search_by_time, aggregate_dialogs and group_dialogs, and before this tool every way of trying an expression cost a page. An agent converging on a working filter — widen it, narrow it, try the other field name — paid for a page of fenced summaries per attempt and discarded every row. The two failure modes also look alike from outside: a malformed expression comes back as invalid_params, which lands in the error channel where a model acts on it least, and an expression that parses but selects nothing returns the same empty page as an empty capture.

A parse failure is a successful call. Every other tool rejects a bad filter with invalid_params, which is right there and wrong here: learning what is wrong with an expression is the entire point of this tool, and an error object carries that message where a model is least likely to act on it. So a bad expression answers valid: false with the parser's own text — position, caret and hint included — and the only error this tool raises is one it did not expect.

// validate_filter { "expr": "state = Failed" }
{
  "schema_version": 1,
  "expr": "state = Failed",
  "valid": false,
  "error": "invalid filter 'state = Failed': unexpected input at position 6: '='\n  state = Failed\n        ^\nvalid operators: ==, !=, <, <=, >, >=, =~ (regex)\nsee docs/filter-dsl.md for fields, values, and diagnostic aliases",
  "total_matched": null,
  "total_dialogs": 2
}

total_matched stays null on a parse failure rather than dropping to 0, because a zero there reads as "parsed, matched nothing" — the opposite of what happened. Fix the expression and the count arrives, measured against the whole store with no cursor and no truncation. The example runs against tests/pcap-samples/sip-rtp-g711.pcap:

// validate_filter { "expr": "state == 'Completed' and rtp.mos < 4.5" }
{
  "schema_version": 1,
  "expr": "state == 'Completed' and rtp.mos < 4.5",
  "valid": true,
  "error": null,
  "total_matched": 1,
  "total_dialogs": 2
}

Read total_dialogs beside total_matched. It is the denominator, and it comes back even on a parse failure: 0 matches out of 0 dialogs is an empty capture, 0 out of 4000 is an expression that selects nothing, and no single number separates them.

Aliases expand here exactly as they do everywhere else, because this tool calls the same compiler the other tools call. A second parser would eventually accept an expression list_dialogs then rejects, which is worse than no tool at all. This response carries your own expression and two integers and nothing read off the wire, so it appends no provenance note.

Everything the capture holds about one participant.

The rest of this surface keys on Call-ID, which is the right shape for "why did this call fail" and the wrong shape for the question that comes first. An operator handed a complaint holds a phone, a trunk or a subscriber — an address or a name — and wants to know what that thing has been doing. Agents reason in entities too. Answering from a dialog-centric surface meant listing every dialog, filtering client-side, and re-deriving per-entity facts the stores already hold.

Exactly one selector, and the tool refuses both. A caller passing an address and a name means either their intersection or their union, the two give different answers, and picking one silently would answer a question nobody asked:

{ "code": -32602,
  "message": "give exactly one of ip or user, not both: the two select different sets, and whether you meant their intersection or their union changes the answer" }

The example runs against tests/pcap-samples/sip-rtp-g711.pcap:

// describe_endpoint { "ip": "10.0.2.20", "limit": 1 }
{
  "schema_version": 1,
  "endpoint_kind": "ip",
  "endpoint": "10.0.2.20",
  "dialogs": 2,
  "by_method": { "INVITE": 2 },
  "by_state": { "Completed": 1, "InCall": 1 },
  "messages_sent": 5,
  "messages_received": 5,
  "calls": {
    "invites": 2, "with_final_status": 2, "failed": 0,
    "failure_rate_pct": 0.0, "by_final_status": { "200": 2 }
  },
  "registration": {
    "applicable": false, "dialogs": 0, "succeeded": 0, "failed": 0,
    "auth_loops": 0, "problem_call_ids": []
  },
  "user_agents": [],
  "stack": {
    "branch_cookie": "z9hG4bK", "branch_shape": "hex",
    "tag_shape": "other", "callid_has_host": true,
    "confidence": 0, "requests_read": 5, "mixed": false
  },
  "streams": {
    "count": 2, "orphaned": 0, "packets": 839, "lost_packets": 0,
    "max_jitter_ms": 0.0061987502747274615,
    "codecs": ["⟦untrusted-capture-data⟧PCMA⟦/untrusted-capture-data⟧",
               "⟦untrusted-capture-data⟧PCMU⟦/untrusted-capture-data⟧"]
  },
  "findings": {
    "selectable": true, "findings": [], "total_matched": 0, "armed_kinds": [],
    "note": "No detection rule is armed on this server, so no finding could have been recorded. ..."
  },
  "recent_dialogs": [ /* one fenced dialog summary */ ],
  "truncated": true
}

A phone behind NAT puts its own private address in the Contact of a REGISTER. The registrar must notice that the packet arrived from a public address the header does not name, and route later requests to where it came from. When it does, everything works. When it does not, every inbound call goes to an unroutable host and the phone never rings.

The observation is not the finding. Measured against the private corpus on 2026-09-08, 1,660 of 2,226 REGISTER contacts carry a private host — 74.6% — and that estate works. A rule firing on the observation alone would report three quarters of a healthy fleet.

Any request to the private host is a finding, not a majority of them. A proxy that sends some requests to the source and some to the header still sends some nobody receives, and 99 deliverable requests do not make the hundredth deliverable.

Silence is not success. A capture that ended before the first inbound call reports no-later-requests, which is distinct from rewritten on purpose: reading it as success is how a capture that stopped too early becomes a clean bill of health.

Corroborated against the registered AoR, not the address. A request the registrar sent to the private Contact carries no address belonging to the endpoint — that is exactly what going to the wrong host means — so nothing address-based can find it. The tie is the user part in the request URI and To, matched case-sensitively per RFC 3261 section 19.1.4.

diagnose_registration reports the observation for a single call. The corroborated finding lives here, because settling it needs what happened across the endpoint's other dialogs.

A banner names a PRODUCT and one product ships more than one stack. top_talkers by=ua reports Asterisk PBX 20.15.2 as a single row at share_pct: 100.0 across 507 dialogs, and tshark finds 18 distinct source addresses behind that one label — running two different stacks, which need different configuration, different NAT handling and different re-INVITE handling. The banner cannot tell them apart. The syntax can.

It names a library, never a product. z9hG4bKPj is pjproject's, and pjproject ships inside Asterisk's res_pjsip, Grandstream UCM and FreePBX alike — so naming a vendor from the shape would be a guess wearing the shape of a measurement. The same discipline find_correlated applies with identifier_match.

Two observations are the floor for an inference. The magic cookie alone is mandatory for every compliant sender, so it distinguishes nothing, and callid_has_host alone splits the world roughly in half. One agreeing observation infers nothing, and an unrecognized stack reports its shapes with no inference at all. sipnab does not force it into the nearest label.

Read from requests only. A response echoes the request's branch, From tag and Call-ID verbatim, so reading one would fingerprint the party that SENT the request as though it were the party that answered — and on any dialog those are two different stacks. An endpoint that only answers reports requests_read: 0 and infers nothing.

limit bounds the page and never the counts. dialogs, by_method, by_state, calls and streams describe every match, and only recent_dialogs shortens — with truncated saying so. recent_dialogs runs newest first, because an operator chasing a complaint wants what just happened, and list_dialogs already pages the whole history oldest-first for anyone sweeping it.

An ip matches on MESSAGES, not on the dialog's opening addresses. A dialog records the socket pair its first message arrived on, so a proxy re-originating mid-dialog, a re-INVITE from a second interface, and a BYE from the far side all belong to the call while carrying different addresses. Matching the dialog record alone would silently drop them, and the dropped ones are exactly the transfers and hand-offs an operator is looking for.

A user matches the From or To user part EXACTLY. RFC 3261 section 19.1.4 makes the user part case-sensitive, so Alice and alice name two URIs, and folding the case here would file one endpoint's traffic under the name of a second.

Three fields answer differently for a user, and each says so rather than inventing a number:

That selectable flag matters because an empty list has three readings, not one. selectable: false means nobody could ask. An empty armed_kinds means nothing was watching, and the note says so in the same words security_findings uses. Only on a server with a detector armed does an empty list mean the endpoint stayed clean.

failure_rate_pct guards its denominator: it comes back null, not 0.0, when nothing reached a final status. A zero there hands a clean bill of health to an endpoint nobody has measured. registration.applicable does the same job for REGISTER — false means the endpoint sent none, so the four counts under it read as "no input" rather than "no failures". A registration counts by the REQUEST rather than by the dialog's method, because a REGISTER can arrive inside a dialog something else opened once Call-ID reuse is in play, and a registration nobody examined reports as a healthy one. The Call-IDs in problem_call_ids go straight into diagnose_registration.

user_agents attributes a banner to whoever wrote it: User-Agent off requests the address SENT and Server off responses it sent, per RFC 3261 section 20.41 and RFC 3261 section 20.35. Reading them off received messages would file the far end's software under this endpoint. For a user only User-Agent on requests whose From user matches counts, the one case where the URI identifies the party that wrote the header. Values arrive fenced, and so do the summaries in recent_dialogs.

Incremental fetch of the dialogs updated after a cursor position.

Returns { dialogs, next_cursor, source_exhausted, source_stopped_early, capture_identity }, where dialogs holds the same summary rows list_dialogs returns, fencing included. This page object carries no returned, total_matched or truncated — "how many are there" is not a question a tail can answer, because the store keeps changing underneath it. Poll until dialogs comes back empty and source_exhausted is true.

next_cursor is compound — <RFC 3339>|<Call-ID> — not a bare timestamp. Dialogs can share an updated_at, so resuming from the (updated_at, Call-ID) pair is what keeps a tie group split across a page boundary from vanishing or arriving twice. Pass it back unmodified. A client that rebuilds a bare timestamp from a dialog's updated_at instead falls back to the pre-compound strictly after filter and loses or repeats the tied dialogs — that bare-timestamp form is still accepted, so the mistake is silent rather than an error. | occurs in neither an RFC 3339 timestamp nor a valid Call-ID (RFC 3261 word), so the split is unambiguous.

source_exhausted is false while more dialog updates can still arrive and true once the capture source is fully drained — the end of an -I pcap replay, or a live capture that has hit its --count/--duration/--autostop stop condition. sipnab keeps serving MCP after that, so this is the flag to poll to learn a replay has finished: stop when it turns true instead of polling forever.

// tail_dialogs { "limit": 1 }
{
  "dialogs": [
    {
      "call_id": "[email protected]",
      "state": "Completed",
      "method": "INVITE",
      "from_user": "⟦untrusted-capture-data⟧sipp⟦/untrusted-capture-data⟧",
      "to_user": "⟦untrusted-capture-data⟧test⟦/untrusted-capture-data⟧",
      "msg_count": 6,
      "final_status_code": 200,
      "duration_sec": 8.504,
      "created_at": "2016-11-26T14:52:59.666393+00:00",
      "updated_at": "2016-11-26T14:53:08.170676+00:00",
      "timing": {
        "pdd_ms": null,
        "setup_ms": 4,
        "retransmits": 0,
        "duration_ms": 8499
      },
      "frame": "tests/pcap-samples/sip-rtp-g711.pcap#0@db88659b94678546",
      "input_origin": "wire"
    }
  ],
  "next_cursor": "2016-11-26T14:53:08.170676+00:00|[email protected]",
  "source_exhausted": true,
  "source_stopped_early": false,
  "capture_identity": {
    "node": "capture-01",
    "instance": "1d1a718cb5c33b7c52754-1",
    "dialog_generation": 13,
    "stream_generation": 2
  }
}

Waits until a filter selects at least one dialog, or until a deadline passes — whichever happens first. One call replaces a tail_dialogs loop in which every turn that finds nothing still costs a model call.

Returns { matched, stopped_because, dialogs, returned, total_matched, truncated, elapsed_ms, timeout_seconds, timeout_clamped, poll_interval_ms, polls, scans, source_exhausted, capture_identity }, where dialogs holds the same summary rows list_dialogs returns, fencing included, and is empty unless matched is true.

There is no page-size argument. This tool answers did it happen, and the rows are evidence that it did rather than a page to work through — so it returns what any list tool returns to a caller that named no limit: the default fifty rows, cut to --mcp-max-rows when the operator set that lower. list_dialogs with the same filter is the paging surface, with the cursors and field projection that belong there. The response carries reported either way, so a bounded page never reads as a smaller event than it was.

A deadline that passes is an answer, not an error. It comes back as a successful call carrying matched: false — because "the fault has not reproduced" and "the tool broke" are different findings, and an agent has to be able to tell them apart.

stopped_because names which of three endings this was, and the two negative ones differ in whether asking again could ever help:

The numbers this tool applies, and what moves each one:

• Deadline default: 30 seconds (DEFAULT_TIMEOUT_SECONDS). Used when the call names no timeout_seconds.
• Deadline ceiling: 60 seconds (DEFAULT_MCP_MAX_WAIT_SECONDS, which await_condition reads as DEFAULT_MAX_WAIT_SECONDS). The shipped value of --mcp-max-wait-seconds; the operator moves it, and a request above it is clamped rather than refused.
• Poll default: 500 milliseconds (DEFAULT_POLL_INTERVAL_MS). Used when the call names no poll_interval_ms.
• Poll floor: 100 milliseconds (MIN_POLL_INTERVAL_MS). A smaller request meets that floor, so no caller can turn this into a spin loop, and the response carries the value actually used.

polls counts the looks and scans counts the looks that ran the filter. They differ because both stores number their revisions, so a look at a capture that has not moved resolves by comparing two integers rather than by re-running the filter — an idle capture costs almost nothing to watch.

Nothing this call allocates outlives it. There is no subscription registry, no per-client filter and no background task, which is why the deadline is not a detail: it is what ends the server's obligation. --mcp-max-wait-seconds bounds that obligation for the same reason --mcp-max-rows bounds a response, and for a reason of its own — a waiting call occupies one of --mcp-max-concurrent slots while producing nothing.

// await_condition { "filter": "state == Failed", "timeout_seconds": 20 }
{
  "schema_version": 1,
  "filter": "state == Failed",
  "matched": true,
  "stopped_because": "condition_met",
  "dialogs": [
    {
      "call_id": "[email protected]",
      "state": "Failed",
      "method": "INVITE",
      "from_user": "⟦untrusted-capture-data⟧sipp⟦/untrusted-capture-data⟧",
      "to_user": "⟦untrusted-capture-data⟧test⟦/untrusted-capture-data⟧",
      "msg_count": 4,
      "duration_sec": 1.204,
      "created_at": "2016-11-26T14:52:59.666393+00:00",
      "updated_at": "2016-11-26T14:53:00.870676+00:00",
      "frame": "tests/pcap-samples/sip-rtp-g711.pcap#0@db88659b94678546"
    }
  ],
  "returned": 1,
  "total_matched": 1,
  "truncated": false,
  "elapsed_ms": 4512,
  "timeout_seconds": 20,
  "timeout_clamped": false,
  "poll_interval_ms": 500,
  "polls": 10,
  "scans": 3,
  "source_exhausted": false,
  "capture_identity": {
    "node": "capture-01",
    "instance": "1d1a718cb5c33b7c52754-1",
    "dialog_generation": 41,
    "stream_generation": 7
  }
}

Finds the other legs of one call — the far side of a B2BUA, SBC or PBX hop.

Returns source_call_id, legs, total_matched, heuristic_only, capture_identity, timing_clock and schema_version. A leg the source has no relationship with answers with an empty legs array and total_matched: 0, never an error. There is no cursor — raise limit to reach past a truncated answer, and a call with more than 1000 correlated legs is a capture problem rather than a paging one.

The example runs against tests/pcap-samples/sip-rtp-g711.pcap, whose two calls share an SDP origin:

// find_correlated { "call_id": "[email protected]" }
{
  "schema_version": 1,
  "source_call_id": "[email protected]",
  "legs": [
    { "call_id": "[email protected]", "score": 90, "strategy": "sdp_origin",
      "identifier_match": true, "observed_gap_ms": null }
  ],
  "total_matched": 1,
  "heuristic_only": false,
  "capture_identity": {
    "node": "capture-01",
    "instance": "1d1a718cb5c33b7c52754-1",
    "dialog_generation": 13,
    "stream_generation": 2
  },
  "timing_clock": null              // non-null only when a timing_heuristic leg is returned
}

Read strategy, not just score. Two strategies score 100 and they are not the same claim:

The two P-Charging-Vector rows are one header and two different claims. RFC 7315 section 4.6 says the ICID identifies a dialog, so a conformant B2BUA emits a different icid-value on each side and charging_vector_icid is silent across it — a match there means some intermediary copied a per-dialog identifier onto a second dialog, which no RFC grants. The parameter that addresses the hop is related-icid (RFC 7315 section 4.6.4.1), and it is optional. Two limits worth knowing before you rely on either: the first proxy generates the icid (RFC 7315 section 5.6), so a leg arriving from an endpoint carries none and this is useless at the access edge. And RFC 7315 section 4.6.2.2 lets the next hop "modify the contents", which RFC 7315 section 6.6 calls normal behavior, so unlike Session-ID there is no end-to-end constancy requirement at all. Full argument: docs/design/icid-correlation.md.

Neither strategy puts the matched value in the response. RFC 7315 section 4.6's own suggested construction embeds the generating proxy's hostname or address in the icid, so it is operator-internal rather than opaque, and strategy names the strategy and nothing else.

identifier_match carries that distinction as a boolean, so a caller can filter on it without knowing which names mean what. heuristic_only says whether every returned leg came from a guess — a call tree built only from timing is a hypothesis, and an agent that cannot tell presents it as a finding.

observed_gap_ms appears only for timing_heuristic, because there it is the evidence: a 15 ms gap on a quiet box and a 1,900 ms gap on a busy SBC score identically and mean very different things. On an identifier match it is null, since the elapsed time is not why they matched.

A caveat worth stating plainly: most deployments emit no correlation header at all. Where none is present, the only strategy left is the bottom row, and on a busy SBC unrelated calls routinely share an endpoint inside its window.

Every leg of one call, as a tree.

The TUI has stitched B2BUA legs together since the x key, and nothing on the MCP surface reached it. find_correlated answers one hop from one Call-ID, so an agent facing a carrier call across an SBC and a PBX — three or four dialogs deep — had to call it on each result and assemble the graph itself. Multi-leg is the normal case in carrier work, and get_dialog hands back a quarter of the call without saying so.

The example runs against tests/pcap-samples/sip-rtp-g711.pcap, whose two calls share an SDP origin, with each leg's dialog summary trimmed to its first three keys:

// get_call_tree { "call_id": "[email protected]" }
{
  "schema_version": 1,
  "root_call_id": "[email protected]",
  "legs": [
    {
      "call_id": "[email protected]",
      "depth": 0,
      "parent_call_id": null,
      "score": null,
      "strategy": null,
      "identifier_match": null,
      "followed": true,
      "dialog": { "call_id": "[email protected]", "state": "Completed", "method": "INVITE" }
    },
    {
      "call_id": "[email protected]",
      "depth": 1,
      "parent_call_id": "[email protected]",
      "score": 90,
      "strategy": "sdp_origin",
      "identifier_match": true,
      "followed": true,
      "dialog": { "call_id": "[email protected]", "state": "InCall", "method": "INVITE" }
    }
  ],
  "total_legs": 2,
  "max_depth": 1,
  "truncated": false,
  "heuristic_edges": 0,
  "total_messages": 10,
  "first_activity": "2016-11-26T14:52:59.666393+00:00",
  "last_activity": "2016-11-26T14:53:08.290927+00:00"
}

Every leg past the root names the leg it came from (parent_call_id), how far out it sits (depth), and the strategy and score of that one edge — the same strategy vocabulary find_correlated tabulates. The root carries null for all four, because the caller named it rather than any strategy matching it.

The walk stops at a timing guess, and says so. Six of the seven correlation strategies compare a value both legs carry, and the walk expands those transitively. timing_heuristic links two INVITE dialogs that share an endpoint address and started inside the leg-correlation window, so on a proxy carrying ten calls a second every dialog sits within a guess of every other. Expanded transitively that is not a call tree, it is the capture. Such an edge still appears in legs with followed: false, so an agent that wants the next hop calls get_call_tree again rooted there and sees what it costs.

Read followed before you read the shape. A leaf appears for two opposite reasons — a timing_heuristic edge the walk declined to expand, or a leg the row cap cut the walk short of — and followed reflects what the walk actually visited rather than what it intended to visit. A leg still sitting in the queue when limit ended the walk reports followed: false, because claiming it had searched that subtree would describe work nobody did. truncated says the cap fired at all.

heuristic_edges counts the guesses in the whole tree. Zero means every link is an identifier both legs carried. total_messages is the size of the merged ladder the TUI's extended flow renders, and first_activity and last_activity bracket the call rather than the root leg.

An unknown call_id fails with invalid_params rather than answering with an empty tree. A call with no other legs and a Call-ID nobody holds are different facts, and one empty answer for both collapses them — a lone dialog comes back as a one-leg tree with total_legs: 1 and max_depth: 0.

"Why did this one work and that one not?"

Parameters: call_id_a and call_id_b (both string, both required) — two Call-IDs the store holds. Either one unknown fails with invalid_params naming it. No optional parameters, and passing the same Call-ID twice is legal and answers with an empty differences.

Each side reports call_id, state, final_status_code, msg_count, methods (sorted) and hints. differences names the fields that differ, so you are not diffing two objects by eye. The example compares the two calls in tests/pcap-samples/sip-rtp-g711.pcap:

// compare_dialogs { "call_id_a": "[email protected]", "call_id_b": "[email protected]" }
{
  "schema_version": 1,
  "a": { "call_id": "[email protected]", "state": "Completed", "final_status_code": 200,
         "msg_count": 6, "methods": ["ACK", "BYE", "INVITE"], "hints": [] },
  "b": { "call_id": "[email protected]", "state": "InCall", "final_status_code": 200,
         "msg_count": 4, "methods": ["ACK", "INVITE"], "hints": [] },
  "differences": ["state", "msg_count", "methods"]
}

final_status_code matches on both sides here and so stays out of differences — the second call simply never sent a BYE.

Is today worse than yesterday, and where.

Baseline comparison is what turns a capture tool into an operations tool, and nothing else on this surface reaches past the loaded capture. The answer has to be a diff of AGGREGATES rather than of dialog lists — two captures never share a Call-ID, so comparing rows finds every dialog different and says nothing. This tool reads both files, groups each one the way aggregate_dialogs groups, and ranks the buckets by how far they MOVED.

The example diffs two files in tests/pcap-samples:

// compare_captures { "a": "sip-rtp-g711.pcap", "b": "sip-auth-failure.pcapng",
//                    "dimensions": ["state"], "top_n": 4 }
{
  "schema_version": 1,
  "a": { "filename": "sip-rtp-g711.pcap", "packets": 852, "dialogs": 2,
         "streams": 2, "dialogs_dropped": 0, "read_error": null },
  "b": { "filename": "sip-auth-failure.pcapng", "packets": 8, "dialogs": 2,
         "streams": 0, "dialogs_dropped": 0, "read_error": null },
  "dimensions": [
    {
      "dimension": "state",
      "buckets": [
        { "value": "Completed",  "a": 1, "b": 0, "delta": -1 },
        { "value": "Failed",     "a": 0, "b": 1, "delta":  1 },
        { "value": "InCall",     "a": 1, "b": 0, "delta": -1 },
        { "value": "Terminated", "a": 0, "b": 1, "delta":  1 }
      ],
      "other": { "value": "(other)", "a": 0, "b": 0, "delta": 0 },
      "distinct_values": 4
    }
  ],
  "summary": "'sip-rtp-g711.pcap' (2 dialogs) is the baseline; 'sip-auth-failure.pcapng' (2 dialogs) is held against it, so delta is b minus a. Neither is the capture this server has loaded."
}

Buckets rank by absolute movement, not by size. The question is what changed, and the largest bucket is usually the one that changed least, so "today is worse than yesterday, and here is where" reads off the first row. delta is b - a throughout. A value absent from one side counts as zero there rather than as missing, because a response code appearing only in b IS the finding.

Neither file becomes the loaded capture. Both reads land in private stores that the call drops before it builds the answer, so what an agent asked a minute ago stays true afterwards. The read runs on a blocking thread, since two whole captures inside a tool handler would otherwise hold the single runtime thread the MCP server and the REST API share.

One thing does escape that isolation, which is why this tool carries readOnlyHint: false: reading a file through the shared pipeline bumps the PROCESS-WIDE undecodable-frame tallies and the ICMP evidence store that get_capture_report reports. It destroys nothing, and something observable moves. This reuses open_capture's existing behavior rather than inventing a new one.

Read the two CaptureSide blocks before the deltas. dialogs_dropped above zero means that side hit the dialog ceiling and every count under it is a FLOOR rather than a total, and read_error names a read that stopped early. A truncated pcap is the normal state of a rotating capture's newest member, so a partial read reports rather than fails — and summary restates both conditions in words, because a comparison against a partial population is a wrong answer wearing the shape of a right one.

Four refusals, each cheaper than the mistake it prevents:

The vocabulary check runs BEFORE either file opens, because reading two captures is the most expensive thing this surface does and a mistyped dimension must not cost it. The same-file check runs after the resolver fully resolves both names, so it catches two spellings of one file as well as the same name twice. And a capture that yielded no dialogs AND reported a read error fails with internal_error rather than diffing: every bucket would appear to collapse to zero, which is a finding that is not there.

Note the dimension list here is the plain aggregate_dialogs nine. group_dialogs's three extras — to_domain, hour, next_hop — do not apply, and hour in particular would compare two captures of different days bucket by bucket.

You have a call-id. These explain what happened to that one call -- its signaling, its media, and the specific negotiations that tend to break.

Start here. The first question in VoIP triage is which half of the stack failed. Signaling decides whether a call connects. RTP decides whether you can hear it. They have different causes and different fixes, and confusing them is the most common wrong turn — so ask this before anything else.

Parameters: call_id (string, required) — a Call-ID the store holds, as returned by list_dialogs. An unknown one fails with invalid_params (-32602) naming the value. There are no optional parameters.

// triage_call { "call_id": "[email protected]" }
{
  "schema_version": 1,
  "call_id": "[email protected]",
  "verdict": "media",              // "signaling" | "media" | "both" | "none"
  "state": "Completed",
  "final_status_code": 200,
  "signaling": { "problem": false, "hints": [] },
  "media": {
    "problem": true,
    "one_way_audio": true,
    "nat_mismatch": false,
    "no_media": false,
    "stream_count": 1,
    "hints": ["RTP flowed 10.0.2.15:27942 -> 10.0.2.20:6000 only (SSRC 0x343da99b). No reverse media flow detected."]
  },
  "termination": {                 // absent when nothing said why the call ended
    "cause_code": 38,
    "cause_text": "Network out of order",
    "protocol": "Q.850",
    "source_header": "Reason",
    "frame_ref": 7
  }
}

A clean 200 OK with one-way audio is a media problem. Nothing in the SIP exchange is wrong, and time spent reading it is time lost.

Where to go next, by verdict:

termination is a fact about the call, not a fault, so it never moves verdict. A call that cleared normally reports verdict: "none" and a Q.850 cause of 16 at the same time, and both are true.

It answers the question the verdict cannot: "the call ended" and "the call ended because the far end was out of order" are different answers, and only the second closes a ticket.

sipnab reads the last message that names a cause — a call that went through a challenge, a retry and a clear carries more than one, and the one that says why it ended is the last thing said. Reason on a BYE or a CANCEL counts, which is the case this exists for: a call that clears normally has no failure response to hang a cause on.

Where one message carries both protocols, sipnab picks the non-SIP one, because a SIP cause restates final_status_code and that is already its own field. A Q.850 cause is the gateway's, and the fact nothing else recovers.

The same block appears on get_dialog_report and on GET /v1/dialogs/{call_id}/report, from one assembler.

Paginated dialog with full SIP messages.

Returns:

Every messages row carries call_id, is_request, cseq (method and number), from, to, src, src_port, dst, dst_port, transport, timestamp, frame and schema_version. Two more appear when sipnab observed them and are left out rather than sent as null when it did not:

• dscp — the RFC 2474 marking on the frame that carried this message, 0 to 63. Absent means no IP header was read, which is what a HEP-delivered message looks like. 0 means sipnab saw the frame and the frame said best effort. Unmarked signaling is itself a common fault, so the two must not collapse into one value.
• input_origin — wire, hep or uprobe, the source that delivered this message.

The rest depends on the direction, so branch on is_request rather than expecting one shape:

• A request adds method, and contact and sdp when it carried them.
• A response adds status_code, reason, response_context and ua, and carries no method — read cseq.method for the transaction it answers.

This tool fences, and it is the one that returns the most capture text. reason, from, to, contact, ua, sdp and malformed in messages[] come back wrapped in ⟦untrusted-capture-data⟧ markers, the same treatment get_message gives them. The SDP body keeps its line structure, --mcp-max-body-bytes bounds it, and the header values arrive capped with every control character removed.

This page said the opposite until 0.5.134 — that the fields came back verbatim and that a reader should reach for get_message instead. Both tools fenced the whole time. Treat every string in messages[] as attacker-written regardless: the markers say where the text came from, they do not make it safe.

The example runs against tests/pcap-samples/sip-rtp-g711.pcap:

// get_dialog { "call_id": "[email protected]", "max_messages": 1 }
{
  "complete": false,
  "total_messages": 6,
  "next_cursor": 1,
  "dialog": {
    "call_id": "[email protected]",
    "state": "Completed",
    "method": "INVITE",
    "from_user": "⟦untrusted-capture-data⟧sipp⟦/untrusted-capture-data⟧",
    "to_user": "⟦untrusted-capture-data⟧test⟦/untrusted-capture-data⟧",
    "msg_count": 6,
    "final_status_code": 200,
    "duration_sec": 8.504,
    "created_at": "2016-11-26T14:52:59.666393+00:00",
    "updated_at": "2016-11-26T14:53:08.170676+00:00",
    "timing": { "pdd_ms": null, "setup_ms": 4, "retransmits": 0, "duration_ms": 8499 },
    "frame": "tests/pcap-samples/sip-rtp-g711.pcap#0@db88659b94678546",
    "input_origin": "wire"
  },
  "messages": [
    {
      "call_id": "[email protected]",
      "method": "INVITE",
      "is_request": true,
      "cseq": { "method": "INVITE", "number": 1 },
      "from": "⟦untrusted-capture-data⟧\"PCMU/8000\" <sip:[email protected]:5060>;tag=1⟦/untrusted-capture-data⟧",
      "to": "⟦untrusted-capture-data⟧test <sip:[email protected]:5060>⟦/untrusted-capture-data⟧",
      "contact": "⟦untrusted-capture-data⟧sip:[email protected]:5060⟦/untrusted-capture-data⟧",
      "src": "10.0.2.20",
      "src_port": 5060,
      "dst": "10.0.2.15",
      "dst_port": 5060,
      "transport": "UDP",
      "timestamp": "2016-11-26T14:52:59.666393+00:00",
      "sdp": "⟦untrusted-capture-data⟧v=0\no=- 42 42 IN IP4 10.0.2.20\ns=-\nc=IN IP4 10.0.2.20\nt=0 0\nm=audio 6000 RTP/AVP 0\na=rtpmap:0 PCMU/8000\na=recvonly\n⟦/untrusted-capture-data⟧",
      "frame": "tests/pcap-samples/sip-rtp-g711.pcap#0@db88659b94678546",
      "dscp": 0,
      "input_origin": "wire",
      "schema_version": 1
    }
  ]
}

The SDP above arrives with \n line endings, not the \r\n the wire carried. Fencing strips every control character a quoting document could act on and keeps only \n and \t, so a client that reassembles the body and compares it byte for byte against the packet finds a difference that is sipnab's, not the endpoint's. Read it as text, not as the original octets — reach for show_evidence when you need those.

total_messages is 6 and next_cursor is 1, so five messages remain. Call again with cursor: 1 to continue, and stop when complete turns true.

Per-call diagnostic report for one Call-ID. Backed by output::generate_call_report — same content as --call-report.

"json" answers with the structured object below. "markdown" and "text" answer with one text block holding the rendered report, byte-identical to what render_ladder produces for the same dialog. All three append the provenance note as a second content block. The two rendered formats also carry the INCOMPLETE RUN block described under get_capture_report when the capture was not read in full. "json" carries source_exhausted and source_stopped_early as fields instead.

The example runs against tests/pcap-samples/sip-rtp-g711.pcap:

// get_dialog_report { "call_id": "[email protected]" }
{
  "schema_version": 1,
  "call_id": "[email protected]",
  "state": "Completed",
  "method": "INVITE",
  "final_status_code": 200,
  "final_status_reason": "OK",
  "from": "sipp",
  "from_display": "PCMU/8000",
  "to": "test",
  "to_display": "test",
  "msg_count": 6,
  "duration_sec": 8.504,
  "frame": "tests/pcap-samples/sip-rtp-g711.pcap#0@db88659b94678546",
  "timing": {
    "retransmits": 0,
    "setup_ms": 4,
    "teardown_ms": 0,
    "trying_delay_ms": 0
  },
  "diagnosis": {
    "hints": [
      "RTP flowed 10.0.2.15:27942 -> 10.0.2.20:6000 only (SSRC 0x343da99b). No reverse media flow detected."
    ],
    "nat_mismatch": false,
    "no_media": false,
    "one_way_audio": true
  },
  "sdp_timeline": [ /* the same rows get_sdp_timeline returns */ ],
  "streams": [ /* the same rows rtp_stats returns, without mos */ ]
}

A termination block appears beside these fields on a call that said why it ended — the same object, from the same assembler, that triage_call documents above. It is absent from the example because this sample's BYE carries no Reason header and no vendor equivalent, which is the honest rendering: sipnab drops the block, and never sends null, when nothing on the wire named a cause.

This report bundles what triage_call, get_sdp_timeline and rtp_stats answer separately, so one call replaces three when you already know which call to read. Its streams rows omit mos and mos_grounded — ask rtp_stats when the question is audio quality rather than what the call did.

Unlike the summary rows elsewhere, from and to here arrive unfenced, and the trailing provenance note explains why: a rendered report interleaves sipnab's diagnosis with header values the sender wrote, and fencing the whole document would tell an agent to distrust the analysis as well.

Single SIP message at a given zero-based index.

Where an index comes from, because the number means nothing on its own: msg_count on any list_dialogs row is the count, so the last valid index is msg_count - 1. get_dialog pages messages from its cursor, so the Nth row of that page sits at cursor + N, and every lint_dialog finding reports the message_index it fired on.

An index at or past the end fails with index 999 out of range for dialog with 7 messages — the count is in the message, so a caller that guessed corrects itself without another round trip.

Returns one message in the same shape get_dialog uses for a messages row, plus the provenance note as a second content block. The difference is the fencing: this tool wraps from, to, contact, sdp, ua, reason, malformed and extension_headers, and leaves call_id, addresses, ports, method, status_code, cseq and timestamps verbatim so they pass into the next call.

// get_message { "call_id": "[email protected]", "index": 0 }
{
  "schema_version": 1,
  "call_id": "[email protected]",
  "method": "INVITE",
  "is_request": true,
  "cseq": { "method": "INVITE", "number": 1 },
  "from": "⟦untrusted-capture-data⟧\"PCMU/8000\" <sip:[email protected]:5060>;tag=1⟦/untrusted-capture-data⟧",
  "to": "⟦untrusted-capture-data⟧test <sip:[email protected]:5060>⟦/untrusted-capture-data⟧",
  "contact": "⟦untrusted-capture-data⟧sip:[email protected]:5060⟦/untrusted-capture-data⟧",
  "sdp": "⟦untrusted-capture-data⟧v=0\no=- 42 42 IN IP4 10.0.2.20\ns=-\nc=IN IP4 10.0.2.20\nt=0 0\nm=audio 6000 RTP/AVP 0\na=rtpmap:0 PCMU/8000\na=recvonly\n⟦/untrusted-capture-data⟧",
  "src": "10.0.2.20",
  "src_port": 5060,
  "dst": "10.0.2.15",
  "dst_port": 5060,
  "transport": "UDP",
  "timestamp": "2016-11-26T14:52:59.666393+00:00",
  "frame": "tests/pcap-samples/sip-rtp-g711.pcap#0@db88659b94678546",
  "dscp": 0,
  "input_origin": "wire",
  "extension_headers": [
    "⟦untrusted-capture-data⟧Via: SIP/2.0/UDP 10.0.2.20:5060;branch=z9hG4bK-1966-1-0⟦/untrusted-capture-data⟧",
    "⟦untrusted-capture-data⟧Max-Forwards: 70⟦/untrusted-capture-data⟧",
    "⟦untrusted-capture-data⟧Content-Type: application/sdp⟦/untrusted-capture-data⟧",
    "⟦untrusted-capture-data⟧Content-Length: 123⟦/untrusted-capture-data⟧"
  ]
}

dscp and input_origin carry the meanings get_dialog gives them. sipnab omits either key rather than sending null when it observed neither.

Every header the fields above do NOT already carry, in wire form ("Name: value") and in wire order — one entry per header line.

The named fields are a closed list, and every vendor-, carrier- and SBC-specific fact lives outside it: X-Asterisk-*, Reason, Diversion, P-Asserted-Identity, Remote-Party-ID, Require, RSeq. The parser has always retained them, so this was a projection gap rather than a parsing one. Before it existed the only route to one of those values was decode_evidence, which needs a server-side --mcp-file-root opt-in, a reachable original capture, and one call per frame.

Six header names never appear here, because they are already fields of their own: Call-ID, From, To, Contact, User-Agent and CSeq. sipnab drops nothing else — Via and Content-Length are in the list above because the sample carries them and nothing pretends otherwise.

The list keeps duplicates and wire order. Via is a stack whose order is the route the request took, so three Via lines are three entries in the order they arrived.

Fenced whole, name included. For an extension header the NAME is the sender's choice as much as the value is, so the marker pair wraps the entire Name: value string. This widens the prompt-injection surface the threat model already tracks — see deferred-and-declined.md — it does not introduce a new one: the same bytes were already reachable through search_messages, which returns the raw message.

No new ceiling. The parser refuses a message with more than 200 headers or a header line longer than 8 KiB, so what reaches this field is already bounded by the operator's own limits.

Call-flow ladder for one Call-ID.

Returns one text content block holding the rendered report, and the provenance note as a second block. There is no JSON shape here — ask get_dialog_report with format: "json" for fields a program can read.

render_ladder { "call_id": "[email protected]" }

Output is byte-identical to the report sipnab -N --call-report <id> --markdown --no-cli-print / sipnab -N --call-report <id> --no-cli-print writes for the same dialog. --no-cli-print matters for the comparison: without it the CLI writes the whole capture's per-message dump ahead of the report, and the tool never does.

Over a capture that was not read in full — still loading, or a read that stopped before the file's end — the tool appends an INCOMPLETE RUN block after the ladder, which --call-report does not. The ladder itself does not change: the block goes after it, so no line of the drawing moves.

# Call Report: [email protected]

## Summary

| Field | Value |
|-------|-------|
| Time | 2016-11-26 14:52:59 -> 14:53:08 (8s) |
| From | sipp |
| To | test |
| State | Completed |

## Timing

| Metric | Value |
|--------|-------|
| PDD | - |
| Setup | 0.00s |
| Ring | - |
| Teardown | 0.00s |
| Retransmits | 0 |

## Media Streams

| SSRC | Codec | Source | Destination | Packets | Jitter | Loss |
|------|-------|--------|-------------|---------|--------|------|
| 0x343da99b | PCMU | 10.0.2.15:27942 | 10.0.2.20:6000 | 425 | 0ms | 0.0% |

## Issues

- RTP flowed 10.0.2.15:27942 -> 10.0.2.20:6000 only (SSRC 0x343da99b). No reverse media flow detected.

The offer/answer exchanges in order — codecs, media address, port and mode per negotiation, including re-INVITEs. Use it when audio changed mid-call, or when the two ends disagree about the codec.

Parameters: call_id (string, required) — a Call-ID the store holds. No optional parameters.

Every exchange carries direction (offer or answer), codecs, media_addr, media_port, mode (sendrecv, sendonly, recvonly or inactive), timestamp, and event — null unless sipnab classified the exchange, as with the MediaAnchorChange below. A call carrying no SDP answers with an empty exchanges array rather than an error.

// get_sdp_timeline { "call_id": "[email protected]" }
{
  "call_id": "[email protected]",
  "exchanges": [
    {
      "codecs": [
        "PCMU"
      ],
      "direction": "offer",
      "event": null,
      "media_addr": "10.0.2.20",
      "media_port": 6000,
      "mode": "recvonly",
      "timestamp": "2016-11-26T14:52:59.666393+00:00"
    },
    {
      "codecs": [
        "PCMU",
        "telephone-event"
      ],
      "direction": "answer",
      "event": "MediaAnchorChange",
      "media_addr": "10.0.2.15",
      "media_port": 27942,
      "mode": "sendonly",
      "timestamp": "2016-11-26T14:52:59.670743+00:00"
    }
  ],
  "schema_version": 1
}

The offer promises recvonly on 10.0.2.20:6000 and the answer replies sendonly from 10.0.2.15:27942, which is why triage_call calls this capture one-way media rather than a fault.

For 488 Not Acceptable Here, which usually means nobody offered the far end a codec it accepts.

Parameters: call_id (string, required) — a Call-ID the store holds. No optional parameters.

Returns offered, answered, common, result, sdp_exchange_count, final_status_code, call_id and schema_version. Codec names come from the SDP unfenced, because they are tokens from a registry rather than free text.

// check_codec_negotiation { "call_id": "[email protected]" }
{
  "schema_version": 1,
  "call_id": "[email protected]",
  "offered": ["PCMU"],
  "answered": ["PCMU", "telephone-event"],
  "common": ["PCMU"],
  "result": "ok",
  "final_status_code": 200,
  "sdp_exchange_count": 2
}

result has five values, and the distinction matters:

no_answer and no_sdp_in_capture are deliberately separate: reporting the first for the second sends you hunting a reply that was never expected.

"Is this phone online?" — a different question from "why did this call fail?".

Parameters: call_id (string, required) — a Call-ID the store holds. No optional parameters. The call need not carry a REGISTER, and the answer says so when it does not.

Read applicable first. It is false for a dialog carrying no REGISTER, and the response then holds only call_id, reason and schema_version — no hints, no registration_failure. Reporting a healthy registration for a call that never attempted one would be worse than admitting the question does not apply:

// diagnose_registration { "call_id": "[email protected]" }   — an INVITE dialog
{
  "schema_version": 1,
  "call_id": "[email protected]",
  "applicable": false,
  "reason": "this dialog carries no REGISTER request"
}

When it does apply, registration_failure is null for a registration that worked, and otherwise names the kind — rejected, shortened_expiry or an auth loop reported through auth_loop. evidence lists the message indexes behind the verdict, ready for get_message. The example runs against tests/pcap-samples/sip-auth-failure.pcapng:

// diagnose_registration { "call_id": "[email protected]" }
{
  "schema_version": 1,
  "call_id": "[email protected]",
  "applicable": true,
  "final_status_code": null,
  "auth_loop": null,
  "registration_failure": {
    "kind": "rejected",
    "code": 403,
    "evidence": [0, 3],
    "requested_expiry_sec": null,
    "granted_expiry_sec": null
  },
  "contact_rewrite": {
    "contact_host": "203.0.113.1:42952",
    "contact_host_private": false,
    "source_public": true,
    "rewrite_required": false
  },
  "hints": [
    "Call failed: 403 Forbidden.",
    "Registration rejected: 403 Forbidden. The endpoint answered an authentication challenge and the registrar refused the credentials it offered, so the fault is in the account, its password or its permission to register — none of which is a reachability problem."
  ]
}

final_status_code is null here even though the registrar answered 403, because the dialog never reached a state that records one. Read registration_failure.code for the status that decided the verdict.

A phone behind NAT registers its own private address, and the registrar must notice the packet came from a public address the header does not name and route later requests there instead. When it does not, every inbound call goes to an unroutable host and the phone never rings.

rewrite_required is the conjunction that shape needs: contact_host_private && source_public. The sample above reports false — a public Contact from a public source needs nothing rewritten, which is the honest reading and not a fault ruled out.

This is deliberately not a finding. 1,660 of 2,226 REGISTER contacts in the private corpus carry a private host — 74.6%, measured 2026-09-08 — and that estate works. What separates the working case from the broken one is which address later requests actually used, and one dialog cannot see that. Ask describe_endpoint, which crosses an endpoint's dialogs and reports verdict and is_finding.

The block is absent when the dialog carries no REGISTER — the same applicable: false case the top of this section describes.

"Was this call recorded, and who is on the recording?" A session recording client (SRC) — OpenSIPS's siprec module, an SBC — sends the recording server an INVITE whose body carries an application/rs-metadata+xml part describing what it is about to record. sipnab reads that part off the wire and returns it.

Read recorded first. It is false when the dialog carried no SIPREC metadata, and the response then holds only call_id, reason, capture_identity and schema_version. The reason says what that does and does not mean: sipnab reports what reached the capture point, so a recorder signaling on a path it cannot see is indistinguishable here from a call nobody recorded. It is not a statement that the call went unrecorded.

Otherwise siprec carries:

label and participant_id are the two that matter. The label is the SDP a=label naming the m= line the SRC cut the recorded stream from, so on a call with audio and video it says which is which. The participant_id is the party that sends that stream, which is the only route from a recorded stream back to a person — nothing inside the stream element names one. sipnab reads it from <participantstreamassoc>, whose <send> children mean ownership and whose <recv> children do not. The party at the other end hears a stream without owning it.

// siprec_metadata { "call_id": "[email protected]" }
{
  "schema_version": 1,
  "call_id": "[email protected]",
  "recorded": true,
  "siprec": {
    "session_id": "4f1c0a2e",
    "mode": "complete",
    "participants": [
      { "participant_id": "9b2d1f00", "aor": "sip:[email protected]", "name": "Alice" },
      { "participant_id": "c7e40a13", "aor": "sip:[email protected]" }
    ],
    "streams": [
      { "stream_id": "1a2b3c4d", "label": "0", "participant_id": "9b2d1f00" },
      { "stream_id": "2b3c4d5e", "label": "1", "participant_id": "9b2d1f00" },
      { "stream_id": "3c4d5e6f", "label": "2", "participant_id": "c7e40a13" }
    ]
  }
}

sipnab reads SIPREC and does not speak it. It is not a session recording client and not a recording server — it observes the signaling between them, which is the same posture it takes toward every other protocol it reads.

"The MOS is 3.6 — why?" rtp_stats gives the score. This gives the facts underneath it, and each one says what kind of number it is.

Read applicable first. It is false when no RTP stream belongs to the dialog, and the response then holds only call_id, reason, capture_identity and schema_version. An empty streams array would read as "sipnab checked the media and it was fine", which is a different claim from "no media reached the capture point".

Otherwise streams carries one entry per stream, each with five blocks:

endpoint_reported sits apart from everything beside it on purpose. Nobody authenticates RTCP and anyone can forge it, and a report describes the path from the sender to the reporter — on a mid-path capture, a different segment from the one sipnab watches. The two disagreeing is normal and informative, and merging them would destroy exactly that signal. Nothing under this key feeds the MOS.

qos.remarked_to appears only when the stream's last packet carries a different code point from its first — an SBC or a policy boundary rewriting the marking in flight. Its presence is the finding, and a steady stream omits it rather than repeating the same number.

The example runs against tests/pcap-samples/sip-rtp-g711.pcap:

// media_diagnostics { "call_id": "[email protected]" }
{
  "schema_version": 1,
  "call_id": "[email protected]",
  "applicable": true,
  "streams": [
    {
      "ssrc": "0x343da99b",
      "src": "10.0.2.15:27942",
      "dst": "10.0.2.20:6000",
      "codec": "PCMU",
      "packets": 425,
      "qos": {
        "marking_observed": true,
        "dscp": 0,
        "name": "CS0 / default (best effort)",
        "expedited": false
      },
      "jitter": {
        "grounded": true,
        "clock_basis": "rfc3551",
        "clock_rate_hz": 8000,
        "measured_ms": 0.0054046519599899685
      },
      "delay": { "source": "assumed", "assumed": true, "one_way_ms": 100.0 },
      "silence": { "cn_frames": 0, "periods": 0, "total_ms": 0 }
    }
  ],
  "capture_identity": {
    "instance": "6dac718cb96d767d0f490-1",
    "node": "sbc-1",
    "dialog_generation": 13,
    "stream_generation": 2
  }
}

Three things in that answer are worth reading together. The media is in the default queue, so it competes with bulk traffic — the most common cause of jitter that adding bandwidth does not fix. The jitter figure IS a measurement, because payload type 0 has a clock rate RFC 3551 Table 4 fixes. And the delay behind the MOS is a default, not anything this capture showed, so a MOS built on it is only as good as that assumption.

clock_basis has three values: rfc3551 (a static payload type), rtpmap (a dynamic one an SDP named), and assumed (neither, and the reason grounded is false).

Per-stream RTP quality for one call, or across the whole capture.

This tool has two modes, and call_id is the switch. Pass it for one dialog's streams. Omit it to sweep the whole capture. Five parameters belong to the sweep alone:

Only the two MOS bounds fail alongside a call_id. They ask a question about the whole capture, so sending one with a Call-ID is a misunderstanding of the tool, and sipnab answers invalid_params (-32602) rather than quietly doing nothing. Per-call mode simply skips orphaned, limit and cursor: a call holds every stream it holds, so there is nothing there to page or to filter.

With call_id the answer keeps its existing shape — { call_id, streams, diagnosis }, where streams is an array of stream JSON objects (codec, MOS, jitter, loss%, packets, SSRC, quality intervals) and diagnosis carries the standard one-way / NAT-mismatch flags plus the asymmetry signals (codec_asymmetry, ptime_asymmetry, payload_type_asymmetry, duration_asymmetry, late_media). A MOS bound alongside a call_id returns invalid_params (-32602) rather than quietly doing nothing.

// rtp_stats { "call_id": "[email protected]" }
{
  "call_id": "[email protected]",
  "streams": [
    {
      "associated_dialog": "[email protected]",
      "dialog_assertion": "signaled",
      "codec": "PCMU",
      "src": "10.0.2.15:27942",
      "dst": "10.0.2.20:6000",
      "ssrc": "0x343da99b",
      "payload_type": 0,
      "packets": 425,
      "octets": 68000,
      "loss_pct": 0.0,
      "jitter_ms": 0.0054046519599899685,
      "mos": 4.358100599599484,
      "mos_grounded": true,
      "mos_grounding": "published",
      "orphaned": false,
      "dscp": 0,
      "input_origin": "wire",
      "first_seen": "2016-11-26T14:52:59.689083+00:00",
      "last_seen": "2016-11-26T14:53:08.169060+00:00",
      "round_trip_note": "Not measured. No endpoint reported a round trip for this stream, so latency is unknown rather than good — a stream with clean jitter and no loss can still be unusable on delay alone (ITU-T G.114).",
      "quality_intervals": [
        {
          "jitter_ms": 0.0063823922199494915,
          "loss_pct": 0.0,
          "mos": 4.358100053908192,
          "mos_grounded": true,
          "packets": 252,
          "r_factor": 90.79984682258672,
          "timestamp": "2016-11-26T14:53:04.709076+00:00",
          "verdict": "acceptable"
        }
      ],
      "frame": "tests/pcap-samples/sip-rtp-g711.pcap#5@ae02f78d2d48b4f0",
      "schema_version": 1
    }
  ],
  "diagnosis": {
    "actual_media": null,
    "hints": [
      "RTP flowed 10.0.2.15:27942 -> 10.0.2.20:6000 only (SSRC 0x343da99b). No reverse media flow detected."
    ],
    "nat_mismatch": false,
    "no_media": false,
    "one_way_audio": true,
    "private_media_address": false,
    "sdp_media": "10.0.2.20"
  }
}

diagnosis always carries one_way_audio, nat_mismatch, no_media, private_media_address, sdp_media, actual_media and hints. The asymmetry signals named above appear only when sipnab found one, so an absent codec_asymmetry means the legs agreed rather than that the check did not run.

Per-call mode returns no total_matched, truncated or next_cursor — a call holds every stream it holds, so there is nothing to page. quality_intervals holds one entry per completed sampling window, so a short call legitimately returns an empty array while this eight-second one returns a single row. The window is five seconds by default. --quality-interval narrows it, down to one second, without shortening the hour of call time the trend covers.

Each interval carries its own mos, r_factor and verdict. The stream-level MOS is a mean over the whole call, and a mean hides a burst shorter than itself: one 90 % loss figure this project had to explain turned out to be three bursts of half a second. sipnab scores an interval on its own jitter and loss and on the STREAM's resolved path delay, so a number in the trend and the headline beside it rest on one basis.

verdict has three states and the third is the point:

not_scorable is the only answer for an ungrounded codec, and it is not a shade of good or bad. Anything that COUNTS degraded intervals has to read the verdict first: a refusal to judge is not the absence of a problem, and reading it as one reports a healthy call on a codec nobody can score.

Each stream carries mos_grounded and mos_grounding. estimate_mos returns the same number — 4.216 at 10 ms jitter — for AMR, AMR-WB, EVS, G.722 and for a stream whose codec was never identified, because sipnab only has published ITU-T G.113 impairment values for G.711, G.729 and Opus. When mos_grounded is false the MOS means unknown, not "about 4.2", and a mos_note says so.

mos_grounding names which basis the number rests on, because "grounded" now covers two of them:

For AMR-WB specifically the placeholder is wrong by roughly a full MOS point in either direction: its nine modes genuinely span about 4.49 down to 3.51. Do not report a MOS to a human without checking this field. See MOS and codecs for the full picture.

Each stream also says who asserted the SDP media endpoint that tied it to its Call-ID:

A relay cannot be wrong about which socket it opened, so the address is authoritative — and it is still not an endpoint. An agent reasoning about where media went must not report a media-relay address as the far party's, because it names the box in the middle and the two lead to opposite conclusions.

sipnab emits the key whenever it knows the answer, signaled included. Absent means nobody recorded who asserted it, never "a party did". Do not default it.

Distinct from dialog_origin, which names the capture source that delivered the assertion rather than its author. See rtpengine relay attribution.

"Every stream with a MOS below 3.5" is one call rather than a listing plus one rtp_stats per dialog, which costs thousands of round trips on a real capture. The sweep also reaches streams the per-call mode cannot: a stream that never linked to a dialog has no Call-ID to ask about, and an orphan is not an oddity — it is what a NAT or one-way-audio fault looks like from the media side.

A MOS bound only judges codecs sipnab has a real impairment value for — one G.113 publishes, or one this deployment declared in [media.codec_ie]. min_mos and max_mos skip every ungrounded stream and count it in ungrounded_excluded, because a bound on a placeholder picks calls out of a guess — and it goes wrong in both directions. A healthy AMR-WB stream never appears in a max_mos sweep, while a degraded one turns up on a figure that never described it. Reporting the skipped count keeps the difference visible: "2 streams below 3.5" and "2 streams below 3.5, plus 200 I cannot score" describe different captures, and on any network carrying AMR-WB, EVS or G.722 the second one is the truth. Omit both bounds and the sweep lists every stream, including the codecs with no published value, each still carrying mos_grounded.

The example runs against tests/pcap-samples/codec-negotiation.pcap, which carries four streams — two PCMU, two G722 — and no dialogs at all:

// rtp_stats { "max_mos": 4.5, "limit": 1 }
{
  "schema_version": 1,
  "streams": [
    {
      "codec": "PCMU",
      "dscp": 0,
      "dst": "127.0.0.1:5084",
      "first_seen": "2026-07-08T18:35:27.407583+00:00",
      "frame": "tests/pcap-samples/codec-negotiation.pcap#5@5d4c3e3d970a836b",
      "input_origin": "wire",
      "jitter_ms": 0.26954164761616456,
      "last_seen": "2026-07-08T18:35:30.407077+00:00",
      "loss_pct": 0.0,
      "mos": 4.357953149337916,
      "mos_grounded": true,
      "mos_grounding": "published",
      "octets": 24160,
      "orphaned": true,
      "packets": 151,
      "payload_type": 0,
      "quality_intervals": [],
      "round_trip_note": "Not measured. No endpoint reported a round trip for this stream, so latency is unknown rather than good — a stream with clean jitter and no loss can still be unusable on delay alone (ITU-T G.114).",
      "schema_version": 1,
      "src": "127.0.0.1:5094",
      "ssrc": "0x0e330af3"
    }
  ],
  "returned": 1,
  "total_matched": 2,
  "ungrounded_excluded": 2,
  "truncated": true,
  "next_cursor": "2026-07-08T18:35:27.407583+00:00|[email protected]:5094>127.0.0.1:5084",
  "capture_identity": {
    "node": "capture-01",
    "instance": "22fa418cb5c799c57abef-1",
    "dialog_generation": 1,
    "stream_generation": 4
  }
}

The sweep adds frame, capture_identity and the page fields the per-call mode omits.

orphaned means "no dialog claims this stream", and nothing else. It is associated_dialog.is_none(), which sipnab computes while building the response, so the two fields can never disagree: every stream above reports orphaned: true, which is the truth about a capture holding four streams and no dialogs at all.

sipnab computes orphaned per response as associated_dialog.is_none(), so a stream reports it from its FIRST packet. That matters because a short unclaimed stream is exactly what a NAT or one-way-audio fault looks like from the media side: an agent filtering for orphans to find one must not have to wait for a sweep to notice. Reading associated_dialog directly means the same thing.

total_matched: 2 and ungrounded_excluded: 2 account for all four streams. The two G722 streams score 4.22 from the placeholder arm, which would have put them under a 4.5 bound on a number that means nothing.

Whether the traffic obeys the RFCs, and which clause it broke. These turn "the call failed" into "12.1.1 requires a Contact and there is none".

Conformance, which is not the question triage_call answers. That tool asks why a call failed. This one asks whether the traffic obeys the specification. A call can complete over messages that break four MUSTs, and a fully conformant call can hit a busy signal.

The rules that earn this tool its place compare the declaration against the observation. sipnab holds the signaling and the RTP in one process, so it can report that the SDP declared PCMU on payload type 0 while the wire carried payload type 8, that RTP arrived on a port no m= line advertised, that sendrecv promised media in both directions and the capture holds it in one, or that the packet spacing contradicts a=ptime. A linter reading message text reaches none of that, because the defect sits in neither message.

The RFC 3261 syntax rules and the RFC 3264 offer/answer rules run alongside them. Everything citing RFC 4566, 3551 or 5761 belongs to the observation half. SIP conformance rules lists every rule, the section behind it, and the suppression syntax.

Selectors take two forms — the catalog's own names, and one per RFC the rules cite:

• By category: all, must, rfc (MUST and SHOULD together), interop, observation (observed also works) and syntax.
• By RFC: rfc3261, rfc3262, rfc3264, rfc3551, rfc4028, rfc4566, rfc5761, rfc7989.

An unknown selector fails with invalid_params (-32602) naming the whole vocabulary, so a typo such as rfc3621 cannot quietly select nothing and hand back an empty list that reads as a clean call. Passing an empty array behaves as omitting the parameter.

The example runs against tests/pcap-samples/b2bua-asterisk.pcapng. Its SDP negotiates sendrecv in both directions, and the capture carries 355 RTP packets in one:

// lint_dialog { "call_id": "[email protected]:5060",
//               "rulesets": ["observed"] }
{
  "schema_version": 1,
  "call_id": "[email protected]:5060",
  "rulesets": ["observed"],
  "severity_min": "info",
  "message_count": 15,
  "rtp_streams_observed": 1,
  "finding_count": 1,
  "severity_counts": { "error": 0, "warning": 1, "notice": 0, "info": 0 },
  "findings": [
    {
      "rule_id": "OBS-3264-6.1-DIRECTION-UNMET",
      "severity": "warning",
      "basis": "observation",
      "rfc": 3264,
      "section": "6.1",
      "message_index": 0,
      "observed": "⟦untrusted-capture-data⟧355 RTP packets observed, none of them toward one negotiated endpoint⟦/untrusted-capture-data⟧",
      "expected": "media in both directions, as a=sendrecv promised",
      "explanation": "§6.1 makes sendrecv a promise to send as well as receive. ...",
      "frame_ref": "tests/pcap-samples/b2bua-asterisk.pcapng#23@08cb2267de5498ce"
    }
  ],
  "rules_not_evaluated": [
    {
      "reason": "needs the endpoint pairs RTCP arrived on. ...",
      "rule_ids": ["OBS-5761-5.1.1-RTCP-MUX-UNANSWERED"]
    }
  ],
  "findings_withheld": { "suppressed": 0, "below_severity": 0, "capped": 0 },
  "suppressions": { "file": null, "patterns": [], "findings_suppressed": 0 },
  "rule_catalog": "docs/sip-lint-rules.md"
}

rfc and section stay separate fields rather than prose inside the explanation, and that is the whole point of the shape. An agent quotes RFC 3264 section 6.1 out of the data instead of inventing a section number that reads plausibly, and explain_rule turns the identifier back into the citation and the link.

frame_ref on each finding points at the frame the rule fired on. Hand it to show_evidence and the claim becomes bytes a reader can check, which is the difference between a finding and an assertion. observed quotes the capture and therefore arrives fenced. expected and explanation are sipnab's own words, so they do not.

rules_not_evaluated names what the run could not settle, grouped by reason. A rule that found nothing and a rule that never ran leave the same empty finding list behind, and only this field separates them. Two reasons appear on this tool:

• No RTP reached the call, so the OBS- rules had nothing to compare the declaration against.
• OBS-5761-5.1.1-RTCP-MUX-UNANSWERED needs the endpoint pairs RTCP arrived on. The stream store folds an RTCP report into the stream it describes and keeps no record of where it landed, so no MCP tool raises this rule.

A project silences rules with a .sipnablint — one identifier per line, or a prefix ending *, with # starting a comment. SIP conformance rules documents the pattern syntax.

sipnab looks for one beside the capture, then climbs toward the project root and stops there. A capture that sits outside any project — a corpus mount, a share, /tmp — adopts nothing from above itself, because inheriting a stranger's suppression list would switch off rules nobody here turned off. suppression_file overrides the search outright, and a file it names that sipnab cannot open returns invalid_params rather than quietly linting with every rule on.

Two response fields carry the consequences, and every call includes both, even when every number is zero:

"suppressions": {
  "file": "/srv/captures/.sipnablint",   // null when none applied
  "patterns": ["OBS-*", "SIP-3261-8.1.1.6-MAX-FORWARDS-MISSING"],
  "findings_suppressed": 4
},
"findings_withheld": { "suppressed": 4, "below_severity": 2, "capped": 0 }

A response carrying no field and a response carrying zero must not be the same bytes. The first says nothing about whether the run hid findings. The second says it hid none.

The three counts stay apart because they send you to three different places: something you wrote down silenced it, your severity floor dropped it, or there was simply too much of it and the per-rule cap stopped after 25. capped is the only lower bound of the three — a rule may stop evaluating once it hits the cap, and nothing can count what it then never raises. suppressed and below_severity are exact, which is why suppression deliberately does not short-circuit the rule.

The response names the file rather than merely acknowledging one. "4 findings suppressed" leaves you nothing to act on when the search walked up three directories to find the file that did it.

The same rules against one message, named by its zero-based index — the shape a CI job or a header-level argument with a vendor wants. lint_dialog reports message_index on every finding, so this tool narrows a hit rather than finding new ones.

There is no rulesets or severity_min here. Every rule that can run on one message runs, and the response reports the rest under rules_not_evaluated.

// validate_message { "call_id": "[email protected]", "index": 0 }
{
  "schema_version": 1,
  "call_id": "[email protected]",
  "message_index": 0,
  "message_count": 2,
  "finding_count": 2,
  "severity_counts": { "error": 0, "warning": 2, "notice": 0, "info": 0 },
  "findings": [
    {
      "rule_id": "SIP-3261-8.1.1.6-MAX-FORWARDS-MISSING",
      "severity": "warning", "basis": "must", "rfc": 3261, "section": "8.1.1.6",
      "message_index": 0,
      "observed": "⟦untrusted-capture-data⟧no Max-Forwards header field⟦/untrusted-capture-data⟧",
      "expected": "Max-Forwards: 70",
      "explanation": "§8.1.1.6 makes a UAC insert one into every request it originates. ...",
      "frame_ref": "tests/pcap-samples/sip-488-codec-reject.pcapng#4@b2b8ff6b3eeddf54"
    },
    {
      "rule_id": "SIP-3261-8.1.1.7-BRANCH-COOKIE",
      "severity": "warning", "basis": "must", "rfc": 3261, "section": "8.1.1.7",
      "message_index": 0,
      "observed": "⟦untrusted-capture-data⟧top Via branch without the z9hG4bK prefix⟦/untrusted-capture-data⟧",
      "expected": "branch=z9hG4bK...",
      "explanation": "§8.1.1.7 makes every compliant branch begin with z9hG4bK. ...",
      "frame_ref": "tests/pcap-samples/sip-488-codec-reject.pcapng#4@b2b8ff6b3eeddf54"
    }
  ],
  "findings_withheld": { "suppressed": 0, "below_severity": 0, "capped": 0 },
  "suppressions": { "file": null, "patterns": [], "findings_suppressed": 0 },
  "rules_not_evaluated": [
    { "reason": "reads a dialog's messages against each other, and this tool reads one message alone. Call lint_dialog.",
      "rule_ids": ["SIP-3261-8.1.1.2-TO-TAG-IN-INITIAL-REQUEST", "..."] },
    { "reason": "compares the declaration against the observed media, and this tool reads one message alone. Call lint_dialog.",
      "rule_ids": ["OBS-3264-6.1-PT-UNDECLARED", "..."] },
    { "reason": "needs the endpoint pairs RTCP arrived on. ...",
      "rule_ids": ["OBS-5761-5.1.1-RTCP-MUX-UNANSWERED"] }
  ],
  "rule_catalog": "docs/sip-lint-rules.md"
}

That example runs against tests/pcap-samples/sip-488-codec-reject.pcapng, whose first OPTIONS ping carries neither a Max-Forwards header field nor the RFC 3261 branch cookie.

observed quotes the message, so it arrives fenced. expected is sipnab's own words, so it does not. frame_ref points at the frame the finding fired on — hand it to show_evidence to read the bytes behind the claim. findings_withheld counts what the response left out and why, and suppressions names the .sipnablint file that took part, both of them exactly as lint_dialog reports them.

Nineteen of the forty-one rules skip on a one-message run, which is why the response names them. Reach for lint_dialog first and use this to confirm one message.

Turns a rule identifier back into its catalog entry, so an identifier lifted out of a finding, a CI log or a suppression file resolves without a round trip to the source.

Parameters: rule_id (string, required) — one of the 41 catalog identifiers, matched exactly, such as OBS-3264-6.1-PT-UNDECLARED. No optional parameters, and the tool reads no capture, so it answers the same on any server. An unknown identifier fails with invalid_params (-32602) listing all 41, which doubles as the way to enumerate them.

// explain_rule { "rule_id": "OBS-3264-6.1-DIRECTION-UNMET" }
{
  "schema_version": 1,
  "rule_id": "OBS-3264-6.1-DIRECTION-UNMET",
  "title": "sendrecv negotiated, media observed one way",
  "severity": "warning",
  "basis": "observation",
  "rfc": 3264,
  "section": "6.1",
  "citation": "RFC 3264 §6.1",
  "url": "https://www.rfc-editor.org/rfc/rfc3264#section-6.1",
  "scope": "media",
  "rulesets": ["all", "observation", "observed", "rfc3264"],
  "rule_catalog": "docs/sip-lint-rules.md"
}

rulesets lists every selector that reaches this rule, so any entry passes straight back as a lint_dialog rulesets value. scope says what the rule has to read before it can run: message, dialog or media.

An unknown identifier returns invalid_params (-32602) listing all forty-one, because an empty answer would read as "that rule found nothing".

The IANA registry, not an agent's recollection.

Parameters: code (integer, required) — a SIP status code from 100 to 699. Outside that range fails with 999 is not a SIP response code (100-699). No optional parameters, and this tool reads no capture either, so it answers on a server holding nothing.

// explain_response_code { "code": 488 }
{
  "schema_version": 1,
  "code": 488,
  "class": "failure",     // provisional|success|redirect|challenge|canceled|declined|failure
  "explanation": "488 Not Acceptable Here — Codec negotiation failed. Compare the SDP offer against the callee's supported codecs and ptime values.",
  "registered": true
}

class distinguishes a challenge from a failure: 401 is challenge, not failure, because a challenged call has not failed — it is mid-handshake. registered: false means the code is outside the registry, usually a vendor extension. The tool says so rather than inventing a meaning.

A pass/fail verdict on the loaded capture, and an exit code for a build.

Every other tool here makes a bad day shorter. This one prevents it, and it moves sipnab from something an operator reaches for during an incident to something that runs on every commit. The rules live in a checked-in sipnab.expect.toml beside the SBC config: that file is the UX, and this tool is how an agent reasons about it.

Passing the file's own bytes is the point of rules_toml: the agent then judges the capture against exactly what CI judges it against, rather than against its own transcription. Passing both, or neither, fails — two suites in one call have no defined order, and a call with no suite would report a verdict on nothing.

One rule is a metric, a comparison, a threshold, and what it applies to: