Copy docs into Zeek repo directly

This is based on commit 2731def9159247e6da8a3191783c89683363689c from the
zeek-docs repo.

doc/devel/plugins/connkey-vxlan-fivetuple-plugin-src/CMakeLists.txt

@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 3.15 FATAL_ERROR)
+
+project(ZeekPluginConnKeyVxlanVniFivetuple)
+
+include(ZeekPlugin)
+
+zeek_add_plugin(
+    Zeek
+    ConnKey_Vxlan_Vni_Fivetuple
+    SOURCES
+    src/Factory.cc
+    src/Plugin.cc
+    SCRIPT_FILES scripts/__load__.zeek
+)

doc/devel/plugins/connkey-vxlan-fivetuple-plugin-src/COPYING

@@ -0,0 +1,26 @@
+Copyright (c) 2025 by the Zeek Project. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

doc/devel/plugins/connkey-vxlan-fivetuple-plugin-src/Makefile

@@ -0,0 +1,23 @@
+#
+# Convenience Makefile providing a few common top-level targets.
+#
+
+cmake_build_dir=build
+arch=`uname -s | tr A-Z a-z`-`uname -m`
+
+all: build-it
+
+build-it:
+	( cd $(cmake_build_dir) && make )
+
+install:
+	( cd $(cmake_build_dir) && make install )
+
+clean:
+	( cd $(cmake_build_dir) && make clean )
+
+distclean:
+	rm -rf $(cmake_build_dir)
+
+test:
+	make -C tests

doc/devel/plugins/connkey-vxlan-fivetuple-plugin-src/VERSION

@@ -0,0 +1 @@
+0.1.0

doc/devel/plugins/connkey-vxlan-fivetuple-plugin-src/configure

@@ -0,0 +1,193 @@
+#!/bin/sh
+#
+# Wrapper for viewing/setting options that the plugin's CMake
+# scripts will recognize.
+#
+# Don't edit this. Edit configure.plugin to add plugin-specific options.
+#
+
+set -e
+command="$0 $*"
+
+if [ -e $(dirname $0)/configure.plugin ]; then
+    # Include custom additions.
+    . $(dirname $0)/configure.plugin
+fi
+
+usage() {
+
+    cat 1>&2 <<EOF
+Usage: $0 [OPTIONS]
+
+  Plugin Options:
+    --cmake=PATH               Path to CMake binary
+    --zeek-dist=DIR            Path to Zeek source tree
+    --install-root=DIR         Path where to install plugin into
+    --with-binpac=DIR          Path to BinPAC installation root
+    --with-broker=DIR          Path to Broker installation root
+    --with-bifcl=PATH          Path to bifcl executable
+    --enable-debug             Compile in debugging mode
+    --disable-cpp-tests        Don't build C++ unit tests
+EOF
+
+    if type plugin_usage >/dev/null 2>&1; then
+        plugin_usage 1>&2
+    fi
+
+    echo
+
+    exit 1
+}
+
+# Function to append a CMake cache entry definition to the
+# CMakeCacheEntries variable
+#   $1 is the cache entry variable name
+#   $2 is the cache entry variable type
+#   $3 is the cache entry variable value
+append_cache_entry() {
+    CMakeCacheEntries="$CMakeCacheEntries -D $1:$2=$3"
+}
+
+# set defaults
+builddir=build
+zeekdist=""
+installroot="default"
+zeek_plugin_begin_opts=""
+CMakeCacheEntries=""
+
+while [ $# -ne 0 ]; do
+    case "$1" in
+        -*=*) optarg=$(echo "$1" | sed 's/[-_a-zA-Z0-9]*=//') ;;
+        *) optarg= ;;
+    esac
+
+    case "$1" in
+        --help | -h)
+            usage
+            ;;
+
+        --cmake=*)
+            CMakeCommand=$optarg
+            ;;
+
+        --zeek-dist=*)
+            zeekdist=$(cd $optarg && pwd)
+            ;;
+
+        --install-root=*)
+            installroot=$optarg
+            ;;
+
+        --with-binpac=*)
+            append_cache_entry BinPAC_ROOT_DIR PATH $optarg
+            binpac_root=$optarg
+            ;;
+
+        --with-broker=*)
+            append_cache_entry BROKER_ROOT_DIR PATH $optarg
+            broker_root=$optarg
+            ;;
+
+        --with-bifcl=*)
+            append_cache_entry BifCl_EXE PATH $optarg
+            ;;
+
+        --enable-debug)
+            append_cache_entry BRO_PLUGIN_ENABLE_DEBUG BOOL true
+            ;;
+
+        --disable-cpp-tests)
+            zeek_plugin_begin_opts="DISABLE_CPP_TESTS;$zeek_plugin_begin_opts"
+            ;;
+
+        *)
+            if type plugin_option >/dev/null 2>&1; then
+                plugin_option $1 && shift && continue
+            fi
+
+            echo "Invalid option '$1'.  Try $0 --help to see available options."
+            exit 1
+            ;;
+    esac
+    shift
+done
+
+if [ -z "$CMakeCommand" ]; then
+    # prefer cmake3 over "regular" cmake (cmake == cmake2 on RHEL)
+    if command -v cmake3 >/dev/null 2>&1; then
+        CMakeCommand="cmake3"
+    elif command -v cmake >/dev/null 2>&1; then
+        CMakeCommand="cmake"
+    else
+        echo "This plugin requires CMake, please install it first."
+        echo "Then you may use this script to configure the CMake build."
+        echo "Note: pass --cmake=PATH to use cmake in non-standard locations."
+        exit 1
+    fi
+fi
+
+if [ -z "$zeekdist" ]; then
+    if type zeek-config >/dev/null 2>&1; then
+        zeek_config="zeek-config"
+    else
+        echo "Either 'zeek-config' must be in PATH or '--zeek-dist=<path>' used"
+        exit 1
+    fi
+
+    append_cache_entry BRO_CONFIG_PREFIX PATH $(${zeek_config} --prefix)
+    append_cache_entry BRO_CONFIG_INCLUDE_DIR PATH $(${zeek_config} --include_dir)
+    append_cache_entry BRO_CONFIG_PLUGIN_DIR PATH $(${zeek_config} --plugin_dir)
+    append_cache_entry BRO_CONFIG_LIB_DIR PATH $(${zeek_config} --lib_dir)
+    append_cache_entry BRO_CONFIG_CMAKE_DIR PATH $(${zeek_config} --cmake_dir)
+    append_cache_entry CMAKE_MODULE_PATH PATH $(${zeek_config} --cmake_dir)
+
+    build_type=$(${zeek_config} --build_type)
+
+    if [ "$build_type" = "debug" ]; then
+        append_cache_entry BRO_PLUGIN_ENABLE_DEBUG BOOL true
+    fi
+
+    if [ -z "$binpac_root" ]; then
+        append_cache_entry BinPAC_ROOT_DIR PATH $(${zeek_config} --binpac_root)
+    fi
+
+    if [ -z "$broker_root" ]; then
+        append_cache_entry BROKER_ROOT_DIR PATH $(${zeek_config} --broker_root)
+    fi
+else
+    if [ ! -e "$zeekdist/zeek-path-dev.in" ]; then
+        echo "$zeekdist does not appear to be a valid Zeek source tree."
+        exit 1
+    fi
+
+    # BRO_DIST is the canonical/historical name used by plugin CMake scripts
+    # ZEEK_DIST doesn't serve a function at the moment, but set/provided anyway
+    append_cache_entry BRO_DIST PATH $zeekdist
+    append_cache_entry ZEEK_DIST PATH $zeekdist
+    append_cache_entry CMAKE_MODULE_PATH PATH $zeekdist/cmake
+fi
+
+if [ "$installroot" != "default" ]; then
+    mkdir -p $installroot
+    append_cache_entry BRO_PLUGIN_INSTALL_ROOT PATH $installroot
+fi
+
+if [ -n "$zeek_plugin_begin_opts" ]; then
+    append_cache_entry ZEEK_PLUGIN_BEGIN_OPTS STRING "$zeek_plugin_begin_opts"
+fi
+
+if type plugin_addl >/dev/null 2>&1; then
+    plugin_addl
+fi
+
+echo "Build Directory        : $builddir"
+echo "Zeek Source Directory   : $zeekdist"
+
+mkdir -p $builddir
+cd $builddir
+
+"$CMakeCommand" $CMakeCacheEntries ..
+
+echo "# This is the command used to configure this build" >config.status
+echo $command >>config.status
+chmod u+x config.status

doc/devel/plugins/connkey-vxlan-fivetuple-plugin-src/scripts/__load__.zeek

@@ -0,0 +1,3 @@
+redef record conn_id_ctx += {
+	vxlan_vni: count &log &optional;
+};

doc/devel/plugins/connkey-vxlan-fivetuple-plugin-src/scripts/__preload__.zeek

@@ -0,0 +1 @@
+# Empty

doc/devel/plugins/connkey-vxlan-fivetuple-plugin-src/src/Factory.cc

@@ -0,0 +1,105 @@
+// See the file "COPYING" in the main distribution directory for copyright.
+
+#include "Factory.h"
+
+#include <memory>
+
+#include "zeek/ID.h"
+#include "zeek/Val.h"
+#include "zeek/iosource/Packet.h"
+#include "zeek/packet_analysis/Analyzer.h"
+#include "zeek/packet_analysis/Manager.h"
+#include "zeek/packet_analysis/protocol/ip/conn_key/IPBasedConnKey.h"
+#include "zeek/packet_analysis/protocol/ip/conn_key/fivetuple/Factory.h"
+#include "zeek/util-types.h"
+
+namespace zeek::conn_key::vxlan_vni_fivetuple {
+
+class VxlanVniConnKey : public zeek::IPBasedConnKey {
+public:
+    VxlanVniConnKey() {
+        // Ensure padding holes in the key struct are filled with zeroes.
+        memset(static_cast<void*>(&key), 0, sizeof(key));
+    }
+
+    detail::PackedConnTuple& PackedTuple() override { return key.tuple; }
+
+    const detail::PackedConnTuple& PackedTuple() const override { return key.tuple; }
+
+protected:
+    zeek::session::detail::Key DoSessionKey() const override {
+        return {reinterpret_cast<const void*>(&key), sizeof(key), session::detail::Key::CONNECTION_KEY_TYPE};
+    }
+
+    void DoPopulateConnIdVal(zeek::RecordVal& conn_id, zeek::RecordVal& ctx) override {
+        // Base class populates conn_id fields (orig_h, orig_p, resp_h, resp_p)
+        zeek::IPBasedConnKey::DoPopulateConnIdVal(conn_id, ctx);
+
+        if ( conn_id.GetType() != id::conn_id )
+            return;
+
+        if ( (key.vxlan_vni & 0xFF000000) == 0 ) // High-bits unset: Have VNI
+            ctx.Assign(GetVxlanVniOffset(), static_cast<zeek_uint_t>(key.vxlan_vni));
+        else
+            ctx.Remove(GetVxlanVniOffset());
+    }
+
+    // Extract VNI from most outer VXLAN layer.
+    void DoInit(const Packet& pkt) override {
+        static const auto& analyzer = zeek::packet_mgr->GetAnalyzer("VXLAN");
+
+        // Set the high-bits: This is needed because keys can get reused.
+        key.vxlan_vni = 0xFF000000;
+
+        if ( ! analyzer || ! analyzer->IsEnabled() )
+            return;
+
+        auto spans = zeek::packet_mgr->GetAnalyzerData(analyzer);
+
+        if ( spans.empty() || spans[0].size() < 8 )
+            return;
+
+        key.vxlan_vni = spans[0][4] << 16 | spans[0][5] << 8 | spans[0][6];
+    }
+
+    static int GetVxlanVniOffset() {
+        static const auto& conn_id_ctx = zeek::id::find_type<zeek::RecordType>("conn_id_ctx");
+        static int vxlan_vni_offset = conn_id_ctx->FieldOffset("vxlan_vni");
+        return vxlan_vni_offset;
+    }
+
+private:
+    friend class Factory;
+
+    struct {
+        struct detail::PackedConnTuple tuple;
+        uint32_t vxlan_vni;
+    } __attribute__((packed, aligned)) key; // packed and aligned due to usage for hashing
+};
+
+zeek::ConnKeyPtr Factory::DoNewConnKey() const { return std::make_unique<VxlanVniConnKey>(); }
+
+zeek::expected<zeek::ConnKeyPtr, std::string> Factory::DoConnKeyFromVal(const zeek::Val& v) const {
+    if ( v.GetType() != id::conn_id )
+        return zeek::unexpected<std::string>{"unexpected value type"};
+
+    auto ck = zeek::conn_key::fivetuple::Factory::DoConnKeyFromVal(v);
+    if ( ! ck.has_value() )
+        return ck;
+
+    int vxlan_vni_offset = VxlanVniConnKey::GetVxlanVniOffset();
+    static int ctx_offset = id::conn_id->FieldOffset("ctx");
+
+    auto* k = static_cast<VxlanVniConnKey*>(ck.value().get());
+    auto* ctx = v.AsRecordVal()->GetFieldAs<zeek::RecordVal>(ctx_offset);
+
+    if ( vxlan_vni_offset < 0 )
+        return zeek::unexpected<std::string>{"missing vlxan_vni field"};
+
+    if ( ctx->HasField(vxlan_vni_offset) )
+        k->key.vxlan_vni = ctx->GetFieldAs<zeek::CountVal>(vxlan_vni_offset);
+
+    return ck;
+}
+
+} // namespace zeek::conn_key::vxlan_vni_fivetuple

doc/devel/plugins/connkey-vxlan-fivetuple-plugin-src/src/Factory.h

@@ -0,0 +1,18 @@
+#pragma once
+
+#include "zeek/ConnKey.h"
+#include "zeek/packet_analysis/protocol/ip/conn_key/fivetuple/Factory.h"
+
+namespace zeek::conn_key::vxlan_vni_fivetuple {
+
+class Factory : public zeek::conn_key::fivetuple::Factory {
+public:
+    static zeek::conn_key::FactoryPtr Instantiate() { return std::make_unique<Factory>(); }
+
+private:
+    // Returns a VxlanVniConnKey instance.
+    zeek::ConnKeyPtr DoNewConnKey() const override;
+    zeek::expected<zeek::ConnKeyPtr, std::string> DoConnKeyFromVal(const zeek::Val& v) const override;
+};
+
+} // namespace zeek::conn_key::vxlan_vni_fivetuple

doc/devel/plugins/connkey-vxlan-fivetuple-plugin-src/src/Plugin.cc

@@ -0,0 +1,26 @@
+
+#include "Plugin.h"
+
+#include <zeek/conn_key/Component.h>
+
+#include "Factory.h"
+
+namespace plugin {
+namespace Zeek_ConnKey_Vxlan_Vni_Fivetuple {
+Plugin plugin;
+}
+} // namespace plugin
+
+using namespace plugin::Zeek_ConnKey_Vxlan_Vni_Fivetuple;
+
+zeek::plugin::Configuration Plugin::Configure() {
+    zeek::plugin::Configuration config;
+    config.name = "Zeek::ConnKey_Vxlan_Vni_Fivetuple";
+    config.description = "ConnKey implementation using the most outer VXLAN VNI";
+    config.version = {0, 1, 0};
+
+    AddComponent(new zeek::conn_key::Component("VXLAN_VNI_FIVETUPLE",
+                                               zeek::conn_key::vxlan_vni_fivetuple::Factory::Instantiate));
+
+    return config;
+}

doc/devel/plugins/connkey-vxlan-fivetuple-plugin-src/src/Plugin.h

@@ -0,0 +1,17 @@
+
+#pragma once
+
+#include <zeek/plugin/Plugin.h>
+
+namespace plugin {
+namespace Zeek_ConnKey_Vxlan_Vni_Fivetuple {
+
+class Plugin : public zeek::plugin::Plugin {
+protected:
+    zeek::plugin::Configuration Configure() override;
+};
+
+extern Plugin plugin;
+
+} // namespace Zeek_ConnKey_Vxlan_Vni_Fivetuple
+} // namespace plugin