A debugging proxy that can log or intercept HTTPS requests. This tool can be used to:
- Monitor HTTPS traffic from applications
- Debug SSL/TLS issues
- Test applications against specific HTTP responses
- Simulate network delays
- Full HTTPS request/response logging
- Custom response injection
- Automatic certificate generation
- Connection delays for testing
- Concurrent connection support
- Binary data handling
The proxy is distributed as a single Python file proxyspy.py. To use it in your project:
- Copy
proxyspy.pyinto your repository - Ensure the
cryptographypackage is available in your Python environment
That's it! The script is self-contained and ready to use.
To develop or test the proxy itself, additional packages are required:
conda install --file requirements.txtThis will install:
- cryptography (required for proxy operation)
- requests (for tests)
- pytest (for running tests)
./proxyspy.py [options] -- command [args...]The tool starts a proxy server and then runs the specified command with appropriate proxy environment variables set.
--logfile FILE, -l FILE: Write logs to FILE (default: stdout)--port PORT, -p PORT: Listen on PORT (default: 8080)--keep-certs: Keep certificates in current directory--delay TIME: Add TIME seconds delay to each connection--return-code N, -r N: Return status code N for all requests--return-header H: Add header H to responses (can repeat)--return-data DATA: Return DATA as response body
Log all HTTPS requests to test.log:
./proxyspy.py --logfile test.log -- curl https://httpbin.org/ipReturn 404 for all requests with a half-second delay:
./proxyspy.py --return-code 404 --delay 0.5 -- python my_script.pyReturn custom response with headers and body:
./proxyspy.py --return-code 200 \
--return-header "Content-Type: application/json" \
--return-data '{"status": "ok"}' \
-- ./my_script.pyThe proxy operates in two modes and can optionally add delays to any connection:
- Creates a CA certificate and per-host certificates
- Establishes SSL tunnels to requested hosts
- Logs all traffic passing through
- Activated by specifying any of: --return-code, --return-data, --return-header
- Returns custom responses instead of connecting to servers
- Useful for testing application behavior
- Optional delay can be added to any connection in either mode
- Delay occurs after connection but before SSL handshake
- Useful for testing timeout and connection handling
Run tests:
pytest -vThe test suite covers:
- Basic forwarding
- Response interception
- Binary data handling
- Connection delays
- Error conditions
When submitting pull requests, please:
- Add tests for new features
- Ensure all tests pass
- Follow existing code style
- Do not add third-party dependencies beyond the required
cryptographypackage- The proxy tester is designed to be a single, self-contained file
- Additional dependencies make it harder for users to incorporate into their projects
This project was primarily developed through a series of conversations with Claude 3.5 Sonnet, an AI assistant from Anthropic (https://claude.ai). The majority of the code, including the test suite and GitHub Actions configuration, was written by Claude in response to requirements and refinements from human developers. This collaborative approach demonstrates how AI assistance can help create well-tested, maintainable code while adhering to strict dependency and design constraints.