httpjail 0.1.2

Monitor and restrict HTTP/HTTPS requests from processes
Documentation

httpjail

Crates.io CI

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

Install:

cargo install httpjail

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
  • Add a --server mode that runs the proxy server but doesn't execute the command
  • Expand test cases to include WebSockets

Quick Start

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

# Log requests to a file
httpjail --request-log requests.log -r "allow: .*" -- npm install
# Log format: "<timestamp> <+/-> <METHOD> <URL>" (+ = allowed, - = blocked)

# 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.txt -- python script.py

# Run as standalone proxy server (no command execution)
httpjail --server -r "allow: .*"
# Server defaults to ports 8080 (HTTP) and 8443 (HTTPS)
# Configure your application:
# HTTP_PROXY=http://localhost:8080 HTTPS_PROXY=http://localhost:8443

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. Export CA trust env vars                    │
│  5. Execute target process in namespace         │
└─────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────┐
│              Target Process                     │
│  • Isolated in network namespace                │
│  • All HTTP/HTTPS → local proxy                 │
│  • CA cert trusted via env vars                 │
└─────────────────────────────────────────────────┘

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 ✅ Transparent MITM + env CA ✅ Env variables 🚧 Cert store
Sudo required ⚠️ Yes ✅ No 🚧
Force all traffic ✅ Yes ❌ No (apps must cooperate) 🚧

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)

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.txt (one rule per line, # comments and blank lines are ignored):

# rules.txt
allow-get: github\.com
deny: telemetry
allow: .*

Use the config:

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

Advanced Options

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

# Server mode - run as standalone proxy without executing commands
httpjail --server -r "allow: github\.com" -r "deny: .*"
# Server defaults to ports 8080 (HTTP) and 8443 (HTTPS)

# Server mode with custom ports (format: port or ip:port)
HTTPJAIL_HTTP_BIND=3128 HTTPJAIL_HTTPS_BIND=3129 httpjail --server -r "allow: .*"
# Configure applications: HTTP_PROXY=http://localhost:3128 HTTPS_PROXY=http://localhost:3129

# Bind to specific interface
HTTPJAIL_HTTP_BIND=192.168.1.100:8080 httpjail --server -r "allow: .*"

Server Mode

httpjail can run as a standalone proxy server without executing any commands. This is useful when you want to proxy multiple applications through the same httpjail instance. The server binds to localhost (127.0.0.1) only for security.

# Start server with default ports (8080 for HTTP, 8443 for HTTPS) on localhost
httpjail --server -r "allow: github\.com" -r "deny: .*"
# Output: Server running on ports 8080 (HTTP) and 8443 (HTTPS). Press Ctrl+C to stop.

# Start server with custom ports using environment variables
HTTPJAIL_HTTP_BIND=3128 HTTPJAIL_HTTPS_BIND=3129 httpjail --server -r "allow: .*"
# Output: Server running on ports 3128 (HTTP) and 3129 (HTTPS). Press Ctrl+C to stop.

# Bind to all interfaces (use with caution - exposes proxy to network)
HTTPJAIL_HTTP_BIND=0.0.0.0:8080 HTTPJAIL_HTTPS_BIND=0.0.0.0:8443 httpjail --server -r "allow: .*"
# Output: Server running on ports 8080 (HTTP) and 8443 (HTTPS). Press Ctrl+C to stop.

# Configure your applications to use the proxy:
export HTTP_PROXY=http://localhost:8080
export HTTPS_PROXY=http://localhost:8443
curl https://github.com  # This request will go through httpjail

Note: In server mode, httpjail does not create network isolation. Applications must be configured to use the proxy via environment variables or application-specific proxy settings.

TLS Interception

httpjail performs HTTPS interception using a locally-generated Certificate Authority (CA). The tool does not modify your system trust store. Instead, it configures the jailed process to trust the httpjail CA via environment variables.

How it works:

  1. CA generation (first run): A unique CA keypair is created and persisted.
  2. Persistent storage (via dirs::config_dir()):
    • macOS: ~/Library/Application Support/httpjail/
    • Linux: ~/.config/httpjail/
    • Windows: %APPDATA%\httpjail\ Files: ca-cert.pem, ca-key.pem (key is chmod 600 on Unix).
  3. Per‑process trust via env vars: For the jailed command, httpjail sets common variables so clients trust the CA without touching system stores:
    • SSL_CERT_FILE and SSL_CERT_DIR
    • CURL_CA_BUNDLE
    • GIT_SSL_CAINFO
    • REQUESTS_CA_BUNDLE
    • NODE_EXTRA_CA_CERTS These apply on both Linux (strong/transparent mode) and macOS (--weak env‑only mode).
  4. Transparent MITM:
    • Linux strong mode redirects TCP 80/443 to the local proxy. HTTPS is intercepted transparently by extracting SNI from ClientHello and presenting a per‑host certificate signed by the httpjail CA.
    • macOS uses explicit proxying via HTTP_PROXY/HTTPS_PROXY and typically negotiates HTTPS via CONNECT; interception occurs after CONNECT.
  5. No system trust changes: httpjail never installs the CA into OS trust stores; there is no global modification and thus no trust cleanup step. The CA files remain in the config dir for reuse across runs.

Notes and limits:

  • Tools that ignore the above env vars will fail TLS verification when intercepted. For those, add tool‑specific flags to point at ca-cert.pem.
  • Long‑lived connections are supported: timeouts are applied only to protocol detection, CONNECT header reads, and TLS handshakes — not to proxied streams (e.g., gRPC/WebSocket).

License

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