Whistle — HTTP, HTTPS & WebSocket Debugging Proxy

Introduction

Whistle is a Node.js-based network debugging tool that acts as a proxy between your application and the network. It enables developers to capture, inspect, replay, and modify HTTP/HTTPS/WebSocket traffic using a flexible rules-based configuration, replacing heavier tools like Charles or Fiddler.

What Whistle Does

• Captures and displays HTTP, HTTPS, and WebSocket traffic in real time
• Modifies request and response headers, bodies, and status codes on the fly
• Maps remote resources to local files for rapid frontend development
• Provides a web-based UI accessible from any browser at the proxy address
• Supports custom plugins to extend capture, rules, and UI panels

Architecture Overview

Whistle runs as a local Node.js proxy server. It intercepts traffic by sitting between the client and the target server, using MITM for HTTPS decryption when a root CA is installed. The rules engine evaluates pattern-based directives that can rewrite URLs, inject headers, throttle bandwidth, or serve mock responses. A built-in web dashboard renders traffic logs and rule editors.

Self-Hosting & Configuration

• Install globally via npm; no build step required
• Configure your browser or system proxy to point to Whistle's port (default 8899)
• Install the root CA certificate for HTTPS inspection
• Write rules in a simple DSL: patterns on the left, actions on the right
• Supports multi-user mode with authentication for shared team proxies

Key Features

• Pattern-based rules engine for URL rewriting, mocking, and header injection
• HTTPS decryption via auto-generated root CA certificates
• WebSocket frame inspection and modification
• Built-in Weinre integration for remote mobile debugging
• Plugin architecture with community extensions

Comparison with Similar Tools

• Charles Proxy — proprietary, paid license; Whistle is free and open source
• Fiddler — Windows-centric; Whistle is cross-platform via Node.js
• mitmproxy — Python-based with CLI focus; Whistle has a web UI and simpler rule syntax
• Proxyman — macOS-only, paid; Whistle runs everywhere Node.js does
• Lightproxy — built on top of Whistle with an Electron wrapper

FAQ

Q: Does Whistle support HTTPS traffic? A: Yes. Install the auto-generated root CA certificate and Whistle decrypts HTTPS traffic transparently.

Q: Can I use Whistle to mock API responses? A: Yes. Use file, tpl, or statusCode rules to return custom responses without hitting the real server.

Q: Does it work on mobile devices? A: Yes. Point your phone's Wi-Fi proxy to Whistle's IP and port. Use the built-in Weinre panel for DOM inspection.

Q: How do I write rules? A: Rules follow a simple pattern: match-pattern operator://value. For example, example.com/api file:///mock/data.json.

Sources

• https://github.com/avwo/whistle
• https://wproxy.org/whistle/