MCP Tools Signaling - NormB/sipnab GitHub Wiki

The signaling bundle answers follow-up questions about SIP signaling: single messages, call flows, SDP negotiation, related call legs, RFC conformance, time windows, and reproducing a call.

Load only these tools with --mcp-tools signaling, or combine bundles as Choosing which tools load describes. Every tool on this page follows the rules every tool follows, and each section states only what its tool does differently. The MCP tool reference lists the other bundles and finds any tool by name.

Tool Parameters Returns
timeline bucket_seconds? Call volume per fixed-width interval, so a gap or a spike is visible without reading every dialog
group_dialogs by, metrics?, filter?, named?, top_n? Carrier metrics per group — ASR, NER, ACD, post-dial delay, MOS, retransmissions — each beside the population it rests on
search_by_time start, end?, filter?, named?, limit?, cursor?, fields?, max_response_bytes? Dialogs whose first message falls in an RFC 3339 window
validate_filter expr Whether a filter DSL expression parses, the parser's message and position when it does not, and how many dialogs it selects — with no rows
list_named_filters (none) The operator's named filters from the [filters] table, each name with its definition as written
tail_dialogs cursor?, limit?, fields?, max_response_bytes? Cursor-based incremental dialog fetch
await_condition filter, timeout_seconds?, poll_interval_ms? Waits until a filter matches or a deadline passes, whichever is first, so a live capture costs one call instead of a polling loop
find_correlated call_id, limit? The other legs of the same call across a B2BUA, each with a score AND the strategy that matched it
get_call_tree call_id, limit? Every leg of one call as a tree, each edge carrying its parent, depth, score, strategy and whether the walk went through it
th_mappings call_id?, state?, limit? The OpenSIPS topology-hiding mappings held, one row each with its state and which legs sipnab captured, beside the event counts
compare_dialogs call_id_a, call_id_b Two calls side by side, with the differences named
get_dialog_report call_id, format? Structured per-call report (JSON / Markdown / text)
get_message call_id, index Single SIP message at a given index
render_ladder call_id, format? Call-flow ladder (Markdown / text), or an annotated Mermaid diagram
get_sdp_timeline call_id SDP offer/answer exchanges in order: codecs, ptime, direction
check_codec_negotiation call_id Codecs offered vs answered and whether they intersect — for 488s
lint_dialog call_id, rulesets?, severity_min?, suppression_file? Conformance findings for one call, declaration against observation included, each with its RFC and section
validate_message call_id, index, suppression_file? Conformance findings for one message, read alone
explain_rule rule_id The catalog entry behind one rule identifier: citation, basis, scope, selectors
explain_response_code code IANA registry meaning and class for a SIP status code
generate_repro call_id, format?, pin?, vary?, filename? A SIPp scenario replaying one call, with the hypothesis as an input: pin holds the suspected cause fixed, vary regenerates identity
generate_wireshark_filter call_id, include_media? A Wireshark display filter selecting one call's signaling and its RTP by SSRC, plus the tshark line that applies it

Survey — what is in this capture

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".

timeline

Call volume over time, in fixed-width buckets.

Use it to see when call volume changed. aggregate_dialogs counts dialogs but not when they occurred: a trunk that failed for ninety seconds and a trunk that fails one call in forty can produce the same totals, and only the series over time tells them apart. timeline returns one row per interval, counted by sipnab, so the agent does not fetch and bucket every dialog itself.

Name Type Legal values If omitted
bucket_seconds? integer? Greater than zero. 0 fails with invalid_params. 60.

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

Field Type Description
buckets object[] One row per interval, oldest first. Each carries start (inclusive, RFC 3339), bucket_seconds and dialogs.
returned u64 Rows in buckets, so counting the array is never necessary.
bucket_seconds u64 The width actually used, echoed because you may have omitted it.
capture_identity object Which capture answered — see capture_status.
source_exhausted bool true once sipnab has read the capture source to its end.
source_stopped_early bool true when a source's read ended before the source did.
schema_version u32 1 for this shape.

There is no truncated and no cursor: this tool takes no limit and returns every bucket in the capture, up to 100,000. When the dialogs span more intervals of the width than that, the call fails with reason limit_exceeded on bucket_seconds, and the message names a width that fits. Ask again with that width or a wider one.

The example runs against tests/pcap-samples/sip-problem-call.pcap, which holds five calls over about fifteen seconds:

// timeline { "bucket_seconds": 5 }
{
  "schema_version": 1,
  "buckets": [
    { "start": "2023-11-14T22:13:20Z", "bucket_seconds": 5, "dialogs": 2 },
    { "start": "2023-11-14T22:13:25Z", "bucket_seconds": 5, "dialogs": 2 },
    { "start": "2023-11-14T22:13:30Z", "bucket_seconds": 5, "dialogs": 1 }
  ],
  "returned": 3,
  "bucket_seconds": 5,
  "capture_identity": {
    "node": "capture-01", "instance": "12de3118df112f1a869f03-2",
    "dialog_generation": 26, "stream_generation": 0
  },
  "source_exhausted": true,
  "source_stopped_early": false
}

Read source_exhausted before reading the series. false means the capture was still loading, and later buckets may still fill.

Buckets align to the epoch, not to the first dialog, so two captures of the same window produce identical bucket boundaries, and you can compare them row by row. The series keeps empty buckets: a row with "dialogs": 0 is an interval with no new calls, which is how a gap in traffic shows. With "bucket_seconds": 1 the same capture returns rows such as { "start": "2023-11-14T22:13:21Z", "bucket_seconds": 1, "dialogs": 0 }.

group_dialogs

Carrier metrics per group, computed inside the store.

Use it to answer questions that need a rate per group: which trunk is failing, which User-Agent has the worst audio, which hour the failures started. aggregate_dialogs returns counts only. group_dialogs computes each rate over every matching dialog in the store, not over one page of rows, and reports the population each rate rests on.

Name Type Legal values If omitted
by string ONE of state, response_code, method, from.user, to.user, ua, src.ip, dst.ip, rtp.codec, to_domain, hour, next_hop. Anything else — including two names in one string, such as "src.ip,hour" — fails with invalid_params naming all twelve. Required.
metrics? string[]? Any of count, asr, ner, acd, pdd_p50, pdd_p95, mos_p10, retransmit_rate. The tool sorts and de-duplicates the list, so the key order in the answer never depends on the order you wrote. An unknown name fails naming all eight. All eight.
filter? string? Alias or DSL, applied before grouping — the same vocabulary list_dialogs takes. No filter — the whole store.
named? string? A [filters] name or alias, in place of filter, as list_dialogs takes it. filter decides.
top_n? integer? Bounded by --mcp-max-rows, the same knob that bounds dialog rows. Everything past it lands in other_count rather than disappearing. 50, the same default as any row limit.

The example runs against tests/pcap-samples/SIP_DTMF2.cap, which holds three REGISTER dialogs and two INVITE dialogs, one answered and one declined with 603:

// group_dialogs { "by": "method", "metrics": ["count", "asr", "ner"], "top_n": 2 }
{
  "schema_version": 1,
  "group_by": "method",
  "metrics": ["asr", "count", "ner"],
  "units": { "asr": "percent", "count": "dialogs", "ner": "percent" },
  "groups": [
    {
      "value": "REGISTER",
      "count": 3,
      "metrics": { "asr": null, "count": 3.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": 3, "seizures": 0, "answered": 0, "delivered": 0,
        "completed_calls": 0, "pdd_measured": 0,
        "mos_grounded_dialogs": 0, "retransmits": 0
      }
    },
    {
      "value": "INVITE",
      "count": 2,
      "metrics": { "asr": 50.0, "count": 2.0, "ner": 100.0 },
      "not_grounded": {},
      "population": {
        "dialogs": 2, "seizures": 2, "answered": 1, "delivered": 2,
        "completed_calls": 0, "pdd_measured": 1,
        "mos_grounded_dialogs": 0, "retransmits": 0
      }
    }
  ],
  "other_count": 0,
  "distinct_values": 2,
  "total_matched": 5,
  "capture_identity": { "node": "capture-01", "instance": "12644a18df004d486b4f30-2",
                        "dialog_generation": 26, "stream_generation": 0 },
  "source_exhausted": true,
  "source_stopped_early": false
}

To read the answer:

  • A null metric means the group has no population for it, and not_grounded says which. The REGISTER group holds no call attempts, so its ASR and NER are null, not 0.
  • units names the unit of every figure. asr and ner are percents, here and in evaluate_expectations, which takes its thresholds in the same unit: a rule reads "value": 99.
  • NER can be high where ASR is low. The INVITE group's 603 counts as delivered, so NER is 100 while ASR is 50.

The eight metrics, and what each one measures:

Metric Unit Definition Population it rests on
count dialogs Dialogs in the group. dialogs
asr percent Answer-seizure ratio: 2xx answers over seizures. seizures
ner percent Network effectiveness ratio (ITU-T E.411): seizures the network delivered over seizures. seizures
acd seconds Average call duration: mean CONVERSATION time, not dialog span. completed_calls
pdd_p50, pdd_p95 milliseconds Post-dial delay percentiles, nearest rank. pdd_measured
mos_p10 mos Tenth-percentile MOS across dialogs holding a stream sipnab can score, worst stream per dialog. mos_grounded_dialogs
retransmit_rate retransmissions per dialog retransmits over dialogs. Never refused — a group exists because a dialog fell into it. dialogs

How sipnab counts the metrics:

  • A seizure is an INVITE dialog that reached a final response. A REGISTER is not a seizure, and neither is an INVITE still ringing when the capture ended.
  • Delivered means a 2xx or one of 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. A trunk whose calls all end in 486 has an ASR of 0 and an NER of 100. 408 Request Timeout does not count as delivered, because a proxy sends it both for a phone that did not answer and for a next hop it could not reach.
  • 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 contributes 60 seconds.
  • Percentiles use nearest rank, with no interpolation, so each percentile is a value an actual call had.
  • sipnab rounds every metric to two decimal places. For the exact ratio, divide the two integers in population.
  • Groups rank by dialog count, largest first, ties broken by value. other_count holds the number of dialogs in the groups past top_n, with no metrics. The groups plus other_count always equal total_matched.

Three dimensions are available here and not in aggregate_dialogs. Every dimension aggregate_dialogs accepts is also accepted here:

Dimension Value Fenced?
to_domain The host half of the To URI, port stripped, IPv6 brackets kept. Yes — the sender wrote it.
hour The calendar hour the dialog opened in, aligned to the epoch like timeline buckets, RFC 3339. No
next_hop host:port the opening message went to, read off the IP and transport headers. No

to_domain, to.user, from.user and ua values arrive wrapped in ⟦untrusted-capture-data⟧, because the sender wrote them (see Untrusted capture text). A state name, a status code, an address, a codec and next_hop come back verbatim, because sipnab derived them.

next_hop names the address and port the opening message went to, as seen at the capture point. It names the actual next hop only when the capture point sits beside the sender, as on a proxy capturing its own trunk traffic.

by takes one dimension. To break a group down further, call again with a filter that selects that group. When a count alone answers the question, use aggregate_dialogs, which skips the metric computation.

Find — narrow to the calls that matter

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.

search_by_time

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

Name Type Legal values If omitted
start string An inclusive RFC 3339 instant, such as "2026-07-31T14:00:00Z". A malformed one fails with start 'x' is not RFC 3339. Required — the call fails.
end? string? An exclusive RFC 3339 instant after start. At or before start fails with invalid_params (-32602). Everything from start onward.
filter? string? An alias name or a raw DSL expression, ANDed with the window. The window alone decides the page.
named? string? A [filters] name or alias, in place of filter, as list_dialogs takes it. filter decides.
limit? u32? Ceiling is --mcp-max-rows (1000 by default). Higher clamps to it, 0 means the default. 50 rows.
cursor? string? The previous response's next_cursor, verbatim (<RFC 3339 created_at>|<Call-ID>). A malformed timestamp half fails with invalid_params. Starts at the oldest dialog in the window.
fields? string[]? Field names to keep on each row, plus call_id. The row here is already narrow, so name one of the four below — see Narrowing a row with fields. The whole row.
max_response_bytes? u64? Bytes for the whole response. Ceiling is --mcp-max-response-bytes (1048576 unless the operator changed it). Higher clamps to it, 0 means the ceiling. Past it the page ends early at a whole row with truncated_by: "bytes" — see Rules every tool follows. The ceiling.

Returns { dialogs, returned, total_matched, truncated, truncated_by, next_cursor, capture_identity, source_exhausted, source_stopped_early, schema_version }, with truncated_by present only when a bound cut the page. 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,
  "truncated_by": "rows",
  "next_cursor": "2016-11-17T21:52:37.703349Z|[email protected]",
  "capture_identity": {
    "node": "capture-01",
    "instance": "128e5a18df0061de520f1d-2",
    "dialog_generation": 9015,
    "stream_generation": 0
  },
  "source_exhausted": true,
  "source_stopped_early": false
}

To read the rest of a truncated window, pass next_cursor back with the same start, end and filter. total_matched counts the whole window, not the remainder, so it stays the same as you page. The cursor is the same compound form list_dialogs issues. Treat it as opaque and pass it back exactly as it arrived.

validate_filter

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

Use it to build a filter for list_dialogs, find_problems, search_by_time, aggregate_dialogs or group_dialogs without fetching a page of rows per attempt. It also tells apart the two outcomes a list tool reports the same way: an expression that does not parse, and an expression that parses but selects nothing.

Name Type Legal values If omitted
expr string A raw filter DSL expression, or one of the diagnostic aliases list_dialogs takes. Nothing you can put here fails the call. Required — the call fails.

A parse failure is a successful call. Other tools reject a bad filter with invalid_params. This one answers valid: false with the parser's own text in error, position, caret and hint included. It raises a JSON-RPC error only for an internal failure.

position is the place the parser stopped as a number: the 0-based character column in expr with its leading and trailing whitespace removed, the number error prints after at position. It is null when the expression parsed, when the parser names no place (an empty expression, an undefined @name, a depth or size limit), and when the error is inside the expansion of an alias or an @name. GET /v1/filters/validate reports the same position over REST.

// 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), in_subnet (CIDR)\nsee docs/filter-dsl.md for fields, values, and diagnostic aliases",
  "position": 6,
  "total_matched": null,
  "total_dialogs": 2,
  "capture_identity": { "node": "capture-01", "instance": "cc2cb18df0ea68adfb9c9-2",
                        "dialog_generation": 13, "stream_generation": 2 },
  "source_exhausted": true,
  "source_stopped_early": false
}

On a parse failure total_matched is null, not 0. Once the expression parses, total_matched counts every matching dialog in the 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,
  "position": null,
  "total_matched": 1,
  "total_dialogs": 2,
  "capture_identity": { "node": "capture-01", "instance": "cc2cb18df0ea68adfb9c9-2",
                        "dialog_generation": 13, "stream_generation": 2 },
  "source_exhausted": true,
  "source_stopped_early": false
}

Read total_dialogs beside total_matched. It is the number of dialogs in the store, returned even on a parse failure: 0 matches out of 0 dialogs is an empty capture, and 0 out of 4000 is an expression that selects nothing.

Aliases expand here as they do in every other tool, and this tool uses the same filter compiler, so list_dialogs accepts an expression that validates here. The response carries no provenance note, because it contains nothing read from the capture.

list_named_filters

Lists the named filters the operator defined in the config file's [filters] table: each name and its definition as written. It takes no arguments and reads no dialog. The answer is the one GET /v1/filters serializes.

Every tool that takes filter also takes named: the name of one entry, or of a diagnostic alias, in place of filter. named: "lab-failed" selects what filter: "@lab-failed" selects, and sipnab accepts a leading @. The tools are list_dialogs, aggregate_dialogs, find_problems, search_by_time, group_dialogs, top_talkers and export_vcon.

Prerequisites. A config file with a [filters] table, passed with --config to the run that serves MCP. sipnab reads the table when it starts, and a name saved with F2 in the terminal UI of the same run joins it at once. Nothing changes on any other system.

Steps. With this sipnab.toml:

[filters]
lab-net    = "src.ip in_subnet '192.0.2.0/24'"
lab-failed = "@lab-net AND state == 'Failed'"

serve MCP over tests/pcap-samples/sip-problem-call.pcap with sipnab -N -I tests/pcap-samples/sip-problem-call.pcap --config sipnab.toml --mcp, then call:

// list_named_filters {}
{
  "schema_version": 1,
  "filters": [
    { "name": "lab-failed", "definition": "@lab-net AND state == 'Failed'" },
    { "name": "lab-net", "definition": "src.ip in_subnet '192.0.2.0/24'" }
  ]
}

Verify. list_dialogs { "named": "lab-failed" } returns the two failed calls from 192.0.2.0/24, [email protected] and [email protected], the dialogs filter: "@lab-failed" returns.

Troubleshoot.

  • invalid_choice on named. No entry or alias has that name. The message lists the defined names, and data.valid_values carries every name named accepts, the [filters] names first:

    {"param": "named", "reason": "invalid_choice", "valid_values": ["lab-failed", "lab-net", "problems", "slow-setup", "short-calls", "one-way", "nat-issues", "codec-asym", "ptime-asym", "payload-asym", "duration-asym", "late-media"]}
  • conflicting_params. The call gave filter and named together. Give one, or write the name into the expression as @name.

  • An empty filters list. The run read no [filters] table: check the --config path.

tail_dialogs

Incremental fetch of the dialogs updated after a cursor position.

Name Type Legal values If omitted
cursor? string? The previous response's next_cursor, verbatim (v2:<N>). A version-1 cursor (<RFC 3339> or <RFC 3339>|<Call-ID>) also parses, and returns dialogs whose updated_at is after it. Starts from the beginning of the store.
limit? u32? Ceiling is --mcp-max-rows (1000 by default). Higher clamps to it, 0 means the default. 50 rows.
fields? string[]? Field names to keep on each row, plus call_id. Same rules as list_dialogs — see Narrowing a row with fields. The whole row.
max_response_bytes? u64? Bytes for the whole response. Ceiling is --mcp-max-response-bytes (1048576 unless the operator changed it). Higher clamps to it, 0 means the ceiling. Past it the page ends early at a whole row with truncated_by: "bytes" — see Rules every tool follows. The ceiling.

Returns { dialogs, next_cursor, source_exhausted, source_stopped_early, capture_identity }, where dialogs holds the same summary rows list_dialogs returns, fencing included. The page carries no returned or total_matched, because the store can change between polls. Poll until dialogs comes back empty and source_exhausted is true.

truncated and truncated_by appear only when the byte budget cut the page: truncated: true and truncated_by: "bytes". A tail page cut by limit says nothing extra, because its next_cursor already names the last row returned and the next poll continues from there either way.

next_cursor is v2:<N>: the number of the last change on the page. The store numbers every message it processes for a dialog, one above the last, and the page holds the dialogs changed after the cursor, in the order they changed. A dialog that changes after the cursor comes back, even when its new message carries a timestamp older than every row the cursor saw, as on an -I set whose files overlap in time. Each number belongs to one change of one dialog, so a page boundary neither skips nor repeats a dialog.

Pass it back unmodified. A version-1 cursor, <RFC 3339>|<Call-ID> or a bare timestamp, from an earlier sipnab still parses: it selects dialogs whose updated_at is after it, and the page hands back a v2: cursor. A v2: cursor without a whole number, or a version this sipnab does not read (v3:1), is invalid_params. See Follow changes with a tail cursor.

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",
      "latest_message_at": "2016-11-26T14:53:08.170676+00:00",
      "earliest_message_at": "2016-11-26T14:52:59.666393+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.170676Z|[email protected]",
  "source_exhausted": true,
  "source_stopped_early": false,
  "capture_identity": {
    "node": "capture-01",
    "instance": "12a32e18df006489ac025b-2",
    "dialog_generation": 13,
    "stream_generation": 2
  }
}

await_condition

Waits until a filter selects at least one dialog, or until a deadline passes — whichever happens first. Use it on a live capture instead of a tail_dialogs polling loop: one call covers the whole wait.

Name Type Legal values If omitted
filter string A named alias or a filter DSL expression, exactly what list_dialogs accepts. validate_filter checks one without waiting. Required — the call fails.
timeout_seconds? u32? Ceiling is --mcp-max-wait-seconds (60 by default). Higher clamps to it and sets timeout_clamped. 0 means "look once and answer". 30 seconds.
poll_interval_ms? u32? Floor is 100 ms. sipnab raises anything smaller and returns the effective value. 500 ms.

Returns { schema_version, filter, matched, stopped_because, dialogs, returned, total_matched, truncated, elapsed_ms, timeout_seconds, timeout_clamped, poll_interval_ms, polls, scans, source_exhausted, source_stopped_early, 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. The tool returns at most 50 rows, or --mcp-max-rows when the operator set that lower. total_matched and truncated say whether more dialogs matched. To page through every match, call list_dialogs with the same filter.

A deadline that passes is a successful call, carrying matched: false, not an error.

stopped_because names which of three endings this was. The two negative ones tell you whether asking again can help:

Value matched Meaning
condition_met true The filter selected at least one dialog
deadline false The wait ran out. Not yet — asking again may still find it
source_exhausted false The capture source drained, so this capture cannot produce a match. The wait returns at once rather than running to the deadline

The limits this tool applies:

  • Deadline without timeout_seconds: 30 seconds.
  • Deadline ceiling: 60 seconds. Change it with --mcp-max-wait-seconds on the server command line. sipnab clamps a request above the ceiling instead of refusing it, and the response says timeout_clamped: true.
  • Poll interval without poll_interval_ms: 500 ms.
  • Poll interval floor: 100 ms. sipnab raises a smaller request to 100, and the response carries the value used.

For example, { "filter": "state == Failed", "timeout_seconds": 100, "poll_interval_ms": 10 } against a server with the default ceiling answers "timeout_seconds": 60, "timeout_clamped": true and "poll_interval_ms": 100.

polls counts the looks and scans counts the looks that ran the filter. A look at a capture that has not changed since the last one skips the filter, so scans can be lower than polls.

A waiting call holds one of the --mcp-max-concurrent slots until it returns, and nothing it allocates outlives it.

The example runs against tests/pcap-samples/sip-problem-call.pcap, which holds four failed calls:

// await_condition { "filter": "state == Failed", "timeout_seconds": 20 }
{
  "capture_identity": {
    "dialog_generation": 26,
    "instance": "768de18dfa973fb11e443-2",
    "node": "capture-01",
    "stream_generation": 0
  },
  "dialogs": [
    {
      "call_id": "[email protected]",
      "created_at": "2023-11-14T22:13:23+00:00",
      "duration_sec": 1.81,
      "earliest_message_at": "2023-11-14T22:13:23+00:00",
      "final_status_code": 486,
      "frame": "tests/pcap-samples/sip-problem-call.pcap#5@884d4525ec86f71b",
      "from_user": "⟦untrusted-capture-data⟧carol⟦/untrusted-capture-data⟧",
      "input_origin": "wire",
      "latest_message_at": "2023-11-14T22:13:24.810+00:00",
      "method": "INVITE",
      "msg_count": 4,
      "state": "Failed",
      "timing": {
        "duration_ms": null,
        "pdd_ms": null,
        "retransmits": 0,
        "setup_ms": null
      },
      "to_user": "⟦untrusted-capture-data⟧dave⟦/untrusted-capture-data⟧",
      "updated_at": "2023-11-14T22:13:24.810+00:00"
    },
    {
      "call_id": "[email protected]",
      "created_at": "2023-11-14T22:13:26+00:00",
      "duration_sec": 1.81,
      "earliest_message_at": "2023-11-14T22:13:26+00:00",
      "final_status_code": 603,
      "frame": "tests/pcap-samples/sip-problem-call.pcap#9@4201862d9613e2f2",
      "from_user": "⟦untrusted-capture-data⟧erin⟦/untrusted-capture-data⟧",
      "input_origin": "wire",
      "latest_message_at": "2023-11-14T22:13:27.810+00:00",
      "method": "INVITE",
      "msg_count": 4,
      "state": "Failed",
      "timing": {
        "duration_ms": null,
        "pdd_ms": null,
        "retransmits": 0,
        "setup_ms": null
      },
      "to_user": "⟦untrusted-capture-data⟧frank⟦/untrusted-capture-data⟧",
      "updated_at": "2023-11-14T22:13:27.810+00:00"
    },
    {
      "call_id": "[email protected]",
      "created_at": "2023-11-14T22:13:29+00:00",
      "duration_sec": 1.81,
      "earliest_message_at": "2023-11-14T22:13:29+00:00",
      "final_status_code": 404,
      "frame": "tests/pcap-samples/sip-problem-call.pcap#13@091b886751922950",
      "from_user": "⟦untrusted-capture-data⟧grace⟦/untrusted-capture-data⟧",
      "input_origin": "wire",
      "latest_message_at": "2023-11-14T22:13:30.810+00:00",
      "method": "INVITE",
      "msg_count": 4,
      "state": "Failed",
      "timing": {
        "duration_ms": null,
        "pdd_ms": null,
        "retransmits": 0,
        "setup_ms": null
      },
      "to_user": "⟦untrusted-capture-data⟧heidi⟦/untrusted-capture-data⟧",
      "updated_at": "2023-11-14T22:13:30.810+00:00"
    },
    {
      "call_id": "[email protected]",
      "created_at": "2023-11-14T22:13:32+00:00",
      "duration_sec": 1.81,
      "earliest_message_at": "2023-11-14T22:13:32+00:00",
      "final_status_code": 503,
      "frame": "tests/pcap-samples/sip-problem-call.pcap#17@cc2aeb6bbdcb704c",
      "from_user": "⟦untrusted-capture-data⟧ivan⟦/untrusted-capture-data⟧",
      "input_origin": "wire",
      "latest_message_at": "2023-11-14T22:13:33.810+00:00",
      "method": "INVITE",
      "msg_count": 4,
      "state": "Failed",
      "timing": {
        "duration_ms": null,
        "pdd_ms": null,
        "retransmits": 0,
        "setup_ms": null
      },
      "to_user": "⟦untrusted-capture-data⟧judy⟦/untrusted-capture-data⟧",
      "updated_at": "2023-11-14T22:13:33.810+00:00"
    }
  ],
  "elapsed_ms": 0,
  "filter": "state == Failed",
  "matched": true,
  "poll_interval_ms": 500,
  "polls": 1,
  "returned": 4,
  "scans": 1,
  "schema_version": 1,
  "source_exhausted": true,
  "source_stopped_early": false,
  "stopped_because": "condition_met",
  "timeout_clamped": false,
  "timeout_seconds": 20,
  "total_matched": 4,
  "truncated": false
}

Against tests/pcap-samples/sip-rtp-g711.pcap, whose one call completed, the same filter returns at once with "matched": false and "stopped_because": "source_exhausted".

find_correlated

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

Name Type Legal values If omitted
call_id string A Call-ID the store holds — the leg to correlate from. A Call-ID the store does not hold fails with a message such as call_id '[email protected]' not found. Required — the call fails.
limit? u32? Ceiling is --mcp-max-rows (1000 by default). Higher clamps to it, 0 means the default. 50 legs.

Returns source_call_id, legs, total_matched, heuristic_only, capture_identity, timing_clock, source_exhausted, source_stopped_early and schema_version. An unknown call_id fails with invalid_params (call_id 'nope' not found, data.reason: "not_found"), the answer REST's /correlated route gives as 404 and --correlate as exit 1. A call with no related legs answers with an empty legs array and total_matched: 0, not an error. There is no cursor: when total_matched is larger than the legs returned, raise limit, up to --mcp-max-rows.

The example runs against tests/fixtures/th-callid/opensips-4.0-default.pcap, three calls one second apart through OpenSIPS topology_hiding("C"). OpenSIPS gives each callee leg a new Call-ID and passes the SDP through, so the first leg is the call's own callee leg, tied by its SDP origin. The other four are the two later calls, tied by timing alone:

// find_correlated { "call_id": "[email protected]" }
{
  "schema_version": 1,
  "source_call_id": "[email protected]",
  "legs": [
    { "call_id": "DLGCH_fl0RBn4qMT8jMAAWMiQgPypeBgE+", "score": 90, "strategy": "sdp_origin",
      "method": "sdp", "identifier_match": true, "observed_gap_ms": null,
      "th_callid": "no_secret" },
    { "call_id": "[email protected]", "score": 50, "strategy": "timing_heuristic",
      "method": "timing", "identifier_match": false, "observed_gap_ms": 999,
      "th_callid": null },
    { "call_id": "DLGCH_fV0RBn4qMT8jMAAWMiQgPypeBgE+", "score": 50, "strategy": "timing_heuristic",
      "method": "timing", "identifier_match": false, "observed_gap_ms": 1000,
      "th_callid": "no_secret" },
    { "call_id": "[email protected]", "score": 50, "strategy": "timing_heuristic",
      "method": "timing", "identifier_match": false, "observed_gap_ms": 1999,
      "th_callid": null },
    { "call_id": "DLGCH_fF0RBn4qMT8jMAAWMiQgPypeBgE+", "score": 50, "strategy": "timing_heuristic",
      "method": "timing", "identifier_match": false, "observed_gap_ms": 2000,
      "th_callid": "no_secret" }
  ],
  "total_matched": 5,
  "heuristic_only": false,
  "th_callid": null,                // set only for an OpenSIPS topology-hiding leg
  "capture_identity": {
    "node": "capture-01",
    "instance": "35da4818e6038418739747-2",
    "dialog_generation": 39,
    "stream_generation": 0
  },
  "timing_clock": {                 // non-null only when a timing_heuristic leg is returned
    "available": true,
    "synchronized": true,
    "est_error_us": 0,
    "max_error_us": 1855500
  },
  "source_exhausted": true,
  "source_stopped_early": false
}

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

strategy What it means Survives a B2BUA?
session_id RFC 7989 Session-ID matched Yes, by design
x_call_id A configured header matched (none configured by default) Only if the SBC inserts it
charging_vector_related_icid One leg's RFC 7315 related-icid names the other's icid-value Yes — but only when the B2BUA chose to emit it (MAY)
th_callid_decoded One leg's OpenSIPS topology_hiding("C") Call-ID decodes, with the configured secret, to the other leg's Call-ID, and the From tags match (Calls through topology hiding) Yes, for OpenSIPS with the secret configured
th_callid_mapping The OpenSIPS script named both Call-IDs in an E_SIPNAB_TH_MAP event Yes, for OpenSIPS with the script change
sdp_origin The RFC 8866 SDP origin tuple matched, the two legs were open at one time, and no two calls in the store used the origin on one hop at once (When an SDP origin counts) Only if the SBC forwards SDP untouched
charging_vector_icid Both legs carry the same RFC 7315 icid-value Not by design: an ICID identifies one dialog, and a B2BUA is two
via_branch Two INVITEs shared a Via branch No: a new transaction gets a new branch
timing_heuristic Same endpoint, close in time Not an identifier at all

The two P-Charging-Vector rows read one header in two ways. 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 finds no match across it. A charging_vector_icid match means an intermediary copied one dialog's identifier onto a second dialog. The parameter that links the two sides of a hop is related-icid (RFC 7315 section 4.6.4.1), and it is optional.

Two limits apply to both:

  • 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.
  • 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.

The design record is docs/design/icid-correlation.md.

Neither strategy puts the matched ICID in the response, because RFC 7315 section 4.6's suggested construction embeds the generating proxy's hostname or address in it.

method groups the strategies by what sipnab compared the legs on:

  • mapping is th_callid_mapping.
  • decoded is th_callid_decoded.
  • mapping is th_callid_mapping: an OpenSIPS E_SIPNAB_TH_MAP event named both legs.
  • header is session_id, x_call_id, both charging-vector strategies and via_branch.
  • sdp is sdp_origin.
  • timing is timing_heuristic.

th_callid has a value only for the callee-side leg of an OpenSIPS topology_hiding("C") call: decoded, no_secret, undecodable, unmatched, mapped or conflict, as Calls through topology hiding explains. The top-level th_callid describes the source, and each leg's th_callid describes that leg. get_call_tree carries the same per-leg th_callid.

identifier_match is true when the leg matched on a value both legs carry, and false for timing_heuristic. sipnab does not report a shared SDP origin that the rule above refuses as sdp_origin: SIPp and some endpoints write one origin into every call, so the next strategy that matches the leg reports it, at that strategy's strength, or none does. heuristic_only is true when every returned leg came from timing_heuristic: treat such a set of legs as a hypothesis to confirm, not a finding.

observed_gap_ms carries a number only for timing_heuristic legs, and null on an identifier match. Read it with the leg's score: a 15 ms gap and a 1,900 ms gap can score the same.

When the legs carry no correlation header, timing_heuristic is the only strategy that can link them, and on a busy SBC unrelated calls can share an endpoint inside its window.

get_call_tree

Every leg of one call, as a tree.

Use it for a call that crosses an SBC, a PBX or a B2BUA, where one call is several dialogs. find_correlated answers one hop from one Call-ID, and get_dialog returns one leg. get_call_tree follows the correlations from any leg and returns every leg it reaches, the same set the TUI's extended call flow (the x key) shows.

Name Type Legal values If omitted
call_id string Any leg of the call. The walk is symmetric, so naming the B-leg returns the same set rooted differently. A Call-ID the store does not hold fails with a message such as call_id '[email protected]' not found. Required — the call fails.
limit? u32? Maximum legs including the root. Ceiling is --mcp-max-rows (1000 by default), higher clamps to it, 0 means the default. 50 legs.

The example runs against tests/fixtures/th-callid/opensips-4.0-default.pcap, the capture in the find_correlated example, with each leg's dialog summary trimmed to its first three keys. The walk follows the callee leg, and not the four timing guesses:

// 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,
      "method": null,
      "identifier_match": null,
      "followed": true,
      "th_callid": null,
      "dialog": { "call_id": "[email protected]", "state": "Completed", "method": "INVITE" }
    },\n    {
      "call_id": "DLGCH_fl0RBn4qMT8jMAAWMiQgPypeBgE+",
      "depth": 1,
      "parent_call_id": "[email protected]",
      "score": 90,
      "strategy": "sdp_origin",
      "method": "sdp",
      "identifier_match": true,
      "followed": true,
      "th_callid": "no_secret",
      "dialog": { "call_id": "DLGCH_fl0RBn4qMT8jMAAWMiQgPypeBgE+", "state": "Completed", "method": "INVITE" }
    },\n    {
      "call_id": "[email protected]",
      "depth": 1,
      "parent_call_id": "[email protected]",
      "score": 50,
      "strategy": "timing_heuristic",
      "method": "timing",
      "identifier_match": false,
      "followed": false,
      "th_callid": null,
      "dialog": { "call_id": "[email protected]", "state": "Completed", "method": "INVITE" }
    },\n    {
      "call_id": "DLGCH_fV0RBn4qMT8jMAAWMiQgPypeBgE+",
      "depth": 1,
      "parent_call_id": "[email protected]",
      "score": 50,
      "strategy": "timing_heuristic",
      "method": "timing",
      "identifier_match": false,
      "followed": false,
      "th_callid": "no_secret",
      "dialog": { "call_id": "DLGCH_fV0RBn4qMT8jMAAWMiQgPypeBgE+", "state": "Completed", "method": "INVITE" }
    },\n    {
      "call_id": "[email protected]",
      "depth": 1,
      "parent_call_id": "[email protected]",
      "score": 50,
      "strategy": "timing_heuristic",
      "method": "timing",
      "identifier_match": false,
      "followed": false,
      "th_callid": null,
      "dialog": { "call_id": "[email protected]", "state": "Completed", "method": "INVITE" }
    },\n    {
      "call_id": "DLGCH_fF0RBn4qMT8jMAAWMiQgPypeBgE+",
      "depth": 1,
      "parent_call_id": "[email protected]",
      "score": 50,
      "strategy": "timing_heuristic",
      "method": "timing",
      "identifier_match": false,
      "followed": false,
      "th_callid": "no_secret",
      "dialog": { "call_id": "DLGCH_fF0RBn4qMT8jMAAWMiQgPypeBgE+", "state": "Completed", "method": "INVITE" }
    }
  ],
  "total_legs": 6,
  "max_depth": 1,
  "truncated": false,
  "heuristic_edges": 4,
  "total_messages": 39,
  "first_activity": "2026-11-03T03:16:48.435806+00:00",
  "last_activity": "2026-11-03T03:16:50.943827+00:00",
  "source_exhausted": true,
  "source_stopped_early": false,
  "capture_identity": { "node": "capture-01", "instance": "35dad618e6038581effeae-2",
                        "dialog_generation": 39, "stream_generation": 0 }
}

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 does not expand timing_heuristic edges. It follows the six strategies that compare a value both legs carry. timing_heuristic links two INVITE dialogs that share an endpoint address and started inside the leg-correlation window, and on a busy proxy that links unrelated calls. A timing edge still appears in legs with followed: false. To follow it, call get_call_tree again rooted at that leg.

Read followed before you read the shape. A leg with followed: false is one the walk did not expand: either a timing_heuristic edge, or a leg still queued when limit stopped the walk. truncated: true says limit stopped the walk.

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 (call_id 'nope' not found, data.reason: "not_found"). A dialog with no other legs comes back as a one-leg tree with total_legs: 1 and max_depth: 0.

th_mappings

The OpenSIPS topology-hiding mappings sipnab holds, one row per mapping, from the E_SIPNAB_TH_MAP events its HEP listener accepted. Use it to find why one call through topology_hiding("C") did not join its caller leg: find_correlated says THAT a leg is conflict or did not join, and this says which mapping and which leg. Exists in a build with the hep feature.

Name Type Legal values If omitted
call_id? string? A Call-ID, either leg. The answer holds only the mapping that names it. Every mapping.
state? string? conflict, pending or joined. Any other word fails with a message naming the three. Every state.
limit? u32? Maximum rows. Ceiling is --mcp-max-rows, higher clamps to it, 0 means the default. 50 rows.
// th_mappings { "call_id": "DLGCH_fl0RBn4kMSMPFR0PPjk8NmETCgM-" }
{
  "call_id": "DLGCH_fl0RBn4kMSMPFR0PPjk8NmETCgM-",
  "capture_identity": { "dialog_generation": 6, "instance": "1f4a17c8e2b91d40-1",
                        "node": "capture-01", "stream_generation": 0 },
  "counts": { "accepted": 3, "conflict": 0, "duplicate": 0, "expired": 0,
              "held": 3, "malformed": 0, "pending": 0, "refused_full": 0 },
  "mappings": [
    { "callee_call_id": "DLGCH_fl0RBn4kMSMPFR0PPjk8NmETCgM-",
      "callee_captured": true, "caller_call_id": "[email protected]",
      "caller_captured": true, "state": "joined" }
  ],
  "schema_version": 1,
  "state": null,
  "th_callid": { "conflict": 0, "decoded": 0, "mapped": 3, "no_secret": 0,
                 "undecodable": 0, "undecoded_with_peer": 0, "unmatched": 0 },
  "total_matched": 1,
  "source_exhausted": false,
  "source_stopped_early": false
}

state is one of three values:

  • joined: sipnab captured both legs, and the mapping joins them.
  • pending: sipnab has not captured a leg yet. caller_captured and callee_captured say which.
  • conflict: another event named one of its Call-IDs with a different partner, so the mapping joins nothing.

Rows come conflicts first, then pending, then joined. No row for a Call-ID means no event named it.

counts is the th_mappings object capture_status returns, and th_callid its th_callid object. The Call-IDs came off the wire, so the response carries the untrusted-content note. GET /v1/th-mappings returns the same fields and values, and --th-mappings prints them at the end of a headless run. Find why a call through topology hiding did not join walks through reading it.

compare_dialogs

"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"],
  "capture_identity": { "node": "capture-01", "instance": "cc2cb18df0ea68adfb9c9-2",
                        "dialog_generation": 13, "stream_generation": 2 }
}

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

Diagnose one call

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.

get_dialog_report

Per-call diagnostic report for one Call-ID, with the same content as sipnab -N --call-report <Call-ID>.

Name Type Legal values If omitted
call_id string A Call-ID the store holds. An unknown one fails with invalid_params (-32602) naming the value. Required — the call fails.
format? string? "json", "markdown" or "text". Anything else fails with unknown format 'x', expected json|markdown|text. "json".

"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, and capture_identity, which names the capture the report came from.

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",
  "input_origin": "wire",
  "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,
    "private_media_address": false
  },
  "termination": {
    "cause_code": 16,
    "cause_text": "NORMAL_CLEARING",
    "frame_ref": 4,
    "protocol": "Q.850",
    "source_header": "Reason"
  },
  "sdp_timeline": [ /* the same rows get_sdp_timeline returns */ ],
  "streams": [ /* the same rows rtp_stats returns, without mos */ ],
  "capture_identity": { "node": "capture-01", "instance": "cc2cb18df0ea68adfb9c9-2",
                        "dialog_generation": 13, "stream_generation": 2 },
  "source_exhausted": true,
  "source_stopped_early": false
}

termination says why the call ended, when a message on the wire named a cause: here the BYE carries a Reason header with Q.850 cause 16. It is the same object triage_call documents on the core bundle page. When nothing on the wire named a cause, the key is absent, not null.

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. The trailing provenance note says which values in the report came from the capture, so treat those as text the sender wrote.

get_message

Single SIP message at a given zero-based index.

Name Type Legal values If omitted
call_id string A Call-ID the store holds. Required — the call fails.
index u32 0 to msg_count - 1 for that dialog. Required — the call fails.

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 reports each page's first_index, so the Nth row of that page sits at first_index + N, and every lint_dialog finding reports the message_index it fired on.

An index at or past the end fails with invalid_params, and the message carries the dialog's message count: index 99 out of range for dialog with 6 messages.

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, has_sdp and timestamps verbatim so they pass into the next call.

// get_message { "call_id": "[email protected]", "index": 0 }
{
  "call_id": "[email protected]",
  "capture_identity": {
    "dialog_generation": 13,
    "instance": "145e7218e1f87297474f48-2",
    "node": "capture-01",
    "stream_generation": 2
  },
  "contact": "⟦untrusted-capture-data⟧sip:[email protected]:5060⟦/untrusted-capture-data⟧",
  "cseq": {
    "method": "INVITE",
    "number": 1
  },
  "dscp": 0,
  "dst": "10.0.2.15",
  "dst_port": 5060,
  "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⟧"
  ],
  "frame": "tests/pcap-samples/sip-rtp-g711.pcap#0@db88659b94678546",
  "from": "⟦untrusted-capture-data⟧\"PCMU/8000\" <sip:[email protected]:5060>;tag=1⟦/untrusted-capture-data⟧",
  "has_sdp": true,
  "input_origin": "wire",
  "is_request": true,
  "method": "INVITE",
  "schema_version": 1,
  "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⟧",
  "source_exhausted": true,
  "source_stopped_early": false,
  "src": "10.0.2.20",
  "src_port": 5060,
  "timestamp": "2016-11-26T14:52:59.666393+00:00",
  "to": "⟦untrusted-capture-data⟧test <sip:[email protected]:5060>⟦/untrusted-capture-data⟧",
  "transport": "UDP"
}

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

extension_headers

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

Read it for vendor-, carrier- and SBC-specific headers that have no named field: X-Asterisk-*, Reason, Diversion, P-Asserted-Identity, Remote-Party-ID, Require, RSeq.

Six header names never appear here, because they are already fields of their own: Call-ID, From, To, Contact, User-Agent and CSeq. The list holds every other header line, Via and Content-Length included.

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. The sender chose the header name as well as the value, so the marker pair wraps the entire Name: value string. The threat model for this text is in deferred-and-declined.md.

The list has the parser's bounds: sipnab refuses a message with more than 200 headers or a header line longer than 8 KiB.

render_ladder

Call-flow ladder for one Call-ID.

Name Type Legal values If omitted
call_id string A Call-ID the store holds. Required — the call fails.
format? string? "markdown", "text" or "mermaid". Anything else, "json" included, fails with unknown format 'x', expected markdown|text|mermaid. "markdown".

Returns one text content block holding the rendered report, and the provenance note as a second block.

"mermaid" returns a Mermaid sequenceDiagram of the call instead, fenced as untrusted text. Each arrow carries a Note with what the ladder knows about that message: its offset from the first message (+0.500s), PDD <n>ms on the first 180, the SDP change against the call's previous SDP (+G722, −PCMU, HOLD, UNHOLD) and retransmission. IPv6 endpoints carry brackets ([2001:db8::1]:5060). The browser analyzer draws the same rows, and the SDP change badges match the TUI ladder's. 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]" }

To get the same report from the command line, add --no-cli-print, which leaves out the per-message dump the CLI otherwise writes first:

sipnab -N -I tests/pcap-samples/sip-rtp-g711.pcap --call-report [email protected] --markdown --no-cli-print

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 block does not change the ladder above it.

# Call Report: [email protected]

## Summary

| Field | Value |
|-------|-------|
| Time | 2016-11-26 14:52:59 -> 14:53:08 (8s) |
| From | sipp |
| To | test |
| State | Completed |
| Cause | Q.850 cause 16 "NORMAL_CLEARING" [Reason] |

## Timing

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

## Media Streams

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

## Issues

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

get_sdp_timeline

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. event is null unless the exchange changed something relative to the same party's previous SDP (Hold, Resume, CodecChange, T38Switch or MediaAnchorChange), or is a REFER (Transfer). sipnab compares an answer with the answering party's own earlier SDP, not with the offer, so the answer below records no event although its address differs from the offer's. 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]",
  "capture_identity": { "node": "capture-01", "instance": "cc2cb18df0ea68adfb9c9-2",
                        "dialog_generation": 13, "stream_generation": 2 },
  "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": null,
      "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.

check_codec_negotiation

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, capture_identity, source_exhausted, source_stopped_early and schema_version. Each codec name in offered, answered and common arrives fenced, because the sender wrote it in the SDP.

// check_codec_negotiation { "call_id": "[email protected]" }
{
  "schema_version": 1,
  "call_id": "[email protected]",
  "offered": ["⟦untrusted-capture-data⟧PCMU⟦/untrusted-capture-data⟧"],
  "answered": ["⟦untrusted-capture-data⟧PCMU⟦/untrusted-capture-data⟧",
               "⟦untrusted-capture-data⟧telephone-event⟦/untrusted-capture-data⟧"],
  "common": ["⟦untrusted-capture-data⟧PCMU⟦/untrusted-capture-data⟧"],
  "result": "ok",
  "final_status_code": 200,
  "sdp_exchange_count": 2,
  "capture_identity": { "node": "capture-01", "instance": "cc2cb18df0ea68adfb9c9-2",
                        "dialog_generation": 13, "stream_generation": 2 },
  "source_exhausted": true,
  "source_stopped_early": false
}

result has five values:

Result Meaning What to do
ok The two sides agreed Codecs are not your problem
no_common_codec Both offered codecs, none shared A codec policy problem — compare the lists
no_answer An offer went out, nothing came back The call did not get far enough to negotiate
sdp_present_but_no_codecs Both sides exchanged SDP, but neither listed a codec Look at the SDP itself — a malformed or media-less m= line
no_sdp_in_capture No SDP at all Not a codec problem. Hold with inactive media, or a reject before any offer

no_answer means the capture holds an SDP offer and no answer to it. no_sdp_in_capture means the capture holds no SDP offer, so there is no answer to look for.

Conformance and rules

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".

lint_dialog

Checks one call against the RFCs. Use it when the question is whether the traffic obeys the specification. Use triage_call when the question is why a call failed. A call can complete over messages that break four MUSTs, and a fully conformant call can end busy.

The observation rules (OBS-) compare what the SDP declared with the media the capture holds. They report, for example, 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.

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.

Name Type Legal values If omitted
call_id string A Call-ID the store holds. Required — the call fails.
rulesets? string[]? The 16 selectors below, OR-ed together. An unknown one fails with invalid_params listing all 16. The whole catalog, reported back as rulesets: ["all"].
severity_min? string? info, notice, warning or error. Anything else fails with unknown severity 'x'. Valid values: info, notice, warning, error. info, so the floor drops nothing.
suppression_file? string? A bare filename inside --mcp-file-root. A file sipnab cannot open fails with invalid_params rather than linting with every rule on. sipnab walks for a .sipnablint beside the capture and upward to the project root.

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, rfc7587, rfc7989.

An unknown selector fails with invalid_params (-32602) naming the whole vocabulary:

unknown ruleset 'rfc3621'. Valid selectors: all, must, rfc, interop, observation, syntax, observed, rfc3261, rfc3262, rfc3264, rfc3551, rfc4028, rfc4566, rfc5761, rfc7587, rfc7989

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"] }
{
  "call_id": "[email protected]:5060",
  "capture_identity": {
    "dialog_generation": 64,
    "instance": "7771d18dfa97985500250-2",
    "node": "capture-01",
    "stream_generation": 2
  },
  "finding_count": 1,
  "findings": [
    {
      "basis": "observation",
      "expected": "media in both directions, as a=sendrecv promised",
      "explanation": "§6.1 makes sendrecv a promise to send as well as receive. One endpoint kept it and the other did not, which the far end hears as dead air on an answered call. The usual causes are a NAT with no inbound pinhole, a firewall dropping the return path, and an endpoint that answered sendrecv while muting locally.",
      "frame_ref": "tests/pcap-samples/b2bua-asterisk.pcapng#23@08cb2267de5498ce",
      "message_index": 0,
      "observed": "⟦untrusted-capture-data⟧355 RTP packets observed, none of them toward one negotiated endpoint⟦/untrusted-capture-data⟧",
      "rfc": 3264,
      "rule_id": "OBS-3264-6.1-DIRECTION-UNMET",
      "section": "6.1",
      "severity": "warning"
    }
  ],
  "findings_withheld": {
    "below_severity": 0,
    "capped": 0,
    "suppressed": 0
  },
  "message_count": 15,
  "rtp_streams_observed": 1,
  "rule_catalog": "docs/sip-lint-rules.md",
  "rules_not_evaluated": [
    {
      "reason": "needs the endpoint pairs RTCP arrived on. The stream store folds RTCP into the stream it reports on and keeps no record of where it landed, so no MCP tool can raise this rule.",
      "rule_ids": [
        "OBS-5761-5.1.1-RTCP-MUX-UNANSWERED"
      ]
    }
  ],
  "rulesets": [
    "observed"
  ],
  "schema_version": 1,
  "severity_counts": {
    "error": 0,
    "info": 0,
    "notice": 0,
    "warning": 1
  },
  "severity_min": "info",
  "source_exhausted": true,
  "source_stopped_early": false,
  "suppressions": {
    "file": null,
    "findings_suppressed": 0,
    "patterns": []
  }
}

To use a finding:

  • Cite rfc and section rather than the prose of explanation, for example RFC 3264 section 6.1. explain_rule turns a rule_id back into the citation and the link.
  • Pass frame_ref to show_evidence to read the bytes of the frame the rule fired on.
  • Treat observed as capture text. It quotes the capture and arrives fenced. expected and explanation are sipnab's own words and arrive unfenced.

rules_not_evaluated names the rules that did not run, grouped by reason, so an empty findings list is not read as a pass for those rules. 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, which the MCP server does not record, so no MCP tool raises this rule.

Suppression, and what it must tell you

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 — uses only a .sipnablint in its own directory. suppression_file replaces the search, and a file it names that sipnab cannot open fails with invalid_params instead of linting with every rule on.

Two response fields report what suppression and filtering left out. 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 }

Each count points at a different cause:

  • suppressed: a pattern in the .sipnablint file that suppressions.file names. Edit that file, or pass another suppression_file.
  • below_severity: your severity_min. Lower it to see them.
  • capped: the per-rule cap of 25 findings.

suppressed and below_severity are exact counts. capped is a lower bound, because a rule can stop evaluating once it reaches the cap.

validate_message

Runs the same rules against one message, named by its zero-based index. Use it to confirm a finding on one message, for example in a CI job or when discussing one header with a vendor. lint_dialog reports message_index on every finding, which is the index this tool takes.

Name Type Legal values If omitted
call_id string A Call-ID the store holds. Required — the call fails.
index u32 0 to msg_count - 1. Out of range fails with invalid_params (-32602) naming the message count. Required — the call fails.
suppression_file? string? A bare filename inside --mcp-file-root, exactly as lint_dialog takes it. Wins outright over the discovery walk. sipnab walks for a .sipnablint beside the capture and upward.

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 }
{
  "call_id": "[email protected]",
  "capture_identity": {
    "dialog_generation": 14,
    "instance": "77d2718dfa97b81aa9e86-2",
    "node": "capture-01",
    "stream_generation": 0
  },
  "finding_count": 2,
  "findings": [
    {
      "basis": "must",
      "expected": "Max-Forwards: 70",
      "explanation": "§8.1.1.6 makes a UAC insert one into every request it originates. Without it a routing loop has nothing to stop it, and RFC 3261 §16.6 leaves each proxy to invent its own starting value.",
      "frame_ref": "tests/pcap-samples/sip-488-codec-reject.pcapng#4@b2b8ff6b3eeddf54",
      "message_index": 0,
      "observed": "⟦untrusted-capture-data⟧no Max-Forwards header field⟦/untrusted-capture-data⟧",
      "rfc": 3261,
      "rule_id": "SIP-3261-8.1.1.6-MAX-FORWARDS-MISSING",
      "section": "8.1.1.6",
      "severity": "warning"
    },
    {
      "basis": "must",
      "expected": "branch=z9hG4bK...",
      "explanation": "§8.1.1.7 makes every compliant branch begin with z9hG4bK, so its absence identifies a stack predating RFC 3261 in one field. Transaction matching then falls back to the RFC 2543 rules, and CANCEL and ACK correlation stop being reliable.",
      "frame_ref": "tests/pcap-samples/sip-488-codec-reject.pcapng#4@b2b8ff6b3eeddf54",
      "message_index": 0,
      "observed": "⟦untrusted-capture-data⟧top Via branch without the z9hG4bK prefix⟦/untrusted-capture-data⟧",
      "rfc": 3261,
      "rule_id": "SIP-3261-8.1.1.7-BRANCH-COOKIE",
      "section": "8.1.1.7",
      "severity": "warning"
    }
  ],
  "findings_withheld": {
    "below_severity": 0,
    "capped": 0,
    "suppressed": 0
  },
  "message_count": 2,
  "message_index": 0,
  "rule_catalog": "docs/sip-lint-rules.md",
  "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",
        "SIP-3261-17.1.1.3-ACK-CSEQ-MISMATCH",
        "SIP-3261-17.1.1.3-ACK-BRANCH-MISMATCH",
        "SIP-3261-12.1.1-RECORD-ROUTE-NOT-COPIED",
        "SIP-3262-4-PRACK-MISSING",
        "SDP-3264-6.1-ANSWER-NO-COMMON-FORMAT",
        "SDP-3264-6.1-ANSWER-EXTRA-FORMAT",
        "SDP-3264-6.1-ANSWER-DIRECTION-ILLEGAL",
        "SDP-3264-8.4-HOLD-CONNECTION-ZERO",
        "SDP-3264-8.3.2-DYNAMIC-PT-REBOUND",
        "SDP-3264-7-TELEPHONE-EVENT-ONE-WAY",
        "SDP-3264-8.2-REJECTED-STREAM-ATTRIBUTES",
        "SDP-7587-7-OPUS-RTPMAP-RATE"
      ]
    },
    {
      "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",
        "OBS-4566-5.14-MEDIA-PORT-MISMATCH",
        "OBS-3264-6.1-DIRECTION-UNMET",
        "OBS-4566-6-PTIME-MISMATCH",
        "OBS-3551-4.2-FRAME-SIZE-IMPOSSIBLE"
      ]
    },
    {
      "reason": "needs the endpoint pairs RTCP arrived on. The stream store folds RTCP into the stream it reports on and keeps no record of where it landed, so no MCP tool can raise this rule.",
      "rule_ids": [
        "OBS-5761-5.1.1-RTCP-MUX-UNANSWERED"
      ]
    }
  ],
  "schema_version": 1,
  "severity_counts": {
    "error": 0,
    "info": 0,
    "notice": 0,
    "warning": 2
  },
  "source_exhausted": true,
  "source_stopped_early": false,
  "suppressions": {
    "file": null,
    "findings_suppressed": 0,
    "patterns": []
  }
}

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, and rules_not_evaluated names them. Run lint_dialog first, and use this tool to confirm one message.

explain_rule

Returns the catalog entry for a rule identifier taken from a finding, a CI log or a suppression file.

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, so a call with any unknown identifier lists the catalog:

'NOPE' is not a rule in the catalog. The 41 rules are: SIP-3261-8.1.1-MANDATORY-HEADER-MISSING, SIP-3261-20.16-CSEQ-MALFORMED, SIP-3261-20.14-CONTENT-LENGTH-MISMATCH, SIP-3261-25.1-HEADER-CONTROL-BYTE, SIP-3261-20-URI-BRACKETS, SIP-3261-19.1.1-URI-PARAM-DEMOTED, SIP-3261-8.1.1.6-MAX-FORWARDS-MISSING, SIP-3261-20.22-MAX-FORWARDS-RANGE, SIP-3261-8.1.1.7-BRANCH-COOKIE, SIP-3261-8.1.1.2-TO-TAG-IN-INITIAL-REQUEST, SIP-3261-8.1.1.5-CSEQ-METHOD-MISMATCH, SIP-3261-17.1.1.3-ACK-CSEQ-MISMATCH, SIP-3261-17.1.1.3-ACK-BRANCH-MISMATCH, SIP-3261-12.1.1-CONTACT-MISSING-IN-2XX, SIP-3261-12.1.1-RECORD-ROUTE-NOT-COPIED, SIP-3261-16.6-RECORD-ROUTE-NOT-LOOSE, SIP-3261-8.1.1.7-VIA-BRANCH-DUPLICATE, SIP-3261-7.3.1-SINGULAR-HEADER-REPEATED, SIP-3262-3-RELIABLE-PROVISIONAL-WITHOUT-RSEQ, SIP-3262-4-PRACK-MISSING, SIP-4028-7.1-SESSION-EXPIRES-BELOW-MIN-SE, SIP-4028-4-SESSION-EXPIRES-TOO-SMALL, SIP-4028-5-MIN-SE-TOO-SMALL, SIP-4028-9-REFRESHER-MISSING, SIP-7989-5-SESSION-ID-MALFORMED, SIP-7989-5-SESSION-ID-UPPERCASE, SIP-7989-11-SESSION-ID-LEGACY-FORM, SDP-3264-6.1-ANSWER-NO-COMMON-FORMAT, SDP-3264-6.1-ANSWER-EXTRA-FORMAT, SDP-3264-6.1-ANSWER-DIRECTION-ILLEGAL, SDP-3264-8.4-HOLD-CONNECTION-ZERO, SDP-3264-8.3.2-DYNAMIC-PT-REBOUND, SDP-3264-7-TELEPHONE-EVENT-ONE-WAY, SDP-3264-8.2-REJECTED-STREAM-ATTRIBUTES, SDP-7587-7-OPUS-RTPMAP-RATE, OBS-3264-6.1-PT-UNDECLARED, OBS-4566-5.14-MEDIA-PORT-MISMATCH, OBS-3264-6.1-DIRECTION-UNMET, OBS-4566-6-PTIME-MISMATCH, OBS-5761-5.1.1-RTCP-MUX-UNANSWERED, OBS-3551-4.2-FRAME-SIZE-IMPOSSIBLE
// 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.html#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.

explain_response_code

The meaning and class of a SIP status code, from the IANA registry.

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 request is waiting for credentials, not refused. registered: false means the code is not in the IANA registry, as with a vendor extension, and the response gives no meaning for it.

Export and handoff

Getting the result out of sipnab and into the next tool, the next team, or a bug report someone else can reproduce.

generate_repro

A SIPp scenario that replays one call, built around your hypothesis of the cause.

pin names the aspects of the captured request you believe caused the outcome, and the scenario copies them byte-for-byte. vary names the identity fields SIPp regenerates per run, so the replay is a new call rather than a retransmission of the captured one. Running the scenario then tests the pinned aspects.

Name Type Legal values If omitted
call_id string A Call-ID the store holds, carrying at least one request. Required — the call fails.
format? string? "sipp", the only one. Anything else fails with unknown format 'x'; 'sipp' is the only one. "sipp".
pin? string[]? Any of branch, call_id, cseq, headers, request_uri, sdp, tags, user_agent. An explicit [] means "nothing", not "the default". Nothing pinned — the scenario tests no theory and the response says so.
vary? string[]? branch, call_id, tags — the three SIPp can regenerate. Anything else from the pin vocabulary fails, naming the three. All three.
filename? string? A bare name in --mcp-file-root to write the scenario to as well. The text comes back either way. The response carries the scenario and nothing touches the disk.
// generate_repro { "call_id": "[email protected]", "pin": ["sdp", "user_agent"] }
{
  "schema_version": 1,
  "call_id": "[email protected]",
  "format": "sipp",
  "hypothesis": {
    "pinned": ["sdp", "user_agent"],
    "varied": ["branch", "call_id", "tags"],
    "generated": ["contact", "content_length", "cseq", "max_forwards", "request_uri", "via"],
    "omitted": ["headers"]
  },
  "asserted": { "provisional": [100], "final": 200 },
  "scenario": "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n<!DOCTYPE scenario SYSTEM \"sipp.dtd\">\n<!-- Generated by sipnab from Call-ID [email protected] -->\n<!-- pinned: sdp user_agent | varied: branch call_id tags -->\n<scenario name=\"sipnab repro [email protected]\">\n  <send retrans=\"500\">\n    <![CDATA[\n\nINVITE sip:test@[remote_ip]:[remote_port] SIP/2.0\nVia: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]\nFrom: <sip:sipp@[local_ip]:[local_port]>;tag=[pid]SIPpTag00[call_number]\nTo: <sip:test@[remote_ip]:[remote_port]>\nCall-ID: [call_id]\nCSeq: 1 INVITE\nContact: <sip:sipp@[local_ip]:[local_port];transport=[transport]>\nMax-Forwards: 70\nContent-Type: application/sdp\nContent-Length: [len]\n\nv=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\n    ]]>\n  </send>\n  <recv response=\"100\" optional=\"true\"/>\n  <recv response=\"200\"/>\n  <send>\n    <![CDATA[\n\nACK sip:test@[remote_ip]:[remote_port] SIP/2.0\nVia: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]\n[last_From:]\n[last_To:]\n[last_Call-ID:]\nCSeq: 1 ACK\nContact: <sip:sipp@[local_ip]:[local_port];transport=[transport]>\nMax-Forwards: 70\nContent-Length: 0\n\n\n    ]]>\n  </send>\n  <pause milliseconds=\"2000\"/>\n  <send retrans=\"500\">\n    <![CDATA[\n\nBYE sip:test@[remote_ip]:[remote_port] SIP/2.0\nVia: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]\n[last_From:]\n[last_To:]\n[last_Call-ID:]\nCSeq: 2 BYE\nMax-Forwards: 70\nContent-Length: 0\n\n\n    ]]>\n  </send>\n  <recv response=\"200\"/>\n</scenario>\n",
  "run": "sipp -sf <scenario.xml> -m 1 <proxy-host>:<port>",
  "caveats": [
    "user_agent was pinned and the captured request carries no User-Agent header, so none is sent",
    "the pinned body names the media endpoint the ORIGINAL caller advertised, so any RTP the far end sends goes there and not to the machine running SIPp",
    "SIPp sends from the host you run it on. Source address, routing and any IP access list differ from the capture, and a reproduction depends on those matching."
  ],
  "source_exhausted": true,
  "source_stopped_early": false
}

Read the hypothesis block as a four-way split of the original request. pinned came across byte-for-byte, varied is what SIPp regenerates, generated is what the template supplies instead of the capture, and omitted is what the capture held and the scenario leaves out. Nothing falls outside those four.

Only branch, call_id and tags can vary, because those are the fields SIPp generates fresh for every call it places. Asking to vary anything else fails:

{ "code": -32602,
  "message": "'sdp' cannot be varied: SIPp has no generator for it. Variable aspects are branch, call_id, tags. Pin it instead if it is part of your hypothesis." }

An aspect in both pin and vary fails:

{ "code": -32602,
  "message": "'call_id' is in both pin and vary. Held fixed and regenerated are opposite instructions, and a scenario that silently picked one would encode a theory nobody stated." }

All three identity fields vary by default. Pin them only when you intend the replay to reach the proxy as a retransmission of the captured call.

Anything unpinned takes a generic value, and caveats says what that changes. With no sdp pin the offer is a stock PCMU one, so a codec or attribute the far end rejected does not appear. With an empty pin list the response says that the scenario encodes no hypothesis. A pinned body brings the captured Content-Type with it.

The recv sequence asserts what the capture actually held: every provisional code seen, plus 100 whether or not the capture held one, and the final status. A call with no final response in the capture asserts nothing about the outcome — the scenario sends the request and waits.

For an INVITE the scenario sends an ACK either way, with the Via that RFC 3261 calls for in each case: a fresh branch on a 2xx, because that ACK is a new transaction, and [last_Via:] on a non-2xx, because RFC 3261 section 17.1.1.3 makes it part of the INVITE transaction.

Twelve headers the scenario always owns come from the template whatever the capture held, pin: ["headers"] included: Via, Contact, Content-Length, Content-Type, CSeq, From, To, Call-ID, Max-Forwards, Record-Route, Route and User-Agent. The template's Via and Contact name the host running SIPp, so responses return to it.

Two escaping rules apply to captured text in the scenario. sipnab strips control characters, CR and LF included, from captured header values. It splits ]]> inside a header value or SDP attribute across two CDATA sections, which keeps the bytes exact.

Everything in scenario beyond the template — the Request-URI, header values, SDP — came from the packet's sender. The response carries the provenance note instead of fencing the scenario field by field. Review the scenario before running it.

generate_wireshark_filter

A display filter selecting one call, and the tshark line that applies it. Use it to hand a call to someone who reads the capture in Wireshark.

Name Type Legal values If omitted
call_id string A Call-ID the store holds. Required — the call fails.
include_media? bool? true adds one rtp.ssrc term per stream attributed to the call. true.
// generate_wireshark_filter { "call_id": "[email protected]" }
{
  "schema_version": 1,
  "call_id": "[email protected]",
  "display_filter": "sip.Call-ID == \"[email protected]\" || rtp.ssrc == 0x343da99b",
  "tshark": "tshark -r 'tests/pcap-samples/sip-rtp-g711.pcap' -Y 'sip.Call-ID == \"[email protected]\" || rtp.ssrc == 0x343da99b'",
  "streams_included": 1,
  "notes": [
    "rtp.ssrc matches only once Wireshark is decoding those packets as RTP. Enable 'Try to decode RTP outside of conversations', or use Decode As on the media ports, if the SSRC terms select nothing."
  ],
  "capture_identity": { "node": "capture-01", "instance": "cc2cb18df0ea68adfb9c9-2",
                        "dialog_generation": 13, "stream_generation": 2 },
  "source_exhausted": true,
  "source_stopped_early": false
}

The tshark line names this run's capture file when the server reads one, and falls back to <capture.pcap> on a live capture. Both the filename and the filter go through POSIX shell quoting, so an embedded quote in a Call-ID closes and reopens the quoted word rather than ending it.

Read notes before using the filter:

  • With include_media: true and no stream attributed to the call, it says the filter selects signaling only.
  • With SSRC terms present, it says that rtp.ssrc matches nothing until Wireshark decodes those packets as RTP, and how to make it do so.

A Call-ID carrying a control character fails. A Wireshark display-filter string literal escapes only \ and ", so it cannot represent the Call-ID:

{ "code": -32602,
  "message": "this Call-ID carries the control character U+0009, which a Wireshark display-filter string literal cannot represent. A filter written around it would not mean what the Call-ID says." }
⚠️ **GitHub.com Fallback** ⚠️