httpjail 0.1.0

Monitor and restrict HTTP/HTTPS requests from processes
Documentation

httpjail

A cross-platform tool for monitoring and restricting HTTP/HTTPS requests from processes using network isolation and transparent proxy interception.

Features

  • 🔒 Process-level network isolation - Isolate processes in restricted network environments
  • 🌐 HTTP/HTTPS interception - Transparent proxy with TLS certificate injection
  • 🎯 Regex-based filtering - Flexible allow/deny rules with regex patterns
  • 📝 Request logging - Monitor and log all HTTP/HTTPS requests
  • 🖥️ Cross-platform - Native support for Linux and macOS
  • ⚡ Zero configuration - Works out of the box with sensible defaults

MVP TODO

  • Update README to be more reflective of AI agent restrictions
  • Block all other TCP/UDP traffic when in jail mode. Exception for UDP to 53. DNS is pretty darn safe.
  • Add a --server mode that runs the proxy server but doesn't execute the command
  • Expand test cases to include WebSockets
  • Add Linux support with parity with macOS
  • Add robust firewall cleanup mechanism for Linux and macOS
  • Support/test concurrent jailing across macOS and Linux

Quick Start

# Allow only requests to github.com
httpjail -r "allow: github\.com" -r "deny: .*" -- claude

# Monitor all requests without blocking
httpjail --log-only -- npm install

# Block specific domains
httpjail -r "deny: telemetry\..*" -r "allow: .*" -- ./my-app

# Method-specific rules
httpjail -r "allow-get: api\.github\.com" -r "deny: .*" -- git pull

# Use config file for complex rules
httpjail --config rules.yaml -- python script.py

Architecture Overview

httpjail creates an isolated network environment for the target process, intercepting all HTTP/HTTPS traffic through a transparent proxy that enforces user-defined rules.

Linux Implementation

┌─────────────────────────────────────────────────┐
│                 httpjail Process                │
├─────────────────────────────────────────────────┤
│  1. Create network namespace                    │
│  2. Setup nftables rules                        │
│  3. Start embedded proxy                        │
│  4. Inject CA certificate                       │
│  5. Execute target process in namespace         │
└─────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────┐
│              Target Process                     │
│  • Isolated in network namespace                │
│  • All HTTP/HTTPS → local proxy                 │
│  • CA cert in trust store                       │
└─────────────────────────────────────────────────┘

macOS Implementation

┌─────────────────────────────────────────────────┐
│                 httpjail Process                 │
├─────────────────────────────────────────────────┤
│  1. Start HTTP/HTTPS proxy servers              │
│  2. Set HTTP_PROXY/HTTPS_PROXY env vars         │
│  3. Generate/load CA certificate                │
│  4. Execute target with proxy environment       │
└─────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────┐
│              Target Process                     │
│  • HTTP_PROXY/HTTPS_PROXY environment vars      │
│  • Applications must respect proxy settings     │
│  • CA cert via environment variables            │
└─────────────────────────────────────────────────┘

Note: Due to macOS PF (Packet Filter) limitations, httpjail uses environment-based proxy configuration on macOS. PF translation rules (such as rdr and route-to) cannot match on user or group, making transparent traffic interception impossible. As a result, httpjail operates in "weak mode" on macOS, relying on applications to respect the HTTP_PROXY and HTTPS_PROXY environment variables. Most command-line tools and modern applications respect these settings, but some may bypass them. See also https://github.com/coder/httpjail/issues/7.

Platform Support

Feature Linux macOS Windows
Traffic isolation ✅ Namespaces + nftables ⚠️ Env vars only 🚧 Planned
TLS interception ✅ CA injection ✅ Env variables 🚧 Cert store
Sudo required ⚠️ Yes ✅ No 🚧
Force all traffic ✅ Yes ❌ No (apps must cooperate) 🚧

Installation

Prerequisites

Linux

  • Linux kernel 3.8+ (network namespace support)
  • nftables (nft command)
  • libssl-dev (for TLS)
  • sudo access (for namespace creation)

macOS

  • macOS 10.15+ (Catalina or later)
  • No special permissions required (runs in weak mode)

Install from source

# Clone the repository
git clone https://github.com/yourusername/httpjail
cd httpjail

# Build with Cargo
cargo build --release

# Install to PATH
sudo cp target/release/httpjail /usr/local/bin/

# CA certificate is auto-generated on first run

Install via Cargo

cargo install httpjail

Usage Examples

Basic Usage

# Simple allow/deny rules
httpjail -r "allow: api\.github\.com" -r "deny: .*" -- git pull

# Multiple allow patterns (order matters!)
httpjail \
  -r "allow: github\.com" \
  -r "allow: githubusercontent\.com" \
  -r "deny: .*" \
  -- npm install

# Deny telemetry while allowing everything else
httpjail \
  -r "deny: telemetry\." \
  -r "deny: analytics\." \
  -r "deny: sentry\." \
  -r "allow: .*" \
  -- ./application

# Method-specific rules
httpjail \
  -r "allow-get: api\..*\.com" \
  -r "deny-post: telemetry\..*" \
  -r "allow: .*" \
  -- ./application

Configuration File

Create a rules.yaml:

# rules.yaml
rules:
  - action: allow
    pattern: "github\.com"
    methods: ["GET", "POST"]

  - action: allow
    pattern: "api\..*\.com"
    methods: ["GET"]

  - action: deny
    pattern: "telemetry"

  - action: deny
    pattern: ".*"

logging:
  level: info
  file: /var/log/httpjail.log

Use the config:

httpjail --config rules.yaml -- ./my-application

Advanced Options

# Dry run - log what would be blocked without blocking
httpjail --dry-run --config rules.yaml -- ./app

# Verbose logging
httpjail -vvv --allow ".*" -- curl https://example.com

# Interactive mode - approve/deny requests in real-time
httpjail --interactive -- ./app

TLS Interception

httpjail uses a locally-generated Certificate Authority (CA) to intercept HTTPS traffic:

  1. Automatic CA Generation: On first run, httpjail generates a unique CA certificate
  2. Persistent CA Storage: The CA is cached in the user's config directory:
    • macOS: ~/Library/Application Support/httpjail/
    • Linux: ~/.config/httpjail/
    • Windows: %APPDATA%\httpjail\
  3. Trust Store Injection: The CA is temporarily added to the system trust store
  4. Certificate Generation: Dynamic certificate generation for intercepted domains
  5. Cleanup: CA is removed from trust store after process termination

Security Considerations

  • CA private key is stored with 600 permissions (Unix) in the config directory
  • CA is only trusted for the duration of the jailed process
  • Each httpjail installation has a unique CA
  • The same CA is reused across runs for consistency
  • Certificates are generated on-the-fly and not persisted

Disable TLS Interception

# Only monitor/block HTTP traffic
httpjail --no-tls-intercept --allow ".*" -- ./app

Command-Line Options

httpjail [OPTIONS] -- <COMMAND> [ARGS]

OPTIONS:
    -r, --rule <RULE>            Add a rule (format: "action[-method]: pattern")
                                 Actions: allow, deny
                                 Methods: get, post, put, delete, head, options, connect, trace, patch
    -c, --config <FILE>          Use configuration file
    --dry-run                    Log actions without blocking
    --log-only                   Monitor without filtering
    --no-tls-intercept          Disable HTTPS interception
    --interactive               Interactive approval mode
    --weak                      Use weak mode (env vars only, no system isolation)
    --timeout <SECONDS>         Timeout for command execution
    -v, --verbose               Increase verbosity (-vvv for max)
    -h, --help                  Print help
    -V, --version               Print version

RULE FORMAT:
    Rules are specified with -r/--rule and use the format:
    "action[-method]: pattern"

    Examples:
    -r "allow: github\.com"              # Allow all methods to github.com
    -r "allow-get: api\..*"              # Allow only GET requests to api.*
    -r "deny-post: telemetry\..*"        # Deny POST requests to telemetry.*
    -r "deny: .*"                        # Deny everything (usually last rule)

    Rules are evaluated in the order specified.

EXAMPLES:
    httpjail -r "allow: github\.com" -r "deny: .*" -- git clone https://github.com/user/repo
    httpjail --config rules.yaml -- npm install
    httpjail --dry-run -r "deny: telemetry" -r "allow: .*" -- ./application
    httpjail --weak -r "allow: .*" -- npm test  # Use environment variables only

License

This project is released into the public domain under the CC0 1.0 Universal license. See LICENSE for details.