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 |
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".
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:
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 }.
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
nullmetric means the group has no population for it, andnot_groundedsays which. The REGISTER group holds no call attempts, so its ASR and NER arenull, not0. -
unitsnames the unit of every figure.asrandnerare percents, here and inevaluate_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
603counts 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,600and603: 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 in486has an ASR of 0 and an NER of 100.408 Request Timeoutdoes 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_countholds the number of dialogs in the groups pasttop_n, with no metrics. The groups plusother_countalways equaltotal_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.
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.
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.
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.
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_choiceonnamed. No entry or alias has that name. The message lists the defined names, anddata.valid_valuescarries every namenamedaccepts, 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 gavefilterandnamedtogether. Give one, or write the name into the expression as@name. -
An empty
filterslist. The run read no[filters]table: check the--configpath.
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
}
}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-secondson the server command line. sipnab clamps a request above the ceiling instead of refusing it, and the response saystimeout_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".
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-IDthere 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:
-
mappingisth_callid_mapping. -
decodedisth_callid_decoded. -
mappingisth_callid_mapping: an OpenSIPSE_SIPNAB_TH_MAPevent named both legs. -
headerissession_id,x_call_id, both charging-vector strategies andvia_branch. -
sdpissdp_origin. -
timingistiming_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.
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.
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_capturedandcallee_capturedsay 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.
"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.
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.
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.
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.
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.
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-printOver 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.
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.
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.
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".
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(observedalso works) andsyntax. -
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
rfcandsectionrather than the prose ofexplanation, for example RFC 3264 section 6.1.explain_ruleturns arule_idback into the citation and the link. -
Pass
frame_reftoshow_evidenceto read the bytes of the frame the rule fired on. -
Treat
observedas capture text. It quotes the capture and arrives fenced.expectedandexplanationare 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-UNANSWEREDneeds the endpoint pairs RTCP arrived on, which the MCP server does not record, 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 — 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.sipnablintfile thatsuppressions.filenames. Edit that file, or pass anothersuppression_file. -
below_severity: yourseverity_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.
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.
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.
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.
Getting the result out of sipnab and into the next tool, the next team, or a bug report someone else can reproduce.
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.
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: trueand no stream attributed to the call, it says the filter selects signaling only. - With SSRC terms present, it says that
rtp.ssrcmatches 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." }