📡 Traffic Inspector Standalone Lab

A standalone, lightweight HTTP/HTTPS transparent proxy and traffic inspection tool designed for educational purposes, defensive security research, and protocol analysis.

Traffic Inspector intercepts, decrypts, and logs web traffic metadata without modifying, injecting, or altering communications. It provides local dashboard and control panel interfaces to visualize processed network streams and inspect plaintext credentials on the wire.

---

🌟 Core Features

• Transparent HTTP/HTTPS Decryption: Terminates TLS streams dynamically using a dynamically generated local Root Certificate Authority (Root CA) to inspect encrypted payloads.
• Plaintext Credential Extraction: Automatically parses Authorization: Basic headers and application/x-www-form-urlencoded request bodies for credentials.
• Local Control Panel: Hosted locally at http://127.0.0.1:7070, visualizing live network logs and parsed credentials in real-time.
• Client-Facing Certificate Download: Hosted at http://<inspector-ip>:8080, allowing target testing devices to download the Root CA cert and follow simple trust setup steps.
• Rotational File Logging: Outputs traffic streams to structured JSON Lines logs (logs/traffic.jsonl and logs/credentials.jsonl) for forensic auditing.

---

🏗️ Project Architecture

traffic-inspector/
├── .env.template            # Override default ports and settings
├── pyproject.toml           # Package metadata and installation script
├── README.md                # General documentation
├── requirements.txt         # Package dependencies
├── main_cli.py              # Shim entry point to resolve project root path
├── config/
│   └── traffic-inspector.yml # Default configuration options
├── src/
│   ├── __init__.py
│   ├── main.py              # Click CLI entry point
│   ├── core/
│   │   ├── __init__.py
│   │   ├── ca.py            # Certificate Authority generator
│   │   ├── config.py        # Config parser and schema validator
│   │   ├── proxy.py         # HTTP/HTTPS socket proxy core
│   │   └── state_manager.py # Local PID/process state tracker
│   └── utils/
│       ├── __init__.py
│       ├── creds_capture.py # Extractor for plaintext authentication fields
│       ├── log_handler.py   # Rotational logging handler
│       ├── parser.py        # Response metadata parser
│       └── traffic_log.py   # In-memory and disk log ring buffers
├── web/
│   ├── control_panel.html   # Visual HTML panel for live traffic and creds
│   └── dashboard.html       # Client certificate trust setup page
└── tests/
    ├── __init__.py
    └── test_config.py       # Configuration and schema validator tests

---

🚀 Getting Started

1. Installation

Install the dependencies:

pip install -r requirements.txt

Alternatively, install the package in editable mode to register the traffic-inspector executable command globally:

pip install -e .

2. Configuration

Initialize the default config file:

python3 main_cli.py init
# Or, if installed globally:
traffic-inspector init

This creates config/traffic-inspector.yml. You can copy .env.template to .env to override specific environment variables.

3. Verification

Validate that your configuration loads correctly:

python3 main_cli.py test

4. Running the Proxy

Start the listeners:

python3 main_cli.py start

You will be greeted with a legal warning. Type YES I UNDERSTAND to proceed (or skip using the -y flag if starting in automated environments).

• Client Dashboard: Browse http://<inspector-ip>:8080/ to download the CA certificate.
• Admin Control Panel: Browse http://127.0.0.1:7070/ to view live traffic logs.

---

📡 Local Transparent Redirection (Linux)

To inspect traffic from the local host transparently (or if this machine is configured as a network gateway/router), enable IP forwarding and configure iptables to redirect ports 80 and 443 into the proxy's transparent ports:

# 1. Enable IPv4 Forwarding
sudo sysctl -w net.ipv4.ip_forward=1

# 2. Redirect HTTP and HTTPS to local proxy ports
sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8081
sudo iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 8443

# 3. Clean up rules when done
sudo iptables -t nat -F PREROUTING
sudo sysctl -w net.ipv4.ip_forward=0

---

🧪 Running Tests

To run the automated test suite:

pytest tests/ -v

---

🛡️ Educational Purpose & Disclaimer

This tool is intended for defensive security audits, penetration testing validation, and security training. It must only be used on targets where you possess explicit, written authorization. All logged events are stored locally on the hosting machine, preventing external data leaks.