scapy.fwdmachine

Forwarding machine.

class scapy.fwdmachine.ForwardMachine(mode: MODE, port: int, cls: Type[Packet], af: AddressFamily = AddressFamily.AF_INET, proto: SocketKind = SocketKind.SOCK_STREAM, remote_address: str = None, remote_af: AddressFamily | None = None, bind_address: str = None, tls: bool = False, crtfile: str | None = None, keyfile: str | None = None, timeout: int = 2, MTU: int = 65535, **kwargs)

Bases: object

Forward Machine

This binds a port and relay any connections from ‘clients’ to their original destination a ‘server’. Forwarding machine can be used in two modes:

• SERVER: the server binds a port on its local IP and forwards packets to a

  remote_address.

• TPROXY: the server binds can intercept packets to any IP destination, provided

  that they are routed through the local server, and some tweaking of the OS routes;

The TPROXY mode is expected to be used on a router with FORWARDING and only a specific set of nat rules set to -j TPROXY. A script called ‘vethrelay.sh’ is provided in the documentation for setting this up.

ForwardMachine supports transparently proxifying TLS. By default, it will generate lookalike self-signed certificates, but it’s also possible to specify a certificate by using crtfile and keyfile.

Parameters:

Parameters:

• port – the port to listen on

• cls – the scapy class to parse on that port

• af – the address family to use (default AF_INET)

• proto – the proto to use (default SOCK_STREAM)

• remote_address – the IP to use in SERVER mode, or by default in TPROXY when the destination is the local IP.

• remote_af – (optional) if provided, use a different address family to connect to the remote host.

• bind_address – the IP to bind locally. “0.0.0.0” by default in SERVER mode, but “2.2.2.2” by default in TPROXY (if you are using the provided ‘vethrelay.sh’ script).

• tls – enable TLS (in both the server and client)

• crtfile – (optional) if provided, uses a certificate instead of self signed ones.

• keyfile – (optional) path to the key file

• timeout – the timeout before connecting to the real server (default 2)

Methods to override:

Func xfrmcs:

a function to call when forwarding a packet from the ‘client’ to the server. If it raises a FORWARD exception, the packet is forwarded as it. If it raises a DROP Exception, the packet is discarded. If it raises a FORWARD_REPLACE(pkt) exception, then pkt is forwarded instead of the original packet.

Func xfrmsc:

same as xfrmcs for packets forwarded from the ‘server’ to the ‘client’.

exception ANSWER(data)

Bases: Exception

class CONTEXT(addr, dest)

Bases: object

CONTEXT object kept during a session

exception DROP

Bases: Exception

exception FORWARD

Bases: Exception

exception FORWARD_REPLACE(data)

Bases: Exception

class MODE(*values)

Bases: Enum

SERVER = 0

TPROXY = 1

exception REDIRECT_TO(host, port, then=None, server_hostname=None)

Bases: Exception

destalias(dest)

Alias a destination to another destination. A destination is the tuple (host, port)

gen_alike_chain(certs, privkey)

Modify a real certificate chain to be served by our own privatekey

get_key_and_alike_chain(cas, dest, server_name)

Generate a PrivateKey and a clone of the ‘cas’ certificate chain signed with it, if not already cached.

The cache uses server_name or dest as key.

handler(sock, addr, dest)

Handler of a client socket

print_reply(evt, cs, req, rep)

run()

Function to start the relay server

xfrmcs(pkt, ctx)

DEV: overwrite me to handle client->server

xfrmsc(pkt, ctx)

DEV: overwrite me to handle server->client