This tool parses a pcap file (e.g. captured by tcpdump), extracts SIP packets from it and converts the flow to a mermaid sequence diagram while filtering unwanted packets.
When documenting SIP call flows, a sequence diagram can greatly improve the understanding of SIP packets going back and forth between involved endpoints. However, managing pictures or other binary formats produced by tools like Visio or Dia are a pain to track via version control, and they are cumbersome to maintain e.g in Markdown documentation.
Mermaid is a nice tool you can run locally to generate such sequence diagrams from simple text based syntax. When using Pandoc to generate documentation out of markdown file, you can even use mermaid-filter to embed mermaid code directly in your documentation and generate the diagrams on the fly when the markdown is rendered to html or pdf.
However, manually writing those sequence diagrams can be a quite repetitive and boring task when documenting a large number of call flows. Therefore, this tool aims to help automizing this process by letting you do an actual SIP call (or registration, or any other SIP scenario), capture a pcap file using tcpdump while doing so, then generate the sequence diagram automatically using this pcap call trace. What's left is pasting it into your documentation, and potentially annotating it with some notes.
$ sudo apt install libnet-pcap-perl libnetpacket-perl libnet-sip-perl
$ sudo yum install libpcap-devel \
# or any other way to install the libpcap development package
$ sudo cpan -i Carton
$ carton install
Usage: ./pcap2mermaid.pl <input.pcap> <output.txt> [mapping string]
PERL5LIB=./lib:./local/lib/perl5 ./pcap2mermaid.pl \
/tmp/test.pcap /tmp/out.txt \
"10.15.17.98:46849=DUT,10.15.17.237:5060=SSW"
To quickly verify the result without installing mermaid, you can use the mermaid live editor where you can paste the output of the tool for a preview.
Eventually, you might want to Install the mermaid-cli for a quick test, then execute:
$ cat /tmp/mermaid-config.json
{
"theme": "forest",
"themeCSS": "",
"cloneCssStyles": false,
"sequence": {
"mirrorActors": false,
"useMaxWidth": false
}
}
$ mmdc -i /tmp/out.txt -o /tmp/out.svg -c /tmp/mermaid-config.json
A final solution would also integrate the mermaid-filter to the documentation generation tool-chain, which is out of scope of this document.
The tool only considers packets from or to port 5060 hardcodedly. If you want to capture traffic between different ports, you have to adapt the variable $filter_string, which is in standard pcap filter syntax.
Also note that all provisional responses with a response code smaller than 180 are automatically ignored. To change this behavior, the $skip_provisional variable must be set to 0.
If no optional mapping string argument is given, every single leg of
all SIP packets are displayed. The name of the endpoints are the
<ip>:<port> tuples. This can take a long time.
To optimize this and make the flow chart more readable, a mapping string accomplishes two things:
- Display a custom name for an endpoint instead of
<ip>:<port>in the flow chart - Ignore all endpoints that do not have a mapping string
The format of the mapping string is a comma-separated list of elements,
each containing a string <ip>:<port>=<name>.
Example: 192.168.0.10:12345=Alice,192.168.0.20:54321=Bob,192.168.0.30=Proxy