sip-ladder 2026.5.25.2

Generate SIP call-flow (ladder) diagrams from pcap files. Mermaid + SVG output.

sip-ladder

Generate SIP call-flow (ladder) diagrams from pcap files.

Reads a pcap, parses SIP messages, groups them into calls by Call-ID, and renders the resulting message flow as either a Mermaid sequence diagram (text, embeddable in Markdown) or a standalone SVG.

The diagram algorithm is ported from sngrep's ncurses "Call Flow" view (src/curses/ui_call_flow.c), with one improvement: sngrep treats every distinct IP:port as a separate actor column, so a proxy listening on :5060 and originating on :5061 shows up twice. sip-ladder uses Via and Contact headers to merge those into a single logical actor.

Install

uv tool install sip-ladder
# or, ad-hoc:
uvx sip-ladder trace.pcap -o flow.mmd

CLI

sip-ladder trace.pcap                   # render all calls as Mermaid to stdout
sip-ladder trace.pcap -o flow.mmd       # write Mermaid to file
sip-ladder trace.pcap -o flow.svg       # extension drives format
sip-ladder trace.pcap --list            # list calls without rendering
sip-ladder trace.pcap --call-id abc...  # render just one call

Library

from sip_ladder import read_pcap, render_mermaid, render_svg

for call in read_pcap("trace.pcap"):
    print(f"{call.call_id}  {call.from_uri} -> {call.to_uri}  ({call.final_response})")
    open(f"{call.call_id}.mmd", "w").write(render_mermaid(call))
    render_svg(call, f"{call.call_id}.svg")

Scope

In-scope for the initial release:

• Offline pcap analysis (UDP and best-effort TCP)
• SIP message parsing (RFC 3261 — common cases)
• Mermaid + SVG renderers
• Via-aware actor reconciliation
• Retransmit detection via CSeq match

Out-of-scope (deferred):

• Live capture (libpcap, HEP/EEP listener, sngrep subprocess streaming)
• RTP / MOS analysis
• TLS decryption
• SIP-over-WebSocket
• Interactive HTML

The architecture leaves clean seams to add these later without restructuring.

License

MIT.