OpenIntercept

OpenIntercept is a work-in-progress local-first desktop tool for intercepting and inspecting HTTP and HTTPS traffic during development.

The project is not functional yet. It is under active development and should not be used as a working proxy until the MVP is stabilized.

The product goal is intentionally narrow: provide a professional, read-only local proxy that is easy to run, easy to trust locally, and easy to contribute to.

The current MVP focuses on:

• starting a local HTTP/HTTPS proxy for development traffic;
• generating and reusing a local CA and per-host certificates for HTTPS MITM;
• making local HTTPS trust setup as automatic as possible for common development workflows;
• displaying captured exchanges in a local desktop UI;
• keeping JVM interception as a follow-up workflow when the target app is a Java process;
• keeping capture read-only: no rewrite, replay, mocking, or mutation.

Project Menu

• Status
• Quick Start
• Usage
• Features
• Roadmap
• Known Limitations
• Stack
• Prerequisites
• Repository Layout
• Development
• CI/CD
• Contributing
• Spring Boot HTTPS Debugging
• License

Status

OpenIntercept is in active MVP development and is not functional yet.

• The desktop application, local proxy, and HTTPS MITM flow are still being integrated and stabilized.
• The current codebase may build or run partially, but the end-to-end product is not ready for real inspection workflows.
• JVM interception exists as a secondary workflow and is still less complete than the core proxy path.
• The project is not yet positioned as a general-purpose production proxy.

Quick Start

1. Install prerequisites

Install Node.js, Rust, and the Tauri prerequisites for your platform.

• Windows: Tauri prerequisites, Node.js, and a JDK such as Eclipse Temurin.
• Linux: see the package list in Prerequisites.
• macOS: install the standard Tauri prerequisites, Node.js, Rust, and a JDK if you want the JVM workflow.

2. Install dependencies

npm install

3. Start the desktop app

npm run dev

This launches the Tauri desktop app and starts the local proxy on 127.0.0.1:8877.

4. Route traffic through OpenIntercept

Configure the application you want to inspect to use:

• HTTP proxy: 127.0.0.1:8877
• HTTPS proxy: 127.0.0.1:8877

For HTTPS interception, the target client must trust the OpenIntercept local CA. The repository includes helper scripts for JVM truststores, and the desktop app generates the CA automatically on first run.

5. Inspect captured exchanges

Use the desktop UI to:

• inspect requests and responses;
• search by method, status, URL, headers, and body text;
• export captures as JSON;
• clear persisted and in-memory traffic.

Usage

Standard local workflow

1. Start OpenIntercept with npm run dev.
2. Trigger the app once so the local CA is generated.
3. Configure your target application to use 127.0.0.1:8877 as its HTTP and HTTPS proxy.
4. Make the target trust the OpenIntercept CA when HTTPS MITM is required.
5. Reproduce the HTTP or HTTPS traffic you want to inspect.
6. Review the captures in the desktop UI.

When HTTPS traffic does not appear

Check the following first:

• the target application is really using the proxy;
• the target trusts the generated OpenIntercept CA;
• the client is not using certificate pinning;
• the client is not forcing HTTP/2 or a custom TLS stack outside the currently supported path.

For Java and Spring Boot workflows, see Spring Boot HTTPS Debugging.

Features

• Local-first desktop application built with Tauri and React.
• Read-only HTTP/HTTPS inspection through a local Rust proxy on 127.0.0.1:8877.
• Local OpenIntercept CA generation and dynamic per-host certificate generation for HTTPS MITM.
• Truststore helper scripts for Windows, Linux, and macOS-style shells to speed up HTTPS setup in local development.
• Explicit non-attach proxy workflow for local applications that can be started with proxy and trust options.
• Java process discovery from the desktop UI.
• Java attach helper and agent that inject JVM proxy properties for selected processes.
• Java/Spring Boot workflow for routing JVM traffic through the proxy when useful.
• HTTP capture with request headers, request body, response headers, response body, status, duration, and errors.
• Robust response reading for Content-Length, Transfer-Encoding: chunked, and EOF fallback responses.
• Captured response body decoding for chunked, gzip, deflate, and br encoded responses.
• Traffic list with method/status filters and text search across URL, method, status, request headers, response headers, request body, and response body.
• Exchange detail tabs: Overview, Request, Response, and Raw.
• Failed HTTPS MITM captures show phase, likely cause, suggested action, host, and raw technical error in the UI.
• JSON export for the selected capture or current filtered capture set.
• Clear traffic action that clears in-memory and persisted captures.
• SQLite persistence for captures with a bounded retention window.

Roadmap

Roadmap state legend: [ ] not started, [~] in progress, [x] completed.

P0 - HTTPS Proxy Core

• Desktop shell with proxy status and traffic list.
• Local proxy startup on 127.0.0.1:8877.
• Basic HTTP request/response capture.
• First-pass HTTPS MITM with local CA and dynamic host certificates.
• Reuse the local CA and generated host certificates across sessions.
• Decode captured compressed bodies: gzip, deflate, and br.
• Support robust HTTP response reading for Content-Length and Transfer-Encoding: chunked.
• Add Clear traffic in the UI and backend.
• Validate end-to-end HTTPS capture against a real local Java/Spring Boot app.

P1 - HTTPS Setup Automation

• Provide JDK truststore management scripts.
• Provide a generated Java truststore for explicit JVM startup flows.
• Add a clearer in-app HTTPS setup guide for the current platform.
• Detect common trust/setup failures and surface the next action directly in the UI.
• Reduce manual certificate steps for the common local proxy workflow as much as platform constraints allow.

P2 - Inspection Usability

• Persist captures to SQLite with a size limit.
• Add filters/search by method, status, URL, and response body text.
• Add exchange detail tabs: Overview, Request, Response, Raw.
• Improve failed HTTPS MITM captures so diagnosis is clear in the UI.
• Extend search to request headers, response headers, and request body text.
• Add export for selected capture or current filtered capture set.

P3 - Inspection Depth

• Add pause/resume capture without stopping the proxy.
• Add structured filters: method=, status=, host=, path*=, header[name]*=, body*=, and bodySize.
• Display URL parts separately: protocol, host, port, path, and query parameters.
• Add visual capture categories: error, mutative, JSON, HTML, image, binary, and unknown.
• Add per-capture pin and delete actions.
• Add body viewers by MIME type: JSON, XML, HTML, form data, multipart, text, hex, image preview, and binary fallback.

P4 - JVM Interception

• Build Java agent and attach helper artifacts.
• Attach to a selected Java PID and inject proxy properties.
• Improve Java attach by injecting OpenIntercept CA trust dynamically into the target JVM.
• Package Java helper artifacts reliably into the Tauri app bundle for release builds.
• Add process attribution so captures can be linked to a Java PID when possible.

P5 - Protocol Coverage

• Support multiple HTTPS requests per MITM tunnel when clients keep the tunnel open.
• Add HTTP/2 support or an explicit downgrade strategy.
• Improve handling for large or streaming bodies with safe memory limits.
• Add explicit binary body handling and content previews by MIME type.

P6 - Analysis and Exports

• Add HAR export for the selected capture and current filtered capture set.
• Add HAR import to inspect previously captured sessions.
• Add request snippet export, starting with curl, Java java.net.http, OkHttp, Python requests, and JavaScript fetch.
• Add inline explanations for common HTTP methods, status codes, and standard headers.
• Add performance details: phase timings where available, compressed and decoded body sizes, content encoding, and cache header summary.

Explicitly Out Of Scope Until Read-Only MVP Is Stable

• Request/response rewrite and breakpoint editing.
• Mock endpoints, synthetic responses, failure injection, and replay/resend.
• Mobile, browser, Docker, Electron, WebRTC, IPFS, Ethereum, GraphQL, and gRPC integrations.

Known Limitations

• The MVP remains read-only and intentionally does not support rewrite, replay, mocking, or mutation.
• OpenIntercept is not functional yet; documented workflows describe the intended MVP behavior and may not work end-to-end today.
• HTTPS setup still depends on platform and client constraints; some flows still require manual trust configuration.
• Java attach currently injects proxy properties but does not yet install CA trust dynamically into the target JVM.
• Some Java clients may ignore JVM proxy properties, reuse prebuilt connection pools, use custom SSL contexts, or pin certificates.
• Process attribution is not implemented; captures are not reliably linked to a Java PID yet.
• HTTP/2 is not supported yet; the proxy currently focuses on HTTP/1.1 flows.
• Capture persistence is bounded and intended for local debugging, not long-term archival.

Stack

• Rust
• Tauri
• React
• SQLite

Prerequisites

Linux (Ubuntu / Debian)

Install the system libraries required by Tauri before running npm install or cargo build:

sudo apt update && sudo apt install -y \
  build-essential \
  libssl-dev \
  libwebkit2gtk-4.1-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  libxdo-dev \
  curl \
  wget \
  file \
  openjdk-21-jdk

Then install Rust via rustup and Node.js via nvm or the official installer.

Windows

Install Node.js, a JDK (e.g. Eclipse Temurin), and the Tauri prerequisites.

Repository Layout

apps/desktop/          Tauri + React desktop application
crates/capture/        Shared capture models
crates/certs/          Local CA and certificate generation
crates/java_processes/ Java process discovery
crates/proxy/          Local proxy entry point
crates/storage/        SQLite storage boundary
docs/                  Product and technical notes
java/                  Java agent and attach helper
scripts/               Local helper scripts for Java/truststore workflows

Development

Install Node.js, Rust, and Tauri prerequisites, then run:

npm install
npm run dev

Useful validation commands:

cargo check
cargo test
npm run typecheck
npm run build

If you only need the frontend during UI work:

npm run web:dev

The Java helper artifacts can be rebuilt with:

./scripts/build-java.ps1

or:

./scripts/build-java.sh

CI/CD

GitHub Actions runs validation on pull requests and pushes to main:

• Rust formatting check with cargo fmt --all -- --check;
• Rust tests with cargo test --workspace;
• frontend typecheck with npm run typecheck;
• desktop build with npm run build.

The same workflow also publishes downloadable WIP build artifacts for:

• Windows x64: openintercept-windows-x64;
• Ubuntu x64: openintercept-ubuntu-x64.

These artifacts are unsigned development builds. They are intended to make testing easier while the project is not functional yet, not to provide stable releases or production-ready installers.

Merges to main also run Semantic Release after the checks pass. A release is created only when the merged commits follow Conventional Commits:

• fix: creates a patch release;
• feat: creates a minor release;
• BREAKING CHANGE: or ! creates a major release.

When Semantic Release creates a version, the CI builds Windows and Ubuntu desktop archives with that version injected into the package metadata and attaches them to the GitHub Release.

Contributing

Contributions are welcome, especially around the core read-only proxy workflow, HTTPS setup ergonomics, UI clarity, and debugging experience.

Start here:

1. Read README.md fully, especially Features, Roadmap, and Known Limitations.
2. Check whether the work fits the current MVP scope.
3. Open an issue for significant changes before starting implementation.
4. Read CONTRIBUTING.md for the development workflow and PR expectations.

Good first contribution areas:

• HTTPS setup guidance and failure diagnosis;
• capture inspection usability;
• JVM trust and attach reliability;
• tests, docs, and reproducible bug reports.

Spring Boot HTTPS Debugging

To route a Spring Boot app through OpenIntercept without Java attach, create a Java truststore from the OpenIntercept CA and start the app with JVM proxy options. This explicit proxy startup flow is currently the most reliable JVM path.

See docs/spring-boot-proxy.md.

For a dedicated local dev JDK, scripts/manage-jdk-truststore.sh (Linux/macOS) or scripts/manage-jdk-truststore.ps1 (Windows) can import or remove the OpenIntercept CA from that JDK's cacerts truststore interactively.

License

OpenIntercept is licensed under the MIT License.