Skip to content

Commit

Permalink
Merge pull request #52 from mlhaigh/proxy_doc
Browse files Browse the repository at this point in the history
Completed documentation for Proxy
  • Loading branch information
iphelix authored Oct 16, 2017
2 parents 200a3b9 + 51b3c44 commit f6bf2db
Showing 1 changed file with 26 additions and 1 deletion.
27 changes: 26 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -298,6 +298,7 @@ file:
Listener: DNSListener
DNSResponse: 192.0.2.123
NXDomains: 0
Hidden: False

[RawTCPListener]
Enabled: True
Expand All @@ -306,6 +307,7 @@ file:
Listener: RawListener
UseSSL: No
Timeout: 10
Hidden: False

The configuration file is broken up into several sections.

Expand Down Expand Up @@ -456,6 +458,7 @@ look at a sample listener configuration:
Listener: RawListener
UseSSL: Yes
Timeout: 10
Hidden: False

The configuration above consists of the listener name `TCPListener1234`. It
will be used for logging purposes so you can distinguish between different
Expand All @@ -479,6 +482,9 @@ The following settings are generic for all listeners:
feature is useful for extending FakeNet-NG's functionality
(e.g. launch a debugger on the connecting pid to help with
unpacking and decoding.)
* **Hidden** - Do not allow traffic to be directed to this listener
without going through the proxy which will determine the
protocol based on the packet contents

The `Port` and `Protocol` settings are necessary for the listeners to know to
which ports to bind and, if they support multiple protocol (e.g RawListener),
Expand All @@ -505,6 +511,8 @@ listeners:
a configurable file which can be specified using
`DumpHTTPPosts` and `DumpHTTPPostsFilePrefix` settings.
* **SMTPListener** - supports SMTP protocol.
* **ProxyListener**- Detects protocol based on packet contents and redirects
packets accordingly.


NOTE: FakeNet-NG will attempt to locate the webroot directory, first by using
Expand Down Expand Up @@ -653,7 +661,7 @@ configuration below:
Listeners: HTTPListener, RawListener, FTPListener, DNSListener, POPListener, SMTPListener, TFTPListener, IRCListener, BITSListener
Hidden: False

Note, the new `Listeners` parameter which defines a list of potential protocol handler
Note, the new `Listeners` parameter which defines a list of potential protocol handlers
to try for all incoming connections.

It is also recommended to define a proxy listener as your default handler by updating
Expand All @@ -667,6 +675,18 @@ With the default listener pointing to the proxy listener, all unknown connection
will be appropriately handled. You can still assign specific listeners to ports to
enforce a specific protocol (e.g. always use HTTP listener for port 80).

The Proxy determines the protocol of packets by polling all available listeners with
the function taste(). Each Listener that implements taste() will respond with a score
indicating the likelihood that the protocol handled by that listener matches the
packet contents. The Proxy will forward the packet to the Listener that returned the
highest score. The RawListener will always return a score of 1, so it will be chosen
in the case that all other Listeners return 0, thus serving as the default.

Users can alter the configuration parameter 'Hidden' in each Listener's configuration.
If Hidden is 'False', the Listener will be bound to a specific port and automatically
receive all traffic on that port. With Hidden set to 'True', the Listener can only
receive traffic that is redirected through the Proxy.

Development
===========

Expand Down Expand Up @@ -725,6 +745,11 @@ Another requirement is to ensure that the listener can reliably shutdown when
the `stop()` method is called. For example, make use of connection timeouts to
ensure that the listener does not block on some connection for too long.

Listeners that implement the function `taste(self, data, dport)` will be
considered when packets are directed by the Proxy. The function must return
a score which indicates the likelihood that the Listener handles the
protocol that is contained in the packet.

The logging convention used by FakeNet-NG's listeners is to use the self.logger
object for the output. That way the logging is uniform across the application.
For example to display an error or warning you would use the following:
Expand Down

0 comments on commit f6bf2db

Please sign in to comment.