flowsynth: network packet capture compiler

by do son · December 10, 2017

Flowsynth is a tool for rapidly modeling network traffic. It can be used to generate text-based hexdumps of packets as well as native libpcap format packet captures.

How it works

Flowsynth uses a syntax language to describe network flows. The syntax language is made up of individual instructions that are parsed by the application and are grouped into events, which are a logical representation of the instructions in the network domain. After all, instructions have been parsed, the events are iterated over and converted into packets, which are the real-world representation of the traffic on the wire.

These three phases are referred to as the parsing phase, rendering phase, and the output phase.

Take the following synfile as an example:

flow default tcp myhost.corp.acme.net:12323 > google.com:80 (	tcp.initialize; );

  default > ( content:"GET / HTTP/1.1\x0d\x0a"; content:"Host: google.com\x0d\x0a\x0d\x0a"; );

  default < ( content:"HTTP/1.1 200 OK"; );

This sample contains two types of instructions: Flow declarations and event declarations. The first line (flow default tcp…) declares to Flowsynth that a flow is being tracked between myhost.corp.acme.net and google.com. The flow name is the default. All events that apply to this flow will use this name (default) to identify which flow they apply to. The third argument specifies which protocol the flow will use. In this case, it’s tcp. Next, we specify the source and destination addresses and ports. Finally, an optional attributes section is included at the end. The tcp.initialize attribute is included, which tells Flowsynth to automatically generate a three-way handshake for this flow. It’s worth noting that each attribute and line should be closed with a semicolon (;), as shown above. When this flow declaration instruction is parsed by Flowsynth the application will automatically generate event entries in the compiler timeline to establish a three-way handshake.

Next, Flowsynth will parse the event declaration default > ( content … Flowsynth will immediately identify that this event declaration belongs to the ‘default’ flow that was just declared. Once this event is associated with the flow any protocol-specific values (like TCP SEQ and ACK numbers) will automatically be applied to the event. The directionality of this specific event is ‘>’, or TO_SERVER. Once the parent flow and directionality have been established Flowsynth will parse the optional attributes section. Just like the flow declaration, each optional attribute must be closed with a semicolon (;). The two ‘content’ attributes are used to specify the packet’s payload. In this case, an HTTP request is being rendered. Flowsynth will read these instructions and generate an entry in the compiler timeline for this event.

The last event declaration that is parsed by the application shows the server’s response to the client. Using the same methods described above, Flowsynth will parse the event declaration and add it to the compiler timeline.

Once all the instructions have been parsed and processed, Flowsynth iterates over the compiler timeline and renders any events to native packets. In this phase of the application several important things happen:

Protocol-specific intelligence, like TCP SEQ/ACK calculations, and ACK generation takes place.
Specific features of attributes, like converting ‘\x3A‘ to ‘:‘ take place.

Once all of the events have been rendered to native pcaps the output phase occurs. During the output phase, the native packets are delivered to the user in one of the two output formats, as a hexdump, or as a native PCAP file.

Install

git clone https://github.com/secureworks/flowsynth.git
cd flowsynth
pip install -r requirements.txt

Usage

flowsynth.py input.syn

In this most basic example, Flowsynth will read input.syn and output the resulting hexdump to the screen. By default, Flowsynth will use ‘hex’ format.