netserpent 0.1.0/README

netserpent 0.1.0
****************

This document have some general infomations on netserpent.
If you want to know how to install and use it, you may see "INSTALL"
file in the same directory.
If you want to write your own filter plugin, you may see the
"doc/filterplugin-tutorial.*" files.

Abstract
========

Netserpent is a third-party-hack-program framework under network 3rd
level. It configurably hijacks the 3rd level connections(currently
support tcp) outgoing or forwarding, and configurably use plugins to
determine how to hack the hijacked connection. You can write your own
plugins to :
 - log network sessions
 - transparently do network proxy for up-level programms. Even use
 the shiped chain plugin to chain these plugins together in order to
 make up a network proxy chain
 - analyse some non-open 3rd level network protocal
 - any tricks you can imagine

Architecure
===========

Currently it use netfilter/iptables to hijack connections, and working
completely in user space. See this ascii-art :

+---------------------------------+ forward
 | netfilter hooks | connections
 <.................................................................
 | . iptables framework | .
kernel space | . | .
-------------------+----.--------+-------------------+-------.------
user space . | iptables utility | .
 . | | .
 . +-------------^-----+ .
 . +--------------++ .
 . |control prog || .
 . +--------------++ .
 +--------.---+----------+ | .
 | . | map | | outgoing
 | . | --+-------+ connections
 +--------.---+----------+
 | plugin system |
 +-------+-------+ . |
 |loader | +--|-----.--------------+
 +-------+ | . libnetserpent
 | .
 +-------------|----+ .+-------------------+
 | cli | | > echo |
 | script v | | dnat |
 | | | ....... |
 | | | |
 +------------------+ +-------------------+
 loader plugins filter plugins

Some comments :

* map
 A mechanism to control which connections to hijack and how to deal
 with them. It use control prog to interactive with the iptables. 

* control prog
 Since generally iptables need privilege to operate, so the
 netserpent map do not directly interactive with iptables. The
 control prog usually used as a sudo-able or setuid program to get
 rid of the privilege problem and meet the minimal privilege
 reqirement.

* loader and loader plugins
 As a library can not run itself, a netserpent loader is a program
 linked with libnetserpent and run the startup code to rock
 everything up. Though the netserpent framework is configurable, but
 the loader doesn't config it itself. Instead, it loads loader
 plugins. Currently it has cli(command line interface) and script
 plugin, these plugins will operate the netserpent map in their
 behavior.

* Since forward and outgoing connections can all be hijacked, so what
 if the filter plugin makes a outgoing connection? So currently
 libnetserpent will not infect the connections generated by the
 programs which have the same uid of the linked program(the loader).

Status
======

This is the first release. It's in the stage of achitecture and api
review, and haven't registed to sourceforge or otherwhere. Your idea
and contribute is greatly appreciated and will be the strongest
motivity to this project, so just fell free to contact me.

Contact
======= 

E-mail/GTALK: hellwolf DOT misty AT gmail DOT com