Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Manage your pcap collection

branch: master

This branch is 0 commits ahead and 0 commits behind master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 bin
Octocat-spinner-32 lib
Octocat-spinner-32 test
Octocat-spinner-32 .document
Octocat-spinner-32 .gitignore
Octocat-spinner-32 LICENSE.txt
Octocat-spinner-32 README.html
Octocat-spinner-32 README.md
Octocat-spinner-32 Rakefile
Octocat-spinner-32 VERSION
Octocat-spinner-32 pcapr-local.gemspec
README.md

pcapr.Local

Introduction

pcapr.Local is a tool for browsing and managing a large repository of packet capture files (pcaps). After you install and configure pcapr.Local with the location of your pcaps, it automatically indexes those pcaps and enables you to navigate your collection using a web browser. Pcapr.Local extends and integrates with Xtractr, so it uses the Xtractr web UI hosted on pcapr.net. However, because the UI is configured to talk to the local Xtractr instance managed by pcapr.Local, your data never leaves your network.

In addition to managing pcaps, pcapr.Local helps you leverage your custom Wireshark dissectors to create Scenarios in Mu Studio. Just download the PAR file (Pcap ARchive) file created by pcapr.Local and import it into Mu Studio, where your Wireshark data guides Scenario creation.

You can learn more about pcapr.Local in our announcement blog.

pcapr.Local

Dependencies

Supported Environments

Linux (any flavor). You can install on a dedicated Linux system or in a virtual machine (VM).

Ruby & Rubygems

Ruby (1.8.6, 1.8.7, 1.9.2) + Rubygems (1.3.7 or higher). When using Ruby 1.8.6, you must install rubygems 1.3.7. Rubygems officially ceased support for ruby 1.8.6 as of the rubygems 1.4.0 release, so any version 1.4.x or higher will not install on a ruby 1.8.6 system.

CouchDB

Local and remote installations supported. If you have configured a username and password for the CouchDB service, you'll need to provide those user credentials during the pcapr.Local gem installation. On Ubuntu/Debian you can install CouchDB with:

$ sudo apt-get install couchdb

Wireshark (any version)

Pcapr.Local will automatically use the installed version of tshark (a component of Wireshark) to create the pcap indexes. When using a package manager (such as aptitude on Ubuntu), you might need to install tshark command line utility separately if it's not included as part of the Wireshark installation.

Zip (any version)

Pcapr.Local requires zip to create PAR files from your indexed pcaps.

Running pcapr.Local

  1. Install the gem.
  2. Run the "startpcapr" executable that is installed with the gem:

    $ startpcapr

This configuration script asks you some basic questions and records your answers in a config file at ~/.pcapr_local/config that will be used on subsequent invocations. After collecting configuration information, the server process returns a prompt but continues running in the background. To monitor the process, tail the pcapr.Local log file with:

$ tail -F ~/pcapr.Local/log/server.log
  1. Add your packet capture files to the pcap directory you configured (default ~/pcapr.Local/pcaps) and wait a few minutes for pcap.Local to index them.
  2. Point your web browser to http://localhost:8080 (or whatever you configured).
  3. Stop the pcapr.Local server with:

    $ stoppcapr

Creating PAR Files

A PAR file (Pcap ARchive) is a format that can be imported into Mu Studio to create a Scenario. Although a PAR file is equivalent to a pcap file for the purposes of Scenario creation, because a PAR contains dissection data from your local Wireshark installation, you'll get the full benefits of any custom dissectors used by that installation. Additionally, when you import a PAR file you'll bypass flow selection and go directly to the Scenario Editor.

In the Web UI

Point your web browser to http://localhost:8080 (or whatever you configured), then select a pcap to view its details. At the bottom of the details page, click the Download PAR File link.

On the Command Line

The gem bundles a CLI tool for creating PAR files called 'pcap2par'. To use, just provide a path to your pcap:

$  pcap2par my_traffic.pcap

This creates a PAR file called "export.par" in the current directory. You can optionally specify the name of the output file as a second argument:

$ pcap2par my_traffic.pcap ~/par_files/my_traffic.par 
Something went wrong with that request. Please try again.