Registry / http-networking / http-mitm-proxy

http-mitm-proxy

library1.1.0jsnpmunverified

http-mitm-proxy is a robust Node.js-based HTTP and HTTPS Man In The Middle (MITM) proxy designed for intercepting, inspecting, and modifying network traffic, including WebSocket communications. It provides granular control over requests and responses through its event-driven API, allowing developers to implement custom filters and handlers. A key feature is its automatic generation of SSL certificates using `node-forge`, which facilitates transparent interception of encrypted HTTPS connections, requiring users to trust a generated root CA certificate. The current stable version is 1.1.0, which was published approximately two years ago. While the library is still widely used and downloaded, its maintenance status is currently considered inactive, with no new releases in the past year and limited recent activity on its GitHub repository. Key differentiators include its pure Node.js implementation, bundled TypeScript definitions, and a modular API for extending functionality with various request and response filters.

http-networking auth-security testing devops

npm install http-mitm-proxy

github ↗package ↗

INSTALL

IMPORT

SIG · HTTP-MITM-PROXY

http-mitm-proxy

http-networkingjavascriptv1.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Proxy

✓ import { Proxy } from 'http-mitm-proxy';

✗ const Proxy = require('http-mitm-proxy');

The main Proxy class is a named export. CommonJS users should access it via '.Proxy' property.

Proxy.gunzip

✓ import { Proxy } from 'http-mitm-proxy'; const { gunzip } = Proxy;

✗ import { gunzip } from 'http-mitm-proxy';

`gunzip` is a static utility function on the `Proxy` class, not a direct named export.

Context

✓ import { Context } from 'http-mitm-proxy';

✗ import Context from 'http-mitm-proxy/Context';

The `Context` interface/type is a named export for TypeScript users to type their handlers.

This quickstart initializes an HTTP MITM proxy on port 8081 and demonstrates how to intercept and modify responses, specifically replacing Google search result titles with 'Pwned!'. It also includes basic error handling. To intercept HTTPS, the generated CA certificate must be trusted by the client.

import { Proxy } from 'http-mitm-proxy'; const proxy = new Proxy(); proxy.onError(function(ctx, err) { console.error('Proxy error for URL:', ctx?.clientToProxyRequest?.url || 'N/A', 'Error:', err); }); proxy.onRequest(function(ctx, callback) { // Example: Modify Google search results if (ctx.clientToProxyRequest.headers.host === 'www.google.com' && ctx.clientToProxyRequest.url.startsWith('/search')) { ctx.use(Proxy.gunzip); // Decompress gzipped responses ctx.onResponseData(function(ctx, chunk, callback) { // Replace all h3 titles with "Pwned!" chunk = Buffer.from(chunk.toString().replace(/<h3.*?<\/h3>/g, '<h3>Pwned!</h3>')); return callback(null, chunk); }); } return callback(); }); console.log('HTTP MITM Proxy listening on port 8081'); proxy.listen({ port: 8081 });

mitm-proxy --version

Debug

Known issues

breakingThe `engines` field in `package.json` specifies Node.js `>=16`, which is stricter than the `README`'s mention of testing starting from Node.js 12.x. Users on Node.js versions below 16 may encounter installation issues or unexpected runtime behavior. Always adhere to the `engines` field for compatibility.

fix

Ensure your Node.js environment is version 16 or newer. Update Node.js or use a version manager like `nvm` to switch to a compatible version (e.g., `nvm install 16 && nvm use 16`).

affects: <1.1.0

gotchaTo successfully intercept HTTPS traffic without browser or client warnings, the root CA certificate generated by `http-mitm-proxy` must be explicitly installed and trusted by the client's operating system or browser. This certificate is typically found at `options.sslCaDir + '/certs/ca.pem'` after the proxy starts. Failure to do so will result in SSL/TLS errors and security warnings.

fix

Locate the `ca.pem` file in your configured `sslCaDir` (default usually in a temporary directory) and manually import it into your system's or browser's trusted root certificate store. Specific steps vary by OS/browser.

affects: >=0.1.0

deprecatedThe `http-mitm-proxy` project is currently in a state of inactive maintenance. According to recent analysis, there have been no new npm releases in the past year and minimal recent activity on its GitHub repository. While still functional, critical bug fixes, security patches, or new feature development may not be actively pursued.

fix

Consider auditing the project's codebase for any security vulnerabilities if used in production. For long-term projects, explore more actively maintained alternatives or be prepared to fork and maintain the library internally.

affects: >=1.1.0

breakingWhile not explicitly documented in the provided excerpt, a major version bump from 0.x to 1.x typically introduces breaking API changes. Users migrating from pre-1.0 versions should thoroughly review the project's commit history and examples for any API alterations that may not be backward compatible.

fix

Refer to the project's GitHub repository for detailed changelogs or release notes between 0.x and 1.x. Test your application thoroughly after upgrading and adapt your code to the new API if necessary.

affects: >=1.0.0

Errors

Common errors & fixes

Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE

The client system or browser does not trust the self-signed root CA certificate generated by the proxy for HTTPS interception.

fix

Manually install the `ca.pem` certificate from the proxy's `sslCaDir` into your client's operating system or browser's trusted root certificate store.

Error: proxy error: certificate has expired

The generated SSL certificates (either the root CA or an intermediate certificate) have expired according to the client's system clock.

fix

Ensure your system's date and time are correct. If the issue persists, delete the contents of the `sslCaDir` directory to force the proxy to regenerate new CA and host certificates.

ERR_CERT_COMMON_NAME_INVALID

The requested hostname does not match the 'Common Name' or 'Subject Alternative Names' (SANs) in the generated SSL certificate, which can happen with certain strict clients or configurations.

fix

Ensure the `sslCaDir` is correctly set up and the CA is trusted. For specific or complex hostname scenarios, consider using the `proxy.onCertificateRequired` hook to provide custom certificates that exactly match the target host.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

node-forgerequiredUsed internally for automatic SSL certificate generation and handling HTTPS traffic.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/joeferner/node-http-mitm-proxy ↗

packagehttps://www.npmjs.com/package/http-mitm-proxy ↗