Skip to content

Running from Source

IB_U_Z_Z_A_R_Dl edited this page Nov 20, 2026 · 5 revisions

๐Ÿ Running from Source

Use this method if you want to run the application directly from Python source code on Windows, Linux, or macOS.

1. Prerequisites

  • Python: Python 3.14 (see pyproject.toml)
  • Packet Capture Driver / Library:
    • Windows: Install Npcap
    • Linux (Ubuntu 22.04+ / Debian 12+ x64): Install libpcap and python3-venv:
      sudo apt update && sudo apt install libpcap0.8 python3-venv
    • macOS: Built-in libpcap (pre-installed at /usr/lib/libpcap.A.dylib)

2. Clone the Repository

git clone https://github.com/BUZZARDGTA/Session-Sniffer.git
cd Session-Sniffer

3. Setup & Run

โšก Option A: With uv (Recommended)

uv is the recommended dependency and virtual-environment manager for development. It automatically manages .venv, locks dependencies via uv.lock, and installs development tools.

From the repository root:

uv sync --extra dev

Note

  • Linux: Grant raw capture capabilities to Python in .venv:
    sudo setcap cap_net_raw,cap_net_admin,cap_sys_ptrace=eip $(readlink -f .venv/bin/python)
  • macOS: Grant read and write permissions to BPF packet capture devices:
    sudo chmod 666 /dev/bpf*
    (Tip: Alternatively, install Wireshark's ChmodBPF package to retain BPF permissions across reboots).

Launch the application:

uv run python -m session_sniffer

๐Ÿ“ฆ Option B: With standard venv and pip

If you prefer not to use uv, you can manually create a virtual environment and install dependencies:

๐ŸชŸ Windows Setup

python -m venv --upgrade-deps .venv
.venv\Scripts\pip install -e .
.venv\Scripts\python -m session_sniffer

๐Ÿง Linux (Ubuntu / Debian) Setup

python3 -m venv --upgrade-deps .venv
.venv/bin/pip install -e .
sudo setcap cap_net_raw,cap_net_admin,cap_sys_ptrace=eip $(readlink -f .venv/bin/python)
.venv/bin/python -m session_sniffer

๐ŸŽ macOS Setup

python3 -m venv --upgrade-deps .venv
.venv/bin/pip install -e .
sudo chmod 666 /dev/bpf*
.venv/bin/python -m session_sniffer

Tip

Looking to compile a standalone executable instead? See the Building from Source page.