owl-proxy 0.1.5

MITM proxy with CA certificate management - server, client, and certificate tools

Owl Proxy

MITM proxy with CA certificate management — server, client, and certificate tools.

Install

pip install owl-proxy

Quick Start

# 1. Generate CA certificate
owl-proxy cert generate

# 2. Install CA into OS trust store (requires sudo)
owl-proxy cert install

# 3a. Run as a standalone proxy server
owl-proxy server --port 8443 --auth user:pass

# 3b. Run as a local MITM client (direct mode)
owl-proxy client --direct

# 3c. Run client forwarding through a remote server
owl-proxy client --remote http://my-server:8443 --auth user:pass

Certificate Setup

Owl Proxy uses a root CA to sign per-domain certificates for HTTPS interception. Both server and client need the CA certificate and private key.

Generate

owl-proxy cert generate
# Saves to ~/.owl-proxy/ca.crt and ~/.owl-proxy/ca.key

Export for sharing

# Full bundle (cert + key) — for setting up server/client on another machine
owl-proxy cert export -d ./certs

# Certificate only — for browser/OS trust installation
owl-proxy cert export -d ./certs --cert-only

Install to OS trust store

Installs the CA so browsers and system tools trust it automatically:

# Install from default location (~/.owl-proxy/ca.crt)
owl-proxy cert install

# Install from a specific path
owl-proxy cert install --cert ./certs/ca.crt

# Preview commands without executing
owl-proxy cert install --dry-run

What it does per platform:

• macOS: Adds to System Keychain via security add-trusted-cert
• Linux (Debian/Ubuntu): Copies to /usr/local/share/ca-certificates/ + update-ca-certificates
• Linux (RHEL/Fedora): Copies to /etc/pki/ca-trust/source/anchors/ + update-ca-trust
• Windows: Uses certutil -addstore ROOT

Use exported certs on another machine

# Copy the bundle to the target machine, then:
owl-proxy server --ca-cert ./certs/ca.crt --ca-key ./certs/ca.key --auth user:pass
owl-proxy client --ca-cert ./certs/ca.crt --ca-key ./certs/ca.key --remote http://server:8443

Other cert commands

owl-proxy cert info              # Show CA details (CN, expiry, fingerprint)
owl-proxy cert uninstall         # Remove CA from OS trust store

Modes

Server

Run on any machine (Raspberry Pi, VPS, cloud VM, etc.) as a proxy server:

owl-proxy server --host 0.0.0.0 --port 8443 --auth user:pass
owl-proxy server --auth-token my-secret-token
owl-proxy server --no-auth                        # no auth (trusted LAN only)

Client

Run locally as a MITM proxy. Intercepts HTTPS with dynamic per-domain certificates:

# Direct mode — fetches URLs itself (no remote server needed)
owl-proxy client --direct --port 8080

# Remote mode — forwards through an Owl Proxy server
owl-proxy client --remote http://my-server:8443 --auth user:pass --port 8080

# Serve a PAC file for browser auto-configuration
owl-proxy client --direct --pac

Browser Configuration

To use the proxy with a browser, configure it to use the client's address:

System proxy (all browsers):

• macOS: System Settings > Network > Wi-Fi > Details > Proxies > Web Proxy (HTTP) and Secure Web Proxy (HTTPS) — set to 127.0.0.1 port 8080
• Windows: Settings > Network & Internet > Proxy > Manual proxy — set to 127.0.0.1:8080
• Linux (GNOME): Settings > Network > Network Proxy > Manual — set HTTP and HTTPS to 127.0.0.1 port 8080

Firefox (independent proxy settings): Settings > General > Network Settings > Manual proxy configuration — set HTTP Proxy to 127.0.0.1, Port 8080, check "Also use this proxy for HTTPS"

With PAC file (auto-configuration): Start the client with --pac, then point your browser's auto-config URL to:

http://127.0.0.1:8080/proxy.pac

Test with curl:

# HTTP
curl --proxy http://127.0.0.1:8080 http://httpbin.org/ip

# HTTPS (using the CA cert)
curl --proxy http://127.0.0.1:8080 --cacert ~/.owl-proxy/ca.crt https://httpbin.org/ip

Configuration

Settings can be provided via CLI flags, environment variables, or both:

Environment Variable	Description
OWL_PROXY_HOST	Server bind address
OWL_PROXY_PORT	Server bind port
OWL_PROXY_USERNAME	Auth username
OWL_PROXY_PASSWORD	Auth password
OWL_PROXY_TOKEN	Bearer token
OWL_PROXY_TIMEOUT	Request timeout (seconds)
OWL_CLIENT_HOST	Client listen address
OWL_CLIENT_PORT	Client listen port
OWL_REMOTE_SERVER	Remote server URL

Data is stored in ~/.owl-proxy/ by default (respects XDG_DATA_HOME).

Security

• The CA private key (ca.key) can sign certificates for any domain — keep it secure
• Use chmod 600 on ca.key (done automatically by cert generate and cert export)
• Always use --auth in production to prevent unauthorized proxy access
• SSRF protection blocks requests to localhost and private IP ranges