{"id":16068,"library":"http-mitm-proxy","title":"HTTP Man In The Middle (MITM) Proxy","description":"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.","status":"maintenance","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/joeferner/node-http-mitm-proxy","tags":["javascript","mitm","http","https","ssl","websocket","proxy","typescript"],"install":[{"cmd":"npm install http-mitm-proxy","lang":"bash","label":"npm"},{"cmd":"yarn add http-mitm-proxy","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-mitm-proxy","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for automatic SSL certificate generation and handling HTTPS traffic.","package":"node-forge","optional":false}],"imports":[{"note":"The main Proxy class is a named export. CommonJS users should access it via '.Proxy' property.","wrong":"const Proxy = require('http-mitm-proxy');","symbol":"Proxy","correct":"import { Proxy } from 'http-mitm-proxy';"},{"note":"`gunzip` is a static utility function on the `Proxy` class, not a direct named export.","wrong":"import { gunzip } from 'http-mitm-proxy';","symbol":"Proxy.gunzip","correct":"import { Proxy } from 'http-mitm-proxy';\nconst { gunzip } = Proxy;"},{"note":"The `Context` interface/type is a named export for TypeScript users to type their handlers.","wrong":"import Context from 'http-mitm-proxy/Context';","symbol":"Context","correct":"import { Context } from 'http-mitm-proxy';"}],"quickstart":{"code":"import { Proxy } from 'http-mitm-proxy';\n\nconst proxy = new Proxy();\n\nproxy.onError(function(ctx, err) {\n  console.error('Proxy error for URL:', ctx?.clientToProxyRequest?.url || 'N/A', 'Error:', err);\n});\n\nproxy.onRequest(function(ctx, callback) {\n  // Example: Modify Google search results\n  if (ctx.clientToProxyRequest.headers.host === 'www.google.com' && ctx.clientToProxyRequest.url.startsWith('/search')) {\n    ctx.use(Proxy.gunzip); // Decompress gzipped responses\n\n    ctx.onResponseData(function(ctx, chunk, callback) {\n      // Replace all h3 titles with \"Pwned!\"\n      chunk = Buffer.from(chunk.toString().replace(/<h3.*?<\\/h3>/g, '<h3>Pwned!</h3>'));\n      return callback(null, chunk);\n    });\n  }\n  return callback();\n});\n\nconsole.log('HTTP MITM Proxy listening on port 8081');\nproxy.listen({ port: 8081 });","lang":"typescript","description":"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."},"warnings":[{"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`).","message":"The `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.","severity":"breaking","affected_versions":"<1.1.0"},{"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.","message":"To 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The `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.","severity":"deprecated","affected_versions":">=1.1.0"},{"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.","message":"While 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.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The client system or browser does not trust the self-signed root CA certificate generated by the proxy for HTTPS interception.","error":"Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE"},{"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.","cause":"The generated SSL certificates (either the root CA or an intermediate certificate) have expired according to the client's system clock.","error":"Error: proxy error: certificate has expired"},{"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.","cause":"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.","error":"ERR_CERT_COMMON_NAME_INVALID"}],"ecosystem":"npm"}