Zeek XDP Filtering

Uses XDP in order to "shunt" traffic - that way, Zeek doesn't waste its time analyzing packets that won't get any useful information.

You can use the provided configuration that is similar in functionality to bro-react:

@load xdp/shunt/bulk

This provides a few configuration knobs, but it should shunt connections that are deemed "too large" and unshunt it when a certain time elapses without the connection terminating.

The XDP program will still forward certain TCP packets, namely FIN, RST, SYN, and ACK packets. This way, Zeek can tell when a connection is complete and properly terminate it.

Manual Shunting

You may also choose to manually shunt connections based on your own criteria. You can use the provided BIFs for that. For example, this shunts encrypted sessions, then unshunts when it sees a FIN/RST TCP packet:

@load xdp
@load xdp/shunt/conn_id

global xdp_prog: opaque of XDP::Program;

event zeek_init()
	{
	local opts: XDP::ShuntOptions = [
		$attach_mode=XDP::SKB, # SKB is more for testing, NATIVE is better
		$conn_id_map_max_size=131072, # A bit over the max number of shunted connections
		$ip_pair_map_max_size=1, # We can't remove the map, so make it very small
	];
	xdp_prog = XDP::start_shunt(opts);
	}

event connection_state_remove(c: connection)
	{
	XDP::Shunt::ConnID::unshunt(xdp_prog, c$id);
	}

event XDP::Shunt::ConnID::unshunted_conn(cid: conn_id, stats: XDP::ShuntedStats)
	{
	assert stats$present;
	print fmt("Unshunted connection from %s:%d<->%s:%d. Transmitted %d bytes and %d packets. Last packet was at %s.",
	    cid$orig_h, cid$orig_p, cid$resp_h, cid$resp_p, stats$bytes_from_1 +
	    stats$bytes_from_2, stats$packets_from_1 + stats$packets_from_2,
	    stats$timestamp);
	}

event XDP::Shunt::ConnID::shunted_conn(cid: conn_id)
	{
	print fmt("Shunted connection from %s:%d<->%s:%d", cid$orig_h, cid$orig_p,
	    cid$resp_h, cid$resp_p);
	}

event ssl_established(c: connection)
	{
	XDP::Shunt::ConnID::shunt(xdp_prog, c$id);
	}

event zeek_done()
	{
	XDP::end_shunt(xdp_prog);
	}

IP Pairs

Shunting with IP pairs is similar:

@load xdp
@load xdp/shunt/ip_pair

global xdp_prog: opaque of XDP::Program;

event zeek_init()
	{
	local opts: XDP::ShuntOptions = [
		$attach_mode=XDP::SKB, # SKB is more for testing, NATIVE is better
		$conn_id_map_max_size=1, # We can't remove the map, so make it very small
		$ip_pair_map_max_size=131072, # A bit over the max number of shunted connections
	];
	xdp_prog = XDP::start_shunt(opts);
	}

event connection_state_remove(c: connection)
	{
	XDP::Shunt::IPPair::unshunt(xdp_prog, c$id$orig_h, c$id$resp_h);
	}

event XDP::Shunt::IPPair::unshunted_pair(ip1: addr, ip2: addr,
    stats: XDP::ShuntedStats)
	{
	assert stats$present;
	print fmt("Unshunted connection from %s<->%s. Transmitted %d bytes and %d packets. Last packet was at %s.",
	    ip1, ip2, stats$bytes_from_1 + stats$bytes_from_2,
	    stats$packets_from_1 + stats$packets_from_2, stats$timestamp);
	}

event XDP::Shunt::IPPair::shunted_pair(ip1: addr, ip2: addr)
	{
	print fmt("Shunted connection from %s<->%s", ip1, ip2);
	}

event ssl_established(c: connection)
	{
	XDP::Shunt::IPPair::shunt(xdp_prog, c$id$orig_h, c$id$resp_h);
	}

event zeek_done()
	{
	XDP::end_shunt(xdp_prog);
	}

Internals

This plugin uses XDP (eXpress Data Path) in order to filter traffic before it reaches user applications, like Zeek. This is filtering purely on the network device that Zeek sees traffic from.

The XDP program itself simply checks if a certain IP pair or 5-tuple are in the "shunting map." This map is managed entirely from user space, that is, the Zeek program.

Any shunted connections keep state about certain statistics, such as the last packet seen and how many bytes/packets were seen from each direction. This may help the user determine how effective the shunting was, or simply unshunt connections after a certain time elapsed without any traffic.

Shunting may raise some Zeek events, namely for FIN and RST TCP packets. This is done via BPF ring buffers.

TODOs

• Add (better) way to filter the returned maps before converting to Zeek vals
• Potentially split the IP pair and conn id shunting in different XDP programs
• Test it