test-tunnel

The test-tunnel library: write tests for network tunnelling utilities

[Home | GitLab | Download | PyPI | ReadTheDocs]

Overview

The test-tunnel library's purpose is to make it easy to write either command-line tools or test modules that start some network tunnelling server (e.g. stunnel, microsocks, Dante) and verify that it does indeed forward connections and data as expected.

A tunnel test scenario

Test classes derived from the test-tunnel library's [TestTunnel][test_tunnel.run_test.TestTunnel] class have a [run()][test_tunnel.run_test.TestTunnel.run] method that performs the following actions:

• examines the IPv4 and IPv6 network interfaces currently configured on the running system and picks two available ports to listen on for each one
• makes a "possible connections" mapping, determining which of these addresses may be used as source and destination addresses for TCP connections. It is possible that some pairs are invalid either due to network protocol limitations or due to local system policy.
• picks a set of (server, proxy as client, proxy as server, client) address/port combinations from the above mapping so that the client may connect to the proxy and the proxy, in turn, may connect to the server

Writing a test class for a new tool

To write a new test class it is enough to create a new Python class derived from [test_tunnel.run_test.TestTunnel][] and implement at least the three methods defined as abstract in that base class:

• [slug()][test_tunnel.run_test.TestTunnel.slug]: return a short text string used in log messages to identify the tested program (e.g. "microsocks", "socat")
• [do_spawn_server()][test_tunnel.run_test.TestTunnel.do_spawn_server]: start the tested tool with the specified address and port to listen on and address and port to forward connections to. This method may possibly prepare a configuration file if the tool needs it, or it may start the tool and pass the addresses and ports directly on the command line if supported.
• [do_handshake()][test_tunnel.run_test.TestTunnel.do_handshake]: once a client socket has been connected to the already started tool (see the [do_spawn_server()][test_tunnel.run_test.TestTunnel.do_spawn_server] method), send and receive any "handshake" data required to make the tool establish a connection to the test listener started by the test-tunnel library itself. For a SOCKS5 server this should be the protocol negotiation and authentication, for an HTTP proxy server this would be the CONNECT request, etc.

Example tools

The test-tunnel library contains two example command-line tools that implement the test classes for two data forwarding programs: the [socat][test_tunnel.cmd_test.socat] multipurpose relay tool and the [microsocks][test_tunnel.cmd_test.microsocks] SOCKS5 server. They may serve as a starting point for writing new test classes.

Contact

The test-tunnel library was written by Peter Pentchev. It is developed in a GitLab repository. This documentation is hosted at Ringlet with a copy at ReadTheDocs.