Skip to content
casaziumPublic

About

Desktop tool for seeing, debugging and rewriting HTTP traffic

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

564 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Wirescry

A desktop tool for seeing, debugging and rewriting HTTP traffic. Built with Electron, TypeScript and React, with Mockttp as the proxy engine.

For using Wirescry, see the documentation. This README is for building and working on it. FEATURES.md has the plan.

Requirements

  • Node.js 22.12 or later (tested with Node 26 and npm 11)
  • macOS, Windows or Linux

Install

npm install

Electron downloads its binary the first time it runs, so the first npm run dev takes a little longer.

Run

npm run dev

This opens the Wirescry window with hot reload. The toolbar shows the proxy port (usually 8000), and requests appear in the list as they pass through.

The list stays fast with thousands of requests and keeps the most recent 10,000. Search with Cmd/Ctrl+F, narrow it with the quick filters (JSON, HTML, gRPC, Errors and so on) or field filters in the search box such as status>=400, status=5xx, method=POST, host=api.*, path~login, size>1mb, time>500ms, grpc=NOT_FOUND or -host=*.google.com (the ? button lists them), and use Pause recording to let traffic through without recording it. Click a request, or use the arrow keys, to see its headers and bodies.

To send traffic through it:

  • Chrome, Chromium, Edge or Brave: click Launch to open the browser with a fresh temporary profile that uses the proxy and trusts Wirescry's certificate. The profile is deleted when the browser closes.

  • Firefox: Firefox can't be told to trust a certificate from the command line, so Wirescry keeps its own Firefox profile in the user data folder. The first launch opens a setup page at http://wirescry.internal/ (answered by the proxy itself) where you trust the certificate once. Later launches go straight to browsing.

  • Terminals: Setup → Terminals opens Terminal or iTerm (macOS), PowerShell or Command Prompt (Windows), or your terminal (Linux) with variables that send Node.js, Python, Ruby, Go, PHP, Java, curl and git through Wirescry. The same variables are shown for bash, zsh, fish, PowerShell and cmd, to paste into a terminal that's already open. They point tools at a CA bundle (ca-bundle.pem in the user data folder) holding Wirescry's CA plus the usual public and system roots. Java gets JAVA_TOOL_OPTIONS with proxy settings and a JKS trust store holding the same certificates (Java can't read PEM bundles). PHP gets an extra .ini (through PHP_INI_SCAN_DIR) that points its curl and OpenSSL settings at the bundle. On Windows, curl.exe ignores CURL_CA_BUNDLE, so terminals there point CURL_HOME at a Wirescry curl config that sets the CA and turns off revocation checks (a local CA has nowhere to publish revocation lists); your own _curlrc isn't read in those terminals. Known gaps: the Python and Ruby built into macOS ignore the certificate setting, and Go on Windows reads only the Windows certificate store.

  • Java programs: Setup → Java programs turns on Wirescry's Java agent (native/java-agent) for programs started from Wirescry terminals, or with a -javaagent option it shows for programs started elsewhere, and, with a JDK 17 or later (11 on Windows) on the computer, attaches it to programs already running. The agent sends HTTP and HTTPS through Wirescry and trusts its certificate, even in programs with their own trust store, for HttpURLConnection, Java's HttpClient, OkHttp, Apache HttpClient 4 and 5, Jetty's HttpClient (9.4.25 and later) and Reactor Netty's HttpClient (1.0 to 1.3), and so Spring's WebClient. Java 8 and later. See Java programs.

  • Docker containers: with Docker Desktop on macOS, Windows (Linux containers) or Linux, or Docker Engine on Linux, containers started with docker run or docker compose up in a Wirescry terminal are set up too, through a relay for the Docker API, with no changes to images or compose files. On Windows a small helper (native/docker-pipe) does the named pipes. See Docker containers.

  • Android devices: Setup → Android sets the proxy of a phone or emulator connected for debugging, over USB or Wi-Fi (Android 7 and later, with adb), and puts it back when you stop. See Android devices.

  • Anything else: the Setup view shows the proxy address and a Save certificate… button.

  • curl:

    curl --proxy http://127.0.0.1:8000 --cacert "$HOME/Library/Application Support/Wirescry/ca.pem" https://example.com/

    On Linux the certificate is in ~/.config/Wirescry/ca.pem, and on Windows in %APPDATA%\Wirescry\ca.pem.

The Setup view also lets you fix the proxy port (it's otherwise picked automatically, starting at 8000) and reset the certificate, which creates a new one and removes the Firefox profile.

npm start runs the production build without packaging it.

When requests fail

If the real server can't be reached, the request's Status shows why: DNS, Refused, TLS, Timeout, Reset, No route, or Closed (the client gave up first). The detail pane explains the problem in plain language, with the original error. The client receives a 502 from Wirescry in these cases. Wirescry doesn't impose its own response timeout, so long-polling and other slow responses keep working; a request still waiting just shows ….

WebSocket connections show in the list with status 101 and type websocket. Select one to see its messages live: direction, time since the connection opened, size and content, with JSON formatted and binary shown as hex. Filter by sent or received, or search the text. Messages are kept in memory, at most 64 KB of each and 64 MB in total; the oldest are dropped first, and the view says when.

Logs

Errors and warnings from the window, the backend and the UI are written to wirescry.log (Help → Show Log File):

  • macOS: ~/Library/Logs/Wirescry/
  • Windows: %APPDATA%\Wirescry\logs\
  • Linux: ~/.config/Wirescry/logs/

The file is readable only by you, starts over past 5 MB (keeping one previous file), and never contains the API token. It does include hostnames of requests that failed.

Test and check

npm test

The backend's tests again, under Electron's own Node, which the app runs on. It uses BoringSSL rather than OpenSSL, so TLS errors differ:

npm run test:electron
npm run lint
npm run typecheck
npm run format:check

The backend tests start the real proxy and API, push an HTTPS request through the proxy to a local server, and check that it streams to an API client. They also check that the API rejects a missing or wrong token, other origins and non-loopback hosts.

Package

node scripts/build-java-agent.mjs
node scripts/build-docker-pipe.mjs --windows   # for Windows installers only
npm run package

The first line builds the Java agent, which every installer carries. It needs a JDK 17 or later; see native/java-agent/README.md. The second builds the Docker pipe helper that Windows installers carry; it needs Go 1.21 or later, and builds on any computer. The last builds unsigned installers for the current platform into release/. Use package:mac, package:win or package:linux for a specific one.

Signed releases, notarization and auto-update are handled by the release workflow; see docs/RELEASING.md.

Plugins and Pro

Pro features live in a separate, private repo (wirescry-pro) and plug into the app through src/plugin-api:

  • Backend plugins run in the backend process. They get a data folder, a small secure store (one JSON value, encrypted with the OS keychain through the main process's safeStorage, or plain where there's no keychain, which the store reports), the app's version and build date, can add proxy rules that run after Wirescry's setup page and before normal pass-through, handle calls from their UI, and send it events. Their rules can use Wirescry's own pass-through step, optionally with Mockttp's request and response transforms (to forward or rewrite) or its beforeRequest and beforeResponse callbacks (to pause, for breakpoints).
  • UI plugins add views as toolbar tabs. They can also save and open files, always through a system dialog where the user picks the file (up to 16 MB), for example to export and import rules, put a short badge on their tabs (such as how many requests are paused), and offer actions on a captured exchange, shown in its details and in the right-click menu on its row (such as Pro's Mock…). An action can read that exchange's headers and bodies and switch to the plugin's tab.

The build uses the empty stubs in src/pro-stub unless WIRESCRY_PRO_DIR points at a wirescry-pro checkout, usually next to this one:

WIRESCRY_PRO_DIR=../wirescry-pro npm run dev

How plugins are kept in line (src/backend/plugin-host.ts):

  • A plugin declares the PLUGIN_API_VERSION it was built for, and isn't loaded with any other. Bump the version for breaking changes to src/plugin-api.
  • A plugin that throws, or takes more than 10 seconds to start, is marked as failed, and its rules are removed. Calls to it are refused, and it can't add rules back. Other plugins and the free features keep working.
  • Plugin rules keep only their matchers and steps, so they can't jump ahead of the setup page. Requests a plugin rule handled show a Rule badge, and rule= finds them in the search box.
  • A view that crashes shows an error in its tab, not a blank app.

Plugins always start. Pro checks its own license, in Pro's code rather than this open-source app: without a valid license it applies no rules and pauses nothing, and its tabs ask for a license key. Development builds run Pro without a license; that's decided when the app is built, so release builds don't have the shortcut. Set WIRESCRY_PRO_DIR when running tests to include test/pro-integration.test.ts, which runs the real Pro module in the backend.

With WIRESCRY_PRO_DIR set:

  • npm run typecheck:pro typechecks the app with Pro in place of the stubs. Run it after changing src/plugin-api.
  • A production build with Pro has to compile Pro's backend to bytecode before it can be packaged; electron-builder refuses otherwise. See docs/RELEASING.md.

How it fits together

Part Folder Job
Main process src/main Window, menu, app protocol, and starting and restarting the backend
Backend src/backend Runs in its own Electron utility process: CA, Mockttp proxy, local API, browser launching
Preload src/preload Gives the UI one thing: how to reach the backend
UI src/renderer React app (Vite) that talks to the backend over a WebSocket
Shared src/shared Types used by more than one part
Java agent native/java-agent The agent Java programs load: stub, implementation, weaver (Byte Buddy) and attacher. Built by scripts/build-java-agent.mjs
Docker pipe native/docker-pipe A small Go helper for Docker's named pipes on Windows. Built by scripts/build-docker-pipe.mjs

Security basics:

  • Certificate authority: each install creates its own CA on first run, stored in the app's user data folder (ca.key is readable only by the user). No CA ships with the app.
  • Proxy: only accepts connections from this computer. On Windows and macOS it listens on 127.0.0.1 and ::1 only (a small Mockttp patch sets the address), so nothing listens on the network and Windows doesn't ask to let Wirescry through its firewall. On Linux it listens on every network interface, as Docker containers reach it at their bridge network's address, and Wirescry drops connections from other machines as they arrive. A fixed port, and each port of a range, is checked first, so another program already answering 127.0.0.1 there can't silently lose its traffic to Wirescry, or receive Wirescry's.
  • Local API: listens on 127.0.0.1 only. Each connection needs the secret token generated at launch, an allowed Origin, and a loopback Host header (which blocks DNS rebinding).
  • Renderer: contextIsolation and sandbox on, nodeIntegration off, a strict Content Security Policy, and no navigation, new windows or permission requests. Packaged builds serve the UI from wirescry://app.

Captured traffic is split in two:

  • RequestStore (src/backend/store.ts) holds each exchange's summary, headers and timing, in memory.
  • BodyStore (src/backend/body-store.ts) holds bodies. They stream in chunk by chunk as they pass through the proxy: up to 64 KB stays in memory, and anything larger goes straight to a file in bodies/ in the user data folder, so a large body is never held in memory whole. The folder is emptied on every start and on Clear. Each body keeps up to 512 MB; past that the size is still counted and the traffic still passes through.

The UI fetches headers and bodies only for the exchange you select. Bodies are decoded (gzip, deflate, brotli, zstd) as a stream in the backend, which stops once it has the first 5 MB the UI shows. HTML, XML, JavaScript and CSS bodies up to 2 MB are pretty-printed by js-beautify and xml-formatter in a worker thread, so formatting a large file never stalls the proxy.

Notes

  • Mockttp is patched after install by scripts/patch-mockttp.mjs (run by npm install's postinstall), until the fixes are in a Mockttp release: HTTP/2 responses that end with their headers (gRPC's Trailers-Only), and plain-http requests that offer an upgrade other than WebSocket. Packaging refuses an unpatched install, for example one made with --ignore-scripts.
  • tls-impersonate, an optional Mockttp dependency for TLS fingerprint mirroring, is not built and not packaged. Mockttp works without it, and Wirescry doesn't use that feature.

License

Wirescry's free app is open source under the GNU Affero General Public License v3.0 (AGPL-3.0-only). Copyright © 2026 Bob Casazza.

Wirescry Pro features are developed separately and aren't covered by this license. Released builds of Wirescry include them, locked until a Pro license is active.

Contributions will need a contributor license agreement, so the project can keep offering combined builds with Pro. Details will be here before outside contributions are accepted.

About

Desktop tool for seeing, debugging and rewriting HTTP traffic

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages