Writing a Connection Key Plugin
Added in version 8.0.
By default, Zeek looks up internal connection state using the classic five-tuple
of originator and responder IP addresses, ports, and the numeric protocol
identifier (for TCP, UDP, etc). Zeek’s data structure driving this is called a
connection key, or ConnKey.
In certain environments the classic five-tuple does not sufficiently distinguish connections. Consider traffic mirrored from multiple VLANs with overlapping IP address ranges. Concretely, a connection between 10.0.0.1 and 10.0.0.2 in one VLAN is distinct from a connection between the same IPs in another VLAN. Here, Zeek should include the VLAN identifier into the connection key, and you can instruct Zeek to do so by loading the policy/frameworks/conn_key/vlan_fivetuple.zeek policy script.
Zeek’s plugin API allows adding support for additional custom connection keys. This section provides a tutorial on how to do so, using the example of VXLAN-enabled flow tuples. If you’re not familiar with plugin development, head over to the Writing Plugins section.
Our goal is to implement a custom connection key to scope connections transported within a VXLAN tunnel by the VXLAN Network Identifier (VNI).
As a test case, we have encapsulated the HTTP GET trace
from the Zeek repository twice with VXLAN using VNIs 4711 and 4242, respectively,
and merged the resulting two PCAP files with the original PCAP.
The resulting PCAP
contains three HTTP connections, two of which are VXLAN-encapsulated.
By default, Zeek will create the same connection key for the original and
encapsulated HTTP connections, since they have identical inner five-tuples.
Therefore, Zeek creates only a single http.log entry, and two entries
in conn.log.
$ zeek -C -r Traces/vxlan-overlapping-http-get.pcap
$ zeek-cut -m uid method host uri < http.log
uid method host uri
CpWF5etn1l2rpaLu3 GET bro.org /download/CHANGES.bro-aux.txt
$ zeek-cut -m uid service history orig_pkts resp_pkts < conn.log
uid service history orig_pkts resp_pkts
Cq2CY245oGGbibJ8k9 http ShADTadtFf 21 21
CMleDu4xANIMzePYd7 vxlan D 28 0
Note that just two of the HTTP connections are encapsulated.
That is why the VXLAN connection shows only 28 packets.
Each HTTP connection has 14 packets total, 7 in each direction. Zeek aggregates
all packets into the single HTTP connection, but only 28 of them were
transported within the VXLAN tunnel connection. Note also the t and T
flags in the history field. These stand for retransmissions,
caused by Zeek not discriminating between the different HTTP connections.
The plugin we’ll develop below adds the VXLAN VNI to the connection key.
As a result, Zeek will correctly report three HTTP connections, tracked
and logged separately. We’ll add the VNI as
vxlan_vni to the conn_id_ctx record, making it available
in http.log and conn.log via the id.ctx.vxlan_vni column.
After activating the plugin Zeek tracks each HTTP connection individually and the logs will look as follows:
$ zeek-cut -m uid method host uri id.ctx.vxlan_vni < http.log
uid method host uri id.ctx.vxlan_vni
CBifsS2vqGEg8Fa5ac GET bro.org /download/CHANGES.bro-aux.txt 4711
CEllEz13txeSrbGqBe GET bro.org /download/CHANGES.bro-aux.txt 4242
CRfbJw1kBBvHDQQBta GET bro.org /download/CHANGES.bro-aux.txt -
$ zeek-cut -m uid service history orig_pkts resp_pkts id.ctx.vxlan_vni < conn.log
uid service history orig_pkts resp_pkts id.ctx.vxlan_vni
CRfbJw1kBBvHDQQBta http ShADadFf 7 7 -
CEllEz13txeSrbGqBe http ShADadFf 7 7 4242
CBifsS2vqGEg8Fa5ac http ShADadFf 7 7 4711
CC6Ald2LejCS1qcDy4 vxlan D 28 0 -
Implementation
Adding alternative connection keys involves implementing two classes.
First, a factory class producing zeek::ConnKey instances. This
is the class created through the added zeek::conn_key::Component.
Second, a custom connection key class derived from zeek::ConnKey.
Instances of this class are created by the factory. This is a typical
abstract factory pattern.
Our plugin’s Configure() method follows the standard pattern of setting up
basic information about the plugin and registering our own ConnKey component.
1zeek::plugin::Configuration Plugin::Configure() {
2 zeek::plugin::Configuration config;
3 config.name = "Zeek::ConnKey_Vxlan_Vni_Fivetuple";
4 config.description = "ConnKey implementation using the most outer VXLAN VNI";
5 config.version = {0, 1, 0};
6
7 AddComponent(new zeek::conn_key::Component("VXLAN_VNI_FIVETUPLE",
8 zeek::conn_key::vxlan_vni_fivetuple::Factory::Instantiate));
9
10 return config;
11}
Next, in the Factory.cc file, we’re implementing a custom zeek::ConnKey class.
This class is named VxlanVniConnKey and inherits from zeek::IPBasedConnKey.
While zeek::ConnKey is technically the base class, in this tutorial we’ll
derive from zeek::IPBasedConnKey.
Currently, Zeek only supports IP-based connection tracking via the
IPBasedAnalyzer analyzer. This analyzer requires zeek::IPBasedConnKey
instances.
1class VxlanVniConnKey : public zeek::IPBasedConnKey {
2public:
3 VxlanVniConnKey() {
4 // Ensure padding holes in the key struct are filled with zeroes.
5 memset(static_cast<void*>(&key), 0, sizeof(key));
6 }
7
8 detail::PackedConnTuple& PackedTuple() override { return key.tuple; }
9
10 const detail::PackedConnTuple& PackedTuple() const override { return key.tuple; }
11
12protected:
13 zeek::session::detail::Key DoSessionKey() const override {
14 return {reinterpret_cast<const void*>(&key), sizeof(key), session::detail::Key::CONNECTION_KEY_TYPE};
15 }
16
17 void DoPopulateConnIdVal(zeek::RecordVal& conn_id, zeek::RecordVal& ctx) override {
18 // Base class populates conn_id fields (orig_h, orig_p, resp_h, resp_p)
19 zeek::IPBasedConnKey::DoPopulateConnIdVal(conn_id, ctx);
20
21 if ( conn_id.GetType() != id::conn_id )
22 return;
23
24 if ( (key.vxlan_vni & 0xFF000000) == 0 ) // High-bits unset: Have VNI
25 ctx.Assign(GetVxlanVniOffset(), static_cast<zeek_uint_t>(key.vxlan_vni));
26 else
27 ctx.Remove(GetVxlanVniOffset());
28 }
29
30 // Extract VNI from most outer VXLAN layer.
31 void DoInit(const Packet& pkt) override {
32 static const auto& analyzer = zeek::packet_mgr->GetAnalyzer("VXLAN");
33
34 // Set the high-bits: This is needed because keys can get reused.
35 key.vxlan_vni = 0xFF000000;
36
37 if ( ! analyzer || ! analyzer->IsEnabled() )
38 return;
39
40 auto spans = zeek::packet_mgr->GetAnalyzerData(analyzer);
41
42 if ( spans.empty() || spans[0].size() < 8 )
43 return;
44
45 key.vxlan_vni = spans[0][4] << 16 | spans[0][5] << 8 | spans[0][6];
46 }
47
48 static int GetVxlanVniOffset() {
49 static const auto& conn_id_ctx = zeek::id::find_type<zeek::RecordType>("conn_id_ctx");
50 static int vxlan_vni_offset = conn_id_ctx->FieldOffset("vxlan_vni");
51 return vxlan_vni_offset;
52 }
53
54private:
55 friend class Factory;
56
57 struct {
58 struct detail::PackedConnTuple tuple;
59 uint32_t vxlan_vni;
60 } __attribute__((packed, aligned)) key; // packed and aligned due to usage for hashing
61};
The current pattern for custom connection keys is to embed the bytes used for
the zeek::session::detail::Key as a packed struct within a ConnKey instance.
We override DoPopulateConnIdVal() to set the vxlan_vni field
of the conn_id_ctx record value to the extracted VXLAN VNI. A small trick
employed is that we default the most significant byte of key.vxlan_vni to 0xFF.
As a VNI has only 24 bits, this allows us to determine if a VNI was actually
extracted, or whether it remained unset.
The DoInit() implementation is the actual place for connection key customization.
This is where we extract the VXLAN VNI from packet data. To do so, we’re using the relatively
new GetAnalyzerData() API of the packet analysis manager.
This API allows generic access to the raw data layers analyzed by a give packet analyzer.
For our use-case, we take the most outer VXLAN layer, if any, and extract the VNI
into key.vxlan_vni.
There’s no requirement to use the GetAnalyzerData() API. If the zeek::Packet
instance passed to DoInit() contains the needed information, e.g. VLAN identifiers
or information from the packet’s raw bytes, you can use them directly.
Specifically, GetAnalyzerData() may introduce additional overhead into the
packet path that you can avoid if the information is readily available
elsewhere.
Using other Zeek APIs to determine connection key information is of course
also possible.
The next part shown concerns the Factory class itself. The
DoConnKeyFromVal() method contains logic to produce a VxlanVniConnKey
instance from an existing conn_id record.
This is needed in order for the lookup_connection builtin function to work properly.
The implementation re-uses the DoConnKeyFromVal() implementation of the
default fivetuple::Factory that our factory inherits from to extract the
classic five-tuple information.
1zeek::ConnKeyPtr Factory::DoNewConnKey() const { return std::make_unique<VxlanVniConnKey>(); }
2
3zeek::expected<zeek::ConnKeyPtr, std::string> Factory::DoConnKeyFromVal(const zeek::Val& v) const {
4 if ( v.GetType() != id::conn_id )
5 return zeek::unexpected<std::string>{"unexpected value type"};
6
7 auto ck = zeek::conn_key::fivetuple::Factory::DoConnKeyFromVal(v);
8 if ( ! ck.has_value() )
9 return ck;
10
11 int vxlan_vni_offset = VxlanVniConnKey::GetVxlanVniOffset();
12 static int ctx_offset = id::conn_id->FieldOffset("ctx");
13
14 auto* k = static_cast<VxlanVniConnKey*>(ck.value().get());
15 auto* ctx = v.AsRecordVal()->GetFieldAs<zeek::RecordVal>(ctx_offset);
16
17 if ( vxlan_vni_offset < 0 )
18 return zeek::unexpected<std::string>{"missing vlxan_vni field"};
19
20 if ( ctx->HasField(vxlan_vni_offset) )
21 k->key.vxlan_vni = ctx->GetFieldAs<zeek::CountVal>(vxlan_vni_offset);
22
23 return ck;
24}
Calling the fivetuple::Factory::DoConnKeyFromVal() in turn calls our
own factory’s DoNewConnKey() method through virtual dispatch. Since our
factory overrides this method to always return a VxlanVniConnKey instance,
the static cast later is safe.
Last, the plugin’s __load__.zeek file is shown. It includes the extension
of the conn_id_ctx identifier by the vxlan_vni field.
1redef record conn_id_ctx += {
2 vxlan_vni: count &log &optional;
3};
Using the custom Connection Key
After installing the plugin, the new connection key implementation can be
selected by redefining the script-level ConnKey::factory variable.
This can either be done in a separate script, but we do it directly on the
command-line for simplicity. The ConnKey::CONNKEY_VXLAN_VNI_FIVETUPLE is
registered in Zeek during the plugin’s AddComponent() call during
Configure(), where the component has the name VXLAN_VNI_FIVETUPLE.
$ zeek -C -r Traces/vxlan-overlapping-http-get.pcap ConnKey::factory=ConnKey::CONNKEY_VXLAN_VNI_FIVETUPLE
Viewing the conn.log now shows three separate HTTP connections,
two of which have a vxlan_vni value set in their logs.
$ zeek-cut -m uid service history orig_pkts resp_pkts id.ctx.vxlan_vni < conn.log
uid service history orig_pkts resp_pkts id.ctx.vxlan_vni
CRfbJw1kBBvHDQQBta http ShADadFf 7 7 -
CEllEz13txeSrbGqBe http ShADadFf 7 7 4242
CBifsS2vqGEg8Fa5ac http ShADadFf 7 7 4711
CC6Ald2LejCS1qcDy4 vxlan D 28 0 -