Metadata-Version: 2.4
Name: owl-proxy
Version: 0.1.3
Summary: MITM proxy with CA certificate management - server, client, and certificate tools
Project-URL: Homepage, https://www.olib.ai
Project-URL: Repository, https://github.com/Olib-AI/owl-proxy
Author-email: Olib AI <support@olib.ai>
License-Expression: MIT
Keywords: certificate,https,mitm,owl,proxy,ssl,tls,tunnel
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: click>=8.0.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.2.0; extra == 'dev'
Description-Content-Type: text/markdown

# Owl Proxy

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

## Install

```bash
pip install owl-proxy
```

## Quick Start

```bash
# 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

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

### Export for sharing

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
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:

```bash
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:

```bash
# 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:**
```bash
# 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
