mitm-core

A TypeScript-based, extensible Man-in-the-Middle (MITM) proxy framework for Node.js.

mitm-core provides a typed plugin system and phased processing pipeline for intercepting, inspecting, and modifying network traffic. It enables developers to build custom proxy behavior, network debugging tools, and traffic analysis applications.

Documentation

• Official Documentation
• API Reference
• Examples

Prerequisites

mitm-core intercepts HTTPS traffic by generating leaf certificates for target hosts and signing them with a Root Certificate Authority (CA). Before starting the proxy with HTTPS interception enabled, you must provide a CA certificate and its corresponding private key.

Root CA Setup

Place your Root CA credentials in the creds/__self__/ directory at the root of your project.

Expected directory structure:

your-project/
├── creds/
│   └── __self__/
│       ├── CA.pem
│       └── key.pem
├── package.json
└── index.js

• CA.crt — The Root CA certificate.
• key.pem — The corresponding private key.

Generate a Root CA

You can generate a local Root CA using OpenSSL.

Create the required directory and move into it:

mkdir -p creds/__self__
cd creds/__self__

Generate a 2048-bit private key:

openssl genrsa -out key.pem 2048

Generate a self-signed Root CA certificate valid for 10 years:

openssl req -x509 -new -nodes \
  -key key.pem \
  -sha256 \
  -days 3650 \
  -out CA.pem

When prompted, provide the certificate details. Set the Common Name to a recognizable name, such as mitm-core-root.

Protect Your CA Credentials

Keep key.pem private. Do not commit your CA private key to version control or distribute it to untrusted parties.

If you use a local CA for development, only install and trust its certificate on systems you own or are authorized to administer.

Configure Certificate Trust

Clients must trust the Root CA certificate to accept certificates generated by the proxy without certificate-validation errors. Configure trust only in the test environment or on devices you are authorized to manage.

For usage instructions and a working proxy setup, see the Quick Start Guide.

Installation

Install mitm-core from npm:

npm install mitm-core

Import the required APIs into your project:

import { Proxy, BasePlugin } from "mitm-core";

For setup instructions and a working proxy example, see the Quick Start Guide.

Features

• HTTP/1.1 Interception — Intercept and process plain HTTP requests and responses.
• HTTPS Interception — Decrypt HTTPS traffic through TLS interception using dynamically generated certificates.
• WebSocket Support — Intercept and modify WebSocket (ws://) and secure WebSocket (wss://) messages.
• Typed Plugin System — Extend proxy behavior with custom plugins, typed event payloads, and lifecycle hooks.
• Phased Processing Pipeline — Process traffic through organized pipeline phases with controlled execution and abort handling.
• Rule Engine — Define custom, file-backed rules for matching targets and controlling proxy behavior.
• Plugin Development — Build custom plugins using BasePlugin, typed event payloads, and lifecycle hooks to extend proxy behavior and implement custom traffic-handling logic.
• Certificate Caching — Cache generated TLS certificates to reduce repeated certificate-generation work.
• Response Caching — Optionally cache eligible upstream responses.
• Asynchronous Plugin Execution — Support synchronous and asynchronous plugin handlers with configurable execution timeouts.
• Streaming Responses — Forward large request and response bodies through streaming pipelines.
• Connection Lifecycle Management — Handle proxy startup, shutdown, connection errors, and socket cleanup.
• TypeScript-First API — Provide typed interfaces and event maps for better IDE support and compile-time checking.

Benchmark Results

Initial local benchmark results for mitm-core. These measurements are preliminary and are not representative of sustained performance.

HTTP/1.1

| Metric | Result | | -------------------------- | -----------------: | | Average throughput | 3,227 requests/sec | | Average latency | 2.53 ms | | p99 latency | 12 ms | | Test duration | 5 seconds | | Concurrent connections | 10 | | Reported errors / timeouts | 0 / 0 |

Mixed-Protocol Load

| Metric | Result | | --------------------- | --------------------: | | Protocols | HTTP, HTTPS, WS, WSS | | Total operations | 400 | | Successful operations | 400 | | Failed operations | 0 | | Reported duration | 1.426 seconds | | Aggregate throughput | 280.50 operations/sec |

Test Environment

• CPU: AMD Ryzen 5 5600G (12 logical CPUs)
• Memory: 13 GiB RAM
• OS: Fedora Linux 44 Workstation
• Node.js: v24.18.0

Results were measured locally and may vary depending on hardware, workload, and configuration. Detailed benchmarking methodology and further stress-test results will be documented separately.

Security Notice

mitm-core is intended for authorized security research, traffic analysis, and debugging.

Only intercept traffic on systems and networks you own or have explicit permission to test. You are responsible for complying with applicable laws and protecting intercepted data. Keep your Root CA private key secure, and avoid installing or distributing CA certificates beyond environments you control.

Contributing

Contributions are welcome! See CONTRIBUTING.md to get started.

License

MIT © Debanshu Panigrahi

See LICENSE for full terms.