For users that are already familiar with CMake, the project should be easy to build once the required dependencies have been installed and the repository has been cloned with all the submodules. No special steps are required for the configure and build steps.

Project options have been grouped under the ZEEK_AGENT prefix and will show up in configuration tools such as ccmake and cmake-gui. You can open the graphical configuration rompt automatically by running cmake --build . --target edit_cache from the build folder.

It is also possible to run the following scripts to configure, build, test and generate the binary packages directly: scripts/build_linux_release.sh, scripts/build_macos_release.sh. (Note that this will install package dependencies automatically, and hence requires root permissions).

Only the following following build types are supported:

When building on Linux, the preferred method is with the osquery-toolchain.

The Zeek Agent makes use of the EndpointSecurity API to capture system events such as process execution. In order to access this information the program needs to be codesigned and contain the necessary entitlements.

When building on macOS, the -DZEEK_AGENT_CODESIGN_IDENTITY:STRING=<IDENTITY> should always be added to the CMake parameters. If you are not familiar with how code signing works on macOS, refer to the Signing macOS builds page.

In case code signing can't be performed, Zeek Agent will work without the EndpointSecurity API.

Clone the repository along with all the necessary submodules: git clone https://github.com/zeek/zeek-agent --recursive

If the repository has already been cloned without --recursive (or if the repository is being updated with new commits), then the submodules can be updated again with the following commands:

git submodule sync --recursive
git submodule update --init --recursive

osquery-toolchain Acquire the toolchain from the osquery-toolchain release page and extract it to, e.g., /opt/osquery-toolchain.

System compiler Make sure that both the system compiler and C++ library support C++17 (a recent OS such as Catalina or Ubuntu 19.10 are recommended).

Linux dependencies: libssl-dev

Standalone No additional steps required.

osquery-enabled

1. Clone the osquery repository: git clone https://github.com/osquery/osquery
2. Link the Zeek Agent folder inside the osquery source tree:ln -s /path/to/zeek-agent/source/folder /path/to/osquery/source/folder/external/extension_zeek-agent

Make sure to reference the official osquery build guide, as it contains the steps required to install additional dependencies and enable symbolic links on Windows.

The version compatibility setting should match the version of the Zeek instance that has been deployed. Add one of the following two settings to your CMake command line in the following section:

• Zeek >= 3.1: -DZEEK_AGENT_ZEEK_COMPATIBILITY:STRING="3.1"
• Zeek <= 3.0: -DZEEK_AGENT_ZEEK_COMPATIBILITY:STRING="3.0"

Create the build folder

mkdir build && cd build

Configure the project

• Use the osquery source folder for osquery-enabled builds
• Use the Zeek Agent source folder for standalone builds

Option #1: Configure with the system compiler:

As depicted in the build type matrix, this method can only build the standalone version for Linux and both the standalone and the osquery-enabled version for macOS.

cmake -DCMAKE_BUILD_TYPE:STRING=RelWithDebInfo -DZEEK_AGENT_ENABLE_INSTALL:BOOL=ON -DZEEK_AGENT_ENABLE_TESTS:BOOL=ON -DZEEK_AGENT_ZEEK_COMPATIBILITY:STRING="xxx" /path/to/source

Option #2: Configure with the osquery-toolchain, standalone build:

cmake -DCMAKE_BUILD_TYPE:STRING=RelWithDebInfo -DZEEK_AGENT_ENABLE_INSTALL:BOOL=ON -DZEEK_AGENT_ENABLE_TESTS:BOOL=ON -DZEEK_AGENT_ZEEK_COMPATIBILITY:STRING="xxx" -DZEEK_AGENT_TOOLCHAIN_PATH:PATH=/opt/osquery-toolchain /path/to/source

Option #3: Configure with the osquery-toolchain, osquery-enabled build:

cmake -DCMAKE_BUILD_TYPE:STRING=RelWithDebInfo -DZEEK_AGENT_ENABLE_INSTALL:BOOL=ON -DZEEK_AGENT_ENABLE_TESTS:BOOL=ON -DZEEK_AGENT_ZEEK_COMPATIBILITY:STRING="xxx" -DOSQUERY_TOOLCHAIN_SYSROOT:PATH=/opt/osquery-toolchain /path/to/source

Build the project

• macOS: cmake --build . -j $(($(sysctl -n hw.physicalcpu)+1))
• Linux: cmake --build . -j $(($(nproc)+1))

Output binaries are stored here:

• osquery-enabled build: build/external/extension_zeek-agent/zeek-agent.
• standalone build: build/zeek-agent

Run the tests

cmake --build . --target zeek_agent_tests

Install Zeek Agent:

cd build_folder

mkdir install
export DESTDIR="$(realpath install)"

cmake --build . --target install

Configure the packaging project

mkdir package_build && cd package_build

cmake -DZEEK_AGENT_INSTALL_PATH:PATH="${DESTDIR}" /path/to/zeek-agent/source/packaging

Generate the packages

cmake --build . --target package