SipSpy
From Wesip
From Wesip
Contents |
Introduction
SipSpy is VozTelecom's own SIP-network monitoring solution. The SipSpy software is licensed under the GPL version 2.
Since the beginning, we found SIP a tough protocol. Branch-IDs, CSeq's that sometimes increase sometimes not, Parallel forkings, race conditions between Cancel and Invites... Furthermore, SIP being such a distributed and decoupled protocol, it becoms a nightmare to see how packets come and go, and what responses generate. (If you're reading this, you probably know what I mean ;))
In order to address this and overcome any difficulties SIP can pose to the developer, SipSpy was born.
The philosophy is to have a monitoring agent (spyAgent) in each one of the SIP-network nodes that processes SIP messages, so we could have an agent in the inbound proxy, another in the outbound proxy, and another in the Application Server. Then there's a JAVA application (SipSpy) that connects to each one of these agents, and asks them to report any SIP traffic they see, according to certain matching rules (as we're not interested in seeing all the traffic that passes through each of the nodes). These matching rules are:
- An arbitrary regexp that must match the SIP packet.
- BPF filter, such as those frequenlty used with libpcap (ethereal, ngrep and co.)
So the Java user interface, connects to several agents distributed through the SIP network, and asks them to report any SIP packet matching those rules. Then, SipSpy correlates the CallID in all the packets received through the different nodes, and generates a nice and ordered list of SIP dialogs seen. When you click on any of the dialogs, you see all the packets belonging to that dialog, with the transactions nicely coulored (request and response), and you can click any message to see its contents. All the messages are sorted according to the time they were seen, so you should better synchronize the clocks of your monitoring nodes. You can select different dialogs at the same time, and see the message flow nicely depicted. SipSpy can be ran as an Applet embedded in a web page, or as an standalone program. It requires java 1.5.
The SpyAgent has been developed in C, using libpcap, and should consume almost no resources, so monitoring the network is as little intrusive as possible (it always depends on the rules you give it to matching packets, if the regexp/BPF matches a lot of packets, it will incurr higher CPU load).
Each SipSpy can connect to several SpyAgents, and each SpyAgent can serve different SipSpies.
Features
- Roles: each SipSpy that connects to a spyAgent, must authenticate itself using a login and password, these are transferred using a digest method, so that passwords dont travel in clear-text, and replay attacks are avoided. Also each user is assigned a role: plain or admin. Admins can change the device on which the sipSpy is monitoring, and can change the BPF filter, whereas plain users cannot. Also, you can provide spyAgent wich a regexp for each of the users. Then, when a SipSpy provides a new regexp to match SIP packets, spyAgent will match the regexp to that regexp (that is, a regexp on a regexp), so you can limit the regexp's that users can use to monitor SIP traffic.
- SIP dialogs/sessions save and load: SipSpy can save the monitored packets in an XML file, so that when someone detects a bug in the SIP network, they can save a copy of the SIP dialog and send it to the administrators to address it.
- Server-based session saving: If one of your users/admins detects a bug in the SIP network, you can ask him to reproduce the bug and monitor all the SIP packets involved, and then save that SIP session to the server, so the next morning when developers go to work, they can download from the server the buggy SIP dialog.
the SpyAgents should run in Linux and FreeBSD.
There's a branch to port it to APR (Apache Portable Runtime) so that it could also run in WIndows, but unfortunately I do have a lot of work to do, so if anyone is interested in contributing, any help is welcome.
here's a picture of how the architecture works:
The red box is the list of all the SIP Dialogs that have been seen throughout all the SpyAgents.
The blue box is the Dialogs that have been selected to be viewed in the main panel.
The orange box is the main panel, where the selected sessions are displayed. All the messages belonging to the same transaction are painted in the same color.
The green box shows the selected SIP message (the selected message turns red on the display panel).
The light blue box on top, is the toolbar. There you can clear the sesssions panel, launch the connection manager, save the selected sessions, save all the sessions, open a saved session, remove some selected sessions, save the session remotely to the server, play some remotely saved session.
The yellow box is the Connection Manager, where you can see all the SpyAgents you're connected to. There you can edit the regexp to match packets, the BPF filter and interface where spyAgent should capture (if youre an admin), the IP address and port where the agent is listening, and the username and password used to connect to that SpyAgent.
Here is a picture of the Connection Manager:
And here's another screenshot:
Documentation/Help
In SIP implementations using TCP, a request is sent with 'src' port a high number, and dst port usually 5060, but in the 'via' header, the SIP implementation usually asks the response to be sent to the 'canonical' SIP port, 5060, or if the TCP connection is still open, to the TCP 'high-numbered' port.
SIpSpy uses each host:port as a new actor, depicted as a computer on the SipSpy pannel. So it can be quite annoying to have depicted a new Host:port for each TCP connection.
That's why I chose to use the topmost via's host:port as the endpoint even when TCP is using another port.
If you want SipSpy to draw the endpoints with their TCP port, you can define a JVM argument like this: -Dstrict.addresses=true
or in the Ant build.xml define a property in the 'run' target like this:
<target name="run">
<java jar="sipSpy.jar" fork="true">
<sysproperty key="log4j.configuration" value="file:conf/log4j.properties"/>
<sysproperty key="strict.addresses" value="true"/>
<classpath refid="project.classpath">
</classpath>
</java>
</target>
(note the sysproperty strict.addresses with value='true'
this is what happens with strict-addresses enabled:
and this is what heppens withoug strict-addresses:
in some scenarios you might prefer one or the other. At some point this will be a runtime configuration parameter.
spyAgent Man Page
Secrets file
Mailing List
Questions and answers on SipSpy can be published to sipspy-users@lists.sourceforge.net and more info can be found at: sipySpy @ sourceForge
Downoad
Alternatively, if you want to checkout the source code, you can try:
svn co http://sipspy.svn.sf.net/svnroot/sipspy/trunk sipSpy
Try it Live ! as an applet
and Thanks to Yourkit!!
YourKit is kindly supporting open source projects with its full-featured Java Profiler.
YourKit, LLC is creator of innovative and intelligent tools for profiling Java and .NET applications. Take a look at YourKit's leading software products: