tcpigeon
v1.0.5
Published
A simple transparent TCP proxy implementation for debugging purposes.
Downloads
8
Maintainers
Readme
Tcpigeon
_
\. _(9>
\==_)
-\'=
It carries messages over long distances and it will generally return to its nest.
_
<6)_ ,/
(_==/
=\'-
Tcpigeon is a simple transparent TCP proxy implementation you can use for debugging purposes. It acts as a mitm entity which intercepts, logs and delivers TCP messages from client(s) to server in both directions.
Use cases
- You wrote a communication protocol and you need to verify the data exchanged between source and destination.
- You have to inspect the payload of every TCP message sent by two end-points.
This is the scenario:
<===> client 1
remote server <===> TCPIGEON <===> client 2
...
<===> client n
Install
npm:
$ npm install tcpigeon [-g]
or clone the repository:
git clone https://github.com/skanna/tcpigeon.git
Require
var Tcpigeon = require('tcpigeon');
See examples.
Tests
If you don't have mocha
installed you need to install devDependecies:
$ cd tcpigeon
$ npm install
Run tests:
$ npm test
Options
options = {
proxy_port : 30080, // proxy port
proxy_addr : '127.0.0.1', // proxy address
remote_port : null, // remote server port - mandatory
remote_host : null, // remote server host - mandatory
encoding : 'utf8', // character encoding
logging : 'file', // log type
max_conn : 100 // max allowed connections
}
remote_port
andremote_host
are mandatory, the other parameters have default values as shown.encoding
can assume the same values as in the Buffer module.logging
possible values are: "file" (default), "console" or "nolog".- The
max_conn
value should be equal to the remote server capacity, at least.
Methods
// Run proxy
Tcpigeon#fly(Object tcpigeon_options) : net.Server
// Stop proxy
Tcpigeon#land() : undefined
// Drop the connection to the specified client
Tcpigeon#kill(ip_address) : undefined
// Returns the list of the open sockets in the form 'ip_address:port'
Tcpigeon#flock() : Array
The fly
method returns null
in case of configuration error, (ie an option in a bad format). In case there are many open sockets shared with the same client the kill
method will destroy the first one it finds.
Events
Custom events:
// new connection - a pigeon can fly
// source format is ip_address:port
'carrier' : function(String source)
// a pigeon has a new message for you
'post' : function(String message)
// a pigeon was killed :(
'killed' : function(Number clients)
// error - no more flying pigeons
'falling' : function(Object Error)
Logging
Each line is preceded by a datetime value and a symbol that categorizes it. Use these symbols to spot:
- (EE) errors
- (WW) warnings
- (II) general informations
- (++) new connections
- (--) disconnections
- (<<) client to server direction
- (>>) server to client direction
The length of every message is printed too.
example:
9/28/2017, 3:48:43 PM - (II) Tcpigeon Server listening to {"address":"127.0.0.1","family":"IPv4","port":30080}
9/28/2017, 3:48:51 PM - (++) connection from 127.0.0.1:51313
9/28/2017, 3:48:51 PM - (II) 1 clients currently connected
9/28/2017, 3:48:51 PM - (<<) from 127.0.0.1:51313: client ONE - length: 10 bytes
9/28/2017, 3:48:51 PM - (<<) client ONE - length: 10 bytes
9/28/2017, 3:48:51 PM - (>>) client ONE - length: 10 bytes
9/28/2017, 3:48:51 PM - (>>) to 127.0.0.1:51313: client ONE - length: 10 bytes
Acknowledgements
Coding style is inpired to the modules written by @rootslab :+1: (have a look!!)
Thank you for giving me a lot of precious suggestions!