Installation & Setup

Install & Run

1. Install dependencies

   ProxyServer has only two npm dependencies: ws (WebSockets) and node-forge (TLS certificate generation).

   npm install

2. Start the server

   node server.js

   You'll see:

   === HTTPS MITM Setup ===
   CA certificate: /path/to/ProxyServer/certs/ca.crt
   
   === ProxyServer Ready ===
     Proxy:     http://localhost:9080
     Dashboard: http://localhost:9081

3. Open the dashboard

   Navigate to http://localhost:9081 in any browser. You'll see the traffic list (empty) and a status bar showing "Connected".

4. Send traffic through the proxy

   Configure any HTTP client to use localhost:9080 as its proxy and make requests. They'll appear in the dashboard in real time.

Custom Ports

Use environment variables to change the default ports:

# Use port 7070 for proxy and 7071 for dashboard
PROXY_PORT=7070 DASHBOARD_PORT=7071 node server.js

Configuring HTTP Clients

curl

The -x flag tells curl to use a proxy:

# Simple GET request
curl -x http://localhost:9080 http://httpbin.org/get

# POST with JSON body
curl -x http://localhost:9080 \
  -X POST http://httpbin.org/post \
  -H "Content-Type: application/json" \
  -d '{"user": "admin", "action": "login"}'

# HTTPS (requires trusting the CA certificate first — see below)
curl -x http://localhost:9080 https://httpbin.org/get

macOS System Proxy

Configure all HTTP traffic from your Mac to route through the proxy:

# Enable HTTP proxy on Wi-Fi
networksetup -setwebproxy Wi-Fi localhost 9080

# Enable HTTPS proxy (requires CA trust)
networksetup -setsecurewebproxy Wi-Fi localhost 9080

# Disable when done
networksetup -setwebproxystate Wi-Fi off
networksetup -setsecurewebproxystate Wi-Fi off

Firefox

Firefox has its own proxy settings separate from the OS:

1. Open Settings > General > scroll to Network Settings
2. Click Settings...
3. Select Manual proxy configuration
4. HTTP Proxy: localhost, Port: 9080
5. Check "Also use this proxy for HTTPS"
6. Click OK

Chrome

Chrome uses your operating system's proxy settings. On macOS, configure the system proxy as shown above. On Linux:

# Launch Chrome with a specific proxy
google-chrome --proxy-server="http://localhost:9080"

iOS / Android

Mobile devices can use the proxy if they're on the same network:

1. Find your computer's local IP address (e.g., 192.168.1.42)
2. On the mobile device, go to Wi-Fi settings > proxy > Manual
3. Set Server: 192.168.1.42, Port: 9080
4. For HTTPS: install the CA certificate on the device (see certificates guide)

HTTPS Setup (Quick Version)

On first run, ProxyServer generates a root CA certificate at certs/ca.crt. Trust it once to enable HTTPS interception:

# macOS — add to system keychain (Chrome uses this automatically)
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain certs/ca.crt

# Firefox — must import separately
# Preferences → Privacy & Security → Certificates → View Certificates → Import

For a full explanation of why this is needed and how it works, read the TLS & Certificates guide.

Verifying Everything Works