[](https://github.com/abhinavsingh/proxy.py)
[//]: # (DO-NOT-REMOVE-docs-badges-START)
[](https://pypi.org/project/proxy.py/)
[](https://hub.docker.com/r/abhinavsingh/proxy.py)
[](https://github.com/abhinavsingh/proxy.py)
[](https://gitter.im/proxy-py/community)
[](https://github.com/abhinavsingh/proxy.py/blob/develop/LICENSE)
[](https://abhinavsingh.com/proxy-py-a-lightweight-single-file-http-proxy-server-in-python/)
[](https://abhinavsingh.com/proxy-py-a-lightweight-single-file-http-proxy-server-in-python/)
[](https://abhinavsingh.com/proxy-py-a-lightweight-single-file-http-proxy-server-in-python/)
[](https://pypi.org/project/proxy.py/)
[](https://www.python.org/)
[](http://mypy-lang.org/)
[](https://proxypy.readthedocs.io/)
[](https://codecov.io/gh/abhinavsingh/proxy.py)
[](https://github.com/abhinavsingh/proxy.py/actions/workflows/test-library.yml)
[](https://github.com/abhinavsingh/proxy.py/issues)
[](https://twitter.com/imoracle)
[](https://github.com/jaxl-innovations-private-limited)
# Table of Contents
- [Features](#features)
- [Install](#install)
- [Using PIP](#using-pip)
- [Stable version](#stable-version-with-pip)
- [Development version](#development-version-with-pip)
- [Using Docker](#using-docker)
- [Stable version from Docker Hub](#stable-version-from-docker-hub)
- [Development Version from GHCR](#development-version-from-ghcr)
- [Build container locally](#build-development-version-locally)
- [Using HomeBrew](#using-homebrew)
- [Stable version](#stable-version-with-homebrew)
- [Development version](#development-version-with-homebrew)
- [Start proxy.py](#start-proxypy)
- [From command line when installed using PIP](#from-command-line-when-installed-using-pip)
- [Run it](#run-it)
- [Understanding logs](#understanding-logs)
- [Enable DEBUG logging](#enable-debug-logging)
- [From command line using repo source](#from-command-line-using-repo-source)
- [Docker Image](#docker-image)
- [Customize Startup Flags](#customize-startup-flags)
- [Plugin Examples](#plugin-examples)
- [HTTP Proxy Plugins](#http-proxy-plugins)
- [ShortLink Plugin](#shortlinkplugin)
- [Modify Post Data Plugin](#modifypostdataplugin)
- [Mock Api Plugin](#mockrestapiplugin)
- [Redirect To Custom Server Plugin](#redirecttocustomserverplugin)
- [Filter By Upstream Host Plugin](#filterbyupstreamhostplugin)
- [Cache Responses Plugin](#cacheresponsesplugin)
- [Man-In-The-Middle Plugin](#maninthemiddleplugin)
- [Proxy Pool Plugin](#proxypoolplugin)
- [Filter By Client IP Plugin](#filterbyclientipplugin)
- [Modify Chunk Response Plugin](#modifychunkresponseplugin)
- [Cloudflare DNS Resolver Plugin](#cloudflarednsresolverplugin)
- [Custom DNS Resolver Plugin](#customdnsresolverplugin)
- [Custom Network Interface](#customnetworkinterface)
- [Program Name Plugin](#programnameplugin)
- [HTTP Web Server Plugins](#http-web-server-plugins)
- [Web Server Route](#web-server-route)
- [Reverse Proxy Plugins](#reverse-proxy-plugins)
- [Reverse Proxy](#reverse-proxy)
- [Plugin Ordering](#plugin-ordering)
- [End-to-End Encryption](#end-to-end-encryption)
- [TLS Interception](#tls-interception)
- [TLS Interception With Docker](#tls-interception-with-docker)
- [Proxy Over SSH Tunnel](#proxy-over-ssh-tunnel)
- [Proxy Remote Requests Locally](#proxy-remote-requests-locally)
- [Proxy Local Requests Remotely](#proxy-local-requests-remotely)
- [Embed proxy.py](#embed-proxypy)
- [Blocking Mode](#blocking-mode)
- [Non-blocking Mode](#non-blocking-mode)
- [Ephemeral Port](#ephemeral-port)
- [Loading Plugins](#loading-plugins)
- [Unit testing with proxy.py](#unit-testing-with-proxypy)
- [`proxy.TestCase`](#proxytestcase)
- [Override Startup Flags](#override-startup-flags)
- [With `unittest.TestCase`](#with-unittesttestcase)
- [Utilities](#utilities)
- [TCP](#tcp-sockets)
- [new_socket_connection](#new_socket_connection)
- [socket_connection](#socket_connection)
- [Http](#http-client)
- [build_http_request](#build_http_request)
- [build_http_response](#build_http_response)
- [Public Key Infrastructure](#pki)
- [API Usage](#api-usage)
- [CLI Usage](#cli-usage)
- [Run Dashboard](#run-dashboard)
- [Inspect Traffic](#inspect-traffic)
- [Chrome DevTools Protocol](#chrome-devtools-protocol)
- [Frequently Asked Questions](#frequently-asked-questions)
- [Deploying proxy.py in production](#deploying-proxypy-in-production)
- [What not to do?](#what-not-to-do)
- [Via Requirements](#via-requirements)
- [Via Docker Container](#via-docker-container)
- [Integrate your CI/CD with proxy.py](#integrate-your-cicd-with-proxypy)
- [Stable vs Develop](#stable-vs-develop)
- [Release Schedule](#release-schedule)
- [Threads vs Threadless](#threads-vs-threadless)
- [Threadless Remote vs Local Execution Mode](#threadless-remote-vs-local-execution-mode)
- [SyntaxError: invalid syntax](#syntaxerror-invalid-syntax)
- [Unable to load plugins](#unable-to-load-plugins)
- [Unable to connect with proxy.py from remote host](#unable-to-connect-with-proxypy-from-remote-host)
- [Basic auth not working with a browser](#basic-auth-not-working-with-a-browser)
- [Docker image not working on MacOS](#docker-image-not-working-on-macos)
- [`ValueError: filedescriptor out of range in select`](#valueerror-filedescriptor-out-of-range-in-select)
- [None:None in access logs](#nonenone-in-access-logs)
- [OSError when wrapping client for TLS Interception](#oserror-when-wrapping-client-for-tls-interception)
- [Plugin Developer and Contributor Guide](#plugin-developer-and-contributor-guide)
- [High level architecture](#high-level-architecture)
- [Everything is a plugin](#everything-is-a-plugin)
- [Internal Documentation](#internal-documentation)
- [Read The Doc](#read-the-doc)
- [pydoc](#pydoc)
- [pyreverse](#pyreverse)
- [Development Guide](#development-guide)
- [Setup Local Environment](#setup-local-environment)
- [Setup Git Hooks](#setup-git-hooks)
- [Sending a Pull Request](#sending-a-pull-request)
- [Projects Using Proxy.Py](#projects-using-proxypy)
- [Benchmarks](#benchmarks)
- [Flags](#flags)
- [Changelog](https://proxypy.rtfd.io/en/latest/changelog)
- [v2.x](https://proxypy.rtfd.io/en/latest/changelog#v2x)
- [v1.x](https://proxypy.rtfd.io/en/latest/changelog#v1x)
- [v0.x](https://proxypy.rtfd.io/en/latest/changelog#v0x)
[//]: # (DO-NOT-REMOVE-docs-badges-END)
# Features
- Fast & Scalable
- Scale up by using all available cores on the system
- Threadless executions using asyncio
- Made to handle `tens-of-thousands` connections / sec
```console
# On Macbook Pro 2019 / 2.4 GHz 8-Core Intel Core i9 / 32 GB RAM
❯ ./helper/benchmark.sh
CONCURRENCY: 100 workers, TOTAL REQUESTS: 100000 req
Summary:
Success rate: 1.0000
Total: 2.5489 secs
Slowest: 0.0443 secs
Fastest: 0.0006 secs
Average: 0.0025 secs
Requests/sec: 39232.6572
Total data: 1.81 MiB
Size/request: 19 B
Size/sec: 727.95 KiB
Response time histogram:
0.001 [5006] |■■■■■
0.001 [19740] |■■■■■■■■■■■■■■■■■■■■■
0.002 [29701] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
0.002 [21278] |■■■■■■■■■■■■■■■■■■■■■■
0.003 [15376] |■■■■■■■■■■■■■■■■
0.004 [6644] |■■■■■■■
0.004 [1609] |■
0.005 [434] |
0.006 [83] |
0.006 [29] |
0.007 [100] |
Latency distribution:
10% in 0.0014 secs
25% in 0.0018 secs
50% in 0.0023 secs
75% in 0.0030 secs
90% in 0.0036 secs
95% in 0.0040 secs
99% in 0.0047 secs
Details (average, fastest, slowest):
DNS+dialup: 0.0025 secs, 0.0015 secs, 0.0030 secs
DNS-lookup: 0.0000 secs, 0.0000 secs, 0.0001 secs
Status code distribution:
[200] 100000 responses
```
Consult [Threads vs Threadless](#threads-vs-threadless) and [Threadless Remote vs Local Execution Mode](#threadless-remote-vs-local-execution-mode) to control number of CPU cores utilized.
See [Benchmark](https://github.com/abhinavsingh/proxy.py/tree/develop/benchmark#readme) for more details and for how to run benchmarks locally.
- Lightweight
- Uses only `~5-20 MB` RAM
- No memory leaks
- Start once and forget, no restarts required
- Compressed containers size is only `~25 MB`
- No external dependency other than standard Python library
- Programmable
- Customize proxy behavior using [Proxy Server Plugins](#http-proxy-plugins). Example:
- `--plugins proxy.plugin.ProxyPoolPlugin`
- Enable builtin [Web Server](#http-web-server-plugins). Example:
- `--enable-web-server --plugins proxy.plugin.WebServerPlugin`
- Enable builtin [Reverse Proxy Server](#reverse-proxy-plugins). Example:
- `--enable-reverse-proxy --plugins proxy.plugin.ReverseProxyPlugin`
- Plugin API is currently in *development phase*. Expect breaking changes. See [Deploying proxy.py in production](#deploying-proxypy-in-production) on how to ensure reliability across code changes.
- Can listen on multiple ports
- Use `--ports` flag to provide additional ports
- Optionally, use `--port` flag to override default port `8899`
- Capable of serving multiple protocols over the same port
- Real-time Dashboard
- Optionally, enable [proxy.py dashboard](#run-dashboard).
- Use `--enable-dashboard`
- Then, visit `http://localhost:8899/dashboard`
- [Inspect, Monitor, Control and Configure](#inspect-traffic) `proxy.py` at runtime
- [Chrome DevTools Protocol](#chrome-devtools-protocol) support
- Extend dashboard frontend using `typescript` based [plugins](https://github.com/abhinavsingh/proxy.py/tree/develop/dashboard/src/plugins)
- Dashboard is currently in *development phase* Expect breaking changes.
- Secure
- Enable end-to-end encryption between clients and `proxy.py`
- See [End-to-End Encryption](#end-to-end-encryption)
- Private
- Protection against DNS based traffic blockers
- Browse with malware and adult content protection enabled
- See [DNS-over-HTTPS](#cloudflarednsresolverplugin)
- Man-In-The-Middle
- Can decrypt TLS traffic between clients and upstream servers
- See [TLS Interception](#tls-interception)
- Supported http protocols for proxy requests
- `http(s)`
- `http1`
- `http1.1` with pipeline
- `http2`
- `websockets`
- Support for `HAProxy Protocol`
- See `--enable-proxy-protocol` flag
- Static file server support
- See `--enable-static-server` and `--static-server-dir` flags
- Optimized for large file uploads and downloads
- See `--client-recvbuf-size`, `--server-recvbuf-size`, `--max-sendbuf-size` flags
- `IPv4` and `IPv6` support
- See `--hostname` flag
- Unix domain socket support
- See `--unix-socket-path` flag
- Basic authentication support
- See `--basic-auth` flag
- PAC (Proxy Auto-configuration) support
- See `--pac-file` and `--pac-file-url-path` flags
# Install
Consult [Deploying proxy.py in production](#deploying-proxypy-in-production) when deploying production grade applications using `proxy.py`.
## Using PIP
### Stable Version with PIP
Install from `PyPi`
```console
❯ pip install --upgrade proxy.py
```
or from GitHub `master` branch
```console
❯ pip install git+https://github.com/abhinavsingh/proxy.py.git@master
```
### Development Version with PIP
```console
❯ pip install git+https://github.com/abhinavsingh/proxy.py.git@develop
```
## Using Docker
Multi-platform containers are available via:
- Docker Hub
- `latest` tag points to last `stable` release
- `docker pull abhinavsingh/proxy.py:latest`
- GitHub container registry (GHCR)
- `latest` tag points to last `develop` release
- `docker pull ghcr.io/abhinavsingh/proxy.py:latest`
Stable version container releases are available for following platforms:
- `linux/386`
- `linux/amd64`
- `linux/arm/v6`
- `linux/arm/v7`
- `linux/arm64/v8`
- `linux/ppc64le`
- `linux/s390x`
### Stable Version from Docker Hub
Run `proxy.py` latest container:
```console
❯ docker run -it -p 8899:8899 --rm abhinavsingh/proxy.py:latest
```
Docker daemon will automatically pull the matching platform image.
To run specific target platform container on multi-platform supported servers:
```console
❯ docker run -it -p 8899:8899 --rm --platform linux/arm64/v8 abhinavsingh/proxy.py:latest
```
### Development Version from GHCR
Run `proxy.py` container from cutting edge code in the develop branch:
```console
❯ docker run -it -p 8899:8899 --rm ghcr.io/abhinavsingh/proxy.py:latest
```
### Build Development Version Locally
```console
❯ git clone https://github.com/abhinavsingh/proxy.py.git
❯ cd proxy.py && make container
❯ docker run -it -p 8899:8899 --rm abhinavsingh/proxy.py:latest
```
[](https://github.com/moby/vpnkit/issues/469)
`docker` image is currently broken on `macOS` due to incompatibility with [vpnkit](https://github.com/moby/vpnkit/issues/469).
## Using HomeBrew
Updated formulae for `HomeBrew` are maintained in `develop` branch under the `helper/homebrew` directory.
- `stable` formulae installs the package from `master` branch.
- `develop` formulae installs the package from `develop` branch.
### Stable Version with HomeBrew
```console
❯ brew install https://raw.githubusercontent.com/abhinavsingh/proxy.py/develop/helper/homebrew/stable/proxy.rb
```
### Development Version with HomeBrew
```console
❯ brew install https://raw.githubusercontent.com/abhinavsingh/proxy.py/develop/helper/homebrew/develop/proxy.rb
```
# Start proxy.py
## From command line when installed using PIP
When `proxy.py` is installed using `pip`,
an executable named `proxy` is placed under your `$PATH`.
### Run it
Simply type `proxy` on command line to start with default configuration.
```console
❯ proxy
...[redacted]... - Loaded plugin proxy.http.proxy.HttpProxyPlugin
...[redacted]... - Started 8 threadless workers
...[redacted]... - Started 8 acceptors
...[redacted]... - Listening on 127.0.0.1:8899
```
### Understanding logs
Things to notice from above logs:
- `Loaded plugin`
- `proxy.py` will load `proxy.http.proxy.HttpProxyPlugin` by default
- As name suggests, this core plugin adds `http(s)` proxy server capabilities to `proxy.py` instance
- `Started N threadless workers`
- By default, `proxy.py` will start as many worker processes as there are CPU cores on the machine
- Use `--num-workers` flag to customize number of worker processes
- See [Threads vs Threadless](#threads-vs-threadless) to understand how to control execution mode
- `Started N acceptors`
- By default, `proxy.py` will start as many acceptor processes as there are CPU cores on the machine
- Use `--num-acceptors` flag to customize number of acceptor processes
- See [High Level Architecture](#high-level-architecture) to understand relationship between acceptors and workers
- `Started server on ::1:8899`
- By default, `proxy.py` listens on IPv6 `::1`, which is equivalent of IPv4 `127.0.0.1`
- If you want to access `proxy.py` from external host, use `--hostname ::` or `--hostname 0.0.0.0` or bind to any other interface available on your machine.
- See [CustomNetworkInterface](#customnetworkinterface) for how to customize `proxy.py` *public IP seen by upstream servers*.
- `Port 8899`
- Use `--port` flag to customize default TCP port.
### Enable DEBUG logging
All the logs above are `INFO` level logs, default `--log-level` for `proxy.py`
Lets start `proxy.py` with `DEBUG` level logging:
```console
❯ proxy --log-level d
...[redacted]... - Open file descriptor soft limit set to 1024
...[redacted]... - Loaded plugin proxy.http_proxy.HttpProxyPlugin
...[redacted]... - Started 8 workers
...[redacted]... - Started server on ::1:8899
```
You can use single letter to customize log level. Example:
- `d = DEBUG`
- `i = INFO`
- `w = WARNING`
- `e = ERROR`
- `c = CRITICAL`
As we can see from the above logs, before starting up:
- `proxy.py` tried to set open file limit `ulimit` on the system
- Default value for `--open-file-limit` used is `1024`
- `--open-file-limit` flag is a no-op on `Windows` operating systems
See [flags](#flags) for full list of available configuration options.
## From command line using repo source
If you are trying to run `proxy.py` from source code,
there is no binary file named `proxy` in the source code.
To start `proxy.py` from source code follow these instructions:
- Clone repo
```console
❯ git clone https://github.com/abhinavsingh/proxy.py.git
❯ cd proxy.py
```
- Create a Python 3 virtual env
```console
❯ python3 -m venv venv
❯ source venv/bin/activate
```
- Install deps
```console
❯ make lib-dep
```
- Generate `proxy/common/_scm_version.py`
NOTE: *Following step is not necessary for editable installs.*
This file writes SCM detected version to `proxy/common/_scm_version.py` file.
```console
❯ ./write-scm-version.sh
```
- Optionally, run tests
```console
❯ make
```
- Run `proxy.py`
```console
❯ python -m proxy
```
See [Plugin Developer and Contributor Guide](#plugin-developer-and-contributor-guide)
if you plan to work with `proxy.py` source code.
## Docker image
### Customize startup flags
By default `docker` binary is started with IPv4 networking flags:
--hostname 0.0.0.0 --port 8899
You can override flag from command line when starting the docker container. For example, to check `proxy.py` version within the docker container, run:
❯ docker run -it \
-p 8899:8899 \
--rm abhinavsingh/proxy.py:latest \
-v
# Plugin Examples
- See [plugin](https://github.com/abhinavsingh/proxy.py/tree/develop/proxy/plugin) module for full code.
- All the bundled plugin examples also works with `https` traffic
- Require additional flags and certificate generation
- See [TLS Interception](#tls-interception).
- Plugin examples are also bundled with Docker image.
- See [Customize startup flags](#customize-startup-flags) to try plugins with Docker image.
## HTTP Proxy Plugins
### ShortLinkPlugin
Add support for short links in your favorite browsers / applications.
[](https://github.com/abhinavsingh/proxy.py#user-content-shortlinkplugin)
Start `proxy.py` as:
```console
❯ proxy \
--plugins proxy.plugin.ShortLinkPlugin
```
Now you can speed up your daily browsing experience by visiting your
favorite website using single character domain names :). This works
across all browsers.
Following short links are enabled by default:
| Short Link | Destination URL |
| :--------: | :--------------: |
| a/ | `amazon.com` |
| i/ | `instagram.com` |
| l/ | `linkedin.com` |
| f/ | `facebook.com` |
| g/ | `google.com` |
| t/ | `twitter.com` |
| w/ | `web.whatsapp.com` |
| y/ | `youtube.com` |
| proxy/ | `localhost:8899` |
### ModifyPostDataPlugin
Modifies POST request body before sending request to upstream server.
Start `proxy.py` as:
```console
❯ proxy \
--plugins proxy.plugin.ModifyPostDataPlugin
```
By default plugin replaces POST body content with hard-coded `b'{"key": "modified"}'`
and enforced `Content-Type: application/json`.
Verify the same using `curl -x localhost:8899 -d '{"key": "value"}' http://httpbin.org/post`
```console
{
"args": {},
"data": "{\"key\": \"modified\"}",
"files": {},
"form": {},
"headers": {
"Accept": "*/*",
"Content-Length": "19",
"Content-Type": "application/json",
"Host": "httpbin.org",
"User-Agent": "curl/7.54.0"
},
"json": {
"key": "modified"
},
"origin": "1.2.3.4, 5.6.7.8",
"url": "https://httpbin.org/post"
}
```
Note following from the response above:
1. POST data was modified `"data": "{\"key\": \"modified\"}"`.
Original `curl` command data was `{"key": "value"}`.
2. Our `curl` command did not add any `Content-Type` header,
but our plugin did add one `"Content-Type": "application/json"`.
Same can also be verified by looking at `json` field in the output above:
```
"json": {
"key": "modified"
},
```
3. Our plugin also added a `Content-Length` header to match length
of modified body.
### MockRestApiPlugin
Mock responses for your server REST API.
Use to test and develop client side applications
without need of an actual upstream REST API server.
Start `proxy.py` as:
```console
❯ proxy \
--plugins proxy.plugin.ProposedRestApiPlugin
```
Verify mock API response using `curl -x localhost:8899 http://api.example.com/v1/users/`
```console
{"count": 2, "next": null, "previous": null, "results": [{"email": "you@example.com", "groups": [], "url": "api.example.com/v1/users/1/", "username": "admin"}, {"email": "someone@example.com", "groups": [], "url": "api.example.com/v1/users/2/", "username": "admin"}]}
```
Verify the same by inspecting `proxy.py` logs:
```console
... [redacted] ... - access_log:1210 - ::1:64792 - GET None:None/v1/users/ - None None - 0 byte
```
Access log shows `None:None` as server `ip:port`. `None` simply means that
the server connection was never made, since response was returned by our plugin.
Now modify `ProposedRestApiPlugin` to returns REST API mock
responses as expected by your clients.
### RedirectToCustomServerPlugin
Redirects all incoming `http` requests to custom web server.
By default, it redirects client requests to inbuilt web server,
also running on `8899` port.
Start `proxy.py` and enable inbuilt web server:
```console
❯ proxy \
--enable-web-server \
--plugins proxy.plugin.RedirectToCustomServerPlugin
```
Verify using `curl -v -x localhost:8899 http://google.com`
```
... [redacted] ...
< HTTP/1.1 404 NOT FOUND
< Server: proxy.py v1.0.0
< Connection: Close
<
* Closing connection 0
```
Above `404` response was returned from `proxy.py` web server.
Verify the same by inspecting the logs for `proxy.py`.
Along with the proxy request log, you must also see a http web server request log.
```
... [redacted] ... - access_log:1241 - ::1:49525 - GET /
... [redacted] ... - access_log:1157 - ::1:49524 - GET localhost:8899/ - 404 NOT FOUND - 70 bytes
```
### FilterByUpstreamHostPlugin
Drops traffic by inspecting upstream host.
By default, plugin drops traffic for `facebook.com` and `www.facebok.com`.
Start `proxy.py` as:
```console
❯ proxy \
--plugins proxy.plugin.FilterByUpstreamHostPlugin
```
Verify using `curl -v -x localhost:8899 http://facebook.com`:
```console
... [redacted] ...
< HTTP/1.1 418 I'm a tea pot
< Proxy-agent: proxy.py v1.0.0
* no chunk, no close, no size. Assume close to signal end
<
* Closing connection 0
```
Above `418 I'm a tea pot` is sent by our plugin.
Verify the same by inspecting logs for `proxy.py`:
```console
... [redacted] ... - handle_readables:1347 - HttpProtocolException type raised
Traceback (most recent call last):
... [redacted] ...
... [redacted] ... - access_log:1157 - ::1:49911 - GET None:None/ - None None - 0 bytes
```
### CacheResponsesPlugin
Caches Upstream Server Responses.
Start `proxy.py` as:
```console
❯ proxy \
--plugins proxy.plugin.CacheResponsesPlugin
```
You may also use the `--cache-requests` flag to enable request packet caching for inspection.
Verify using `curl -v -x localhost:8899 http://httpbin.org/get`:
```console
... [redacted] ...
< HTTP/1.1 200 OK
< Access-Control-Allow-Credentials: true
< Access-Control-Allow-Origin: *
< Content-Type: application/json
< Date: Wed, 25 Sep 2019 02:24:25 GMT
< Referrer-Policy: no-referrer-when-downgrade
< Server: nginx
< X-Content-Type-Options: nosniff
< X-Frame-Options: DENY
< X-XSS-Protection: 1; mode=block
< Content-Length: 202
< Connection: keep-alive
<
{
"args": {},
"headers": {
"Accept": "*/*",
"Host": "httpbin.org",
"User-Agent": "curl/7.54.0"
},
"origin": "1.2.3.4, 5.6.7.8",
"url": "https://httpbin.org/get"
}
* Connection #0 to host localhost left intact
```
Get path to the cache file from `proxy.py` logs:
```console
... [redacted] ... - GET httpbin.org:80/get - 200 OK - 556 bytes
... [redacted] ... - Cached response at /var/folders/k9/x93q0_xn1ls9zy76m2mf2k_00000gn/T/httpbin.org-1569378301.407512.txt
```
Verify contents of the cache file `cat /path/to/your/cache/httpbin.org.txt`
```console
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Wed, 25 Sep 2019 02:24:25 GMT
Referrer-Policy: no-referrer-when-downgrade
Server: nginx
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Content-Length: 202
Connection: keep-alive
{
"args": {},
"headers": {
"Accept": "*/*",
"Host": "httpbin.org",
"User-Agent": "curl/7.54.0"
},
"origin": "1.2.3.4, 5.6.7.8",
"url": "https://httpbin.org/get"
}
```
### ManInTheMiddlePlugin
Modifies upstream server responses.
Start `proxy.py` as:
```console
❯ proxy \
--plugins proxy.plugin.ManInTheMiddlePlugin
```
Verify using `curl -v -x localhost:8899 http://google.com`:
```console
... [redacted] ...
< HTTP/1.1 200 OK
< Content-Length: 28
<
* Connection #0 to host localhost left intact
Hello from man in the middle
```
Response body `Hello from man in the middle` is sent by our plugin.
### ProxyPoolPlugin
Forward incoming proxy requests to a set of upstream proxy servers.
Let's start 2 upstream proxies first. To simulate upstream proxies,
start `proxy.py` on port `9000` and `9001`
```console
❯ proxy --port 9000
```
```console
❯ proxy --port 9001
```
Now, start `proxy.py` with `ProxyPoolPlugin` (on default `8899` port),
pointing to our upstream proxies at `9000` and `9001` port.
```console
❯ proxy \
--plugins proxy.plugin.ProxyPoolPlugin \
--proxy-pool localhost:9000 \
--proxy-pool localhost:9001
```
Make a curl request via `8899` proxy:
`curl -v -x localhost:8899 http://httpbin.org/get`
Verify that `8899` proxy forwards requests to upstream proxies
by checking respective logs.
If an upstream proxy require credentials, pass them as arguments. Example:
`--proxy-pool user:pass@upstream.proxy:port`
### FilterByClientIpPlugin
Reject traffic from specific IP addresses. By default this
plugin blocks traffic from `127.0.0.1` and `::1`.
Start `proxy.py` as:
```console
❯ proxy \
--plugins proxy.plugin.FilterByClientIpPlugin
```
Send a request using `curl -v -x localhost:8899 http://google.com`:
```console
... [redacted] ...
> Proxy-Connection: Keep-Alive
>
< HTTP/1.1 418 I'm a tea pot
< Connection: close
<
* Closing connection 0
```
Modify plugin to your taste e.g. Allow specific IP addresses only.
### ModifyChunkResponsePlugin
This plugin demonstrate how to modify chunked encoded responses. In able to do so, this plugin uses `proxy.py` core to parse the chunked encoded response. Then we reconstruct the response using custom hard-coded chunks, ignoring original chunks received from upstream server.
Start `proxy.py` as:
```console
❯ proxy \
--plugins proxy.plugin.ModifyChunkResponsePlugin
```
Verify using `curl -v -x localhost:8899 http://httpbin.org/stream/5`:
```console
... [redacted] ...
modify
chunk
response
plugin
* Connection #0 to host localhost left intact
* Closing connection 0
```
Modify `ModifyChunkResponsePlugin` to your taste. Example, instead of sending hard-coded chunks, parse and modify the original `JSON` chunks received from the upstream server.
### CloudflareDnsResolverPlugin
This plugin uses `Cloudflare` hosted `DNS-over-HTTPS` [API](https://developers.cloudflare.com/1.1.1.1/encrypted-dns/dns-over-https/make-api-requests/dns-json) (json).
`DoH` mandates a HTTP2 compliant client. Unfortunately `proxy.py`
does not provide that yet, so we use a dependency. Install it:
```console
❯ pip install "httpx[http2]"
```
Now start `proxy.py` as:
```console
❯ proxy \
--plugins proxy.plugin.CloudflareDnsResolverPlugin
```
By default, `CloudflareDnsResolverPlugin` runs in `security` mode and provides malware protection.
Use `--cloudflare-dns-mode family` to also enable adult content protection too.
### CustomDnsResolverPlugin
This plugin demonstrate how to use a custom DNS resolution implementation with `proxy.py`.
This example plugin currently uses Python's in-built resolution mechanism. Customize code
to your taste. Example, query your custom DNS server, implement `DoH` or other mechanisms.
Start `proxy.py` as:
```console
❯ proxy \
--plugins proxy.plugin.CustomDnsResolverPlugin
```
### CustomNetworkInterface
`HttpProxyBasePlugin.resolve_dns` callback can also be used to configure `network interface` which must be used as the `source_address` for connection to the upstream server.
See [this thread](https://github.com/abhinavsingh/proxy.py/issues/535#issuecomment-961510862)
for more details.
PS: There is no plugin named, but [CustomDnsResolverPlugin](#customdnsresolverplugin)
can be easily customized according to your needs.
### ProgramNamePlugin
Attempts to resolve program `(application)` name for proxy requests originating from the local machine.
If identified, client IP in the access logs is replaced with program name.
Start `proxy.py` as:
```console
❯ proxy \
--plugins proxy.plugin.ProgramNamePlugin
```
Make a request using `curl`:
```console
❯ curl -v -x localhost:8899 https://httpbin.org/get
```
You must see log lines like this:
```console
... [redacted] ... - [I] server.access_log:419 - curl:58096 - CONNECT httpbin.org:443 - 6010 bytes - 1824.62ms
```
Notice `curl` in-place of `::1` or `127.0.0.1` as client IP.
[](#programnameplugin) If `ProgramNamePlugin` does not work reliably on your operating system, kindly contribute by sending a pull request and/or open an issue. Thank you!!!
## HTTP Web Server Plugins
### Web Server Route
Demonstrates inbuilt web server routing using plugin.
Start `proxy.py` as:
```console
❯ proxy --enable-web-server \
--plugins proxy.plugin.WebServerPlugin
```
Verify using `curl -v localhost:8899/http-route-example`, should return:
```console
HTTP route response
```
## Reverse Proxy Plugins
Extends in-built Web Server to add Reverse Proxy capabilities.
### Reverse Proxy
Start `proxy.py` as:
```console
❯ proxy --enable-reverse-proxy \
--plugins proxy.plugin.ReverseProxyPlugin
```
With default configuration, `ReverseProxyPlugin` plugin is equivalent to
following `Nginx` config:
```console
location /get {
proxy_pass http://httpbin.org/get
}
```
Verify using `curl -v localhost:8899/get`:
```console
{
"args": {},
"headers": {
"Accept": "*/*",
"Host": "localhost",
"User-Agent": "curl/7.64.1"
},
"origin": "1.2.3.4, 5.6.7.8",
"url": "https://localhost/get"
}
```
## Plugin Ordering
When using multiple plugins, depending upon plugin functionality,
it might be worth considering the order in which plugins are passed
on the command line.
Plugins are called in the same order as they are passed. Example,
say we are using both `FilterByUpstreamHostPlugin` and
`RedirectToCustomServerPlugin`. Idea is to drop all incoming `http`
requests for `facebook.com` and `www.facebook.com` and redirect other
`http` requests to our inbuilt web server.
Hence, in this scenario it is important to use
`FilterByUpstreamHostPlugin` before `RedirectToCustomServerPlugin`.
If we enable `RedirectToCustomServerPlugin` before `FilterByUpstreamHostPlugin`,
`facebook` requests will also get redirected to inbuilt web server,
instead of being dropped.
# End-to-End Encryption
By default, `proxy.py` uses `http` protocol for communication with clients e.g. `curl`, `browser`. For enabling end-to-end encrypting using `tls` / `https` first generate certificates. **Checkout** the repository and run:
```console
make https-certificates
```
Start `proxy.py` as:
```console
❯ proxy \
--cert-file https-cert.pem \
--key-file https-key.pem
```
Verify using `curl -x https://localhost:8899 --proxy-cacert https-cert.pem https://httpbin.org/get`:
```console
{
"args": {},
"headers": {
"Accept": "*/*",
"Host": "httpbin.org",
"User-Agent": "curl/7.54.0"
},
"origin": "1.2.3.4, 5.6.7.8",
"url": "https://httpbin.org/get"
}
```
If you want to avoid passing `--proxy-cacert` flag, also consider signing generated SSL certificates. Example:
First, generate CA certificates:
```console
make ca-certificates
```
Then, sign SSL certificate:
```console
make sign-https-certificates
```
Now restart the server with `--cert-file https-signed-cert.pem` flag. Note that you must also trust generated `ca-cert.pem` in your system keychain.
# TLS Interception
By default, `proxy.py` will not decrypt `https` traffic between client and server.
To enable TLS interception first generate root CA certificates:
```console
❯ make ca-certificates
```
Lets also enable `CacheResponsePlugin` so that we can verify decrypted
response from the server. Start `proxy.py` as:
```console
❯ proxy \
--plugins proxy.plugin.CacheResponsesPlugin \
--ca-key-file ca-key.pem \
--ca-cert-file ca-cert.pem \
--ca-signing-key-file ca-signing-key.pem
```
[](https://github.com/abhinavsingh/proxy.py#user-content-flags) Also provide explicit CA bundle path needed for validation of peer certificates. See `--ca-file` flag.
Verify TLS interception using `curl`
```console
❯ curl -v -x localhost:8899 --cacert ca-cert.pem https://httpbin.org/get
```
```console
* issuer: C=US; ST=CA; L=SanFrancisco; O=proxy.py; OU=CA; CN=Proxy PY CA; emailAddress=proxyca@mailserver.com
* SSL certificate verify ok.
> GET /get HTTP/1.1
... [redacted] ...
< Connection: keep-alive
<
{
"args": {},
"headers": {
"Accept": "*/*",
"Host": "httpbin.org",
"User-Agent": "curl/7.54.0"
},
"origin": "1.2.3.4, 5.6.7.8",
"url": "https://httpbin.org/get"
}
```
The `issuer` line confirms that response was intercepted.
Also verify the contents of cached response file. Get path to the cache
file from `proxy.py` logs.
`❯ cat /path/to/your/tmp/directory/httpbin.org-1569452863.924174.txt`
```console
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Wed, 25 Sep 2019 23:07:05 GMT
Referrer-Policy: no-referrer-when-downgrade
Server: nginx
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Content-Length: 202
Connection: keep-alive
{
"args": {},
"headers": {
"Accept": "*/*",
"Host": "httpbin.org",
"User-Agent": "curl/7.54.0"
},
"origin": "1.2.3.4, 5.6.7.8",
"url": "https://httpbin.org/get"
}
```
Viola!!! If you remove CA flags, encrypted data will be found in the
cached file instead of plain text.
Now use CA flags with other
[plugin examples](#plugin-examples) to see them work with `https` traffic.
## TLS Interception With Docker
Important notes about TLS Interception with Docker container:
- Since `v2.2.0`, `proxy.py` docker container also ships with `openssl`. This allows `proxy.py`
to generate certificates on the fly for TLS Interception.
- For security reasons, `proxy.py` docker container does not ship with
CA certificates.
Here is how to start a `proxy.py` docker container
with TLS Interception:
1. Generate CA certificates on host computer
```console
❯ make ca-certificates
```
2. Copy all generated certificates into a separate directory. We'll later mount this directory into our docker container
```console
❯ mkdir /tmp/ca-certificates
❯ cp ca-cert.pem ca-key.pem ca-signing-key.pem /tmp/ca-certificates
```
3. Start docker container
```console
❯ docker run -it --rm \
-v /tmp/ca-certificates:/tmp/ca-certificates \
-p 8899:8899 \
abhinavsingh/proxy.py:latest \
--hostname 0.0.0.0 \
--plugins proxy.plugin.CacheResponsesPlugin \
--ca-key-file /tmp/ca-certificates/ca-key.pem \
--ca-cert-file /tmp/ca-certificates/ca-cert.pem \
--ca-signing-key /tmp/ca-certificates/ca-signing-key.pem
```
- `-v /tmp/ca-certificates:/tmp/ca-certificates` flag mounts our CA certificate directory in container environment
- `--plugins proxy.plugin.CacheResponsesPlugin` enables `CacheResponsesPlugin` so that we can inspect intercepted traffic
- `--ca-*` flags enable TLS Interception.
4. From another terminal, try TLS Interception using `curl`. You can omit `--cacert` flag if CA certificate is already trusted by the system.
```console
❯ curl -v \
--cacert ca-cert.pem \
-x 127.0.0.1:8899 \
https://httpbin.org/get
```
5. Verify `issuer` field from response headers.
```console
* Server certificate:
* subject: CN=httpbin.org; C=NA; ST=Unavailable; L=Unavailable; O=Unavailable; OU=Unavailable
* start date: Jun 17 09:26:57 2020 GMT
* expire date: Jun 17 09:26:57 2022 GMT
* subjectAltName: host "httpbin.org" matched cert's "httpbin.org"
* issuer: CN=example.com
* SSL certificate verify ok.
```
6. Back on docker terminal, copy response dump path logs.
```console
...[redacted]... [I] access_log:338 - 172.17.0.1:56498 - CONNECT httpbin.org:443 - 1031 bytes - 1216.70 ms
...[redacted]... [I] close:49 - Cached response at /tmp/httpbin.org-ae1a927d064e4ab386ea319eb38fe251.txt
```
7. In another terminal, `cat` the response dump:
```console
❯ docker exec -it $(docker ps | grep proxy.py | awk '{ print $1 }') cat /tmp/httpbin.org-ae1a927d064e4ab386ea319eb38fe251.txt
HTTP/1.1 200 OK
...[redacted]...
{
...[redacted]...,
"url": "http://httpbin.org/get"
}
```
# Proxy Over SSH Tunnel
**This is a WIP and may not work as documented**
Requires `paramiko` to work.
See [requirements-tunnel.txt](https://github.com/abhinavsingh/proxy.py/blob/develop/requirements-tunnel.txt)
## Proxy Remote Requests Locally
|
+------------+ | +----------+
| LOCAL | | | REMOTE |
| HOST | <== SSH ==== :8900 == | SERVER |
+------------+ | +----------+
:8899 proxy.py |
|
FIREWALL
(allow tcp/22)
## What
Proxy HTTP(s) requests made on a `remote` server through `proxy.py` server
running on `localhost`.
### How
- Requested `remote` port is forwarded over the SSH connection.
- `proxy.py` running on the `localhost` handles and responds to
`remote` proxy requests.
### Requirements
1. `localhost` MUST have SSH access to the `remote` server
2. `remote` server MUST be configured to proxy HTTP(s) requests
through the forwarded port number e.g. `:8900`.
- `remote` and `localhost` ports CAN be same e.g. `:8899`.
- `:8900` is chosen in ascii art for differentiation purposes.
### Try it
Start `proxy.py` as:
```console
❯ # On localhost
❯ proxy --enable-tunnel \
--tunnel-username username \
--tunnel-hostname ip.address.or.domain.name \
--tunnel-port 22 \
--tunnel-remote-port 8899 \
--tunnel-ssh-key /path/to/ssh/private.key \
--tunnel-ssh-key-passphrase XXXXX
...[redacted]... [I] listener.setup:97 - Listening on 127.0.0.1:8899
...[redacted]... [I] pool.setup:106 - Started 16 acceptors in threadless (local) mode
...[redacted]... [I] transport._log:1873 - Connected (version 2.0, client OpenSSH_7.6p1)
...[redacted]... [I] transport._log:1873 - Authentication (publickey) successful!
...[redacted]... [I] listener.setup:116 - SSH connection established to ip.address.or.domain.name:22...
...[redacted]... [I] listener.start_port_forward:91 - :8899 forwarding successful...
```
Make a HTTP proxy request on `remote` server and
verify that response contains public IP address of `localhost` as origin:
```console
❯ # On remote
❯ curl -x 127.0.0.1:8899 http://httpbin.org/get
{
"args": {},
"headers": {
"Accept": "*/*",
"Host": "httpbin.org",
"User-Agent": "curl/7.54.0"
},
"origin": "x.x.x.x, y.y.y.y",
"url": "https://httpbin.org/get"
}
```
Also, verify that `proxy.py` logs on `localhost` contains `remote` IP as client IP.
```console
access_log:328 - remote:52067 - GET httpbin.org:80
```
## Proxy Local Requests Remotely
|
+------------+ | +----------+
| LOCAL | | | REMOTE |
| HOST | === SSH =====> | SERVER |
+------------+ | +----------+
| :8899 proxy.py
|
FIREWALL
(allow tcp/22)
Not planned.
If you have a valid use case, kindly open an issue. You are always welcome to send
contributions via pull-requests to add this functionality :)
> To proxy local requests remotely, make use of [Proxy Pool Plugin](#proxypoolplugin).
# Embed proxy.py
## Blocking Mode
Start `proxy.py` in embedded mode with default configuration
by using `proxy.main` method. Example:
```python
import proxy
if __name__ == '__main__':
proxy.main()
```
Customize startup flags by passing them as kwargs:
```python
import ipaddress
import proxy
if __name__ == '__main__':
proxy.main(
hostname=ipaddress.IPv6Address('::1'),
port=8899
)
```
Note that:
1. `main` is equivalent to starting `proxy.py` from command line.
2. `main` does not accept any `args` (only `kwargs`).
3. `main` will automatically consume any available `sys.argv` as `args`.
3. `main` will block until `proxy.py` shuts down.
## Non-blocking Mode
Start `proxy.py` in non-blocking embedded mode with default configuration
by using `Proxy` context manager: Example:
```python
import proxy
if __name__ == '__main__':
with proxy.Proxy() as p:
# Uncomment the line below and
# implement your app your logic here
proxy.sleep_loop()
```
Note that:
1. `Proxy` is similar to `main`, except `Proxy` will not block.
2. Internally, `Proxy` is a context manager which will start
`proxy.py` when called and will shut it down once the scope ends.
3. Unlike `main`, startup flags with `Proxy` can also be customized
by using `args` and `kwargs`. e.g. `Proxy(['--port', '8899'])` or
by using passing flags as kwargs e.g. `Proxy(port=8899)`.
4. Unlike `main`, `Proxy` will not inspect `sys.argv`.
## Ephemeral Port
Use `--port=0` to bind `proxy.py` on a random port allocated by the kernel.
In embedded mode, you can access this port. Example:
```python
import proxy
if __name__ == '__main__':
with proxy.Proxy() as p:
print(p.flags.port)
proxy.sleep_loop()
```
`flags.port` will give you access to the random port allocated by the kernel.
## Loading Plugins
Users can use `--plugins` flag multiple times to load multiple plugins.
See [Unable to load plugins](#unable-to-load-plugins) if you are running into issues.
When using in embedded mode, you have a few more options. Example:
1. Provide a fully-qualified name of the plugin class as `bytes` to the `proxy.main` method or `proxy.Proxy` context manager.
2. Provide `type` instance of the plugin class. This is especially useful if you plan to define plugins at runtime.
Example, load a single plugin using `--plugins` flag:
```python
import proxy
if __name__ == '__main__':
proxy.main(plugins=['proxy.plugin.CacheResponsesPlugin'])
```
For simplicity, you can also pass the list of plugins as a keyword argument to `proxy.main` or the `Proxy` constructor.
Example:
```python
import proxy
from proxy.plugin import FilterByUpstreamHostPlugin
if __name__ == '__main__':
proxy.main(plugins=[
b'proxy.plugin.CacheResponsesPlugin',
FilterByUpstreamHostPlugin,
])
```
# Unit testing with proxy.py
## `proxy.TestCase`
To setup and tear down `proxy.py` for your Python `unittest` classes, simply use `proxy.TestCase` instead of `unittest.TestCase`.
Example:
```python
import proxy
class TestProxyPyEmbedded(proxy.TestCase):
def test_my_application_with_proxy(self) -> None:
self.assertTrue(True)
```
Note that:
1. `proxy.TestCase` overrides `unittest.TestCase.run()` method to setup and tear down `proxy.py`.
2. `proxy.py` server will listen on a random available port on the system.
This random port is available as `self.PROXY.flags.port` within your test cases.
3. Only a single acceptor and worker is started by default (`--num-workers 1 --num-acceptors 1`) for faster setup and tear down.
4. Most importantly, `proxy.TestCase` also ensures `proxy.py` server
is up and running before proceeding with execution of tests. By default,
`proxy.TestCase` will wait for `10 seconds` for `proxy.py` server to start,
upon failure a `TimeoutError` exception will be raised.
## Override startup flags
To override default startup flags, define a `PROXY_PY_STARTUP_FLAGS` variable in your test class.
Example:
```python
class TestProxyPyEmbedded(TestCase):
PROXY_PY_STARTUP_FLAGS = [
'--num-workers', '2',
'--num-acceptors', '1',
'--enable-web-server',
]
def test_my_application_with_proxy(self) -> None:
self.assertTrue(True)
```
See [test_embed.py] for full working example.
[test_embed.py]:
https://github.com/abhinavsingh/proxy.py/blob/develop/tests/testing/test_embed.py
## With `unittest.TestCase`
If for some reasons you are unable to directly use `proxy.TestCase`,
then simply override `unittest.TestCase.run` yourself to setup and tear down `proxy.py`.
Example:
```python
import unittest
import proxy
class TestProxyPyEmbedded(unittest.TestCase):
def test_my_application_with_proxy(self) -> None:
self.assertTrue(True)
def run(self, result: Optional[unittest.TestResult] = None) -> Any:
with proxy.start([
'--num-workers', '1',
'--num-acceptors', '1',
'--port', '... random port ...']):
super().run(result)
```
or simply setup / tear down `proxy.py` within
`setUpClass` and `teardownClass` class methods.
# Utilities
## TCP Sockets
### new_socket_connection
Attempts to create an IPv4 connection, then IPv6 and
finally a dual stack connection to provided address.
```python
>>> conn = new_socket_connection(('httpbin.org', 80))
>>> ...[ use connection ]...
>>> conn.close()
```
### socket_connection
`socket_connection` is a convenient decorator + context manager
around `new_socket_connection` which ensures `conn.close` is implicit.
As a context manager:
```python
>>> with socket_connection(('httpbin.org', 80)) as conn:
>>> ... [ use connection ] ...
```
As a decorator:
```python
>>> @socket_connection(('httpbin.org', 80))
>>> def my_api_call(conn, *args, **kwargs):
>>> ... [ use connection ] ...
```
## HTTP Client
### build_http_request
- Generate HTTP GET request
```python
>>> build_http_request(b'GET', b'/')
b'GET / HTTP/1.1\r\n\r\n'
```
- Generate HTTP GET request with headers
```python
>>> build_http_request(b'GET', b'/', conn_close=True)
b'GET / HTTP/1.1\r\nConnection: close\r\n\r\n'
```
- Generate HTTP POST request with headers and body
```python
>>> import json
>>> build_http_request(b'POST', b'/form',
headers={b'Content-type': b'application/json'},
body=proxy.bytes_(json.dumps({'email': 'hello@world.com'})))
b'POST /form HTTP/1.1\r\nContent-type: application/json\r\n\r\n{"email": "hello@world.com"}'
```
### build_http_response
```python
build_http_response(
status_code: int,
protocol_version: bytes = HTTP_1_1,
reason: Optional[bytes] = None,
headers: Optional[Dict[bytes, bytes]] = None,
body: Optional[bytes] = None) -> bytes
```
## PKI
### API Usage
- `gen_private_key`
```python
gen_private_key(
key_path: str,
password: str,
bits: int = 2048,
timeout: int = 10) -> bool
```
- `gen_public_key`
```python
gen_public_key(
public_key_path: str,
private_key_path: str,
private_key_password: str,
subject: str,
alt_subj_names: Optional[List[str]] = None,
extended_key_usage: Optional[str] = None,
validity_in_days: int = 365,
timeout: int = 10) -> bool
```
- `remove_passphrase`
```python
remove_passphrase(
key_in_path: str,
password: str,
key_out_path: str,
timeout: int = 10) -> bool
```
- `gen_csr`
```python
gen_csr(
csr_path: str,
key_path: str,
password: str,
crt_path: str,
timeout: int = 10) -> bool
```
- `sign_csr`
```python
sign_csr(
csr_path: str,
crt_path: str,
ca_key_path: str,
ca_key_password: str,
ca_crt_path: str,
serial: str,
alt_subj_names: Optional[List[str]] = None,
extended_key_usage: Optional[str] = None,
validity_in_days: int = 365,
timeout: int = 10) -> bool
```
See [pki.py](https://github.com/abhinavsingh/proxy.py/blob/develop/proxy/common/pki.py) and
[test_pki.py](https://github.com/abhinavsingh/proxy.py/blob/develop/tests/common/test_pki.py)
for usage examples.
### CLI Usage
Use `proxy.common.pki` module for:
1. Generation of public and private keys
2. Generating CSR requests
3. Signing CSR requests using custom CA.
```console
python -m proxy.common.pki -h
usage: pki.py [-h] [--password PASSWORD] [--private-key-path PRIVATE_KEY_PATH]
[--public-key-path PUBLIC_KEY_PATH] [--subject SUBJECT]
action
proxy.py v2.2.0 : PKI Utility
positional arguments:
action Valid actions: remove_passphrase, gen_private_key,
gen_public_key, gen_csr, sign_csr
optional arguments:
-h, --help show this help message and exit
--password PASSWORD Password to use for encryption. Default: proxy.py
--private-key-path PRIVATE_KEY_PATH
Private key path
--public-key-path PUBLIC_KEY_PATH
Public key path
--subject SUBJECT Subject to use for public key generation. Default:
/CN=example.com
```
## Internal Documentation
### Read The Doc
- Visit [proxypy.readthedocs.io](https://proxypy.readthedocs.io/)
- Build locally using:
`make lib-doc`
### pydoc
Code is well documented. Grab the source code and run:
`pydoc3 proxy`
### pyreverse
Generate class level hierarchy UML diagrams for in-depth analysis:
`make lib-pyreverse`
# Run Dashboard
Dashboard is currently under development and not yet bundled with `pip` packages.
To run dashboard, you must checkout the source.
Dashboard is written in Typescript and SCSS, so let's build it first using:
```console
❯ make dashboard
```
Also build the embedded `Chrome DevTools` if you plan on using it:
```console
❯ make devtools
```
Now start `proxy.py` with dashboard plugin and by overriding root directory for static server:
```console
❯ proxy --enable-dashboard --static-server-dir dashboard/public
...[redacted]... - Loaded plugin proxy.http.server.HttpWebServerPlugin
...[redacted]... - Loaded plugin proxy.dashboard.dashboard.ProxyDashboard
...[redacted]... - Loaded plugin proxy.dashboard.inspect_traffic.InspectTrafficPlugin
...[redacted]... - Loaded plugin proxy.http.inspector.DevtoolsProtocolPlugin
...[redacted]... - Loaded plugin proxy.http.proxy.HttpProxyPlugin
...[redacted]... - Listening on ::1:8899
...[redacted]... - Core Event enabled
```
Currently, enabling dashboard will also enable all the dashboard plugins.
Visit dashboard:
```console
❯ open http://localhost:8899/dashboard/
```
## Inspect Traffic
***This is a WIP and may not work as documented***
Wait for embedded `Chrome Dev Console` to load. Currently, detail about all traffic flowing
through `proxy.py` is pushed to the `Inspect Traffic` tab. However, received payloads are not
yet integrated with the embedded developer console.
Current functionality can be verified by opening the `Dev Console` of dashboard and inspecting
the websocket connection that dashboard established with the `proxy.py` server.
[](https://github.com/abhinavsingh/proxy.py)
# Chrome DevTools Protocol
For scenarios where you want direct access to `Chrome DevTools` protocol websocket endpoint,
start `proxy.py` as:
```console
❯ proxy --enable-devtools --enable-events
```
Now point your CDT instance to `ws://localhost:8899/devtools`.
# Frequently Asked Questions
## Deploying proxy.py in production
Listed below are a few strategies for using `proxy.py` in your private/production/corporate projects.
### What not to do?
> You MUST `avoid forking` the repository *"just"* to put your plugin code in `proxy/plugin` directory. Forking is recommended workflow for project contributors, NOT for project users.
- Instead, use one of the suggested approaches from below.
- Then load your plugins using `--plugin`, `--plugins` flags or `plugin` kwargs.
- See [skeleton](https://github.com/abhinavsingh/proxy.py/tree/develop/skeleton) app for example standalone project using `proxy.py`.
### Via Requirements
It is *highly* recommended that you use `proxy.py` via `requirements.txt` or similar dependency management setups. This will allow you to take advantages of regular performance updates, bug fixes, security patches and other improvements happening in the `proxy.py` ecosystem. Example:
1. Use `--pre` option to depend upon last `pre-release`
```console
❯ pip install proxy.py --pre
```
Pre-releases are similar to depending upon `develop` branch code, just that pre-releases may not point to the `HEAD`. This could happen because pre-releases are NOT made available on `PyPi` after every PR merge.
2. Use `TestPyPi` with `--pre` option to depend upon `develop` branch code
```console
❯ pip install -i https://test.pypi.org/simple/ proxy.py --pre
```
A pre-release is made available on `TestPyPi` after every PR merge.
3. Use last `stable` release code
As usual, simply use:
```console
❯ pip install proxy.py
```
### Via Docker Container
If you are into deploying containers, then simply build your image from base `proxy.py` container images.
1. Use `GHCR` to build from `develop` branch code:
```console
FROM ghcr.io/abhinavsingh/proxy.py:latest as base
```
*PS: I use GHCR latest for several production level projects*
2. Use `DockerHub` to build from last `stable` release code:
```console
FROM abhinavsingh/proxy.py:latest as base
```
PS: IMHO, container based strategy is *the best approach* and the only strategy that *I use myself*.
### Integrate your CI/CD with proxy.py
*Hey, but you keep making breaking changes in the develop branch.*
I hear you. And hence, for your production grade applications, you *MUST* integrate application CI/CD with `proxy.py`. You must make sure that your application builds and passes its tests for every PR merge into the `proxy.py` upstream repo.
If your application repository is public, in certain scenarios, PR authors may send patch PRs for all dependents to maintain backward incompatibility and green CI/CD.
CI/CD integration ensure your app continues to build with latest `proxy.py` code. Depending upon where you host your code, use the strategy listed below:
- GitHub
TBD
- Google Cloud Build
TBD
- AWS
TBD
- Azure
TBD
- Others
TBD
> At some stage, we'll deprecate `master` branch segregation and simply maintain a `develop` branch. As dependents can maintain stability via CI/CD integrations. Currently, it's hard for a production grade project to blindly depend upon `develop` branch.
## Stable vs Develop
- `master` branch contains latest `stable` code and is available via `PyPi` repository and `Docker` containers via `docker.io` and `ghcr.io` registries.
Issues reported for `stable` releases are considered with top-priority. However, currently we don't back port fixes into older releases. Example, if you reported an issue in `v2.3.1`, but current `master` branch now contains `v2.4.0rc1`. Then, the fix will land in `v2.4.0rc2`.
- `develop` branch contains cutting edge changes
Development branch is kept stable *(most of the times)*. **But**, if you want *100% reliability* and serving users in *production environment*, ALWAYS use the stable version.
### Release Schedule
A `vX.Y.ZrcN` pull request is created once a month which merges `develop` → `master`. Find below how code flows from a pull request to the next stable release.
1. Development release is deployed from `develop` → `test.pypi.org` after every pull request merge
2. Alpha release is deployed from `develop` → `pypi.org` **before** merging the `vX.Y.Z.rcN` pull request from `develop` → `master` branch. There can be multiple alpha releases made before merging the `rc` pull request
3. Beta release is deployed from `master` → `pypi.org`. Beta releases are made in preparation of `rc` releases and can be skipped if unnecessary
4. Release candidate is deployed from `master` → `pypi.org`. Release candidates are always made available before final stable release
5. Stable release is deployed from `master` → `pypi.org`
## Threads vs Threadless
### `v1.x`
`proxy.py` used to spawn new threads for handling client requests.
### `v2.0+`
`proxy.py` added support for threadless execution of client requests using `asyncio`.
### `v2.4.0+`
Threadless execution was turned ON by default for `Python 3.8+` on `mac` and `linux` environments.
`proxy.py` threadless execution has been reported safe on these environments by our users. If you are running into trouble, fallback to threaded mode using `--threaded` flag.
For `windows` and `Python < 3.8`, you can still try out threadless mode by starting `proxy.py` with `--threadless` flag.
If threadless works for you, consider sending a PR by editing `_env_threadless_compliant` method in the `proxy/common/constants.py` file.
## Threadless Remote vs Local execution mode
Original threadless implementation used `remote` execution mode. This is also depicted under [High level architecture](#high-level-architecture) as ASCII art.
Under `remote` execution mode, acceptors delegate incoming client connection processing to a remote worker process. By default, acceptors delegate connections in round-robin fashion. Worker processing the request may or may not be running on the same CPU core as the acceptor. This architecture scales well for high throughput, but results in spawning two process per CPU core.
Example, if there are N-CPUs on the machine, by default, N acceptors and N worker processes are started. You can tune number of processes using `--num-acceptors` and `--num-workers` flag. You might want more workers than acceptors or vice versa depending upon your use case.
In v2.4.x, `local` execution mode was added, mainly to reduce number of processes spawned by default. This model serves well for day-to-day single user use cases and for developer testing scenarios. Under `local` execution mode, acceptors delegate client connections to a companion thread, instead of a remote process. `local` execution mode ensure CPU affinity, unlike in the `remote` mode where acceptor and worker might be running on different CPU cores.
`--local-executor 1` was made default in v2.4.x series. Under `local` execution mode, `--num-workers` flag has no effect, as no remote workers are started.
To use `remote` execution mode, use `--local-executor 0` flag. Then use `--num-workers` to tune number of worker processes.
## SyntaxError: invalid syntax
`proxy.py` is strictly typed and uses Python `typing` annotations. Example:
```python
>>> my_strings : List[str] = []
>>> #############^^^^^^^^^#####
```
Hence a Python version that understands typing annotations is required.
Make sure you are using `Python 3.6+`.
Verify the version before running `proxy.py`:
`❯ python --version`
All `typing` annotations can be replaced with `comment-only` annotations. Example:
```python
>>> my_strings = [] # List[str]
>>> ################^^^^^^^^^^^
```
It will enable `proxy.py` to run on Python `pre-3.6`, even on `2.7`.
However, as all future versions of Python will support `typing` annotations,
this has not been considered.
## Unable to load plugins
Make sure plugin modules are discoverable by adding them to `PYTHONPATH`. Example:
`PYTHONPATH=/path/to/my/app proxy --plugins my_app.proxyPlugin`
```console
...[redacted]... - Loaded plugin proxy.HttpProxyPlugin
...[redacted]... - Loaded plugin my_app.proxyPlugin
```
OR, simply pass fully-qualified path as parameter, e.g.
`proxy --plugins /path/to/my/app/my_app.proxyPlugin`
Here is a quick working example:
- Contents of `/tmp/plug` folder
```console
╰─ ls -1 /tmp/plug ─╯
my_plugin.py
```
- Custom `MyPlugin` class
```console
╰─ cat /tmp/plug/my_plugin.py ─╯
from proxy.http.proxy import HttpProxyBasePlugin
class MyPlugin(HttpProxyBasePlugin):
pass
```
This is an empty plugin for demonstrating external plugin usage. You must implement necessary methods to make your plugins work for real traffic
- Start `proxy.py` with `MyPlugin`
```console
╰─ PYTHONPATH=/tmp/plug proxy --plugin my_plugin.MyPlugin ─╯
...[redacted]... - Loaded plugin proxy.http.proxy.HttpProxyPlugin
...[redacted]... - Loaded plugin my_plugin.MyPlugin
...[redacted]... - Listening on ::1:8899
```
## Unable to connect with proxy.py from remote host
Make sure `proxy.py` is listening on correct network interface.
Try following flags:
- For IPv6 `--hostname ::`
- For IPv4 `--hostname 0.0.0.0`
## Basic auth not working with a browser
Most likely it's a browser integration issue with system keychain.
- First verify that basic auth is working using `curl`
`curl -v -x username:password@localhost:8899 https://httpbin.org/get`
- See [this thread](https://github.com/abhinavsingh/proxy.py/issues/89#issuecomment-534845710)
for further details.
## Docker image not working on macOS
It's a compatibility issue with `vpnkit`.
See [moby/vpnkit exhausts docker resources](https://github.com/abhinavsingh/proxy.py/issues/43)
and [Connection refused: The proxy could not connect](https://github.com/moby/vpnkit/issues/469)
for some background.
## GCE log viewer integration for proxy.py
A starter [fluentd.conf](https://github.com/abhinavsingh/proxy.py/blob/develop/helper/fluentd.conf)
template is available.
1. Copy this configuration file as `proxy.py.conf` under
`/etc/google-fluentd/config.d/`
2. Update `path` field to log file path as used with `--log-file` flag.
By default `/tmp/proxy.log` path is tailed.
3. Reload `google-fluentd`:
`sudo service google-fluentd restart`
Now `proxy.py` logs can be browsed using
[GCE log viewer](https://console.cloud.google.com/logs/viewer).
## `ValueError: filedescriptor out of range in select`
`proxy.py` is made to handle thousands of connections per second
without any socket leaks.
1. Make use of `--open-file-limit` flag to customize `ulimit -n`.
2. Make sure to adjust `--backlog` flag for higher concurrency.
If nothing helps, [open an issue](https://github.com/abhinavsingh/proxy.py/issues/new)
with `requests per second` sent and output of following debug script:
```console
❯ ./helper/monitor_open_files.sh <proxy-py-pid>
```
## None:None in access logs
Sometimes you may see `None:None` in access logs. It simply means
that an upstream server connection was never established i.e.
`upstream_host=None`, `upstream_port=None`.
There can be several reasons for no upstream connection,
few obvious ones include:
1. Client established a connection but never completed the request.
2. A plugin returned a response prematurely, avoiding connection to upstream server.
## OSError when wrapping client for TLS Interception
With `TLS Interception` on, you might occasionally see following exceptions:
```console
2021-11-06 23:33:34,540 - pid:91032 [E] server.intercept:678 - OSError when wrapping client
Traceback (most recent call last):
...[redacted]...
...[redacted]...
...[redacted]...
ssl.SSLError: [SSL: TLSV1_ALERT_UNKNOWN_CA] tlsv1 alert unknown ca (_ssl.c:997)
...[redacted]... - CONNECT oauth2.googleapis.com:443 - 0 bytes - 272.08 ms
```
Some clients can throw `TLSV1_ALERT_UNKNOWN_CA` if they cannot verify the certificate of the server
because it is signed by an unknown issuer CA. Which is the case when we are doing TLS interception.
This can be for a variety of reasons e.g. certificate pinning etc.
Another exception you might see is `CERTIFICATE_VERIFY_FAILED`:
```console
2021-11-06 23:36:02,002 - pid:91033 [E] handler.handle_readables:293 - Exception while receiving from client connection <socket.socket fd=28, family=AddressFamily.AF_INET, type=SocketKind.SOCK_STREAM, proto=0, laddr=('127.0.0.1', 8899), raddr=('127.0.0.1', 51961)> with reason SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain (_ssl.c:997)')
Traceback (most recent call last):
...[redacted]...
...[redacted]...
...[redacted]...
ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain (_ssl.c:997)
...[redacted]... - CONNECT init.push.apple.com:443 - 0 bytes - 892.99 ms
```
In future, we might support serving original HTTPS content for such clients while still
performing TLS interception in the background. This will keep the clients happy without
impacting our ability to TLS intercept. Unfortunately, this feature is currently not available.
Another example with `SSLEOFError` exception:
```console
2021-11-06 23:46:40,446 - pid:91034 [E] server.intercept:678 - OSError when wrapping client
Traceback (most recent call last):
...[redacted]...
...[redacted]...
...[redacted]...
ssl.SSLEOFError: EOF occurred in violation of protocol (_ssl.c:997)
...[redacted]... - CONNECT stock.adobe.io:443 - 0 bytes - 685.32 ms
```
# Plugin Developer and Contributor Guide
## High level architecture
```console
+-------------+
| |
| Proxy([]) |
| |
+------+------+
|
|
+-----------v--------------+
| |
| AcceptorPool(...) |
| |
+------------+-------------+
|
+-----------------+ | +-----------------+
| | | | |
| Acceptor(..) <-------------+-----------> Acceptor(..) |
| | | |
+---+-------------+ +---------+-------+
| |
| |
| +------++------++------++------++------+ |
| | || || || || | |
+----> || || || || <-----+
| || || || || |
+------++------++------++------++------+
Threadless Worker Processes
```
`proxy.py` is made with performance in mind. By default, `proxy.py`
will try to utilize all available CPU cores to it for accepting new
client connections. This is achieved by starting `AcceptorPool` which
listens on configured server port. Then, `AcceptorPool` starts `Acceptor`
processes (`--num-acceptors`) to accept incoming client connections.
Alongside, if `--threadless` is enabled, `ThreadlessPool` is setup
which starts `Threadless` processes (`--num-workers`) to handle
the incoming client connections.
Each `Acceptor` process delegates the accepted client connection
to a threadless process via `Work` class. Currently, `HttpProtocolHandler`
is the default work class.
`HttpProtocolHandler` simply assumes that incoming clients will follow
HTTP specification. Specific HTTP proxy and HTTP server implementations
are written as plugins of `HttpProtocolHandler`.
See documentation of `HttpProtocolHandlerPlugin` for available lifecycle hooks.
Use `HttpProtocolHandlerPlugin` to add new features for http(s) clients. Example,
See `HttpWebServerPlugin`.
## Everything is a plugin
Within `proxy.py` everything is a plugin.
- We enabled `proxy server` plugins using `--plugins` flag.
Proxy server `HttpProxyPlugin` is a plugin of `HttpProtocolHandler`.
Further, Proxy server allows plugin through `HttpProxyBasePlugin` specification.
- All the proxy server [plugin examples](#plugin-examples) were implementing
`HttpProxyBasePlugin`. See documentation of `HttpProxyBasePlugin` for available
lifecycle hooks. Use `HttpProxyBasePlugin` to modify behavior of http(s) proxy protocol
between client and upstream server. Example,
[FilterByUpstreamHostPlugin](#filterbyupstreamhostplugin).
- We also enabled inbuilt `web server` using `--enable-web-server`.
Web server `HttpWebServerPlugin` is a plugin of `HttpProtocolHandler`
and implements `HttpProtocolHandlerPlugin` specification.
- There also is a `--disable-http-proxy` flag. It disables inbuilt proxy server.
Use this flag with `--enable-web-server` flag to run `proxy.py` as a programmable
http(s) server.
## Development Guide
### Setup Local Environment
Contributors must start `proxy.py` from source to verify and develop new features / fixes.
See [Run proxy.py from command line using repo source](#from-command-line-using-repo-source) for details.
[](https://github.com/abhinavsingh/proxy.py/issues/642#issuecomment-960819271) On `macOS`
you must install `Python` using `pyenv`, as `Python` installed via `homebrew` tends
to be problematic. See linked thread for more details.
### Setup Git Hooks
Pre-commit hook ensures tests are passing.
1. `cd /path/to/proxy.py`
2. `ln -s $(PWD)/git-pre-commit .git/hooks/pre-commit`
Pre-push hook ensures lint and tests are passing.
1. `cd /path/to/proxy.py`
2. `ln -s $(PWD)/git-pre-push .git/hooks/pre-push`
### Sending a Pull Request
Every pull request is tested using GitHub actions.
See [GitHub workflow](https://github.com/abhinavsingh/proxy.py/tree/develop/.github/workflows)
for list of tests.
# Projects Using Proxy.Py
Some of the projects using `proxy.py`
1. [ray-project](https://github.com/ray-project/ray)
2. [aio-libs](https://github.com/aio-libs/aiohttp)
3. [wifipumpkin3](https://github.com/P0cL4bs/wifipumpkin3)
4. [MerossIot](https://github.com/albertogeniola/MerossIot)
5. [pyshorteners](https://github.com/ellisonleao/pyshorteners)
6. [Slack API](https://github.com/slackapi/python-slack-events-api)
7. [ibeam](https://github.com/Voyz/ibeam)
8. [PyPaperBot](https://github.com/ferru97/PyPaperBot)
For full list see [used by](https://github.com/abhinavsingh/proxy.py/network/dependents?package_id=UGFja2FnZS01MjQ0MDY5Ng%3D%3D)
# Benchmarks
See [Benchmark](https://github.com/abhinavsingh/proxy.py/tree/develop/benchmark) directory on how to run benchmark comparisons with other OSS web servers.
To run standalone benchmark for `proxy.py`, use the following command from repo root:
```console
❯ ./helper/benchmark.sh
```
# Flags
```console
❯ proxy -h
usage: -m [-h] [--tunnel-hostname TUNNEL_HOSTNAME] [--tunnel-port TUNNEL_PORT]
[--tunnel-username TUNNEL_USERNAME]
[--tunnel-ssh-key TUNNEL_SSH_KEY]
[--tunnel-ssh-key-passphrase TUNNEL_SSH_KEY_PASSPHRASE]
[--tunnel-remote-port TUNNEL_REMOTE_PORT] [--threadless]
[--threaded] [--num-workers NUM_WORKERS] [--enable-events]
[--local-executor LOCAL_EXECUTOR] [--backlog BACKLOG]
[--hostname HOSTNAME] [--port PORT] [--ports PORTS [PORTS ...]]
[--port-file PORT_FILE] [--unix-socket-path UNIX_SOCKET_PATH]
[--num-acceptors NUM_ACCEPTORS] [--version] [--log-level LOG_LEVEL]
[--log-file LOG_FILE] [--log-format LOG_FORMAT]
[--open-file-limit OPEN_FILE_LIMIT]
[--plugins PLUGINS [PLUGINS ...]] [--enable-dashboard]
[--basic-auth BASIC_AUTH] [--enable-ssh-tunnel]
[--work-klass WORK_KLASS] [--pid-file PID_FILE]
[--enable-proxy-protocol] [--enable-conn-pool] [--key-file KEY_FILE]
[--cert-file CERT_FILE] [--client-recvbuf-size CLIENT_RECVBUF_SIZE]
[--server-recvbuf-size SERVER_RECVBUF_SIZE]
[--max-sendbuf-size MAX_SENDBUF_SIZE] [--timeout TIMEOUT]
[--disable-http-proxy] [--disable-headers DISABLE_HEADERS]
[--ca-key-file CA_KEY_FILE] [--ca-cert-dir CA_CERT_DIR]
[--ca-cert-file CA_CERT_FILE] [--ca-file CA_FILE]
[--ca-signing-key-file CA_SIGNING_KEY_FILE]
[--auth-plugin AUTH_PLUGIN] [--cache-requests]
[--cache-by-content-type] [--cache-dir CACHE_DIR]
[--proxy-pool PROXY_POOL] [--enable-web-server]
[--enable-static-server] [--static-server-dir STATIC_SERVER_DIR]
[--min-compression-length MIN_COMPRESSION_LENGTH]
[--enable-reverse-proxy] [--pac-file PAC_FILE]
[--pac-file-url-path PAC_FILE_URL_PATH]
[--cloudflare-dns-mode CLOUDFLARE_DNS_MODE]
[--filtered-upstream-hosts FILTERED_UPSTREAM_HOSTS]
[--filtered-client-ips-mode FILTERED_CLIENT_IPS_MODE]
[--filtered-client-ips FILTERED_CLIENT_IPS]
[--filtered-url-regex-config FILTERED_URL_REGEX_CONFIG]
proxy.py v2.4.3.dev14+gc6b2de6.d20220605
optional arguments:
-h, --help show this help message and exit
--tunnel-hostname TUNNEL_HOSTNAME
Default: None. Remote hostname or IP address to which
SSH tunnel will be established.
--tunnel-port TUNNEL_PORT
Default: 22. SSH port of the remote host.
--tunnel-username TUNNEL_USERNAME
Default: None. Username to use for establishing SSH
tunnel.
--tunnel-ssh-key TUNNEL_SSH_KEY
Default: None. Private key path in pem format
--tunnel-ssh-key-passphrase TUNNEL_SSH_KEY_PASSPHRASE
Default: None. Private key passphrase
--tunnel-remote-port TUNNEL_REMOTE_PORT
Default: 8899. Remote port which will be forwarded
locally for proxy.
--threadless Default: False. Enabled by default on Python 3.8+
(mac, linux). When disabled a new thread is spawned to
handle each client connection.
--threaded Default: True. Disabled by default on Python < 3.8 and
windows. When enabled a new thread is spawned to
handle each client connection.
--num-workers NUM_WORKERS
Defaults to number of CPU cores.
--enable-events Default: False. Enables core to dispatch lifecycle
events. Plugins can be used to subscribe for core
events.
--local-executor LOCAL_EXECUTOR
Default: 1. Enabled by default. Use 0 to disable. When
enabled acceptors will make use of local (same
process) executor instead of distributing load across
remote (other process) executors. Enable this option
to achieve CPU affinity between acceptors and
executors, instead of using underlying OS kernel
scheduling algorithm.
--backlog BACKLOG Default: 100. Maximum number of pending connections to
proxy server.
--hostname HOSTNAME Default: 127.0.0.1. Server IP address.
--port PORT Default: 8899. Server port. To listen on more ports,
pass them using --ports flag.
--ports PORTS [PORTS ...]
Default: None. Additional ports to listen on.
--port-file PORT_FILE
Default: None. Save server port numbers. Useful when
using --port=0 ephemeral mode.
--unix-socket-path UNIX_SOCKET_PATH
Default: None. Unix socket path to use. When provided
--host and --port flags are ignored
--num-acceptors NUM_ACCEPTORS
Defaults to number of CPU cores.
--version, -v Prints proxy.py version.
--log-level LOG_LEVEL
Valid options: DEBUG, INFO (default), WARNING, ERROR,
CRITICAL. Both upper and lowercase values are allowed.
You may also simply use the leading character e.g.
--log-level d
--log-file LOG_FILE Default: sys.stdout. Log file destination.
--log-format LOG_FORMAT
Log format for Python logger.
--open-file-limit OPEN_FILE_LIMIT
Default: 1024. Maximum number of files (TCP
connections) that proxy.py can open concurrently.
--plugins PLUGINS [PLUGINS ...]
Comma separated plugins. You may use --plugins flag
multiple times.
--enable-dashboard Default: False. Enables proxy.py dashboard.
--basic-auth BASIC_AUTH
Default: No authentication. Specify colon separated
user:password to enable basic authentication.
--enable-ssh-tunnel Default: False. Enable SSH tunnel.
--work-klass WORK_KLASS
Default: proxy.http.HttpProtocolHandler. Work klass to
use for work execution.
--pid-file PID_FILE Default: None. Save "parent" process ID to a file.
--enable-proxy-protocol
Default: False. If used, will enable proxy protocol.
Only version 1 is currently supported.
--enable-conn-pool Default: False. (WIP) Enable upstream connection
pooling.
--key-file KEY_FILE Default: None. Server key file to enable end-to-end
TLS encryption with clients. If used, must also pass
--cert-file.
--cert-file CERT_FILE
Default: None. Server certificate to enable end-to-end
TLS encryption with clients. If used, must also pass
--key-file.
--client-recvbuf-size CLIENT_RECVBUF_SIZE
Default: 128 KB. Maximum amount of data received from
the client in a single recv() operation.
--server-recvbuf-size SERVER_RECVBUF_SIZE
Default: 128 KB. Maximum amount of data received from
the server in a single recv() operation.
--max-sendbuf-size MAX_SENDBUF_SIZE
Default: 64 KB. Maximum amount of data to flush in a
single send() operation.
--timeout TIMEOUT Default: 10.0. Number of seconds after which an
inactive connection must be dropped. Inactivity is
defined by no data sent or received by the client.
--disable-http-proxy Default: False. Whether to disable
proxy.HttpProxyPlugin.
--disable-headers DISABLE_HEADERS
Default: None. Comma separated list of headers to
remove before dispatching client request to upstream
server.
--ca-key-file CA_KEY_FILE
Default: None. CA key to use for signing dynamically
generated HTTPS certificates. If used, must also pass
--ca-cert-file and --ca-signing-key-file
--ca-cert-dir CA_CERT_DIR
Default: ~/.proxy/certificates. Directory to store
dynamically generated certificates. Also see --ca-key-
file, --ca-cert-file and --ca-signing-key-file
--ca-cert-file CA_CERT_FILE
Default: None. Signing certificate to use for signing
dynamically generated HTTPS certificates. If used,
must also pass --ca-key-file and --ca-signing-key-file
--ca-file CA_FILE Default: /Users/abhinavsingh/Dev/proxy.py/venv373/lib/
python3.7/site-packages/certifi/cacert.pem. Provide
path to custom CA bundle for peer certificate
verification
--ca-signing-key-file CA_SIGNING_KEY_FILE
Default: None. CA signing key to use for dynamic
generation of HTTPS certificates. If used, must also
pass --ca-key-file and --ca-cert-file
--auth-plugin AUTH_PLUGIN
Default: proxy.http.proxy.auth.AuthPlugin. Auth plugin
to use instead of default basic auth plugin.
--cache-requests Default: False. Whether to also write request packets
in the cache file.
--cache-by-content-type
Default: False. Whether to extract content by type
from responses. Extracted content type is written to
the cache directory e.g. video.mp4.
--cache-dir CACHE_DIR
Default: /Users/abhinavsingh/.proxy/cache. Flag only
applicable when cache plugin is used with on-disk
storage.
--proxy-pool PROXY_POOL
List of upstream proxies to use in the pool
--enable-web-server Default: False. Whether to enable
proxy.HttpWebServerPlugin.
--enable-static-server
Default: False. Enable inbuilt static file server.
Optionally, also use --static-server-dir to serve
static content from custom directory. By default,
static file server serves out of installed proxy.py
python module folder.
--static-server-dir STATIC_SERVER_DIR
Default: "public" folder in directory where proxy.py
is placed. This option is only applicable when static
server is also enabled. See --enable-static-server.
--min-compression-length MIN_COMPRESSION_LENGTH
Default: 20 bytes. Sets the minimum length of a
response that will be compressed (gzipped).
--enable-reverse-proxy
Default: False. Whether to enable reverse proxy core.
--pac-file PAC_FILE A file (Proxy Auto Configuration) or string to serve
when the server receives a direct file request. Using
this option enables proxy.HttpWebServerPlugin.
--pac-file-url-path PAC_FILE_URL_PATH
Default: /. Web server path to serve the PAC file.
--cloudflare-dns-mode CLOUDFLARE_DNS_MODE
Default: security. Either "security" (for malware
protection) or "family" (for malware and adult content
protection)
--filtered-upstream-hosts FILTERED_UPSTREAM_HOSTS
Default: Blocks Facebook. Comma separated list of IPv4
and IPv6 addresses.
--filtered-client-ips-mode FILTERED_CLIENT_IPS_MODE
Default: blacklist. Can be either "whitelist"
(restrict access to specific IPs)or "blacklist" (allow
everything except specific IPs).
--filtered-client-ips FILTERED_CLIENT_IPS
Default: 127.0.0.1,::1. Comma separated list of IPv4
and IPv6 addresses.
--filtered-url-regex-config FILTERED_URL_REGEX_CONFIG
Default: No config. Comma separated list of IPv4 and
IPv6 addresses.
Proxy.py not working? Report at:
https://github.com/abhinavsingh/proxy.py/issues/new
```
Raw data
{
"_id": null,
"home_page": "https://github.com/abhinavsingh/proxy.py",
"name": "proxy.py",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "http,proxy,http proxy server,proxy server,http server,http web server,proxy framework,web framework,Python3",
"author": "Abhinav Singh",
"author_email": "mailsforabhinav+proxy@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/86/22/069e14dc6367b8f688b42f78793c7dd5c65228d107fa78d466f61334d495/proxy.py-2.4.3.tar.gz",
"platform": null,
"description": "[](https://github.com/abhinavsingh/proxy.py)\n\n[//]: # (DO-NOT-REMOVE-docs-badges-START)\n\n[](https://pypi.org/project/proxy.py/)\n[](https://hub.docker.com/r/abhinavsingh/proxy.py)\n[](https://github.com/abhinavsingh/proxy.py)\n[](https://gitter.im/proxy-py/community)\n[](https://github.com/abhinavsingh/proxy.py/blob/develop/LICENSE)\n\n[](https://abhinavsingh.com/proxy-py-a-lightweight-single-file-http-proxy-server-in-python/)\n[](https://abhinavsingh.com/proxy-py-a-lightweight-single-file-http-proxy-server-in-python/)\n[](https://abhinavsingh.com/proxy-py-a-lightweight-single-file-http-proxy-server-in-python/)\n\n[](https://pypi.org/project/proxy.py/)\n[](https://www.python.org/)\n[](http://mypy-lang.org/)\n\n[](https://proxypy.readthedocs.io/)\n[](https://codecov.io/gh/abhinavsingh/proxy.py)\n[](https://github.com/abhinavsingh/proxy.py/actions/workflows/test-library.yml)\n\n[](https://github.com/abhinavsingh/proxy.py/issues)\n[](https://twitter.com/imoracle)\n[](https://github.com/jaxl-innovations-private-limited)\n\n# Table of Contents\n\n- [Features](#features)\n- [Install](#install)\n - [Using PIP](#using-pip)\n - [Stable version](#stable-version-with-pip)\n - [Development version](#development-version-with-pip)\n - [Using Docker](#using-docker)\n - [Stable version from Docker Hub](#stable-version-from-docker-hub)\n - [Development Version from GHCR](#development-version-from-ghcr)\n - [Build container locally](#build-development-version-locally)\n - [Using HomeBrew](#using-homebrew)\n - [Stable version](#stable-version-with-homebrew)\n - [Development version](#development-version-with-homebrew)\n- [Start proxy.py](#start-proxypy)\n - [From command line when installed using PIP](#from-command-line-when-installed-using-pip)\n - [Run it](#run-it)\n - [Understanding logs](#understanding-logs)\n - [Enable DEBUG logging](#enable-debug-logging)\n - [From command line using repo source](#from-command-line-using-repo-source)\n - [Docker Image](#docker-image)\n - [Customize Startup Flags](#customize-startup-flags)\n- [Plugin Examples](#plugin-examples)\n - [HTTP Proxy Plugins](#http-proxy-plugins)\n - [ShortLink Plugin](#shortlinkplugin)\n - [Modify Post Data Plugin](#modifypostdataplugin)\n - [Mock Api Plugin](#mockrestapiplugin)\n - [Redirect To Custom Server Plugin](#redirecttocustomserverplugin)\n - [Filter By Upstream Host Plugin](#filterbyupstreamhostplugin)\n - [Cache Responses Plugin](#cacheresponsesplugin)\n - [Man-In-The-Middle Plugin](#maninthemiddleplugin)\n - [Proxy Pool Plugin](#proxypoolplugin)\n - [Filter By Client IP Plugin](#filterbyclientipplugin)\n - [Modify Chunk Response Plugin](#modifychunkresponseplugin)\n - [Cloudflare DNS Resolver Plugin](#cloudflarednsresolverplugin)\n - [Custom DNS Resolver Plugin](#customdnsresolverplugin)\n - [Custom Network Interface](#customnetworkinterface)\n - [Program Name Plugin](#programnameplugin)\n - [HTTP Web Server Plugins](#http-web-server-plugins)\n - [Web Server Route](#web-server-route)\n - [Reverse Proxy Plugins](#reverse-proxy-plugins)\n - [Reverse Proxy](#reverse-proxy)\n - [Plugin Ordering](#plugin-ordering)\n- [End-to-End Encryption](#end-to-end-encryption)\n- [TLS Interception](#tls-interception)\n - [TLS Interception With Docker](#tls-interception-with-docker)\n- [Proxy Over SSH Tunnel](#proxy-over-ssh-tunnel)\n - [Proxy Remote Requests Locally](#proxy-remote-requests-locally)\n - [Proxy Local Requests Remotely](#proxy-local-requests-remotely)\n- [Embed proxy.py](#embed-proxypy)\n - [Blocking Mode](#blocking-mode)\n - [Non-blocking Mode](#non-blocking-mode)\n - [Ephemeral Port](#ephemeral-port)\n - [Loading Plugins](#loading-plugins)\n- [Unit testing with proxy.py](#unit-testing-with-proxypy)\n - [`proxy.TestCase`](#proxytestcase)\n - [Override Startup Flags](#override-startup-flags)\n - [With `unittest.TestCase`](#with-unittesttestcase)\n- [Utilities](#utilities)\n - [TCP](#tcp-sockets)\n - [new_socket_connection](#new_socket_connection)\n - [socket_connection](#socket_connection)\n - [Http](#http-client)\n - [build_http_request](#build_http_request)\n - [build_http_response](#build_http_response)\n - [Public Key Infrastructure](#pki)\n - [API Usage](#api-usage)\n - [CLI Usage](#cli-usage)\n- [Run Dashboard](#run-dashboard)\n - [Inspect Traffic](#inspect-traffic)\n- [Chrome DevTools Protocol](#chrome-devtools-protocol)\n- [Frequently Asked Questions](#frequently-asked-questions)\n - [Deploying proxy.py in production](#deploying-proxypy-in-production)\n - [What not to do?](#what-not-to-do)\n - [Via Requirements](#via-requirements)\n - [Via Docker Container](#via-docker-container)\n - [Integrate your CI/CD with proxy.py](#integrate-your-cicd-with-proxypy)\n - [Stable vs Develop](#stable-vs-develop)\n - [Release Schedule](#release-schedule)\n - [Threads vs Threadless](#threads-vs-threadless)\n - [Threadless Remote vs Local Execution Mode](#threadless-remote-vs-local-execution-mode)\n - [SyntaxError: invalid syntax](#syntaxerror-invalid-syntax)\n - [Unable to load plugins](#unable-to-load-plugins)\n - [Unable to connect with proxy.py from remote host](#unable-to-connect-with-proxypy-from-remote-host)\n - [Basic auth not working with a browser](#basic-auth-not-working-with-a-browser)\n - [Docker image not working on MacOS](#docker-image-not-working-on-macos)\n - [`ValueError: filedescriptor out of range in select`](#valueerror-filedescriptor-out-of-range-in-select)\n - [None:None in access logs](#nonenone-in-access-logs)\n - [OSError when wrapping client for TLS Interception](#oserror-when-wrapping-client-for-tls-interception)\n- [Plugin Developer and Contributor Guide](#plugin-developer-and-contributor-guide)\n - [High level architecture](#high-level-architecture)\n - [Everything is a plugin](#everything-is-a-plugin)\n - [Internal Documentation](#internal-documentation)\n - [Read The Doc](#read-the-doc)\n - [pydoc](#pydoc)\n - [pyreverse](#pyreverse)\n - [Development Guide](#development-guide)\n - [Setup Local Environment](#setup-local-environment)\n - [Setup Git Hooks](#setup-git-hooks)\n - [Sending a Pull Request](#sending-a-pull-request)\n- [Projects Using Proxy.Py](#projects-using-proxypy)\n- [Benchmarks](#benchmarks)\n- [Flags](#flags)\n- [Changelog](https://proxypy.rtfd.io/en/latest/changelog)\n - [v2.x](https://proxypy.rtfd.io/en/latest/changelog#v2x)\n - [v1.x](https://proxypy.rtfd.io/en/latest/changelog#v1x)\n - [v0.x](https://proxypy.rtfd.io/en/latest/changelog#v0x)\n\n[//]: # (DO-NOT-REMOVE-docs-badges-END)\n\n# Features\n- Fast & Scalable\n\n - Scale up by using all available cores on the system\n\n - Threadless executions using asyncio\n\n - Made to handle `tens-of-thousands` connections / sec\n\n ```console\n # On Macbook Pro 2019 / 2.4 GHz 8-Core Intel Core i9 / 32 GB RAM\n \u276f ./helper/benchmark.sh\n CONCURRENCY: 100 workers, TOTAL REQUESTS: 100000 req\n\n Summary:\n Success rate:\t1.0000\n Total:\t2.5489 secs\n Slowest:\t0.0443 secs\n Fastest:\t0.0006 secs\n Average:\t0.0025 secs\n Requests/sec:\t39232.6572\n\n Total data:\t1.81 MiB\n Size/request:\t19 B\n Size/sec:\t727.95 KiB\n\n Response time histogram:\n 0.001 [5006] |\u25a0\u25a0\u25a0\u25a0\u25a0\n 0.001 [19740] |\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\n 0.002 [29701] |\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\n 0.002 [21278] |\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\n 0.003 [15376] |\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\n 0.004 [6644] |\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\n 0.004 [1609] |\u25a0\n 0.005 [434] |\n 0.006 [83] |\n 0.006 [29] |\n 0.007 [100] |\n\n Latency distribution:\n 10% in 0.0014 secs\n 25% in 0.0018 secs\n 50% in 0.0023 secs\n 75% in 0.0030 secs\n 90% in 0.0036 secs\n 95% in 0.0040 secs\n 99% in 0.0047 secs\n\n Details (average, fastest, slowest):\n DNS+dialup:\t0.0025 secs, 0.0015 secs, 0.0030 secs\n DNS-lookup:\t0.0000 secs, 0.0000 secs, 0.0001 secs\n\n Status code distribution:\n [200] 100000 responses\n ```\n\n Consult [Threads vs Threadless](#threads-vs-threadless) and [Threadless Remote vs Local Execution Mode](#threadless-remote-vs-local-execution-mode) to control number of CPU cores utilized.\n\n See [Benchmark](https://github.com/abhinavsingh/proxy.py/tree/develop/benchmark#readme) for more details and for how to run benchmarks locally.\n\n- Lightweight\n - Uses only `~5-20 MB` RAM\n - No memory leaks\n - Start once and forget, no restarts required\n - Compressed containers size is only `~25 MB`\n - No external dependency other than standard Python library\n\n- Programmable\n - Customize proxy behavior using [Proxy Server Plugins](#http-proxy-plugins). Example:\n - `--plugins proxy.plugin.ProxyPoolPlugin`\n - Enable builtin [Web Server](#http-web-server-plugins). Example:\n - `--enable-web-server --plugins proxy.plugin.WebServerPlugin`\n - Enable builtin [Reverse Proxy Server](#reverse-proxy-plugins). Example:\n - `--enable-reverse-proxy --plugins proxy.plugin.ReverseProxyPlugin`\n - Plugin API is currently in *development phase*. Expect breaking changes. See [Deploying proxy.py in production](#deploying-proxypy-in-production) on how to ensure reliability across code changes.\n\n- Can listen on multiple ports\n - Use `--ports` flag to provide additional ports\n - Optionally, use `--port` flag to override default port `8899`\n - Capable of serving multiple protocols over the same port\n\n- Real-time Dashboard\n - Optionally, enable [proxy.py dashboard](#run-dashboard).\n - Use `--enable-dashboard`\n - Then, visit `http://localhost:8899/dashboard`\n - [Inspect, Monitor, Control and Configure](#inspect-traffic) `proxy.py` at runtime\n - [Chrome DevTools Protocol](#chrome-devtools-protocol) support\n - Extend dashboard frontend using `typescript` based [plugins](https://github.com/abhinavsingh/proxy.py/tree/develop/dashboard/src/plugins)\n - Dashboard is currently in *development phase* Expect breaking changes.\n\n- Secure\n - Enable end-to-end encryption between clients and `proxy.py`\n - See [End-to-End Encryption](#end-to-end-encryption)\n\n- Private\n - Protection against DNS based traffic blockers\n - Browse with malware and adult content protection enabled\n - See [DNS-over-HTTPS](#cloudflarednsresolverplugin)\n\n- Man-In-The-Middle\n - Can decrypt TLS traffic between clients and upstream servers\n - See [TLS Interception](#tls-interception)\n\n- Supported http protocols for proxy requests\n - `http(s)`\n - `http1`\n - `http1.1` with pipeline\n - `http2`\n - `websockets`\n\n- Support for `HAProxy Protocol`\n - See `--enable-proxy-protocol` flag\n\n- Static file server support\n - See `--enable-static-server` and `--static-server-dir` flags\n\n- Optimized for large file uploads and downloads\n - See `--client-recvbuf-size`, `--server-recvbuf-size`, `--max-sendbuf-size` flags\n\n- `IPv4` and `IPv6` support\n - See `--hostname` flag\n\n- Unix domain socket support\n - See `--unix-socket-path` flag\n\n- Basic authentication support\n - See `--basic-auth` flag\n\n- PAC (Proxy Auto-configuration) support\n - See `--pac-file` and `--pac-file-url-path` flags\n\n# Install\n\nConsult [Deploying proxy.py in production](#deploying-proxypy-in-production) when deploying production grade applications using `proxy.py`.\n\n## Using PIP\n\n### Stable Version with PIP\n\nInstall from `PyPi`\n\n```console\n\u276f pip install --upgrade proxy.py\n```\n\nor from GitHub `master` branch\n\n```console\n\u276f pip install git+https://github.com/abhinavsingh/proxy.py.git@master\n```\n\n### Development Version with PIP\n\n```console\n\u276f pip install git+https://github.com/abhinavsingh/proxy.py.git@develop\n```\n\n## Using Docker\n\nMulti-platform containers are available via:\n\n- Docker Hub\n - `latest` tag points to last `stable` release\n - `docker pull abhinavsingh/proxy.py:latest`\n- GitHub container registry (GHCR)\n - `latest` tag points to last `develop` release\n - `docker pull ghcr.io/abhinavsingh/proxy.py:latest`\n\nStable version container releases are available for following platforms:\n\n- `linux/386`\n- `linux/amd64`\n- `linux/arm/v6`\n- `linux/arm/v7`\n- `linux/arm64/v8`\n- `linux/ppc64le`\n- `linux/s390x`\n\n### Stable Version from Docker Hub\n\nRun `proxy.py` latest container:\n\n```console\n\u276f docker run -it -p 8899:8899 --rm abhinavsingh/proxy.py:latest\n```\n\nDocker daemon will automatically pull the matching platform image.\nTo run specific target platform container on multi-platform supported servers:\n\n```console\n\u276f docker run -it -p 8899:8899 --rm --platform linux/arm64/v8 abhinavsingh/proxy.py:latest\n```\n\n### Development Version from GHCR\n\nRun `proxy.py` container from cutting edge code in the develop branch:\n\n```console\n\u276f docker run -it -p 8899:8899 --rm ghcr.io/abhinavsingh/proxy.py:latest\n```\n\n### Build Development Version Locally\n\n```console\n\u276f git clone https://github.com/abhinavsingh/proxy.py.git\n\u276f cd proxy.py && make container\n\u276f docker run -it -p 8899:8899 --rm abhinavsingh/proxy.py:latest\n```\n\n[](https://github.com/moby/vpnkit/issues/469)\n`docker` image is currently broken on `macOS` due to incompatibility with [vpnkit](https://github.com/moby/vpnkit/issues/469).\n\n## Using HomeBrew\n\nUpdated formulae for `HomeBrew` are maintained in `develop` branch under the `helper/homebrew` directory.\n\n- `stable` formulae installs the package from `master` branch.\n- `develop` formulae installs the package from `develop` branch.\n\n### Stable Version with HomeBrew\n\n```console\n\u276f brew install https://raw.githubusercontent.com/abhinavsingh/proxy.py/develop/helper/homebrew/stable/proxy.rb\n```\n\n### Development Version with HomeBrew\n\n```console\n\u276f brew install https://raw.githubusercontent.com/abhinavsingh/proxy.py/develop/helper/homebrew/develop/proxy.rb\n```\n\n# Start proxy.py\n\n## From command line when installed using PIP\n\nWhen `proxy.py` is installed using `pip`,\nan executable named `proxy` is placed under your `$PATH`.\n\n### Run it\n\nSimply type `proxy` on command line to start with default configuration.\n\n```console\n\u276f proxy\n...[redacted]... - Loaded plugin proxy.http.proxy.HttpProxyPlugin\n...[redacted]... - Started 8 threadless workers\n...[redacted]... - Started 8 acceptors\n...[redacted]... - Listening on 127.0.0.1:8899\n```\n\n### Understanding logs\n\nThings to notice from above logs:\n\n- `Loaded plugin`\n - `proxy.py` will load `proxy.http.proxy.HttpProxyPlugin` by default\n - As name suggests, this core plugin adds `http(s)` proxy server capabilities to `proxy.py` instance\n\n- `Started N threadless workers`\n - By default, `proxy.py` will start as many worker processes as there are CPU cores on the machine\n - Use `--num-workers` flag to customize number of worker processes\n - See [Threads vs Threadless](#threads-vs-threadless) to understand how to control execution mode\n\n- `Started N acceptors`\n - By default, `proxy.py` will start as many acceptor processes as there are CPU cores on the machine\n - Use `--num-acceptors` flag to customize number of acceptor processes\n - See [High Level Architecture](#high-level-architecture) to understand relationship between acceptors and workers\n\n- `Started server on ::1:8899`\n - By default, `proxy.py` listens on IPv6 `::1`, which is equivalent of IPv4 `127.0.0.1`\n - If you want to access `proxy.py` from external host, use `--hostname ::` or `--hostname 0.0.0.0` or bind to any other interface available on your machine.\n - See [CustomNetworkInterface](#customnetworkinterface) for how to customize `proxy.py` *public IP seen by upstream servers*.\n\n- `Port 8899`\n - Use `--port` flag to customize default TCP port.\n\n### Enable DEBUG logging\n\nAll the logs above are `INFO` level logs, default `--log-level` for `proxy.py`\n\nLets start `proxy.py` with `DEBUG` level logging:\n\n```console\n\u276f proxy --log-level d\n...[redacted]... - Open file descriptor soft limit set to 1024\n...[redacted]... - Loaded plugin proxy.http_proxy.HttpProxyPlugin\n...[redacted]... - Started 8 workers\n...[redacted]... - Started server on ::1:8899\n```\n\nYou can use single letter to customize log level. Example:\n- `d = DEBUG`\n- `i = INFO`\n- `w = WARNING`\n- `e = ERROR`\n- `c = CRITICAL`\n\nAs we can see from the above logs, before starting up:\n\n- `proxy.py` tried to set open file limit `ulimit` on the system\n- Default value for `--open-file-limit` used is `1024`\n- `--open-file-limit` flag is a no-op on `Windows` operating systems\n\nSee [flags](#flags) for full list of available configuration options.\n\n## From command line using repo source\n\nIf you are trying to run `proxy.py` from source code,\nthere is no binary file named `proxy` in the source code.\n\nTo start `proxy.py` from source code follow these instructions:\n\n- Clone repo\n\n ```console\n \u276f git clone https://github.com/abhinavsingh/proxy.py.git\n \u276f cd proxy.py\n ```\n\n- Create a Python 3 virtual env\n\n ```console\n \u276f python3 -m venv venv\n \u276f source venv/bin/activate\n ```\n\n- Install deps\n\n ```console\n \u276f make lib-dep\n ```\n\n- Generate `proxy/common/_scm_version.py`\n\n NOTE: *Following step is not necessary for editable installs.*\n\n This file writes SCM detected version to `proxy/common/_scm_version.py` file.\n\n ```console\n \u276f ./write-scm-version.sh\n ```\n\n- Optionally, run tests\n\n ```console\n \u276f make\n ```\n\n- Run `proxy.py`\n\n ```console\n \u276f python -m proxy\n ```\n\nSee [Plugin Developer and Contributor Guide](#plugin-developer-and-contributor-guide)\nif you plan to work with `proxy.py` source code.\n\n## Docker image\n\n### Customize startup flags\n\nBy default `docker` binary is started with IPv4 networking flags:\n\n --hostname 0.0.0.0 --port 8899\n\nYou can override flag from command line when starting the docker container. For example, to check `proxy.py` version within the docker container, run:\n\n \u276f docker run -it \\\n -p 8899:8899 \\\n --rm abhinavsingh/proxy.py:latest \\\n -v\n\n# Plugin Examples\n\n- See [plugin](https://github.com/abhinavsingh/proxy.py/tree/develop/proxy/plugin) module for full code.\n- All the bundled plugin examples also works with `https` traffic\n - Require additional flags and certificate generation\n - See [TLS Interception](#tls-interception).\n- Plugin examples are also bundled with Docker image.\n - See [Customize startup flags](#customize-startup-flags) to try plugins with Docker image.\n\n## HTTP Proxy Plugins\n\n### ShortLinkPlugin\n\nAdd support for short links in your favorite browsers / applications.\n\n[](https://github.com/abhinavsingh/proxy.py#user-content-shortlinkplugin)\n\nStart `proxy.py` as:\n\n```console\n\u276f proxy \\\n --plugins proxy.plugin.ShortLinkPlugin\n```\n\nNow you can speed up your daily browsing experience by visiting your\nfavorite website using single character domain names :). This works\nacross all browsers.\n\nFollowing short links are enabled by default:\n\n| Short Link | Destination URL |\n| :--------: | :--------------: |\n| a/ | `amazon.com` |\n| i/ | `instagram.com` |\n| l/ | `linkedin.com` |\n| f/ | `facebook.com` |\n| g/ | `google.com` |\n| t/ | `twitter.com` |\n| w/ | `web.whatsapp.com` |\n| y/ | `youtube.com` |\n| proxy/ | `localhost:8899` |\n\n### ModifyPostDataPlugin\n\nModifies POST request body before sending request to upstream server.\n\nStart `proxy.py` as:\n\n```console\n\u276f proxy \\\n --plugins proxy.plugin.ModifyPostDataPlugin\n```\n\nBy default plugin replaces POST body content with hard-coded `b'{\"key\": \"modified\"}'`\nand enforced `Content-Type: application/json`.\n\nVerify the same using `curl -x localhost:8899 -d '{\"key\": \"value\"}' http://httpbin.org/post`\n\n```console\n{\n \"args\": {},\n \"data\": \"{\\\"key\\\": \\\"modified\\\"}\",\n \"files\": {},\n \"form\": {},\n \"headers\": {\n \"Accept\": \"*/*\",\n \"Content-Length\": \"19\",\n \"Content-Type\": \"application/json\",\n \"Host\": \"httpbin.org\",\n \"User-Agent\": \"curl/7.54.0\"\n },\n \"json\": {\n \"key\": \"modified\"\n },\n \"origin\": \"1.2.3.4, 5.6.7.8\",\n \"url\": \"https://httpbin.org/post\"\n}\n```\n\nNote following from the response above:\n\n1. POST data was modified `\"data\": \"{\\\"key\\\": \\\"modified\\\"}\"`.\n Original `curl` command data was `{\"key\": \"value\"}`.\n2. Our `curl` command did not add any `Content-Type` header,\n but our plugin did add one `\"Content-Type\": \"application/json\"`.\n Same can also be verified by looking at `json` field in the output above:\n ```\n \"json\": {\n \"key\": \"modified\"\n },\n ```\n3. Our plugin also added a `Content-Length` header to match length\n of modified body.\n\n### MockRestApiPlugin\n\nMock responses for your server REST API.\nUse to test and develop client side applications\nwithout need of an actual upstream REST API server.\n\nStart `proxy.py` as:\n\n```console\n\u276f proxy \\\n --plugins proxy.plugin.ProposedRestApiPlugin\n```\n\nVerify mock API response using `curl -x localhost:8899 http://api.example.com/v1/users/`\n\n```console\n{\"count\": 2, \"next\": null, \"previous\": null, \"results\": [{\"email\": \"you@example.com\", \"groups\": [], \"url\": \"api.example.com/v1/users/1/\", \"username\": \"admin\"}, {\"email\": \"someone@example.com\", \"groups\": [], \"url\": \"api.example.com/v1/users/2/\", \"username\": \"admin\"}]}\n```\n\nVerify the same by inspecting `proxy.py` logs:\n\n```console\n... [redacted] ... - access_log:1210 - ::1:64792 - GET None:None/v1/users/ - None None - 0 byte\n```\n\nAccess log shows `None:None` as server `ip:port`. `None` simply means that\nthe server connection was never made, since response was returned by our plugin.\n\nNow modify `ProposedRestApiPlugin` to returns REST API mock\nresponses as expected by your clients.\n\n### RedirectToCustomServerPlugin\n\nRedirects all incoming `http` requests to custom web server.\nBy default, it redirects client requests to inbuilt web server,\nalso running on `8899` port.\n\nStart `proxy.py` and enable inbuilt web server:\n\n```console\n\u276f proxy \\\n --enable-web-server \\\n --plugins proxy.plugin.RedirectToCustomServerPlugin\n```\n\nVerify using `curl -v -x localhost:8899 http://google.com`\n\n```\n... [redacted] ...\n< HTTP/1.1 404 NOT FOUND\n< Server: proxy.py v1.0.0\n< Connection: Close\n<\n* Closing connection 0\n```\n\nAbove `404` response was returned from `proxy.py` web server.\n\nVerify the same by inspecting the logs for `proxy.py`.\nAlong with the proxy request log, you must also see a http web server request log.\n\n```\n... [redacted] ... - access_log:1241 - ::1:49525 - GET /\n... [redacted] ... - access_log:1157 - ::1:49524 - GET localhost:8899/ - 404 NOT FOUND - 70 bytes\n```\n\n### FilterByUpstreamHostPlugin\n\nDrops traffic by inspecting upstream host.\nBy default, plugin drops traffic for `facebook.com` and `www.facebok.com`.\n\nStart `proxy.py` as:\n\n```console\n\u276f proxy \\\n --plugins proxy.plugin.FilterByUpstreamHostPlugin\n```\n\nVerify using `curl -v -x localhost:8899 http://facebook.com`:\n\n```console\n... [redacted] ...\n< HTTP/1.1 418 I'm a tea pot\n< Proxy-agent: proxy.py v1.0.0\n* no chunk, no close, no size. Assume close to signal end\n<\n* Closing connection 0\n```\n\nAbove `418 I'm a tea pot` is sent by our plugin.\n\nVerify the same by inspecting logs for `proxy.py`:\n\n```console\n... [redacted] ... - handle_readables:1347 - HttpProtocolException type raised\nTraceback (most recent call last):\n... [redacted] ...\n... [redacted] ... - access_log:1157 - ::1:49911 - GET None:None/ - None None - 0 bytes\n```\n\n### CacheResponsesPlugin\n\nCaches Upstream Server Responses.\n\nStart `proxy.py` as:\n\n```console\n\u276f proxy \\\n --plugins proxy.plugin.CacheResponsesPlugin\n```\n\nYou may also use the `--cache-requests` flag to enable request packet caching for inspection.\n\nVerify using `curl -v -x localhost:8899 http://httpbin.org/get`:\n\n```console\n... [redacted] ...\n< HTTP/1.1 200 OK\n< Access-Control-Allow-Credentials: true\n< Access-Control-Allow-Origin: *\n< Content-Type: application/json\n< Date: Wed, 25 Sep 2019 02:24:25 GMT\n< Referrer-Policy: no-referrer-when-downgrade\n< Server: nginx\n< X-Content-Type-Options: nosniff\n< X-Frame-Options: DENY\n< X-XSS-Protection: 1; mode=block\n< Content-Length: 202\n< Connection: keep-alive\n<\n{\n \"args\": {},\n \"headers\": {\n \"Accept\": \"*/*\",\n \"Host\": \"httpbin.org\",\n \"User-Agent\": \"curl/7.54.0\"\n },\n \"origin\": \"1.2.3.4, 5.6.7.8\",\n \"url\": \"https://httpbin.org/get\"\n}\n* Connection #0 to host localhost left intact\n```\n\nGet path to the cache file from `proxy.py` logs:\n\n```console\n... [redacted] ... - GET httpbin.org:80/get - 200 OK - 556 bytes\n... [redacted] ... - Cached response at /var/folders/k9/x93q0_xn1ls9zy76m2mf2k_00000gn/T/httpbin.org-1569378301.407512.txt\n```\n\nVerify contents of the cache file `cat /path/to/your/cache/httpbin.org.txt`\n\n```console\nHTTP/1.1 200 OK\nAccess-Control-Allow-Credentials: true\nAccess-Control-Allow-Origin: *\nContent-Type: application/json\nDate: Wed, 25 Sep 2019 02:24:25 GMT\nReferrer-Policy: no-referrer-when-downgrade\nServer: nginx\nX-Content-Type-Options: nosniff\nX-Frame-Options: DENY\nX-XSS-Protection: 1; mode=block\nContent-Length: 202\nConnection: keep-alive\n\n{\n \"args\": {},\n \"headers\": {\n \"Accept\": \"*/*\",\n \"Host\": \"httpbin.org\",\n \"User-Agent\": \"curl/7.54.0\"\n },\n \"origin\": \"1.2.3.4, 5.6.7.8\",\n \"url\": \"https://httpbin.org/get\"\n}\n```\n\n### ManInTheMiddlePlugin\n\nModifies upstream server responses.\n\nStart `proxy.py` as:\n\n```console\n\u276f proxy \\\n --plugins proxy.plugin.ManInTheMiddlePlugin\n```\n\nVerify using `curl -v -x localhost:8899 http://google.com`:\n\n```console\n... [redacted] ...\n< HTTP/1.1 200 OK\n< Content-Length: 28\n<\n* Connection #0 to host localhost left intact\nHello from man in the middle\n```\n\nResponse body `Hello from man in the middle` is sent by our plugin.\n\n### ProxyPoolPlugin\n\nForward incoming proxy requests to a set of upstream proxy servers.\n\nLet's start 2 upstream proxies first. To simulate upstream proxies,\nstart `proxy.py` on port `9000` and `9001`\n\n```console\n\u276f proxy --port 9000\n```\n\n```console\n\u276f proxy --port 9001\n```\n\nNow, start `proxy.py` with `ProxyPoolPlugin` (on default `8899` port),\npointing to our upstream proxies at `9000` and `9001` port.\n\n```console\n\u276f proxy \\\n --plugins proxy.plugin.ProxyPoolPlugin \\\n --proxy-pool localhost:9000 \\\n --proxy-pool localhost:9001\n```\n\nMake a curl request via `8899` proxy:\n\n`curl -v -x localhost:8899 http://httpbin.org/get`\n\nVerify that `8899` proxy forwards requests to upstream proxies\nby checking respective logs.\n\nIf an upstream proxy require credentials, pass them as arguments. Example:\n\n`--proxy-pool user:pass@upstream.proxy:port`\n\n### FilterByClientIpPlugin\n\nReject traffic from specific IP addresses. By default this\nplugin blocks traffic from `127.0.0.1` and `::1`.\n\nStart `proxy.py` as:\n\n```console\n\u276f proxy \\\n --plugins proxy.plugin.FilterByClientIpPlugin\n```\n\nSend a request using `curl -v -x localhost:8899 http://google.com`:\n\n```console\n... [redacted] ...\n> Proxy-Connection: Keep-Alive\n>\n< HTTP/1.1 418 I'm a tea pot\n< Connection: close\n<\n* Closing connection 0\n```\n\nModify plugin to your taste e.g. Allow specific IP addresses only.\n\n### ModifyChunkResponsePlugin\n\nThis plugin demonstrate how to modify chunked encoded responses. In able to do so, this plugin uses `proxy.py` core to parse the chunked encoded response. Then we reconstruct the response using custom hard-coded chunks, ignoring original chunks received from upstream server.\n\nStart `proxy.py` as:\n\n```console\n\u276f proxy \\\n --plugins proxy.plugin.ModifyChunkResponsePlugin\n```\n\nVerify using `curl -v -x localhost:8899 http://httpbin.org/stream/5`:\n\n```console\n... [redacted] ...\nmodify\nchunk\nresponse\nplugin\n* Connection #0 to host localhost left intact\n* Closing connection 0\n```\n\nModify `ModifyChunkResponsePlugin` to your taste. Example, instead of sending hard-coded chunks, parse and modify the original `JSON` chunks received from the upstream server.\n\n### CloudflareDnsResolverPlugin\n\nThis plugin uses `Cloudflare` hosted `DNS-over-HTTPS` [API](https://developers.cloudflare.com/1.1.1.1/encrypted-dns/dns-over-https/make-api-requests/dns-json) (json).\n\n`DoH` mandates a HTTP2 compliant client. Unfortunately `proxy.py`\ndoes not provide that yet, so we use a dependency. Install it:\n\n```console\n\u276f pip install \"httpx[http2]\"\n```\n\nNow start `proxy.py` as:\n\n```console\n\u276f proxy \\\n --plugins proxy.plugin.CloudflareDnsResolverPlugin\n```\n\nBy default, `CloudflareDnsResolverPlugin` runs in `security` mode and provides malware protection.\nUse `--cloudflare-dns-mode family` to also enable adult content protection too.\n\n### CustomDnsResolverPlugin\n\nThis plugin demonstrate how to use a custom DNS resolution implementation with `proxy.py`.\nThis example plugin currently uses Python's in-built resolution mechanism. Customize code\nto your taste. Example, query your custom DNS server, implement `DoH` or other mechanisms.\n\nStart `proxy.py` as:\n\n```console\n\u276f proxy \\\n --plugins proxy.plugin.CustomDnsResolverPlugin\n```\n\n### CustomNetworkInterface\n\n`HttpProxyBasePlugin.resolve_dns` callback can also be used to configure `network interface` which must be used as the `source_address` for connection to the upstream server.\n\nSee [this thread](https://github.com/abhinavsingh/proxy.py/issues/535#issuecomment-961510862)\nfor more details.\n\nPS: There is no plugin named, but [CustomDnsResolverPlugin](#customdnsresolverplugin)\ncan be easily customized according to your needs.\n\n### ProgramNamePlugin\n\nAttempts to resolve program `(application)` name for proxy requests originating from the local machine.\nIf identified, client IP in the access logs is replaced with program name.\n\nStart `proxy.py` as:\n\n```console\n\u276f proxy \\\n --plugins proxy.plugin.ProgramNamePlugin\n```\n\nMake a request using `curl`:\n\n```console\n\u276f curl -v -x localhost:8899 https://httpbin.org/get\n```\n\nYou must see log lines like this:\n\n```console\n... [redacted] ... - [I] server.access_log:419 - curl:58096 - CONNECT httpbin.org:443 - 6010 bytes - 1824.62ms\n```\n\nNotice `curl` in-place of `::1` or `127.0.0.1` as client IP.\n\n[](#programnameplugin) If `ProgramNamePlugin` does not work reliably on your operating system, kindly contribute by sending a pull request and/or open an issue. Thank you!!!\n\n## HTTP Web Server Plugins\n\n### Web Server Route\n\nDemonstrates inbuilt web server routing using plugin.\n\nStart `proxy.py` as:\n\n```console\n\u276f proxy --enable-web-server \\\n --plugins proxy.plugin.WebServerPlugin\n```\n\nVerify using `curl -v localhost:8899/http-route-example`, should return:\n\n```console\nHTTP route response\n```\n\n## Reverse Proxy Plugins\n\nExtends in-built Web Server to add Reverse Proxy capabilities.\n\n### Reverse Proxy\n\nStart `proxy.py` as:\n\n```console\n\u276f proxy --enable-reverse-proxy \\\n --plugins proxy.plugin.ReverseProxyPlugin\n```\n\nWith default configuration, `ReverseProxyPlugin` plugin is equivalent to\nfollowing `Nginx` config:\n\n```console\nlocation /get {\n proxy_pass http://httpbin.org/get\n}\n```\n\nVerify using `curl -v localhost:8899/get`:\n\n```console\n{\n \"args\": {},\n \"headers\": {\n \"Accept\": \"*/*\",\n \"Host\": \"localhost\",\n \"User-Agent\": \"curl/7.64.1\"\n },\n \"origin\": \"1.2.3.4, 5.6.7.8\",\n \"url\": \"https://localhost/get\"\n}\n```\n\n## Plugin Ordering\n\nWhen using multiple plugins, depending upon plugin functionality,\nit might be worth considering the order in which plugins are passed\non the command line.\n\nPlugins are called in the same order as they are passed. Example,\nsay we are using both `FilterByUpstreamHostPlugin` and\n`RedirectToCustomServerPlugin`. Idea is to drop all incoming `http`\nrequests for `facebook.com` and `www.facebook.com` and redirect other\n`http` requests to our inbuilt web server.\n\nHence, in this scenario it is important to use\n`FilterByUpstreamHostPlugin` before `RedirectToCustomServerPlugin`.\nIf we enable `RedirectToCustomServerPlugin` before `FilterByUpstreamHostPlugin`,\n`facebook` requests will also get redirected to inbuilt web server,\ninstead of being dropped.\n\n# End-to-End Encryption\n\nBy default, `proxy.py` uses `http` protocol for communication with clients e.g. `curl`, `browser`. For enabling end-to-end encrypting using `tls` / `https` first generate certificates. **Checkout** the repository and run:\n\n```console\nmake https-certificates\n```\n\nStart `proxy.py` as:\n\n```console\n\u276f proxy \\\n --cert-file https-cert.pem \\\n --key-file https-key.pem\n```\n\nVerify using `curl -x https://localhost:8899 --proxy-cacert https-cert.pem https://httpbin.org/get`:\n\n```console\n{\n \"args\": {},\n \"headers\": {\n \"Accept\": \"*/*\",\n \"Host\": \"httpbin.org\",\n \"User-Agent\": \"curl/7.54.0\"\n },\n \"origin\": \"1.2.3.4, 5.6.7.8\",\n \"url\": \"https://httpbin.org/get\"\n}\n```\n\nIf you want to avoid passing `--proxy-cacert` flag, also consider signing generated SSL certificates. Example:\n\nFirst, generate CA certificates:\n\n```console\nmake ca-certificates\n```\n\nThen, sign SSL certificate:\n\n```console\nmake sign-https-certificates\n```\n\nNow restart the server with `--cert-file https-signed-cert.pem` flag. Note that you must also trust generated `ca-cert.pem` in your system keychain.\n\n# TLS Interception\n\nBy default, `proxy.py` will not decrypt `https` traffic between client and server.\nTo enable TLS interception first generate root CA certificates:\n\n```console\n\u276f make ca-certificates\n```\n\nLets also enable `CacheResponsePlugin` so that we can verify decrypted\nresponse from the server. Start `proxy.py` as:\n\n```console\n\u276f proxy \\\n --plugins proxy.plugin.CacheResponsesPlugin \\\n --ca-key-file ca-key.pem \\\n --ca-cert-file ca-cert.pem \\\n --ca-signing-key-file ca-signing-key.pem\n```\n\n[](https://github.com/abhinavsingh/proxy.py#user-content-flags) Also provide explicit CA bundle path needed for validation of peer certificates. See `--ca-file` flag.\n\nVerify TLS interception using `curl`\n\n```console\n\u276f curl -v -x localhost:8899 --cacert ca-cert.pem https://httpbin.org/get\n```\n\n```console\n* issuer: C=US; ST=CA; L=SanFrancisco; O=proxy.py; OU=CA; CN=Proxy PY CA; emailAddress=proxyca@mailserver.com\n* SSL certificate verify ok.\n> GET /get HTTP/1.1\n... [redacted] ...\n< Connection: keep-alive\n<\n{\n \"args\": {},\n \"headers\": {\n \"Accept\": \"*/*\",\n \"Host\": \"httpbin.org\",\n \"User-Agent\": \"curl/7.54.0\"\n },\n \"origin\": \"1.2.3.4, 5.6.7.8\",\n \"url\": \"https://httpbin.org/get\"\n}\n```\n\nThe `issuer` line confirms that response was intercepted.\n\nAlso verify the contents of cached response file. Get path to the cache\nfile from `proxy.py` logs.\n\n`\u276f cat /path/to/your/tmp/directory/httpbin.org-1569452863.924174.txt`\n\n```console\nHTTP/1.1 200 OK\nAccess-Control-Allow-Credentials: true\nAccess-Control-Allow-Origin: *\nContent-Type: application/json\nDate: Wed, 25 Sep 2019 23:07:05 GMT\nReferrer-Policy: no-referrer-when-downgrade\nServer: nginx\nX-Content-Type-Options: nosniff\nX-Frame-Options: DENY\nX-XSS-Protection: 1; mode=block\nContent-Length: 202\nConnection: keep-alive\n\n{\n \"args\": {},\n \"headers\": {\n \"Accept\": \"*/*\",\n \"Host\": \"httpbin.org\",\n \"User-Agent\": \"curl/7.54.0\"\n },\n \"origin\": \"1.2.3.4, 5.6.7.8\",\n \"url\": \"https://httpbin.org/get\"\n}\n```\n\nViola!!! If you remove CA flags, encrypted data will be found in the\ncached file instead of plain text.\n\nNow use CA flags with other\n[plugin examples](#plugin-examples) to see them work with `https` traffic.\n\n## TLS Interception With Docker\n\nImportant notes about TLS Interception with Docker container:\n\n- Since `v2.2.0`, `proxy.py` docker container also ships with `openssl`. This allows `proxy.py`\n to generate certificates on the fly for TLS Interception.\n\n- For security reasons, `proxy.py` docker container does not ship with\n CA certificates.\n\nHere is how to start a `proxy.py` docker container\nwith TLS Interception:\n\n1. Generate CA certificates on host computer\n\n ```console\n \u276f make ca-certificates\n ```\n\n2. Copy all generated certificates into a separate directory. We'll later mount this directory into our docker container\n\n ```console\n \u276f mkdir /tmp/ca-certificates\n \u276f cp ca-cert.pem ca-key.pem ca-signing-key.pem /tmp/ca-certificates\n ```\n\n3. Start docker container\n\n ```console\n \u276f docker run -it --rm \\\n -v /tmp/ca-certificates:/tmp/ca-certificates \\\n -p 8899:8899 \\\n abhinavsingh/proxy.py:latest \\\n --hostname 0.0.0.0 \\\n --plugins proxy.plugin.CacheResponsesPlugin \\\n --ca-key-file /tmp/ca-certificates/ca-key.pem \\\n --ca-cert-file /tmp/ca-certificates/ca-cert.pem \\\n --ca-signing-key /tmp/ca-certificates/ca-signing-key.pem\n ```\n\n - `-v /tmp/ca-certificates:/tmp/ca-certificates` flag mounts our CA certificate directory in container environment\n - `--plugins proxy.plugin.CacheResponsesPlugin` enables `CacheResponsesPlugin` so that we can inspect intercepted traffic\n - `--ca-*` flags enable TLS Interception.\n\n4. From another terminal, try TLS Interception using `curl`. You can omit `--cacert` flag if CA certificate is already trusted by the system.\n\n ```console\n \u276f curl -v \\\n --cacert ca-cert.pem \\\n -x 127.0.0.1:8899 \\\n https://httpbin.org/get\n ```\n\n5. Verify `issuer` field from response headers.\n\n ```console\n * Server certificate:\n * subject: CN=httpbin.org; C=NA; ST=Unavailable; L=Unavailable; O=Unavailable; OU=Unavailable\n * start date: Jun 17 09:26:57 2020 GMT\n * expire date: Jun 17 09:26:57 2022 GMT\n * subjectAltName: host \"httpbin.org\" matched cert's \"httpbin.org\"\n * issuer: CN=example.com\n * SSL certificate verify ok.\n ```\n\n6. Back on docker terminal, copy response dump path logs.\n\n ```console\n ...[redacted]... [I] access_log:338 - 172.17.0.1:56498 - CONNECT httpbin.org:443 - 1031 bytes - 1216.70 ms\n ...[redacted]... [I] close:49 - Cached response at /tmp/httpbin.org-ae1a927d064e4ab386ea319eb38fe251.txt\n ```\n\n7. In another terminal, `cat` the response dump:\n\n ```console\n \u276f docker exec -it $(docker ps | grep proxy.py | awk '{ print $1 }') cat /tmp/httpbin.org-ae1a927d064e4ab386ea319eb38fe251.txt\n HTTP/1.1 200 OK\n ...[redacted]...\n {\n ...[redacted]...,\n \"url\": \"http://httpbin.org/get\"\n }\n ```\n\n# Proxy Over SSH Tunnel\n\n**This is a WIP and may not work as documented**\n\nRequires `paramiko` to work.\n\nSee [requirements-tunnel.txt](https://github.com/abhinavsingh/proxy.py/blob/develop/requirements-tunnel.txt)\n\n## Proxy Remote Requests Locally\n\n |\n +------------+ | +----------+\n | LOCAL | | | REMOTE |\n | HOST | <== SSH ==== :8900 == | SERVER |\n +------------+ | +----------+\n :8899 proxy.py |\n |\n FIREWALL\n (allow tcp/22)\n\n## What\n\nProxy HTTP(s) requests made on a `remote` server through `proxy.py` server\nrunning on `localhost`.\n\n### How\n\n- Requested `remote` port is forwarded over the SSH connection.\n- `proxy.py` running on the `localhost` handles and responds to\n `remote` proxy requests.\n\n### Requirements\n\n1. `localhost` MUST have SSH access to the `remote` server\n2. `remote` server MUST be configured to proxy HTTP(s) requests\n through the forwarded port number e.g. `:8900`.\n - `remote` and `localhost` ports CAN be same e.g. `:8899`.\n - `:8900` is chosen in ascii art for differentiation purposes.\n\n### Try it\n\nStart `proxy.py` as:\n\n```console\n\u276f # On localhost\n\u276f proxy --enable-tunnel \\\n --tunnel-username username \\\n --tunnel-hostname ip.address.or.domain.name \\\n --tunnel-port 22 \\\n --tunnel-remote-port 8899 \\\n --tunnel-ssh-key /path/to/ssh/private.key \\\n --tunnel-ssh-key-passphrase XXXXX\n...[redacted]... [I] listener.setup:97 - Listening on 127.0.0.1:8899\n...[redacted]... [I] pool.setup:106 - Started 16 acceptors in threadless (local) mode\n...[redacted]... [I] transport._log:1873 - Connected (version 2.0, client OpenSSH_7.6p1)\n...[redacted]... [I] transport._log:1873 - Authentication (publickey) successful!\n...[redacted]... [I] listener.setup:116 - SSH connection established to ip.address.or.domain.name:22...\n...[redacted]... [I] listener.start_port_forward:91 - :8899 forwarding successful...\n```\n\nMake a HTTP proxy request on `remote` server and\nverify that response contains public IP address of `localhost` as origin:\n\n```console\n\u276f # On remote\n\u276f curl -x 127.0.0.1:8899 http://httpbin.org/get\n{\n \"args\": {},\n \"headers\": {\n \"Accept\": \"*/*\",\n \"Host\": \"httpbin.org\",\n \"User-Agent\": \"curl/7.54.0\"\n },\n \"origin\": \"x.x.x.x, y.y.y.y\",\n \"url\": \"https://httpbin.org/get\"\n}\n```\n\nAlso, verify that `proxy.py` logs on `localhost` contains `remote` IP as client IP.\n\n```console\naccess_log:328 - remote:52067 - GET httpbin.org:80\n```\n\n## Proxy Local Requests Remotely\n\n |\n +------------+ | +----------+\n | LOCAL | | | REMOTE |\n | HOST | === SSH =====> | SERVER |\n +------------+ | +----------+\n | :8899 proxy.py\n |\n FIREWALL\n (allow tcp/22)\n\nNot planned.\n\nIf you have a valid use case, kindly open an issue. You are always welcome to send\ncontributions via pull-requests to add this functionality :)\n\n> To proxy local requests remotely, make use of [Proxy Pool Plugin](#proxypoolplugin).\n\n# Embed proxy.py\n\n## Blocking Mode\n\nStart `proxy.py` in embedded mode with default configuration\nby using `proxy.main` method. Example:\n\n```python\nimport proxy\n\nif __name__ == '__main__':\n proxy.main()\n```\n\nCustomize startup flags by passing them as kwargs:\n\n```python\nimport ipaddress\nimport proxy\n\nif __name__ == '__main__':\n proxy.main(\n hostname=ipaddress.IPv6Address('::1'),\n port=8899\n )\n```\n\nNote that:\n\n1. `main` is equivalent to starting `proxy.py` from command line.\n2. `main` does not accept any `args` (only `kwargs`).\n3. `main` will automatically consume any available `sys.argv` as `args`.\n3. `main` will block until `proxy.py` shuts down.\n\n## Non-blocking Mode\n\nStart `proxy.py` in non-blocking embedded mode with default configuration\nby using `Proxy` context manager: Example:\n\n```python\nimport proxy\n\nif __name__ == '__main__':\n with proxy.Proxy() as p:\n # Uncomment the line below and\n # implement your app your logic here\n proxy.sleep_loop()\n```\n\nNote that:\n\n1. `Proxy` is similar to `main`, except `Proxy` will not block.\n2. Internally, `Proxy` is a context manager which will start\n `proxy.py` when called and will shut it down once the scope ends.\n3. Unlike `main`, startup flags with `Proxy` can also be customized\n by using `args` and `kwargs`. e.g. `Proxy(['--port', '8899'])` or\n by using passing flags as kwargs e.g. `Proxy(port=8899)`.\n4. Unlike `main`, `Proxy` will not inspect `sys.argv`.\n\n## Ephemeral Port\n\nUse `--port=0` to bind `proxy.py` on a random port allocated by the kernel.\n\nIn embedded mode, you can access this port. Example:\n\n```python\nimport proxy\n\nif __name__ == '__main__':\n with proxy.Proxy() as p:\n print(p.flags.port)\n proxy.sleep_loop()\n```\n\n`flags.port` will give you access to the random port allocated by the kernel.\n\n## Loading Plugins\n\nUsers can use `--plugins` flag multiple times to load multiple plugins.\nSee [Unable to load plugins](#unable-to-load-plugins) if you are running into issues.\n\nWhen using in embedded mode, you have a few more options. Example:\n\n1. Provide a fully-qualified name of the plugin class as `bytes` to the `proxy.main` method or `proxy.Proxy` context manager.\n2. Provide `type` instance of the plugin class. This is especially useful if you plan to define plugins at runtime.\n\nExample, load a single plugin using `--plugins` flag:\n\n```python\nimport proxy\n\nif __name__ == '__main__':\n proxy.main(plugins=['proxy.plugin.CacheResponsesPlugin'])\n```\n\nFor simplicity, you can also pass the list of plugins as a keyword argument to `proxy.main` or the `Proxy` constructor.\n\nExample:\n\n```python\nimport proxy\nfrom proxy.plugin import FilterByUpstreamHostPlugin\n\nif __name__ == '__main__':\n proxy.main(plugins=[\n b'proxy.plugin.CacheResponsesPlugin',\n FilterByUpstreamHostPlugin,\n ])\n```\n\n# Unit testing with proxy.py\n\n## `proxy.TestCase`\n\nTo setup and tear down `proxy.py` for your Python `unittest` classes, simply use `proxy.TestCase` instead of `unittest.TestCase`.\nExample:\n\n```python\nimport proxy\n\nclass TestProxyPyEmbedded(proxy.TestCase):\n\n def test_my_application_with_proxy(self) -> None:\n self.assertTrue(True)\n```\n\nNote that:\n\n1. `proxy.TestCase` overrides `unittest.TestCase.run()` method to setup and tear down `proxy.py`.\n2. `proxy.py` server will listen on a random available port on the system.\n This random port is available as `self.PROXY.flags.port` within your test cases.\n3. Only a single acceptor and worker is started by default (`--num-workers 1 --num-acceptors 1`) for faster setup and tear down.\n4. Most importantly, `proxy.TestCase` also ensures `proxy.py` server\n is up and running before proceeding with execution of tests. By default,\n `proxy.TestCase` will wait for `10 seconds` for `proxy.py` server to start,\n upon failure a `TimeoutError` exception will be raised.\n\n## Override startup flags\n\nTo override default startup flags, define a `PROXY_PY_STARTUP_FLAGS` variable in your test class.\nExample:\n\n```python\nclass TestProxyPyEmbedded(TestCase):\n\n PROXY_PY_STARTUP_FLAGS = [\n '--num-workers', '2',\n '--num-acceptors', '1',\n '--enable-web-server',\n ]\n\n def test_my_application_with_proxy(self) -> None:\n self.assertTrue(True)\n```\n\nSee [test_embed.py] for full working example.\n\n[test_embed.py]:\nhttps://github.com/abhinavsingh/proxy.py/blob/develop/tests/testing/test_embed.py\n\n## With `unittest.TestCase`\n\nIf for some reasons you are unable to directly use `proxy.TestCase`,\nthen simply override `unittest.TestCase.run` yourself to setup and tear down `proxy.py`.\nExample:\n\n```python\nimport unittest\nimport proxy\n\n\nclass TestProxyPyEmbedded(unittest.TestCase):\n\n def test_my_application_with_proxy(self) -> None:\n self.assertTrue(True)\n\n def run(self, result: Optional[unittest.TestResult] = None) -> Any:\n with proxy.start([\n '--num-workers', '1',\n '--num-acceptors', '1',\n '--port', '... random port ...']):\n super().run(result)\n```\n\nor simply setup / tear down `proxy.py` within\n`setUpClass` and `teardownClass` class methods.\n\n# Utilities\n\n## TCP Sockets\n\n### new_socket_connection\n\nAttempts to create an IPv4 connection, then IPv6 and\nfinally a dual stack connection to provided address.\n\n```python\n>>> conn = new_socket_connection(('httpbin.org', 80))\n>>> ...[ use connection ]...\n>>> conn.close()\n```\n\n### socket_connection\n\n`socket_connection` is a convenient decorator + context manager\naround `new_socket_connection` which ensures `conn.close` is implicit.\n\nAs a context manager:\n\n```python\n>>> with socket_connection(('httpbin.org', 80)) as conn:\n>>> ... [ use connection ] ...\n```\n\nAs a decorator:\n\n```python\n>>> @socket_connection(('httpbin.org', 80))\n>>> def my_api_call(conn, *args, **kwargs):\n>>> ... [ use connection ] ...\n```\n\n## HTTP Client\n\n### build_http_request\n\n- Generate HTTP GET request\n\n ```python\n >>> build_http_request(b'GET', b'/')\n b'GET / HTTP/1.1\\r\\n\\r\\n'\n ```\n\n- Generate HTTP GET request with headers\n\n ```python\n >>> build_http_request(b'GET', b'/', conn_close=True)\n b'GET / HTTP/1.1\\r\\nConnection: close\\r\\n\\r\\n'\n ```\n\n- Generate HTTP POST request with headers and body\n\n ```python\n >>> import json\n >>> build_http_request(b'POST', b'/form',\n headers={b'Content-type': b'application/json'},\n body=proxy.bytes_(json.dumps({'email': 'hello@world.com'})))\n b'POST /form HTTP/1.1\\r\\nContent-type: application/json\\r\\n\\r\\n{\"email\": \"hello@world.com\"}'\n ```\n\n### build_http_response\n\n```python\nbuild_http_response(\n status_code: int,\n protocol_version: bytes = HTTP_1_1,\n reason: Optional[bytes] = None,\n headers: Optional[Dict[bytes, bytes]] = None,\n body: Optional[bytes] = None) -> bytes\n```\n\n## PKI\n\n### API Usage\n\n- `gen_private_key`\n\n ```python\n gen_private_key(\n key_path: str,\n password: str,\n bits: int = 2048,\n timeout: int = 10) -> bool\n ```\n\n- `gen_public_key`\n\n ```python\n gen_public_key(\n public_key_path: str,\n private_key_path: str,\n private_key_password: str,\n subject: str,\n alt_subj_names: Optional[List[str]] = None,\n extended_key_usage: Optional[str] = None,\n validity_in_days: int = 365,\n timeout: int = 10) -> bool\n ```\n\n- `remove_passphrase`\n\n ```python\n remove_passphrase(\n key_in_path: str,\n password: str,\n key_out_path: str,\n timeout: int = 10) -> bool\n ```\n\n- `gen_csr`\n\n ```python\n gen_csr(\n csr_path: str,\n key_path: str,\n password: str,\n crt_path: str,\n timeout: int = 10) -> bool\n ```\n\n- `sign_csr`\n\n ```python\n sign_csr(\n csr_path: str,\n crt_path: str,\n ca_key_path: str,\n ca_key_password: str,\n ca_crt_path: str,\n serial: str,\n alt_subj_names: Optional[List[str]] = None,\n extended_key_usage: Optional[str] = None,\n validity_in_days: int = 365,\n timeout: int = 10) -> bool\n ```\n\nSee [pki.py](https://github.com/abhinavsingh/proxy.py/blob/develop/proxy/common/pki.py) and\n[test_pki.py](https://github.com/abhinavsingh/proxy.py/blob/develop/tests/common/test_pki.py)\nfor usage examples.\n\n### CLI Usage\n\nUse `proxy.common.pki` module for:\n\n1. Generation of public and private keys\n2. Generating CSR requests\n3. Signing CSR requests using custom CA.\n\n```console\npython -m proxy.common.pki -h\nusage: pki.py [-h] [--password PASSWORD] [--private-key-path PRIVATE_KEY_PATH]\n [--public-key-path PUBLIC_KEY_PATH] [--subject SUBJECT]\n action\n\nproxy.py v2.2.0 : PKI Utility\n\npositional arguments:\n action Valid actions: remove_passphrase, gen_private_key,\n gen_public_key, gen_csr, sign_csr\n\noptional arguments:\n -h, --help show this help message and exit\n --password PASSWORD Password to use for encryption. Default: proxy.py\n --private-key-path PRIVATE_KEY_PATH\n Private key path\n --public-key-path PUBLIC_KEY_PATH\n Public key path\n --subject SUBJECT Subject to use for public key generation. Default:\n /CN=example.com\n```\n\n## Internal Documentation\n\n### Read The Doc\n\n- Visit [proxypy.readthedocs.io](https://proxypy.readthedocs.io/)\n- Build locally using:\n\n`make lib-doc`\n\n### pydoc\n\nCode is well documented. Grab the source code and run:\n\n`pydoc3 proxy`\n\n### pyreverse\n\nGenerate class level hierarchy UML diagrams for in-depth analysis:\n\n`make lib-pyreverse`\n\n# Run Dashboard\n\nDashboard is currently under development and not yet bundled with `pip` packages.\nTo run dashboard, you must checkout the source.\n\nDashboard is written in Typescript and SCSS, so let's build it first using:\n\n```console\n\u276f make dashboard\n```\n\nAlso build the embedded `Chrome DevTools` if you plan on using it:\n\n```console\n\u276f make devtools\n```\n\nNow start `proxy.py` with dashboard plugin and by overriding root directory for static server:\n\n```console\n\u276f proxy --enable-dashboard --static-server-dir dashboard/public\n...[redacted]... - Loaded plugin proxy.http.server.HttpWebServerPlugin\n...[redacted]... - Loaded plugin proxy.dashboard.dashboard.ProxyDashboard\n...[redacted]... - Loaded plugin proxy.dashboard.inspect_traffic.InspectTrafficPlugin\n...[redacted]... - Loaded plugin proxy.http.inspector.DevtoolsProtocolPlugin\n...[redacted]... - Loaded plugin proxy.http.proxy.HttpProxyPlugin\n...[redacted]... - Listening on ::1:8899\n...[redacted]... - Core Event enabled\n```\n\nCurrently, enabling dashboard will also enable all the dashboard plugins.\n\nVisit dashboard:\n\n```console\n\u276f open http://localhost:8899/dashboard/\n```\n\n## Inspect Traffic\n\n***This is a WIP and may not work as documented***\n\nWait for embedded `Chrome Dev Console` to load. Currently, detail about all traffic flowing\nthrough `proxy.py` is pushed to the `Inspect Traffic` tab. However, received payloads are not\nyet integrated with the embedded developer console.\n\nCurrent functionality can be verified by opening the `Dev Console` of dashboard and inspecting\nthe websocket connection that dashboard established with the `proxy.py` server.\n\n[](https://github.com/abhinavsingh/proxy.py)\n\n# Chrome DevTools Protocol\n\nFor scenarios where you want direct access to `Chrome DevTools` protocol websocket endpoint,\nstart `proxy.py` as:\n\n```console\n\u276f proxy --enable-devtools --enable-events\n```\n\nNow point your CDT instance to `ws://localhost:8899/devtools`.\n\n# Frequently Asked Questions\n\n## Deploying proxy.py in production\n\nListed below are a few strategies for using `proxy.py` in your private/production/corporate projects.\n\n### What not to do?\n\n> You MUST `avoid forking` the repository *\"just\"* to put your plugin code in `proxy/plugin` directory. Forking is recommended workflow for project contributors, NOT for project users.\n\n- Instead, use one of the suggested approaches from below.\n- Then load your plugins using `--plugin`, `--plugins` flags or `plugin` kwargs.\n- See [skeleton](https://github.com/abhinavsingh/proxy.py/tree/develop/skeleton) app for example standalone project using `proxy.py`.\n\n### Via Requirements\n\nIt is *highly* recommended that you use `proxy.py` via `requirements.txt` or similar dependency management setups. This will allow you to take advantages of regular performance updates, bug fixes, security patches and other improvements happening in the `proxy.py` ecosystem. Example:\n\n1. Use `--pre` option to depend upon last `pre-release`\n\n ```console\n \u276f pip install proxy.py --pre\n ```\n\n Pre-releases are similar to depending upon `develop` branch code, just that pre-releases may not point to the `HEAD`. This could happen because pre-releases are NOT made available on `PyPi` after every PR merge.\n\n2. Use `TestPyPi` with `--pre` option to depend upon `develop` branch code\n\n ```console\n \u276f pip install -i https://test.pypi.org/simple/ proxy.py --pre\n ```\n\n A pre-release is made available on `TestPyPi` after every PR merge.\n\n3. Use last `stable` release code\n\n As usual, simply use:\n\n ```console\n \u276f pip install proxy.py\n ```\n\n### Via Docker Container\n\nIf you are into deploying containers, then simply build your image from base `proxy.py` container images.\n\n1. Use `GHCR` to build from `develop` branch code:\n\n ```console\n FROM ghcr.io/abhinavsingh/proxy.py:latest as base\n ```\n\n *PS: I use GHCR latest for several production level projects*\n\n2. Use `DockerHub` to build from last `stable` release code:\n\n ```console\n FROM abhinavsingh/proxy.py:latest as base\n ```\n\nPS: IMHO, container based strategy is *the best approach* and the only strategy that *I use myself*.\n\n### Integrate your CI/CD with proxy.py\n\n*Hey, but you keep making breaking changes in the develop branch.*\n\nI hear you. And hence, for your production grade applications, you *MUST* integrate application CI/CD with `proxy.py`. You must make sure that your application builds and passes its tests for every PR merge into the `proxy.py` upstream repo.\n\nIf your application repository is public, in certain scenarios, PR authors may send patch PRs for all dependents to maintain backward incompatibility and green CI/CD.\n\nCI/CD integration ensure your app continues to build with latest `proxy.py` code. Depending upon where you host your code, use the strategy listed below:\n\n- GitHub\n\n TBD\n\n- Google Cloud Build\n\n TBD\n\n- AWS\n\n TBD\n\n- Azure\n\n TBD\n\n- Others\n\n TBD\n\n> At some stage, we'll deprecate `master` branch segregation and simply maintain a `develop` branch. As dependents can maintain stability via CI/CD integrations. Currently, it's hard for a production grade project to blindly depend upon `develop` branch.\n\n## Stable vs Develop\n\n- `master` branch contains latest `stable` code and is available via `PyPi` repository and `Docker` containers via `docker.io` and `ghcr.io` registries.\n\n Issues reported for `stable` releases are considered with top-priority. However, currently we don't back port fixes into older releases. Example, if you reported an issue in `v2.3.1`, but current `master` branch now contains `v2.4.0rc1`. Then, the fix will land in `v2.4.0rc2`.\n\n- `develop` branch contains cutting edge changes\n\n Development branch is kept stable *(most of the times)*. **But**, if you want *100% reliability* and serving users in *production environment*, ALWAYS use the stable version.\n\n### Release Schedule\n\nA `vX.Y.ZrcN` pull request is created once a month which merges `develop` \u2192 `master`. Find below how code flows from a pull request to the next stable release.\n\n1. Development release is deployed from `develop` \u2192 `test.pypi.org` after every pull request merge\n\n2. Alpha release is deployed from `develop` \u2192 `pypi.org` **before** merging the `vX.Y.Z.rcN` pull request from `develop` \u2192 `master` branch. There can be multiple alpha releases made before merging the `rc` pull request\n\n3. Beta release is deployed from `master` \u2192 `pypi.org`. Beta releases are made in preparation of `rc` releases and can be skipped if unnecessary\n\n4. Release candidate is deployed from `master` \u2192 `pypi.org`. Release candidates are always made available before final stable release\n\n5. Stable release is deployed from `master` \u2192 `pypi.org`\n\n## Threads vs Threadless\n\n### `v1.x`\n\n`proxy.py` used to spawn new threads for handling client requests.\n\n### `v2.0+`\n\n`proxy.py` added support for threadless execution of client requests using `asyncio`.\n\n### `v2.4.0+`\n\nThreadless execution was turned ON by default for `Python 3.8+` on `mac` and `linux` environments.\n\n`proxy.py` threadless execution has been reported safe on these environments by our users. If you are running into trouble, fallback to threaded mode using `--threaded` flag.\n\nFor `windows` and `Python < 3.8`, you can still try out threadless mode by starting `proxy.py` with `--threadless` flag.\n\nIf threadless works for you, consider sending a PR by editing `_env_threadless_compliant` method in the `proxy/common/constants.py` file.\n\n## Threadless Remote vs Local execution mode\n\nOriginal threadless implementation used `remote` execution mode. This is also depicted under [High level architecture](#high-level-architecture) as ASCII art.\n\nUnder `remote` execution mode, acceptors delegate incoming client connection processing to a remote worker process. By default, acceptors delegate connections in round-robin fashion. Worker processing the request may or may not be running on the same CPU core as the acceptor. This architecture scales well for high throughput, but results in spawning two process per CPU core.\n\nExample, if there are N-CPUs on the machine, by default, N acceptors and N worker processes are started. You can tune number of processes using `--num-acceptors` and `--num-workers` flag. You might want more workers than acceptors or vice versa depending upon your use case.\n\nIn v2.4.x, `local` execution mode was added, mainly to reduce number of processes spawned by default. This model serves well for day-to-day single user use cases and for developer testing scenarios. Under `local` execution mode, acceptors delegate client connections to a companion thread, instead of a remote process. `local` execution mode ensure CPU affinity, unlike in the `remote` mode where acceptor and worker might be running on different CPU cores.\n\n`--local-executor 1` was made default in v2.4.x series. Under `local` execution mode, `--num-workers` flag has no effect, as no remote workers are started.\n\nTo use `remote` execution mode, use `--local-executor 0` flag. Then use `--num-workers` to tune number of worker processes.\n\n## SyntaxError: invalid syntax\n\n`proxy.py` is strictly typed and uses Python `typing` annotations. Example:\n\n```python\n>>> my_strings : List[str] = []\n>>> #############^^^^^^^^^#####\n```\n\nHence a Python version that understands typing annotations is required.\nMake sure you are using `Python 3.6+`.\n\nVerify the version before running `proxy.py`:\n\n`\u276f python --version`\n\nAll `typing` annotations can be replaced with `comment-only` annotations. Example:\n\n```python\n>>> my_strings = [] # List[str]\n>>> ################^^^^^^^^^^^\n```\n\nIt will enable `proxy.py` to run on Python `pre-3.6`, even on `2.7`.\nHowever, as all future versions of Python will support `typing` annotations,\nthis has not been considered.\n\n## Unable to load plugins\n\nMake sure plugin modules are discoverable by adding them to `PYTHONPATH`. Example:\n\n`PYTHONPATH=/path/to/my/app proxy --plugins my_app.proxyPlugin`\n\n```console\n...[redacted]... - Loaded plugin proxy.HttpProxyPlugin\n...[redacted]... - Loaded plugin my_app.proxyPlugin\n```\n\nOR, simply pass fully-qualified path as parameter, e.g.\n\n`proxy --plugins /path/to/my/app/my_app.proxyPlugin`\n\nHere is a quick working example:\n\n- Contents of `/tmp/plug` folder\n\n```console\n\u2570\u2500 ls -1 /tmp/plug \u2500\u256f\nmy_plugin.py\n```\n\n- Custom `MyPlugin` class\n\n```console\n\u2570\u2500 cat /tmp/plug/my_plugin.py \u2500\u256f\nfrom proxy.http.proxy import HttpProxyBasePlugin\n\n\nclass MyPlugin(HttpProxyBasePlugin):\n pass\n```\n\nThis is an empty plugin for demonstrating external plugin usage. You must implement necessary methods to make your plugins work for real traffic\n\n- Start `proxy.py` with `MyPlugin`\n\n```console\n\u2570\u2500 PYTHONPATH=/tmp/plug proxy --plugin my_plugin.MyPlugin \u2500\u256f\n...[redacted]... - Loaded plugin proxy.http.proxy.HttpProxyPlugin\n...[redacted]... - Loaded plugin my_plugin.MyPlugin\n...[redacted]... - Listening on ::1:8899\n```\n\n## Unable to connect with proxy.py from remote host\n\nMake sure `proxy.py` is listening on correct network interface.\nTry following flags:\n\n- For IPv6 `--hostname ::`\n- For IPv4 `--hostname 0.0.0.0`\n\n## Basic auth not working with a browser\n\nMost likely it's a browser integration issue with system keychain.\n\n- First verify that basic auth is working using `curl`\n\n `curl -v -x username:password@localhost:8899 https://httpbin.org/get`\n\n- See [this thread](https://github.com/abhinavsingh/proxy.py/issues/89#issuecomment-534845710)\n for further details.\n\n## Docker image not working on macOS\n\nIt's a compatibility issue with `vpnkit`.\n\nSee [moby/vpnkit exhausts docker resources](https://github.com/abhinavsingh/proxy.py/issues/43)\nand [Connection refused: The proxy could not connect](https://github.com/moby/vpnkit/issues/469)\nfor some background.\n\n## GCE log viewer integration for proxy.py\n\nA starter [fluentd.conf](https://github.com/abhinavsingh/proxy.py/blob/develop/helper/fluentd.conf)\ntemplate is available.\n\n1. Copy this configuration file as `proxy.py.conf` under\n `/etc/google-fluentd/config.d/`\n\n2. Update `path` field to log file path as used with `--log-file` flag.\n By default `/tmp/proxy.log` path is tailed.\n\n3. Reload `google-fluentd`:\n\n `sudo service google-fluentd restart`\n\nNow `proxy.py` logs can be browsed using\n[GCE log viewer](https://console.cloud.google.com/logs/viewer).\n\n## `ValueError: filedescriptor out of range in select`\n\n`proxy.py` is made to handle thousands of connections per second\nwithout any socket leaks.\n\n1. Make use of `--open-file-limit` flag to customize `ulimit -n`.\n2. Make sure to adjust `--backlog` flag for higher concurrency.\n\nIf nothing helps, [open an issue](https://github.com/abhinavsingh/proxy.py/issues/new)\nwith `requests per second` sent and output of following debug script:\n\n```console\n\u276f ./helper/monitor_open_files.sh <proxy-py-pid>\n```\n\n## None:None in access logs\n\nSometimes you may see `None:None` in access logs. It simply means\nthat an upstream server connection was never established i.e.\n`upstream_host=None`, `upstream_port=None`.\n\nThere can be several reasons for no upstream connection,\nfew obvious ones include:\n\n1. Client established a connection but never completed the request.\n2. A plugin returned a response prematurely, avoiding connection to upstream server.\n\n## OSError when wrapping client for TLS Interception\n\nWith `TLS Interception` on, you might occasionally see following exceptions:\n\n```console\n2021-11-06 23:33:34,540 - pid:91032 [E] server.intercept:678 - OSError when wrapping client\nTraceback (most recent call last):\n ...[redacted]...\n ...[redacted]...\n ...[redacted]...\nssl.SSLError: [SSL: TLSV1_ALERT_UNKNOWN_CA] tlsv1 alert unknown ca (_ssl.c:997)\n...[redacted]... - CONNECT oauth2.googleapis.com:443 - 0 bytes - 272.08 ms\n```\n\nSome clients can throw `TLSV1_ALERT_UNKNOWN_CA` if they cannot verify the certificate of the server\nbecause it is signed by an unknown issuer CA. Which is the case when we are doing TLS interception.\nThis can be for a variety of reasons e.g. certificate pinning etc.\n\nAnother exception you might see is `CERTIFICATE_VERIFY_FAILED`:\n\n```console\n2021-11-06 23:36:02,002 - pid:91033 [E] handler.handle_readables:293 - Exception while receiving from client connection <socket.socket fd=28, family=AddressFamily.AF_INET, type=SocketKind.SOCK_STREAM, proto=0, laddr=('127.0.0.1', 8899), raddr=('127.0.0.1', 51961)> with reason SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain (_ssl.c:997)')\nTraceback (most recent call last):\n ...[redacted]...\n ...[redacted]...\n ...[redacted]...\nssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain (_ssl.c:997)\n...[redacted]... - CONNECT init.push.apple.com:443 - 0 bytes - 892.99 ms\n```\n\nIn future, we might support serving original HTTPS content for such clients while still\nperforming TLS interception in the background. This will keep the clients happy without\nimpacting our ability to TLS intercept. Unfortunately, this feature is currently not available.\n\nAnother example with `SSLEOFError` exception:\n\n```console\n2021-11-06 23:46:40,446 - pid:91034 [E] server.intercept:678 - OSError when wrapping client\nTraceback (most recent call last):\n ...[redacted]...\n ...[redacted]...\n ...[redacted]...\nssl.SSLEOFError: EOF occurred in violation of protocol (_ssl.c:997)\n...[redacted]... - CONNECT stock.adobe.io:443 - 0 bytes - 685.32 ms\n```\n\n# Plugin Developer and Contributor Guide\n\n## High level architecture\n\n```console\n +-------------+\n | |\n | Proxy([]) |\n | |\n +------+------+\n |\n |\n +-----------v--------------+\n | |\n | AcceptorPool(...) |\n | |\n +------------+-------------+\n |\n+-----------------+ | +-----------------+\n| | | | |\n| Acceptor(..) <-------------+-----------> Acceptor(..) |\n| | | |\n+---+-------------+ +---------+-------+\n | |\n | |\n | +------++------++------++------++------+ |\n | | || || || || | |\n +----> || || || || <-----+\n | || || || || |\n +------++------++------++------++------+\n Threadless Worker Processes\n```\n\n`proxy.py` is made with performance in mind. By default, `proxy.py`\nwill try to utilize all available CPU cores to it for accepting new\nclient connections. This is achieved by starting `AcceptorPool` which\nlistens on configured server port. Then, `AcceptorPool` starts `Acceptor`\nprocesses (`--num-acceptors`) to accept incoming client connections.\nAlongside, if `--threadless` is enabled, `ThreadlessPool` is setup\nwhich starts `Threadless` processes (`--num-workers`) to handle\nthe incoming client connections.\n\nEach `Acceptor` process delegates the accepted client connection\nto a threadless process via `Work` class. Currently, `HttpProtocolHandler`\nis the default work class.\n\n`HttpProtocolHandler` simply assumes that incoming clients will follow\nHTTP specification. Specific HTTP proxy and HTTP server implementations\nare written as plugins of `HttpProtocolHandler`.\n\nSee documentation of `HttpProtocolHandlerPlugin` for available lifecycle hooks.\nUse `HttpProtocolHandlerPlugin` to add new features for http(s) clients. Example,\nSee `HttpWebServerPlugin`.\n\n## Everything is a plugin\n\nWithin `proxy.py` everything is a plugin.\n\n- We enabled `proxy server` plugins using `--plugins` flag.\n Proxy server `HttpProxyPlugin` is a plugin of `HttpProtocolHandler`.\n Further, Proxy server allows plugin through `HttpProxyBasePlugin` specification.\n\n- All the proxy server [plugin examples](#plugin-examples) were implementing\n `HttpProxyBasePlugin`. See documentation of `HttpProxyBasePlugin` for available\n lifecycle hooks. Use `HttpProxyBasePlugin` to modify behavior of http(s) proxy protocol\n between client and upstream server. Example,\n [FilterByUpstreamHostPlugin](#filterbyupstreamhostplugin).\n\n- We also enabled inbuilt `web server` using `--enable-web-server`.\n Web server `HttpWebServerPlugin` is a plugin of `HttpProtocolHandler`\n and implements `HttpProtocolHandlerPlugin` specification.\n\n- There also is a `--disable-http-proxy` flag. It disables inbuilt proxy server.\n Use this flag with `--enable-web-server` flag to run `proxy.py` as a programmable\n http(s) server.\n\n## Development Guide\n\n### Setup Local Environment\n\nContributors must start `proxy.py` from source to verify and develop new features / fixes.\n\nSee [Run proxy.py from command line using repo source](#from-command-line-using-repo-source) for details.\n\n\n[](https://github.com/abhinavsingh/proxy.py/issues/642#issuecomment-960819271) On `macOS`\nyou must install `Python` using `pyenv`, as `Python` installed via `homebrew` tends\nto be problematic. See linked thread for more details.\n\n### Setup Git Hooks\n\nPre-commit hook ensures tests are passing.\n\n1. `cd /path/to/proxy.py`\n2. `ln -s $(PWD)/git-pre-commit .git/hooks/pre-commit`\n\nPre-push hook ensures lint and tests are passing.\n\n1. `cd /path/to/proxy.py`\n2. `ln -s $(PWD)/git-pre-push .git/hooks/pre-push`\n\n### Sending a Pull Request\n\nEvery pull request is tested using GitHub actions.\n\nSee [GitHub workflow](https://github.com/abhinavsingh/proxy.py/tree/develop/.github/workflows)\nfor list of tests.\n\n# Projects Using Proxy.Py\n\nSome of the projects using `proxy.py`\n\n1. [ray-project](https://github.com/ray-project/ray)\n2. [aio-libs](https://github.com/aio-libs/aiohttp)\n3. [wifipumpkin3](https://github.com/P0cL4bs/wifipumpkin3)\n4. [MerossIot](https://github.com/albertogeniola/MerossIot)\n5. [pyshorteners](https://github.com/ellisonleao/pyshorteners)\n6. [Slack API](https://github.com/slackapi/python-slack-events-api)\n7. [ibeam](https://github.com/Voyz/ibeam)\n8. [PyPaperBot](https://github.com/ferru97/PyPaperBot)\n\nFor full list see [used by](https://github.com/abhinavsingh/proxy.py/network/dependents?package_id=UGFja2FnZS01MjQ0MDY5Ng%3D%3D)\n\n# Benchmarks\n\nSee [Benchmark](https://github.com/abhinavsingh/proxy.py/tree/develop/benchmark) directory on how to run benchmark comparisons with other OSS web servers.\n\nTo run standalone benchmark for `proxy.py`, use the following command from repo root:\n\n```console\n\u276f ./helper/benchmark.sh\n```\n\n# Flags\n\n```console\n\u276f proxy -h\nusage: -m [-h] [--tunnel-hostname TUNNEL_HOSTNAME] [--tunnel-port TUNNEL_PORT]\n [--tunnel-username TUNNEL_USERNAME]\n [--tunnel-ssh-key TUNNEL_SSH_KEY]\n [--tunnel-ssh-key-passphrase TUNNEL_SSH_KEY_PASSPHRASE]\n [--tunnel-remote-port TUNNEL_REMOTE_PORT] [--threadless]\n [--threaded] [--num-workers NUM_WORKERS] [--enable-events]\n [--local-executor LOCAL_EXECUTOR] [--backlog BACKLOG]\n [--hostname HOSTNAME] [--port PORT] [--ports PORTS [PORTS ...]]\n [--port-file PORT_FILE] [--unix-socket-path UNIX_SOCKET_PATH]\n [--num-acceptors NUM_ACCEPTORS] [--version] [--log-level LOG_LEVEL]\n [--log-file LOG_FILE] [--log-format LOG_FORMAT]\n [--open-file-limit OPEN_FILE_LIMIT]\n [--plugins PLUGINS [PLUGINS ...]] [--enable-dashboard]\n [--basic-auth BASIC_AUTH] [--enable-ssh-tunnel]\n [--work-klass WORK_KLASS] [--pid-file PID_FILE]\n [--enable-proxy-protocol] [--enable-conn-pool] [--key-file KEY_FILE]\n [--cert-file CERT_FILE] [--client-recvbuf-size CLIENT_RECVBUF_SIZE]\n [--server-recvbuf-size SERVER_RECVBUF_SIZE]\n [--max-sendbuf-size MAX_SENDBUF_SIZE] [--timeout TIMEOUT]\n [--disable-http-proxy] [--disable-headers DISABLE_HEADERS]\n [--ca-key-file CA_KEY_FILE] [--ca-cert-dir CA_CERT_DIR]\n [--ca-cert-file CA_CERT_FILE] [--ca-file CA_FILE]\n [--ca-signing-key-file CA_SIGNING_KEY_FILE]\n [--auth-plugin AUTH_PLUGIN] [--cache-requests]\n [--cache-by-content-type] [--cache-dir CACHE_DIR]\n [--proxy-pool PROXY_POOL] [--enable-web-server]\n [--enable-static-server] [--static-server-dir STATIC_SERVER_DIR]\n [--min-compression-length MIN_COMPRESSION_LENGTH]\n [--enable-reverse-proxy] [--pac-file PAC_FILE]\n [--pac-file-url-path PAC_FILE_URL_PATH]\n [--cloudflare-dns-mode CLOUDFLARE_DNS_MODE]\n [--filtered-upstream-hosts FILTERED_UPSTREAM_HOSTS]\n [--filtered-client-ips-mode FILTERED_CLIENT_IPS_MODE]\n [--filtered-client-ips FILTERED_CLIENT_IPS]\n [--filtered-url-regex-config FILTERED_URL_REGEX_CONFIG]\n\nproxy.py v2.4.3.dev14+gc6b2de6.d20220605\n\noptional arguments:\n -h, --help show this help message and exit\n --tunnel-hostname TUNNEL_HOSTNAME\n Default: None. Remote hostname or IP address to which\n SSH tunnel will be established.\n --tunnel-port TUNNEL_PORT\n Default: 22. SSH port of the remote host.\n --tunnel-username TUNNEL_USERNAME\n Default: None. Username to use for establishing SSH\n tunnel.\n --tunnel-ssh-key TUNNEL_SSH_KEY\n Default: None. Private key path in pem format\n --tunnel-ssh-key-passphrase TUNNEL_SSH_KEY_PASSPHRASE\n Default: None. Private key passphrase\n --tunnel-remote-port TUNNEL_REMOTE_PORT\n Default: 8899. Remote port which will be forwarded\n locally for proxy.\n --threadless Default: False. Enabled by default on Python 3.8+\n (mac, linux). When disabled a new thread is spawned to\n handle each client connection.\n --threaded Default: True. Disabled by default on Python < 3.8 and\n windows. When enabled a new thread is spawned to\n handle each client connection.\n --num-workers NUM_WORKERS\n Defaults to number of CPU cores.\n --enable-events Default: False. Enables core to dispatch lifecycle\n events. Plugins can be used to subscribe for core\n events.\n --local-executor LOCAL_EXECUTOR\n Default: 1. Enabled by default. Use 0 to disable. When\n enabled acceptors will make use of local (same\n process) executor instead of distributing load across\n remote (other process) executors. Enable this option\n to achieve CPU affinity between acceptors and\n executors, instead of using underlying OS kernel\n scheduling algorithm.\n --backlog BACKLOG Default: 100. Maximum number of pending connections to\n proxy server.\n --hostname HOSTNAME Default: 127.0.0.1. Server IP address.\n --port PORT Default: 8899. Server port. To listen on more ports,\n pass them using --ports flag.\n --ports PORTS [PORTS ...]\n Default: None. Additional ports to listen on.\n --port-file PORT_FILE\n Default: None. Save server port numbers. Useful when\n using --port=0 ephemeral mode.\n --unix-socket-path UNIX_SOCKET_PATH\n Default: None. Unix socket path to use. When provided\n --host and --port flags are ignored\n --num-acceptors NUM_ACCEPTORS\n Defaults to number of CPU cores.\n --version, -v Prints proxy.py version.\n --log-level LOG_LEVEL\n Valid options: DEBUG, INFO (default), WARNING, ERROR,\n CRITICAL. Both upper and lowercase values are allowed.\n You may also simply use the leading character e.g.\n --log-level d\n --log-file LOG_FILE Default: sys.stdout. Log file destination.\n --log-format LOG_FORMAT\n Log format for Python logger.\n --open-file-limit OPEN_FILE_LIMIT\n Default: 1024. Maximum number of files (TCP\n connections) that proxy.py can open concurrently.\n --plugins PLUGINS [PLUGINS ...]\n Comma separated plugins. You may use --plugins flag\n multiple times.\n --enable-dashboard Default: False. Enables proxy.py dashboard.\n --basic-auth BASIC_AUTH\n Default: No authentication. Specify colon separated\n user:password to enable basic authentication.\n --enable-ssh-tunnel Default: False. Enable SSH tunnel.\n --work-klass WORK_KLASS\n Default: proxy.http.HttpProtocolHandler. Work klass to\n use for work execution.\n --pid-file PID_FILE Default: None. Save \"parent\" process ID to a file.\n --enable-proxy-protocol\n Default: False. If used, will enable proxy protocol.\n Only version 1 is currently supported.\n --enable-conn-pool Default: False. (WIP) Enable upstream connection\n pooling.\n --key-file KEY_FILE Default: None. Server key file to enable end-to-end\n TLS encryption with clients. If used, must also pass\n --cert-file.\n --cert-file CERT_FILE\n Default: None. Server certificate to enable end-to-end\n TLS encryption with clients. If used, must also pass\n --key-file.\n --client-recvbuf-size CLIENT_RECVBUF_SIZE\n Default: 128 KB. Maximum amount of data received from\n the client in a single recv() operation.\n --server-recvbuf-size SERVER_RECVBUF_SIZE\n Default: 128 KB. Maximum amount of data received from\n the server in a single recv() operation.\n --max-sendbuf-size MAX_SENDBUF_SIZE\n Default: 64 KB. Maximum amount of data to flush in a\n single send() operation.\n --timeout TIMEOUT Default: 10.0. Number of seconds after which an\n inactive connection must be dropped. Inactivity is\n defined by no data sent or received by the client.\n --disable-http-proxy Default: False. Whether to disable\n proxy.HttpProxyPlugin.\n --disable-headers DISABLE_HEADERS\n Default: None. Comma separated list of headers to\n remove before dispatching client request to upstream\n server.\n --ca-key-file CA_KEY_FILE\n Default: None. CA key to use for signing dynamically\n generated HTTPS certificates. If used, must also pass\n --ca-cert-file and --ca-signing-key-file\n --ca-cert-dir CA_CERT_DIR\n Default: ~/.proxy/certificates. Directory to store\n dynamically generated certificates. Also see --ca-key-\n file, --ca-cert-file and --ca-signing-key-file\n --ca-cert-file CA_CERT_FILE\n Default: None. Signing certificate to use for signing\n dynamically generated HTTPS certificates. If used,\n must also pass --ca-key-file and --ca-signing-key-file\n --ca-file CA_FILE Default: /Users/abhinavsingh/Dev/proxy.py/venv373/lib/\n python3.7/site-packages/certifi/cacert.pem. Provide\n path to custom CA bundle for peer certificate\n verification\n --ca-signing-key-file CA_SIGNING_KEY_FILE\n Default: None. CA signing key to use for dynamic\n generation of HTTPS certificates. If used, must also\n pass --ca-key-file and --ca-cert-file\n --auth-plugin AUTH_PLUGIN\n Default: proxy.http.proxy.auth.AuthPlugin. Auth plugin\n to use instead of default basic auth plugin.\n --cache-requests Default: False. Whether to also write request packets\n in the cache file.\n --cache-by-content-type\n Default: False. Whether to extract content by type\n from responses. Extracted content type is written to\n the cache directory e.g. video.mp4.\n --cache-dir CACHE_DIR\n Default: /Users/abhinavsingh/.proxy/cache. Flag only\n applicable when cache plugin is used with on-disk\n storage.\n --proxy-pool PROXY_POOL\n List of upstream proxies to use in the pool\n --enable-web-server Default: False. Whether to enable\n proxy.HttpWebServerPlugin.\n --enable-static-server\n Default: False. Enable inbuilt static file server.\n Optionally, also use --static-server-dir to serve\n static content from custom directory. By default,\n static file server serves out of installed proxy.py\n python module folder.\n --static-server-dir STATIC_SERVER_DIR\n Default: \"public\" folder in directory where proxy.py\n is placed. This option is only applicable when static\n server is also enabled. See --enable-static-server.\n --min-compression-length MIN_COMPRESSION_LENGTH\n Default: 20 bytes. Sets the minimum length of a\n response that will be compressed (gzipped).\n --enable-reverse-proxy\n Default: False. Whether to enable reverse proxy core.\n --pac-file PAC_FILE A file (Proxy Auto Configuration) or string to serve\n when the server receives a direct file request. Using\n this option enables proxy.HttpWebServerPlugin.\n --pac-file-url-path PAC_FILE_URL_PATH\n Default: /. Web server path to serve the PAC file.\n --cloudflare-dns-mode CLOUDFLARE_DNS_MODE\n Default: security. Either \"security\" (for malware\n protection) or \"family\" (for malware and adult content\n protection)\n --filtered-upstream-hosts FILTERED_UPSTREAM_HOSTS\n Default: Blocks Facebook. Comma separated list of IPv4\n and IPv6 addresses.\n --filtered-client-ips-mode FILTERED_CLIENT_IPS_MODE\n Default: blacklist. Can be either \"whitelist\"\n (restrict access to specific IPs)or \"blacklist\" (allow\n everything except specific IPs).\n --filtered-client-ips FILTERED_CLIENT_IPS\n Default: 127.0.0.1,::1. Comma separated list of IPv4\n and IPv6 addresses.\n --filtered-url-regex-config FILTERED_URL_REGEX_CONFIG\n Default: No config. Comma separated list of IPv4 and\n IPv6 addresses.\n\nProxy.py not working? Report at:\nhttps://github.com/abhinavsingh/proxy.py/issues/new\n```\n",
"bugtrack_url": null,
"license": "'BSD'",
"summary": "\u26a1 Fast \u2022 \ud83e\udeb6 Lightweight \u2022 0\ufe0f\u20e3 Dependency \u2022 \ud83d\udd0c Pluggable \u2022 \ud83d\ude08 TLS interception \u2022 \ud83d\udd12 DNS-over-HTTPS \u2022 \ud83d\udd25 Poor Mans VPN \u2022 \u23ea Reverse & \u23e9 Forward \u2022 \ud83d\udc6e\ud83c\udfff Proxy Server framework \u2022 \ud83c\udf10 Web Server framework \u2022 \u27b5 \u27b6 \u27b7 \u27a0 PubSub framework \u2022 \ud83d\udc77 Work acceptor & executor framework.",
"version": "2.4.3",
"split_keywords": [
"http",
"proxy",
"http proxy server",
"proxy server",
"http server",
"http web server",
"proxy framework",
"web framework",
"python3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "aaafa89b59c9edd64c6f38063aa9e01c630f07909aecf52aaa97a437ce9750b8",
"md5": "1fcc7692c13df965e5963c8c116eeaaf",
"sha256": "03df22468fd9a9da540a5b736cd24c88dead398d887bb78340c54764146cc651"
},
"downloads": -1,
"filename": "proxy.py-2.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1fcc7692c13df965e5963c8c116eeaaf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 206129,
"upload_time": "2022-06-12T05:08:12",
"upload_time_iso_8601": "2022-06-12T05:08:12.046357Z",
"url": "https://files.pythonhosted.org/packages/aa/af/a89b59c9edd64c6f38063aa9e01c630f07909aecf52aaa97a437ce9750b8/proxy.py-2.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8622069e14dc6367b8f688b42f78793c7dd5c65228d107fa78d466f61334d495",
"md5": "77338e24e0daa97e09e0cba55e50a28b",
"sha256": "6134e8f1282db1fd7fa1a4b7049e49307566851023b2ac312d9dd36e92f0c9b1"
},
"downloads": -1,
"filename": "proxy.py-2.4.3.tar.gz",
"has_sig": false,
"md5_digest": "77338e24e0daa97e09e0cba55e50a28b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 294703,
"upload_time": "2022-06-12T05:08:15",
"upload_time_iso_8601": "2022-06-12T05:08:15.086424Z",
"url": "https://files.pythonhosted.org/packages/86/22/069e14dc6367b8f688b42f78793c7dd5c65228d107fa78d466f61334d495/proxy.py-2.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-06-12 05:08:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "abhinavsingh",
"github_project": "proxy.py",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "proxy.py"
}
JSON
