HTTP Man In The Middle (MITM) Proxy

Common errors

• Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE

  cause 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

  cause 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

  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.
  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.

Warnings

• breaking 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.
  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`).
• gotcha 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.
  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.
• deprecated 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.
  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.
• breaking 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.
  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.

Install

• npm install http-mitm-proxy npm
• yarn add http-mitm-proxy yarn
• pnpm add http-mitm-proxy pnpm

Imports

• Proxy
  wrong:

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

  correct:

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

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

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

  correct:

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

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

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

  correct:

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

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

Quickstart

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 });