PCAP Analyzer

Ondrej Spanik (iairu.com)

Use at least Python 3.10

---

Contents:

[TOC]

Preparation for first run

Setup virtual env.

Local environment for Python in root directory of this project:

python -m venv .

This way all PIP packages will be installed directly into the folder of choice and not globally, similar to Node.js projects.

Make sure to activate your virtual environment and check that it has properly activated on any new terminal in your project!

Activation

After opening any terminal where you would like to work with the project (run, install packages, etc.), make sure to use an activation script:

​ Windows CMD: Scripts\activate.bat

​ Windows PowerShell: Scripts\activate.ps1

​ Bash: source Scripts/activate

Activation check

If you aren't sure whether the virtual environment has activated using the methods above in your current terminal instance use:

where pip

Which should point you to ./Scripts/pip. If it doesn't, try running another activation script in the folder. Same thing goes for where python, ...

VSCode auto-activate

Then VSCode setup of Python local environment that will guarantee auto-activation of venv on all subsequent new terminal instances:

Ctrl+Shift+P - Select interpreter - Select Interpreter path - Open the ./Scripts/python (generated by venv) directory

Package dependencies

Package installation recommended AFTER virtual env. setup and activated (check using where pip), as not to saturate your global packages.

pip install scapy[complete]

Not all of the aforementioned packages are used in their entirety, but they're available just in case.

Package version check

In case of incompatibilities, detailed information about package versions in requirements.txt generated using pip freeze > requirements.txt.

Most of these packages are installed as dependencies automatically.

Run

Make sure to activate VENV. See "Activation".

To analyze all frames within a .pcap file and print all hexdumps followed by analysis results, simply use:

python . [path to pcap]

Flags and help

To get a list of up-to-date flags use -h

python . -h

Here are some useful flags:

• To set starting frame use -f (or --first).
• To limit frames read and analyzed use -c (or --count).
• To not use default output file use -o (or --output).
• To print to STDOUT instead of a file use --print.

File/folder hierarchy

File/Folder	Explanation
__main__.py	Where all the parts come together - Loads entered and checked arguments - Passes PCAP path to scapy to retrieve an array of packets - Loops over the array analyzing all packets, output based on flags
_analyze.py	The main point of this project. Class Analyze - Init: Gets a packet as a byte sequence, analyzes it - All analyzed parts are accessible as attributes
_args.py	The first thing that really runs - Defines possible arugments and flags that __main__.py can be ran with - Processes arguments using argparse - Checks arguments / flags for errors
_byte.py	Utilites for working with bytes - Delimiting function (for example for MAC addresses) - Bytes to Int function (builtin to Python only on newest versions, so I made my own) - Hexdump function with configurable offset and byte count per row
_close.py	An output for user-caused and user-readable errors, incl. exit codes - Used for unfixable errors caused by user - Not used for errors caused by developer / bugs

Build

Build using pyinstaller, first pip install pyinstaller, then run pyinstaller -F __main__.py in root directory with VENV activated, which will output __main__.exe binary into dist folder. Make sure to copy protocols folder into the dist folder to include with built binary.