netproxy

A local proxy server library in pure Python where rules decide, per destination, whether to connect with a client certificate and which one. Client certificates can live in the Windows certificate store, on a smart card or in an HSM (via sslcontext), so tools that cannot do mutual TLS reach mTLS-only services through it. Documentation: https://jose-pr.github.io/netproxy/.

Features

• Rule routing — glob and regex host rules, ports, networks and paths pick a route per connection: tunnel directly, originate TLS with a credential, chain through an upstream proxy, or reject.
• mTLS from any keystore — a route's credential is an ssl.SSLContext you build, or a keystore query resolved by sslcontext.
• Three ways in — an HTTP proxy (CONNECT and plain HTTP, upgraded to HTTPS when a rule says so), local tunnel ports, and optional TLS interception with a name-constrained local CA.
• Recording — every session as a capture Wireshark follows (plaintext for the TLS the proxy owns), a TLS key log, or your own Recorder.
• Upstream proxies — chain through a corporate proxy chosen by proxylib (PAC, environment, system settings).

Installation

pip install netproxy

Quick start

A configuration file routes *.corp.example through a client certificate from the Windows store; everything else goes direct:

[server]
listen = "127.0.0.1:3128"

[credentials.work]
backend = "cng"
query = { subject = "alice" }

[[rules]]
match = "*.corp.example"
action = "tls"
credential = "work"

netproxy run -c netproxy.cfg
curl -x http://127.0.0.1:3128 http://api.corp.example/   # sent as HTTPS with alice's certificate

The same from Python:

import asyncio
from netproxy import AsyncProxyServer, Credential, Route, Router

work = Credential(backend="cng", query={"subject": "alice"})
router = Router([("*.corp.example", Route.with_tls(work))])

async def main():
    async with AsyncProxyServer(router, listen="127.0.0.1:3128") as server:
        await server.serve_forever()

asyncio.run(main())

Command line

netproxy run -c netproxy.cfg          # serve
netproxy check -c netproxy.cfg https://api.corp.example/   # which rule and route, no connection
netproxy pac -c netproxy.cfg          # PAC script for browsers
netproxy ca init -c netproxy.cfg      # local CA for intercepting https:// clients

API overview

Development

dotagents pyvenv && dotagents pyvenv 3.9
.pyvenv/<tag>/Scripts/python -m pip install -e ../sslcontext -e ".[dev]"
.pyvenv/<tag>/Scripts/python -m pytest -q -rs

Releasing

This project follows Semantic Versioning and keeps a CHANGELOG.md. Pushing a tag matching v* triggers the release workflow: test gate → build (checking the tag names the version built) → a strict docs build as a gate → GitHub release → publish. The release workflow never deploys the docs site itself: for a final release its last job dispatches the docs workflow at the tag, which owns every Pages deploy.

License

MIT — see LICENSE.