inetric LLC

ssncap Documentation

ssncap supports many options to be as flexible as possible. It can redact the output to conceal social security numbers, encrypt the data to keep it secure for storage, use BPF filters, and log information to syslog to name a few capabilities. To improve security, ssncap can switch to a lower privileged user and/or group after opening the capture device. Running ssncap -h will give you all the available options.


Usage: ./ssncap [-aChjlLsdDvenRslqvX] [-A NUMAFTER] [-B QBEFORE] [-c COUNT]
                [-t THRESHOLD] [-f FOUNDDUMPFILE] [-p SNAPLEN]
                [-S STREAMFILE] [-w DUMPFILE] [-r RPCAP] [-i INTERFACE]
                [-k PUBKF] [-K PRIVKF]
                [-N NUMBERLIST] [-g GROUP] [-u USER] [FILTER]

A packet source is required for non-live capture.
If no packet source is given when live capture is selected, the first
suitable device will be used.
BPF Filter can be specified after all options akin to tcpdump.

-a         Run improved analysis mode.
-A NUM     Save NUM packets after ssn found.
-B NUM     Buffer NUM packets before ssn found - Enables -C.
-c COUNT   Stop after receiving COUNT packets.
-C         Enable packet circular buffer.
-l         Log packet information (-v) to SYSLOG instead of STDOUT.
-L         Log packet information (-v) to both SYSLOG and STDOUT.
-d         Show all duplicates.
-D         Enable redaction dump mode - All digits in all packets written
           to disk and stdout are replaced with 'X'.
-e         Match both with and without dashes.
-f FILE    Save matching packets to FILE.
-g GROUP   Change group to GROUP after opening device.
-G N       Cycle files about every N seconds - Keeps streams for -S intact.
           If the filter is not receiving packets, the files will not be cycled
           until a packet is received.
           File names can use the format specifiers defined by strftime(3).
-k PUBKF   Read public key from file PUBKF to encrypt packet data.
-K PRIVKF  Read private key from file PRIVKF to decrypt packet data.
-i IFACE   Read live traffic from IFACE.
-j         Enable area code and group check.
           No longer valid after Randomized SSN Assignments started on
           June 25, 2011.
-w FILE    Save ALL packets to FILE.
-n         Try for no duplicates.
-N NLIST   Load important numbers from NLIST.
-p SNAP    Set the snap length of the capture.
-R         Reverse mode - show only invalids.
-s         Calculate and show statistics.
-t THRESH  Only show those with score greater than TRHESH - Enables -a.
-r RPCAP   Read from pcap file RPCAP.
-q         Quiet - Nothing is printed to stdout unless a -v or -s is given.
-S FILE    Save N packets before/after found SSN to FILE.
-T FILE    Load table file FILE.
-u USER    Change user to USER after opening device.
-x         Enable redaction print mode - All digits in all packets written
           to STDOUT are replaced with 'X'.
-X         Print packt data in Hex and ASCII.
-z CMD     OLD: Run CMD after every file rotation. The file names will be
           passed as command line arguments. The file order is -w -S -f.
-z CMD     Run CMD once per file after every rotation. The file name will be
           passed as a command line argument.
-v         Used to show the packet info.
-vv        Same as -v but in addition show the packet data.
-vvv       Same as -vv but in addition show rejected fakes and a reason.
-vvvv      Same as -vvv but in addition show the packet data for rejected fakes.
-vvvvv     Same as -vvvv but in addition show collisions.
-vvvvvv    Same as -vvvvv but in addition show all packet data.
FILTER     Apply bpf filter FILTER to the capture.


The output ssncap will give by default consists of the social security number found, the packet number it was found in, the byte in the packet where the number starts, and a score. The score will always be zero unless analysis mode (-a option) is enabled. This score is used for the threshold option (-t).

AAA-GG-XXXX : packet, byte;  score

When statistics are enabled (-s option), ssncap will output at the end of the run:

If capturing live traffic, the packet received and drop counts:
 - Received by filter:  X
 - Dropped by Kernel:   X
        Interface:      X

- Total Packets:          T
- Packets Searched:       P (P/T * 100)
- Average Packet Length:  L
- Average Total Iterations: I (I/L * 100)

Social security number statistics:
- Potentials Found:  F
- Total Accepted:    A (A/F * 100)
- Hash Collisions:   C

Specifying multiple -v options on the command line will increase the output. The next level of verbosity will include time and packet information among other statistics.

2010-09-12 07:31:51.549177 UTC; > TCP; len:103; pf:0; nf:0;

The time is given in UTC. The source IP and source port are first, followed by the destination IP and port. Len is the length of the packet, PF is the potential numbers found, and NF is the count of numbers accepted as socials.

More levels add packet data to the output, or can include numbers that would have been considered socials, but failed one of the tests.


The simplest example is to run ssncap with the interface to listen on or the file to be read.

ssncap -i eth0
ssncap -r ./pcap_file

It is recommended to run ssncap with the least amount of privilege as possible. To do so, ssncap supports switching its user and group with the -u and -g options respectively.

ssncap -i eth0 -u nobody -g nobody

To listen to live traffic while saving 10 packets before and after the packet containing the social security number to a file:

ssncap -i eth0 -S stream_file.pcap -B 10 -A 10

The same but encrypting the resultant file with a public key:

ssncap -i eth0 -k ./public_key_file.pem -S encrypted_stream_file.pcap -B 10 -A 10

To print out the found packets and the information about them:

ssncap -r dump_file.pcap -v
ssncap -r dump_file.pcap -vv

If stream mode was used, the packets without socials found in them will not be printed unless enough -v options are specified.

ssncap -r stream_dump_file.pcap -vvvvvv

ssncap can also cycle files after a given interval and optionally run an executable on the file as well. The executable will be passed the saved files’ name as command line arguments.

The following command will run ssncap on an interface, maintaining a stream of at most 1000 packets before and after the packet found containing the social security number, cycling the file every 3600 seconds, and running the executable on the cycled file.

ssncap -i eth0 -a -B 1000 -A 1000 -S stream_dump-%Y-%m-%d-%H%M%s.pcap -G 3600 -z /path/to/executable

When cycling is enabled, file names support the time formatting specifiers provided by strftime(3). ** Newer versions of ssncap now run the executable once PER each output file, receiving the file name as its only argument. ** Since ssncap supports writing to three files simultaneously in different modes (full capture, stream capture, and found capture), the file names will be passed as different arguments to the executable. The first argument will be the full capture file name, the second the stream capture file name, and the third the found capture file name. If any mode is not currently being used, the empty string will be passed in it’s place.

An example program illustrating how to use the arguments.

echo "Full capture file: $1";
echo "Stream capture file: $2";
echo "Found capture file: $3";

Capture live traffic, using a threshold score of 6, cycling files after 4 hours, maintaining a stream of at most 1000 packets before and after the packet found containing the social security number, encrypting the packet data to a stream file, specifying a BPF filter to only analyze traffic on port 25, and piping the output to sireport to generate interactive graphs of the data.

./ssncap -aqvv -t 6 -i eth0 -G 14400 -k ./public_key.pem -S stream_dump.pcap port 25 | ./sireport -D -w report-%S.html -G 14400 -q -z ./email_report_exec 

Unlike other programs, ssncap can write the packet data to standard out and still use the cycle option to run executables at the specified interval. This allows chaining of capture programs.

./ssncap -a -i eth0 -G 14400 -z ./some_useful_program -S - | tcpdump -r - 


ssncap uses the openssl library for its cryptographic functions. To generate a private key, use the following command:

openssl genrsa -out private_key.pem 2048

This command creates a private 2048 bit RSA key, used here for decryption. To create a key with a pass phrase, use the following command instead:

openssl genrsa -aes256 -out private_key.pem 2048

To generate the corresponding public key, use the following command:

openssl rsa -in private_key.pem -out public_key.pem -pubout

This key is used here for encryption.