initial commit

LICENSE

@@ -0,0 +1,35 @@
+/*
+ *	
+ * Copyright (c) 2016 Cisco Systems, Inc.
+ * All rights reserved.
+ * 
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 
+ *   Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ * 
+ *   Redistributions in binary form must reproduce the above
+ *   copyright notice, this list of conditions and the following
+ *   disclaimer in the documentation and/or other materials provided
+ *   with the distribution.
+ * 
+ *   Neither the name of the Cisco Systems, Inc. nor the names of its
+ *   contributors may be used to endorse or promote products derived
+ *   from this software without specific prior written permission.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+ * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+ * OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ */

Makefile

@@ -0,0 +1,77 @@
+# makefile for pcap2flow
+#
+# Copyright (c) 2016 Cisco Systems 
+
+# variables 
+#
+
+# CWD is the name of the current directory
+#
+TMP = $(shell pwd)
+CWD = $(shell basename $(TMP))
+
+# The version variable identifies the version number of the source
+# code (and not the version of the protocol).
+#
+version = $(shell cat VERSION)
+
+# The sysname variable identifies the system by kernel name, and is
+# used to define a C preprocessor symbol (in the CFLAGS variable) that
+# indicates the operating system type.  Note that it does *not* affect
+# the endianness choice, which is picked up from <sys/types.h>.
+#
+sysname = $(shell uname -s | tr "[:lower:]" "[:upper:]" )
+
+# main executable and unit test program
+#
+pcap2flow: 
+	cd src; $(MAKE)
+	cp src/pcap2flow .
+
+unit_test:
+	cd src; $(MAKE)
+	cp src/unit_test .
+
+# testing
+#
+test: unit_test pcap2flow pcap2flow_test.sh
+	./unit_test
+	./pcap2flow_test.sh
+
+# DOCUMENTATION
+#
+man: pcap2flow.1
+	man ./pcap2flow.1 > pcap2flow.txt 
+	man -Tdvi ./pcap2flow.1 > pcap2flow.dvi 
+	dvipdf pcap2flow.dvi
+	rm -f pcap2flow.dvi
+
+# housekeeping
+#
+clean: 
+	cd src; $(MAKE) clean
+	rm -f pcap2flow unit_test 
+	for a in * .*; do if [ -f "$$a~" ] ; then rm $$a~; fi; done;
+
+distclean: clean
+	if [ -f pcap2flow.bin ]; then echo "pcap2flow.bin is present; (re)move it before building distribution"; exit 1; fi
+	if [ -f upload-key ]; then echo "upload-key is present; (re)move it before building distribution"; exit 1; fi
+	if [ -f upload-key.pub ]; then echo "upload-key.pub is present; (re)move it before building distribution"; exit 1; fi
+
+distname = joy_$(version)
+
+# note: debian friendly tarball name
+#
+package: distclean
+	cd ..; tar cvzf $(distname).orig.tar.gz joy/* 
+
+debian: package
+	cd ..; cp -R joy joy-$(version)
+	cd ../joy-$(version); debuild -us -uc
+
+# installation via shell script
+#
+install: pcap2flow unit_test test
+	./install-sh
+
+# EOF

README

@@ -0,0 +1,125 @@
+                           _              
+                          (_) ___  _   _ 
+                          | |/ _ \| | | |
+                          | | (_) | |_| |
+                         _/ |\___/ \__, |
+                        |__/       |___/
+
+            A package for capturing and analyzing network
+         flow data and intraflow data, for network research, 
+              forensics, and security monitoring. 
+
+Overview
+
+   Joy is a BSD-licensed libpcap-based software package for extracting
+   data features from live network traffic or packet capture (pcap)
+   files, using a flow-oriented model similar to that of IPFIX or
+   Netflow, and then representing these data features in JSON.  It
+   also contains analysis tools that can be applied to these data
+   files.  Joy can be used to explore data at scale, especially
+   security and threat-relevant data.
+
+   JSON is used in order to make the output easily consumable by data
+   analysis tools.  While the JSON output files are somewhat verbose,
+   they are reasonably small, and they respond well to compression.
+
+   Joy can be configured to obtain intraflow data, that is, data and
+   information about events that occur within a network flow,
+   including:
+
+      * the sequence of lengths and arrival times of IP packets,
+        up to some configurable number of packets,
+
+      * the empirical probability distribution of the bytes within the
+        data portion of a flow, and the entropy derived from that
+        value, 
+
+      * the sequence of lengths and arrival times of TLS records, 
+
+      * other non-encrypted TLS data, such as the list of offered
+        ciphersuites, the selected ciphersuite, and the length of the
+        clientKeyExchange field,
+
+      * the name of the process associated with the flow, for flows
+        originate or terminate on the 
+
+   Joy is intended for use by security research, forensics, and for
+   the monitoring of (small scale) networks to detect vulnerabilities,
+   threats and other unauthorized or unwanted behavior.  Researchers,
+   administrators, penetration testers, and security operations teams
+   can put this information to good use, for the protection of the
+   networks being monitored, and in the case of vulnerabilities, for
+   the benefit of the broader community through improved defensive
+   posture.  As with any network monitoring tool, Joy could
+   potentially be misused; do not use it on any network of which you
+   are not the owner or the administrator.
+
+   Flow, in positive psychology, is a state in which a person
+   performing an activity is fully immersed in a feeling of energized
+   focus, deep involvement, and joy.  This second meaning inspired
+   the choice of name for this software package.
+
+   Joy is alpha/beta software; we hope that you use it and benefit
+   from it, but do understand that it is not suitable for production
+   use.
+
+
+Credits
+
+   This package was written by David McGrew and Blake Anderson
+   {mcgrew,blaander}@cisco.com of Cisco Systems Advanced Security
+   Research Group (ASRG).
+
+
+Quick Start
+
+Joy has been successfully run and tested on Linux (Debian, Ubuntu, and
+CentOS) and Mac OSX.
+
+First, obtain the package from github, and change to the joy
+directory.
+
+To build the package, run "make" in the main directory.  This will
+cause the programs to be compiled, linked, stripped, and copied into
+the main directory as apropriate.  It will also run a test script and
+a unit test program.  
+
+The main program for extracting data features from pcap files or live
+packet captures is the program pcap2flow, which occupies the src/
+subdirectory.  
+
+To understand how pcap2flow is configured, read one of
+the configuration files (linux.cfg or macosx.cfg).  To process a pcap
+file in offline mode, run
+
+   pcap2flow [ OPTIONS ] filename [ filename2 ... ]
+
+For instance, 
+
+   pcap2flow bidir=1 output=data.json filename
+
+To run the packet capture in online mode, use the same command form,
+but have OPTIONS include an interface=<value> command, and omit the
+filename(s) from the command line.  For instance,
+
+   sudo ./pcap2flow interface=eth0 bidir=1 output=data.json
+
+
+Installation
+
+To install the package on your system, 
+
+
+Documentation
+
+A man page will be built and installed automatically as part of the
+package.  See the file pcap2flow.1.
+
+
+Testing
+
+Run the script ./pcap2flow_test.sh and the utility src/unit_test to
+test the programs.  These programs will indicate success or failure on
+the command line.
+
+

VERSION

@@ -0,0 +1 @@
+1.0

debian/changelog

@@ -0,0 +1,5 @@
+joy (1.0-1) UNRELEASED; urgency=low
+
+  * Initial release. (Closes: #XXXXXX)
+
+ -- mcgrew <mcgrew@cisco.com>  Mon, 04 Jan 2016 15:22:56 -0500

debian/compat

@@ -0,0 +1 @@
+9

debian/control

@@ -0,0 +1,11 @@
+Source: joy
+Maintainer: mcgrew <mcgrew@cisco.com>
+Section: misc
+Priority: optional
+Standards-Version: 3.9.4
+Build-Depends: debhelper (>= 9), libpcap-dev, libssl-dev
+
+Package: joy
+Architecture: any
+Depends: ${shlibs:Depends}, ${misc:Depends}
+Description: extract and analyze data features from network flows

debian/copyright

@@ -0,0 +1 @@
+Copyright 2016 Cisco Systems

debian/rules

@@ -0,0 +1,3 @@
+#!/usr/bin/make -f
+%:
+	dh $@

debian/source/format

@@ -0,0 +1 @@
+3.0 (quilt)