Mitm.js

When using Mitm.js in a testing framework, use beforeEach and afterEach hooks to ensure interception is enabled only for the duration of each test case and is properly cleaned up afterward.

beforeEach(function() { this.mitm = Mitm() })
afterEach(function() { this.mitm.disable() })

To allow certain connections (like database connections or localhost integration tests) to reach the real network, listen for the connect event and call .bypass() on the provided socket. The connect event provides an opts object containing the original connection parameters (e.g., host and port).

mitm.on("connect", function(socket, opts) {
  if (opts.host == "sql.example.org" && opts.port == 5432) {
    socket.bypass()
  }
})

Install the mitm package using npm to begin intercepting outgoing TCP and HTTP connections in your Node.js application.

npm install mitm

To start intercepting, require the module and invoke it as a function. This creates a Mitm instance and immediately enables interception for all subsequent network requests. To stop intercepting, call the .disable() method on the instance.

var Mitm = require("mitm")
var mitm = Mitm()

// ... intercepting happens here ...

mitm.disable()

To start intercepting network traffic, instantiate Mitm and call .enable(). The Mitm constructor can be called with new Mitm() or as a function Mitm(). Calling .enable() performs the necessary monkey-patching of Node.js core modules (net, tls, http, https) to intercept connections. To stop interception and restore original behavior, call .disable().

Note that Mitm is an EventEmitter, so you can listen for events like connect, connection, and request immediately after instantiation.

```javascript
const Mitm = require('mitm');
const mitm = new Mitm().enable();

// To stop intercepting:
// mitm.disable();
```埋

Mitm.js intercepts Http.request and Https.request calls and emits a request event. The event listener receives a server-side Http.IncomingMessage (req) and Http.ServerResponse (res).

Note: HTTPS requests are currently morphed into HTTP requests to avoid certificate management.

Note: Custom HTTP methods are not supported out-of-the-box because the underlying Node.js HTTP parser throws errors for unsupported methods.

// Asserting on a request
mitm.on("request", function(req, res) {
  req.headers.authorization.must.equal("OAuth DEADBEEF")
})

Http.get("http://example.org")

// Responding to a request
mitm.on("request", function(req, res) {
  res.statusCode = 402
  res.end("Pay up, sugar!")
})

Http.get("http://example.org", function(res) {
  res.setEncoding("utf8")
  res.statusCode // => 402
  res.on("data", console.log) // => "Pay up, sugar!"
})

Mitm.js intercepts Net.connect calls and emits a connection event. The event listener receives a server-side Net.Socket object, allowing you to respond to the client as if you were the remote server.

mitm.on("connection", function(socket) {
  socket.write("Hello back!")
})

var socket = Net.connect(22, "example.org")
socket.write("Hello!")
socket.setEncoding("utf8")
socket.on("data", console.log) // => "Hello back!"

The following events are emitted by a Mitm instance:

The Stubs class provides a mechanism to temporarily replace properties on an object and restore their original values later. This is useful for mocking or intercepting behavior during tests.

• Use .stub(obj, prop, value) to replace obj[prop] with value. The original value is tracked internally.
• Use .restore() to revert all stubbed properties back to their original state in reverse order of stubbing.

const Stubs = require('./lib/stubs');
const stubs = new Stubs();

const myObj = { key: 'original' };

// Replace 'key' with 'mocked'
stubs.stub(myObj, 'key', 'mocked');
console.log(myObj.key); // 'mocked'

// Revert to 'original'
stubs.restore();
console.log(myObj.key); // 'original'

When Mitm is enabled, it intercepts calls to net.connect, net.createConnection, and tls.connect.

• TCP Interception: Emits a connect event on the client socket and a connection event on the server socket.
• TLS Interception: Emits a secureConnect event on the client socket.

Events emitted:

• connect: Emitted on the client-side socket. Arguments: (client, opts).
• connection: Emitted on the server-side socket. Arguments: (server, opts).
• secureConnect: Emitted on the client-side TLS socket.

const Mitm = require('mitm');
const mitm = new Mitm().enable();

mitm.on('connect', (client, opts) => {
  console.log('TCP connection intercepted:', opts);
});

mitm.on('connection', (server, opts) => {
  console.log('Server-side socket created:', opts);
});

When an intercepted connection is identified as an HTTP request, Mitm triggers the request event. This event provides access to both the IncomingMessage (request) and ServerResponse (response) objects.

Mitm automatically cross-references the request and response objects, meaning req.res points to the response and res.req points to the request.

Events emitted:

• request: Emitted when an HTTP request is detected. Arguments: (req, res).

const Mitm = require('mitm');
const mitm = new Mitm().enable();

mitm.on('request', (req, res) => {
  console.log('Intercepted request:', req.method, req.url);
  
  // Cross-references are available:
  // req.res === res
  // res.req === req

  res.end('Intercepted!');
});