Getting Started with PenProxy: Installation, Setup, and Best PracticesPenProxy is a lightweight, developer-focused proxy tool designed to simplify secure remote debugging, request inspection, and traffic manipulation for web and mobile applications. This guide walks you through installing PenProxy, configuring it for common workflows, and following best practices to keep your debugging sessions efficient and secure.
What PenProxy does and when to use it
PenProxy sits between your client (browser, mobile app, or other HTTP(S) client) and the target server. It captures, inspects, and optionally modifies HTTP and HTTPS traffic in real time. Use PenProxy when you need to:
- Debug API requests/responses from a remote device.
- Replay or modify requests for testing.
- Emulate network conditions or inject faults.
- Capture traffic for security testing or performance analysis.
Key benefits: easy remote access, minimal setup, and focused tooling for developers and testers.
System requirements
- Cross-platform support: Windows, macOS, and Linux.
- Node.js (if using the npm-distributed client) or a prebuilt binary for your platform.
- Open ports for proxying (default: 8080 for HTTP, 8443 for HTTPS) — ensure no firewall conflicts.
- Root/admin privileges only when binding to privileged ports (<1024) or installing system certificates for HTTPS interception.
Installation
There are two common installation methods: using a prebuilt binary and using npm (Node.js). Choose the one matching your environment.
- Prebuilt binary (recommended for most users)
- Download the latest release for your OS from the PenProxy releases page.
- Extract the archive and place the executable in a directory on your PATH (optional).
- Make the binary executable (macOS/Linux): chmod +x penproxy
- npm install (developer mode)
- Ensure Node.js (v14+) and npm are installed.
- Install globally: npm install -g penproxy
- Run using: penproxy
Initial configuration and running PenProxy
-
Start PenProxy with defaults:
penproxy
This launches the proxy listening on HTTP port 8080 and HTTPS port 8443, with a web UI on http://localhost:8081 (adjust ports if needed).
-
Configure client(s) to use PenProxy:
- For browsers: set system or browser proxy to http://
:8080 and https to https:// :8443. - For mobile devices: set Wi‑Fi proxy to your machine’s IP and port 8080 (HTTP) / 8443 (HTTPS). For HTTPS interception, you’ll need to install PenProxy’s CA certificate on the device.
- Install the PenProxy CA certificate (for HTTPS interception)
- Access the PenProxy web UI and download the CA certificate (PEM/DER).
- On desktop: import into system or browser certificate store and mark as trusted for TLS interception.
- On Android/iOS: follow platform instructions to install custom CA (note: modern mobile OSes may restrict user CAs for system apps; use development builds or emulator when necessary).
Security note: Only install the CA on devices you control. Removing the CA after debugging closes the interception capability.
Common workflows
- Inspecting requests and responses
- Use the web UI to view live traffic, including headers, cookies, query strings, and bodies.
- Apply filters by host, path, method, or status code to focus the view.
- Export captured sessions for offline analysis.
- Modifying requests/responses (man-in-the-middle)
- Create rules to rewrite headers, query parameters, or response bodies.
- Use regex or JSONPath transformations for complex edits.
- Save rule sets and reapply them to repeatable test scenarios.
- Replay and automation
- Save a recorded request and replay it with modified payloads or headers.
- Integrate with scripts or CI by using penproxy’s CLI to run scripted sessions.
- Simulating network conditions
- Inject latency, bandwidth limits, or intermittent errors to test resilience.
- Combine with replay for load testing or error-handling validation.
Configuration file example
Create a config file (penproxy.yml / .json) to persist settings and rules:
listen: http: 0.0.0.0:8080 https: 0.0.0.0:8443 ui: bind: 127.0.0.1:8081 rules: - name: add-auth-header match: host: api.example.com path: /v1/* actions: - type: add_header header: Authorization value: "Bearer test-token" - name: inject-delay match: host: api.example.com actions: - type: delay ms: 500
Start with config: penproxy –config ./penproxy.yml
Security and privacy considerations
- Only intercept traffic you own or have permission to test.
- Avoid installing PenProxy’s CA on shared or production devices.
- Keep logs and recorded sessions secure; they may contain credentials or PII.
- Rotate any test credentials you expose during debugging.
Troubleshooting
- Browser shows TLS errors: ensure CA certificate is correctly installed and trusted.
- No traffic captured from mobile: verify device proxy and that device can reach your machine (same network, firewall rules).
- Port conflicts: change listen ports in config or stop the conflicting service.
- Large request bodies truncated: increase PenProxy’s max body size in config.
Best practices
- Use named rule sets per project to avoid accidental cross-project interference.
- Keep test credentials and sensitive data in environment variables or secrets manager; scrub or mask data before saving sessions.
- Automate common tasks (replay, transforms) with CLI scripts for repeatable tests.
- Regularly update PenProxy to pick up security fixes.
- Limit web UI access to trusted hosts or bind it to localhost when using on shared networks.
Example use cases
- Debugging a mobile app’s OAuth flow by intercepting token requests.
- Testing backend resilience by injecting 500 errors and latency.
- QA team replaying production-like API calls with masked PII for regression tests.
- Security team auditing API calls and response headers for vulnerabilities.
Conclusion
PenProxy is a compact, flexible tool for developers and testers needing fine-grained control over HTTP(S) traffic. With careful setup—especially around HTTPS interception and CA handling—you can inspect, modify, and replay traffic to accelerate debugging, testing, and security work. Start with a local install, create reusable rule sets, and follow the security best practices above to get reliable, repeatable results.