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

Example output

Given a pcap containing a basic INVITE flow, sip-ladder produces:

---
title: demo-1-simple@atlanta.example INVITE → 200
---
sequenceDiagram
    autonumber
    participant A as alice@192.0.2.10
    participant B as 192.0.2.20:5060
    A->>B: INVITE
    B-->>A: 100 Trying
    B-->>A: 180 Ringing
    B-->>A: 200 OK (INVITE)
    A->>B: ACK
    A->>B: BYE

The pcap that produced this — plus a redirect call and a REFER-based transfer — lives in examples/build_demo_pcap.py. Run it locally to regenerate:

uv run python examples/build_demo_pcap.py
# Produces examples/demo-call-flow.{pcap,mmd,svg}

GitHub, GitLab, Obsidian, and most modern Markdown viewers render the Mermaid block above as a sequence diagram. On platforms that don't (PyPI's README renderer, plain-text consumers), the fenced code block remains readable as-is.

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.

Source and contributions

• Repository: https://git.supported.systems/warehack.ing/sip-ladder
• Issues: https://git.supported.systems/warehack.ing/sip-ladder/issues
• Changelog: CHANGELOG.md
• API documentation: docs/API.md

The repo also includes an docs/agent-threads/ directory with the full audit trail of cross-project design conversations — these are intentionally excluded from the PyPI sdist (per a deliberate "link, don't ship" policy) but are visible in git for anyone curious about why specific design choices were made.

License

MIT — see LICENSE.