DevRelay

A MITM (Man-in-the-Middle) proxy that removes security headers from HTTP requests and responses, allowing for easier web development and testing.

Features

• Supports TLS 1.2 or greater
• HTTP/2 and HTTP/3 support
• WebSocket support
• Automatic certificate management in ~/.mitmproxy
• Simple CLI interface

Installation

Option 1: Install with pipx (Recommended)

pipx installs the package in an isolated environment and makes it available globally:

# Install from local directory
pipx install .

# Or install directly from git repository
pipx install git+https://github.com/yourusername/devrelay.git

Option 2: Install with pip

# Install globally (may require sudo/admin)
pip install .

# Or install in user directory
pip install --user .

# Or install in development mode
pip install -e .

Option 3: Development Setup

For development with all dev tools:

# Using make (requires uv)
make dev

# Or manually with pip
pip install -e ".[dev]"

Quick Start

Prerequisites

• Python 3.13 or later
• For development: uv package manager (optional)

Running the Proxy

After installation, start the proxy with default settings (localhost:8080):

# If installed with pip/pipx
devrelay

# Or run as a Python module
python -m devrelay

# For development setup
make run

Run with custom options:

devrelay --host 0.0.0.0 --port 9090

# Or with Python module
python -m devrelay --host 0.0.0.0 --port 9090

Configure Your Browser

To use the proxy, configure your browser to use it:

1. Set HTTP/HTTPS proxy to 127.0.0.1:8080 (or your custom host/port)
2. On first use, you'll need to install the mitmproxy certificate:
   • Visit http://mitm.it in your proxied browser
   • Follow the instructions to install the certificate for your OS

CLI Options

devrelay [-h] [--host HOST] [--port PORT] [--certdir CERTDIR] [--disable-addon ADDON]

Options:
  -h, --help              Show help message
  --host HOST             Host address to bind to (default: 127.0.0.1)
  --port PORT             Port to listen on (default: 8080)
  --certdir CERTDIR       Certificate directory (default: ~/.mitmproxy)
  --disable-addon ADDON   Disable specific addon(s) (can be used multiple times)

Disabling Addons

You can selectively disable specific addons using the --disable-addon option. This is useful when you only need to remove specific security headers.

Available addons:

• CSP - Content-Security-Policy remover
• COEP - Cross-Origin-Embedder-Policy remover
• COOP - Cross-Origin-Opener-Policy remover
• CORP - Cross-Origin-Resource-Policy inserter
• CORSInserter - CORS headers inserter for webhooks
• CORSPreflight - CORS preflight handler for webhooks

Examples:

Disable CSP and COEP addons:

devrelay --disable-addon CSP --disable-addon COEP

Disable multiple addons with comma-separated values:

devrelay --disable-addon CSP,COEP,COOP

Combine addon disabling with other options:

devrelay --host 0.0.0.0 --port 9090 --disable-addon CSP

You can also use full addon class names:

devrelay --disable-addon CSPRemoverAddon --disable-addon COEPRemoverAddon

Addon names are case-insensitive:

devrelay --disable-addon csp --disable-addon COEP

Configuration File

DevRelay supports configuration via a YAML file located at ~/.mitmproxy/devrelay.yaml. The file is automatically created with default values on first run.

Example configuration:

host: 127.0.0.1
port: 8080
certdir: /home/user/.mitmproxy
disabled_addons:
  - CSP
  - COEP

Configuration precedence (highest to lowest):

1. Command-line arguments
2. YAML configuration file
3. Default values

This means CLI arguments will override values in the YAML file.

Development

Available Make Targets

make help       # Show all available targets
make venv       # Create virtual environment
make install    # Install production dependencies
make dev        # Install development dependencies and pre-commit hooks
make test       # Run tests with coverage
make format     # Format code with black
make lint       # Lint code with flake8
make lintmd     # Lint markdown files with pymarkdownlnt
make typecheck  # Type check with pyright
make check      # Run all checks (format, lint, lintmd, typecheck, test)
make run        # Run the devrelay proxy
make clean      # Remove virtual environment and cache files

Running Tests

make test

This runs pytest with coverage reporting. Coverage reports are generated in:

• Terminal output
• htmlcov/index.html (HTML report)
• coverage.xml (XML report)

Code Quality

Format code:

make format

Run linter:

make lint

Run type checker:

make typecheck

Run all checks at once:

make check

Project Structure

devrelay/
├── devrelay/             # Main package
│   ├── __init__.py       # Module exports
│   ├── __main__.py       # Entry point for python -m devrelay
│   ├── addons.py         # Security header removal addons
│   ├── cli.py            # Command-line interface
│   └── proxy.py          # Proxy server setup
├── tests/                # Test suite
│   ├── __init__.py
│   ├── test_addons.py    # Addon tests
│   ├── test_proxy.py     # Proxy server tests
│   └── test_devrelay.py  # CLI tests
├── pyproject.toml        # Project configuration
├── Makefile              # Build automation
├── .gitignore            # Git ignore patterns
├── README.md             # Human documentation
└── AGENTS.md             # AI agent documentation

How It Works

DevRelay uses mitmproxy to intercept HTTP/HTTPS traffic and modify responses on-the-fly. The proxy includes several addons that remove security headers:

• CSPRemoverAddon: Removes Content-Security-Policy headers
• COEPRemoverAddon: Removes Cross-Origin-Embedder-Policy headers
• COOPRemoverAddon: Removes Cross-Origin-Opener-Policy headers
• CORPInserterAddon: Adds Cross-Origin-Resource-Policy headers to mutations
• CORSInserterForWebhooksAddon: Adds permissive CORS headers to successful mutations
• CORSPreflightForWebhooksAddon: Handles failed OPTIONS requests with CORS headers

This is useful for:

• Testing web applications that have strict security policies
• Developing browser extensions that would otherwise be blocked
• Debugging third-party websites with restrictive headers
• Testing webhook integrations with CORS issues

Security Warning

This tool removes security headers and should only be used for development and testing purposes. Do not use this proxy for general web browsing or on production systems.

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please ensure all tests pass and code is formatted before submitting PRs:

make check