Matahari
Matahari is a HTTP Man In The Middle (MITM) Proxy written in node.js. Supports capturing and modifying the request and response data.
Install
npm install --save matahari
Typescript
type definitions are now included in this project, no extra steps required.
Example
This example will modify any search results coming from google and replace all the result titles with "Pwned!".
var Proxy = ;var proxy = Proxy; proxy; proxy; proxy;
You can find more examples in the examples directory
SSL
Using node-forge allows the automatic generation of SSL certificates within the proxy. After running your app you will find options.sslCaDir + '/certs/ca.pem' which can be imported to your browser, phone, etc.
API
Proxy
- listen(options)
- close
- onError(fn)
- onCertificateRequired
- onCertificateMissing
- onRequest(fn)
- onRequestData(fn)
- onRequestEnd(fn)
- onResponse(fn)
- onResponseData(fn)
- onResponseEnd(fn)
- onWebSocketConnection(fn)
- onWebSocketSend(fn)
- onWebSocketMessage(fn)
- onWebSocketFrame(fn)
- onWebSocketError(fn)
- onWebSocketClose(fn)
- use(fn)
Context
Context functions only effect the current request/response. For example you may only want to gunzip requests made to a particular host.
- isSSL: boolean,
- clientToProxyRequest: IncomingMessage,
- proxyToClientResponse: ServerResponse,
- proxyToServerRequest: ClientRequest,
- serverToProxyResponse: IncomingMessage,
- onError(fn)
- onRequest(fn)
- onRequestData(fn)
- onRequestEnd(fn)
- addRequestFilter(fn)
- onResponse(fn)
- onResponseData(fn)
- onResponseEnd(fn)
- addResponseFilter(fn)
- use(mod)
WebSocket Context
The context available in websocket handlers is a bit different
- isSSL: boolean,
- clientToProxyWebSocket: WebSocket,
- proxyToServerWebSocket: WebSocket,
- onWebSocketConnection(fn)
- onWebSocketSend(fn)
- onWebSocketMessage(fn)
- onWebSocketFrame(fn)
- onWebSocketError(fn)
- onWebSocketClose(fn)
- use(mod)
Proxy
proxy.listen
Starts the proxy listening on the given port.
Arguments
- options - An object with the following options:
- port - The port or named socket to listen on (default: 8080).
- host - The hostname or local address to listen on.
- sslCaDir - Path to the certificates cache directory (default:
process.cwd() + '/.matahari'
) - keepAlive - enable HTTP persistent connection
- timeout - The number of milliseconds of inactivity before a socket is presumed to have timed out. Defaults to no timeout.
- httpAgent - The http.Agent to use when making http requests. Useful for chaining proxys. (default: internal Agent)
- httpsAgent - The https.Agent to use when making https requests. Useful for chaining proxys. (default: internal Agent)
- forceSNI - force use of SNI by the client. Allow matahari to handle all HTTPS requests with a single internal server.
- forceChunkedRequest - Setting this option will remove the content-length from the proxy to server request, forcing chunked encoding.
- ownHost - A test to determine whether a request is pointed to the proxy server itself.
Can be a function with signature
ownHost(hostname, port)
, a regular expression, an exact string, or an array of other tests. The default behavior is to filter requests tolocalhost
and127.0.0.1
on whichever port the proxy server is listening on. This check will always be included because it is certain to result in an infinite request loop, so there's no need to specify it when adding customizedownHost
tests. - ownHostHttpServer - An HTTP server that will be used to handle requests that match the
ownHost
tests. If not specified, then a404
response will be sent with an error message.
Example
proxy.listen({ port: 80 });
proxy.close
Stops the proxy listening.
Example
proxy.close();
proxy.onError(fn) or ctx.onError(fn)
Adds a function to the list of functions to get called if an error occures.
Arguments
- fn(ctx, err, errorKind) - The function to be called on an error.
Example
proxy.onError(function(ctx, err, errorKind) {
// ctx may be null
var url = (ctx && ctx.clientToProxyRequest) ? ctx.clientToProxyRequest.url : "";
console.error(errorKind + ' on ' + url + ':', err);
});
proxy.onCertificateRequired = function(hostname, callback)
Allows the default certificate name/path computation to be overwritten.
The default behavior expects keys/{hostname}.pem
and certs/{hostname}.pem
files to be at self.sslCaDir
.
Arguments
- hostname - Requested hostname.
- callback - The function to be called when certificate files' path were already computed.
Example 1
proxy.onCertificateRequired = function(hostname, callback) {
return callback(null, {
keyFile: path.resolve('/ca/certs/', hostname + '.key'),
certFile: path.resolve('/ca/certs/', hostname + '.crt')
});
};
Example 2: Wilcard certificates
proxy.onCertificateRequired = function(hostname, callback) {
return callback(null, {
keyFile: path.resolve('/ca/certs/', hostname + '.key'),
certFile: path.resolve('/ca/certs/', hostname + '.crt'),
hosts: ["*.mydomain.com"]
});
};
proxy.onCertificateMissing = function(ctx, files, callback)
Allows you to handle missing certificate files for current request, for example, creating them on the fly.
Arguments
- ctx - Context with the following properties
- hostname - The hostname which requires certificates
- data.keyFileExists - Whether key file exists or not
- data.certFileExists - Whether certificate file exists or not
- files - missing files names (
files.keyFile
,files.certFile
and optionalfiles.hosts
) - callback - The function to be called to pass certificate data back (
keyFileData
andcertFileData
)
Example 1
proxy.onCertificateMissing = function(ctx, files, callback) {
console.log('Looking for "%s" certificates', ctx.hostname);
console.log('"%s" missing', ctx.files.keyFile);
console.log('"%s" missing', ctx.files.certFile);
// Here you have the last chance to provide certificate files data
// A tipical use case would be creating them on the fly
//
// return callback(null, {
// keyFileData: keyFileData,
// certFileData: certFileData
// });
};
Example 2: Wilcard certificates
proxy.onCertificateMissing = function(ctx, files, callback) {
return callback(null, {
keyFileData: keyFileData,
certFileData: certFileData,
hosts: ["*.mydomain.com"]
});
};
proxy.onRequest(fn) or ctx.onRequest(fn)
Adds a function to get called at the beginning of a request.
Arguments
- fn(ctx, callback) - The function that gets called on each request.
Example
proxy.onRequest(function(ctx, callback) {
console.log('REQUEST:', ctx.clientToProxyRequest.url);
return callback();
});
proxy.onRequestData(fn) or ctx.onRequestData(fn)
Adds a function to get called for each request data chunk (the body).
Arguments
- fn(ctx, chunk, callback) - The function that gets called for each data chunk.
Example
proxy.onRequestData(function(ctx, chunk, callback) {
console.log('REQUEST DATA:', chunk.toString());
return callback(null, chunk);
});
proxy.onRequestEnd(fn) or ctx.onRequestEnd(fn)
Adds a function to get called when all request data (the body) was sent.
Arguments
- fn(ctx, callback) - The function that gets called when all request data (the body) was sent.
Example
var chunks = [];
proxy.onRequestData(function(ctx, chunk, callback) {
chunks.push(chunk);
return callback(null, chunk);
});
proxy.onRequestEnd(function(ctx, callback) {
console.log('REQUEST END', (Buffer.concat(chunks)).toString());
return callback();
});
proxy.onResponse(fn) or ctx.onResponse(fn)
Adds a function to get called at the beginning of the response.
Arguments
- fn(ctx, callback) - The function that gets called on each response.
Example
proxy.onResponse(function(ctx, callback) {
console.log('BEGIN RESPONSE');
return callback();
});
proxy.onResponseData(fn) or ctx.onResponseData(fn)
Adds a function to get called for each response data chunk (the body).
Arguments
- fn(ctx, chunk, callback) - The function that gets called for each data chunk.
Example
proxy.onResponseData(function(ctx, chunk, callback) {
console.log('RESPONSE DATA:', chunk.toString());
return callback(null, chunk);
});
proxy.onResponseEnd(fn) or ctx.onResponseEnd(fn)
Adds a function to get called when the proxy request to server has ended.
Arguments
- fn(ctx, callback) - The function that gets called when the proxy request to server as ended.
Example
proxy.onResponseEnd(function(ctx, callback) {
console.log('RESPONSE END');
return callback();
});
proxy.onWebSocketConnection(fn) or ctx.onWebSocketConnection(fn)
Adds a function to get called at the beginning of websocket connection
Arguments
- fn(ctx, callback) - The function that gets called for each data chunk.
Example
proxy.onWebSocketConnection(function(ctx, callback) {
console.log('WEBSOCKET CONNECT:', ctx.clientToProxyWebSocket.upgradeReq.url);
return callback();
});
proxy.onWebSocketSend(fn) or ctx.onWebSocketSend(fn)
Adds a function to get called for each WebSocket message sent by the client.
Arguments
- fn(ctx, message, flags, callback) - The function that gets called for each WebSocket message sent by the client.
Example
proxy.onWebSocketSend(function(ctx, message, flags, callback) {
console.log('WEBSOCKET SEND:', ctx.clientToProxyWebSocket.upgradeReq.url, message);
return callback(null, message, flags);
});
proxy.onWebSocketMessage(fn) or ctx.onWebSocketMessage(fn)
Adds a function to get called for each WebSocket message received from the server.
Arguments
- fn(ctx, message, flags, callback) - The function that gets called for each WebSocket message received from the server.
Example
proxy.onWebSocketMessage(function(ctx, message, flags, callback) {
console.log('WEBSOCKET MESSAGE:', ctx.clientToProxyWebSocket.upgradeReq.url, message);
return callback(null, message, flags);
});
proxy.onWebSocketFrame(fn) or ctx.onWebSocketFrame(fn)
Adds a function to get called for each WebSocket frame exchanged (message
, ping
or pong
).
Arguments
- fn(ctx, type, fromServer, data, flags, callback) - The function that gets called for each WebSocket frame exchanged.
Example
proxy.onWebSocketFrame(function(ctx, type, fromServer, data, flags, callback) {
console.log('WEBSOCKET FRAME ' + type + ' received from ' + (fromServer ? 'server' : 'client'), ctx.clientToProxyWebSocket.upgradeReq.url, message);
return callback(null, message, flags);
});
proxy.onWebSocketError(fn) or ctx.onWebSocketError(fn)
Adds a function to the list of functions to get called if an error occures in WebSocket.
Arguments
- fn(ctx, err) - The function to be called on an error in WebSocket.
Example
proxy.onWebSocketError(function(ctx, err) {
console.log('WEBSOCKET ERROR:', ctx.clientToProxyWebSocket.upgradeReq.url, err);
});
proxy.onWebSocketClose(fn) or ctx.onWebSocketClose(fn)
Adds a function to get called when a WebSocket connection is closed
Arguments
- fn(ctx, code, message, callback) - The function that gets when a WebSocket is closed.
Example
proxy.onWebSocketClose(function(ctx, code, message, callback) {
console.log('WEBSOCKET CLOSED BY '+(ctx.closedByServer ? 'SERVER' : 'CLIENT'), ctx.clientToProxyWebSocket.upgradeReq.url, code, message);
callback(null, code, message);
});
proxy.use(module) or ctx.use(module)
Adds a module into the proxy. Modules encapsulate multiple life cycle processing functions into one object.
Arguments
- module - The module to add. Modules contain a hash of functions to add.
Example
proxy.use({
onError: function(ctx, err) { },
onCertificateRequired: function(hostname, callback) { return callback(); },
onCertificateMissing: function(ctx, files, callback) { return callback(); },
onRequest: function(ctx, callback) { return callback(); },
onRequestData: function(ctx, chunk, callback) { return callback(null, chunk); },
onResponse: function(ctx, callback) { return callback(); },
onResponseData: function(ctx, chunk, callback) { return callback(null, chunk); },
onWebSocketConnection: function(ctx, callback) { return callback(); },
onWebSocketSend: function(ctx, message, flags, callback) { return callback(null, message, flags); },
onWebSocketMessage: function(ctx, message, flags, callback) { return callback(null, message, flags); },
onWebSocketError: function(ctx, err) { },
onWebSocketClose: function(ctx, code, message, callback) { },
});
Matahari provide some ready to use modules:
Proxy.gunzip
Gunzip response filter (uncompress gzipped content before onResponseData and compress back after)Proxy.wildcard
Generates wilcard certificates by default (so less certificates are generated)
Context
ctx.addRequestFilter(stream)
Adds a stream into the request body stream.
Arguments
- stream - The read/write stream to add in the request body stream.
Example
ctx.addRequestFilter(zlib.createGunzip());
ctx.addResponseFilter(stream)
Adds a stream into the response body stream.
Arguments
- stream - The read/write stream to add in the response body stream.
Example
ctx.addResponseFilter(zlib.createGunzip());