HTTPSeal

HTTPSeal is a Linux command-line tool for intercepting and analyzing HTTPS/HTTP traffic from specific processes using namespace isolation and DNS hijacking.

Demo

Note: Any API keys shown in the demo have been removed and invalidated for security purposes.

About the Name

HTTPSeal combines "HTTP/HTTPS" with "Seal" - representing the secure encapsulation and isolation of process traffic within a controlled environment. The name is a playful homage to Wireshark 🦈, the legendary network analysis tool. While Wireshark hunts through entire network oceans, HTTPSeal is the specialized marine hunter that focuses precisely on HTTP/HTTPS streams within isolated process territories.

Key Advantages

🎯 Unique Process Isolation: Unlike global proxy tools (mitmproxy, Burp), HTTPSeal only affects processes it launches - no impact on your system or other applications

⚡ Simple Configuration: Target applications need no proxy settings or modifications - just run them with HTTPSeal and they're automatically intercepted

🔐 Advanced Certificate Management: Fully automatic CA handling with XDG-compliant persistent storage (default: $XDG_CONFIG_HOME/httpseal/ca/) - certificates reused between sessions for better performance

🔧 Linux-Native Architecture: Built specifically for Linux using namespace isolation, user namespaces, and bind mounts for maximum security and efficiency

🦈 Wireshark Integration: HTTP mirror server creates real-time plain HTTP replicas of decrypted HTTPS traffic - analyze TLS 1.3 traffic in Wireshark with minimal setup

📊 Multiple Output Formats: Native HAR (HTTP Archive) support for browser dev tools, plus JSON, CSV, and text with dual logging system

🌐 SOCKS5 Proxy Support: Built-in SOCKS5 proxy support with authentication for bypassing network restrictions

⚙️ Configuration-Driven: XDG-compliant JSON configuration files with CLI override capability and practical defaults

Architecture

HTTPSeal combines several Linux technologies to create isolated HTTPS/HTTP interception:

Mount Namespace Isolation: Uses user namespaces with UID mapping (unshare --map-root-user) for isolated filesystem views
DNS Hijacking: Replaces /etc/resolv.conf to redirect DNS queries to local server
IP Address Mapping: Maps domain names to localhost addresses (127.0.0.0/8 range)
HTTPS Proxy: Intercepts traffic on port 443 and performs MITM decryption
HTTP Proxy: Intercepts plain HTTP traffic on port 80 (when enabled)
Certificate Authority: Dynamically generates and caches certificates for target domains (HTTPS only)
Automatic CA Integration: Merges HTTPSeal CA with system CA bundle in isolated namespace
Environment Configuration: Sets SSL/TLS environment variables for transparent certificate usage

Requirements

Operating System: Linux (kernel 3.8+ for user namespace support)
Linux Capabilities:
- CAP_NET_BIND_SERVICE: For binding to privileged ports (80, 443)
- HTTPSeal uses user namespace UID mapping for mount operations (no CAP_SYS_ADMIN required)

Installation

Build from Source

# Clone the repository
git clone https://github.com/hmgle/httpseal.git
cd httpseal

# Build the binary
make build

# Install with required capabilities
sudo make install

Manual Installation

# Build
go build -o httpseal ./cmd/httpseal

# Install binary to any directory in your PATH (examples shown)
sudo cp httpseal /usr/local/bin/          # System-wide installation
# OR
# cp httpseal ~/.local/bin/                 # User-local installation
# OR
# cp httpseal /any/directory/in/your/PATH/  # Custom PATH directory

# IMPORTANT: Set required capability (only CAP_NET_BIND_SERVICE needed)
# Replace the path below with your actual installation directory
sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/httpseal
# OR for user-local installation:
# sudo setcap 'cap_net_bind_service=+ep' ~/.local/bin/httpseal

Usage

Basic Usage

# Intercept HTTPS traffic
httpseal -vv -- wget https://api.github.com/users/octocat

# Intercept HTTP traffic (requires --enable-http flag)
httpseal -vv --enable-http -- curl http://httpbin.org/get

# Intercept both HTTPS and HTTP traffic
httpseal -vv --enable-http -- curl -v https://httpbin.org/get http://httpbin.org/headers

# Intercept any command with mixed traffic
httpseal -vv --enable-http -- python3 -c "import urllib.request; urllib.request.urlopen('http://example.com')"

Advanced Usage

# Verbose mode with all traffic details (HTTPS and HTTP)
httpseal -v --enable-http -- curl -v https://httpbin.org/get http://httpbin.org/headers

# Extra verbose mode - shows all response bodies including binary content
httpseal -vv -- curl https://httpbin.org/get

# Use -vv for extra verbose (equivalent to old -V flag)
httpseal -vv --enable-http -- wget https://baidu.com

# Save mixed traffic to file in JSON format
httpseal --enable-http -o traffic.json --format json -- wget http://httpbin.org/get https://api.github.com/users/octocat

# Save traffic in HAR format for browser dev tools analysis
httpseal -o performance.har --format har -- curl https://api.github.com/users/octocat

# Use SOCKS5 proxy to bypass restrictions
httpseal --socks5-addr 127.0.0.1:1080 -- curl https://www.google.com

# Combine HAR output with Wireshark mirroring and SOCKS5
httpseal --socks5-addr 127.0.0.1:1080 --enable-mirror -o traffic.har --format har -- curl https://restricted-api.com

# HTTP-only monitoring with custom port
httpseal --enable-http --http-port 8080 -q -o http-traffic.log -- some-http-app

# Filter specific domains and limit body size (works for both protocols)
httpseal --enable-http --filter-domain httpbin.org --max-body-size 1024 -- curl http://httpbin.org/get https://httpbin.org/json

# Minimal logging level for both HTTP and HTTPS
httpseal --enable-http --log-level minimal -o summary.txt -- wget http://httpbin.org/json

# 🦈 Wireshark Integration - Mirror both HTTPS and HTTP traffic
httpseal --enable-http --enable-mirror -- curl https://api.github.com/users/octocat http://httpbin.org/get

# Custom mirror port for Wireshark analysis of mixed traffic
httpseal --enable-http --enable-mirror --mirror-port 9090 -- wget https://httpbin.org/get http://httpbin.org/headers

# HAR format for browser dev tools and performance analysis
httpseal -o traffic.har --format har -- curl https://api.github.com/users/octocat

# Configuration file with advanced settings
httpseal --config ./my-config.json -- curl https://api.github.com/users/octocat

# Advanced filtering with session tracking and size limits
httpseal --filter-domain api.github.com --max-body-size 2048 --exclude-content-type image/ -o filtered.csv --format csv -- curl https://api.github.com/users/octocat

# SOCKS5 proxy support (useful for bypassing network restrictions)
httpseal --socks5-addr 127.0.0.1:1080 -- curl https://www.google.com

# SOCKS5 with authentication
httpseal --socks5-addr 127.0.0.1:1080 --socks5-user myuser --socks5-pass mypass -- wget https://github.com

# Configuration file usage
httpseal --config ./my-config.json -- curl https://httpbin.org/get

# Dual logging - minimal console, verbose file
httpseal --log-level minimal --file-log-level verbose -o detailed.log -- curl https://api.github.com/users/octocat

# Advanced filtering and connection management
httpseal --filter-domain github.com --connection-timeout 60 --max-body-size 2048 -- curl https://api.github.com/users/octocat

# Certificate reuse for performance (automatic with persistent CA directory)
httpseal --ca-dir ./my-ca -o traffic.json -- curl https://api.github.com/users/octocat

🌊 Wireshark Integration (HTTP Mirror)

HTTPSeal features an HTTP Mirror Server that creates real-time HTTP replicas of decrypted HTTPS traffic and plain HTTP traffic, enabling Wireshark analysis without complex TLS certificate configuration.

How It Works

Client → HTTPSeal (HTTPS Proxy) → Real Server
             ↓
    HTTP Mirror Server (localhost:8080)
             ↓
        Wireshark Capture

HTTPS Interception: HTTPSeal intercepts and decrypts HTTPS traffic as usual
HTTP Mirroring: Decrypted traffic is replicated as plain HTTP on a local port
Wireshark Analysis: Capture the mirror port to see all HTTPS traffic in plain text

Quick Start with Wireshark

# Terminal 1: Start Wireshark and capture on loopback interface
wireshark -i lo -f "tcp port 8080"

# Terminal 2: Run HTTPSeal with mirror enabled
httpseal --enable-mirror -- curl https://api.github.com/users/octocat

Mirror Features

🔥 Simplified TLS Analysis: No certificate imports, no key files - just capture HTTP traffic
📊 Broad Protocol Support: Works with all TLS versions (1.2, 1.3, modern cipher suites)
🎯 Real-time Streaming: Traffic appears in Wireshark as it's intercepted
🏷️ Preserved Headers: Original domain info preserved with X-HTTPSeal-* headers
⚡ Efficient Mirroring: Minimal overhead, goroutine-based mirroring

Mirror Options

# Enable mirror server (default port 8080)
httpseal --enable-mirror -- <command>

# Custom mirror port
httpseal --enable-mirror --mirror-port 9090 -- <command>

# Combine with other options
httpseal --enable-mirror -v --format json -o traffic.json -- <command>

Wireshark Configuration

Start Wireshark: Capture on loopback interface (lo)
Apply Filter: Use tcp port 8080 (or your custom mirror port)
Run HTTPSeal: Use --enable-mirror flag
Watch Magic: See decrypted HTTPS traffic as readable HTTP in Wireshark!

Why This Approach Works Well

Traditional Wireshark TLS Decryption:

❌ Requires RSA private keys
❌ Only works with RSA key exchange (not modern ECDHE)
❌ C

Httpseal

Install / Use

README