tcpflow -- A TCP Flow Recorder

Note: I am no longer actively maintaining tcpflow. This page has the most recent version I released personally. Maintenance has been taken over by Simson Garfinkel, who distributes new versions at his site.

Downloads and Documentation

The most recent version of tcpflow is v0.21, released 7 August 2003. You can also see the history of previous releases.

There is an HTMLized version of the tcpflow man page.

tcpflow is free software, distributed under the GNU General Public License (GPL); see the file COPYING (in the distribution) for details.

Sources and "Official" Builds

Contributed Builds and Packages (off-site)

What is tcpflow?

tcpflow is a program that captures data transmitted as part of TCP connections (flows), and stores the data in a way that is convenient for protocol analysis or debugging. A program like 'tcpdump' shows a summary of packets seen on the wire, but usually doesn't store the data that's actually being transmitted. In contrast, tcpflow reconstructs the actual data streams and stores each flow in a separate file for later analysis.

tcpflow understands sequence numbers and will correctly reconstruct data streams regardless of retransmissions or out-of-order delivery. However, it currently does not understand IP fragments; flows containing IP fragments will not be recorded properly.

tcpflow is based on the LBL Packet Capture Library (available from LBL) and therefore supports the same rich filtering expressions that programs like 'tcpdump' support. It should compile under most popular versions of UNIX; see the INSTALL file for details.

tcpflow stores all captured data in files that have names of the form

            128.129.130.131.02345-010.011.012.013.45103

where the contents of the above file would be data transmitted from host 128.129.131.131 port 2345, to host 10.11.12.13 port 45103.

What use is it?

I originally wrote this program to capture the data being sent by various programs that use undocumented network protocols in an attempt to reverse engineer them. RealPlayer (and most other streaming media players), ICQ, and AOL IM are good examples of this type of application.

In tinkering with it, I later also found tcpflow to be useful for checking to see what cookies my browser was sending to various sites, looking at the MIME headers of HTTP requests people are sending to my web server, and verifying that various connections to my machine that were supposed to be encrypted actually were encrypted. Checking on protocol encryption is particularly useful for sites that carry data of financial value in their payloads, such as banking clients.

Security Implications

Although I wrote tcpflow to help the Forces of Good, in the wrong hands it can certainly be used for the Forces of Evil. In the wrong hands this program can be used to do things like read incoming and outgoing mail, and sniff passwords. I have chosen to release it anyway, because crackers already have tools specifically optimized for doing "evil" network sniffing easily, and this program will most likely not make their lives any easier.

Theoretically, the Good Guys might be able to use programs like this to monitor their networks for evidence of attacks. Such Good Guys are directed to software such as Vern Paxson's Bro, which is specifically designed to do network-based intrusion detection. Also, you should be aware that there are certain problems that make network intrusion detectors inherently unreliable in the face of a sufficiently advanced attacker; for more information, see SecNet's paper on the topic, or a presentation I gave.

Bugs

Please send bug reports to jelson@circlemud.org.

tcpflow currently does not understand IP fragments. Flows containing IP fragments will not be recorded correctly.

tcpflow never frees state associated with flows that it records, so will grow large if used to capture a very large number of flows (e.g., on the order of 100,000 flows or more).

There appears to be a bug in the way that Linux delivers packets to libpcap when using the loopback interface ("localhost"). When listening to the Linux loopback interface, selective packet filtering is not possible; all TCP flows on the localhost interface will be recorded.

Release History

You can read the more detailed ChangeLog if you like.


Back to my software page
Back to my home page

Jeremy Elson
Last updated: 7 August 2003