The Zeek Agent is an endpoint monitoring tool for Linux and macOS that reports, by default, file, socket, and process events to Zeek. On Linux, event data is captured from the Linux Audit using the Unix domain socket plugin that comes with Audisp. On macOS, Zeek Agent leverages Endpoint Security framework to capture file and process events while to collect socket events Zeek Agent uses OpenBSM. Collected event data from endpoint is stored in an SQL database (using SQLite virtual tables internally) on the host. Events from this database are later fetched by Zeek using scheduled queries.
On the Zeek side, the Zeek Agent Framework provides the API to access Zeek Agents, as well as some default scripts recording endpoint activity into Zeek logs.
This Documentation Provides a detailed overview of how to setup Zeek Agent on both Linux and MacOS.
Follow all the numbered steps in the exact same order as numbered to successfully install Zeek Agent on Linux.
There are certain dependencies that must be present within a system before installing Zeek Agent on it. They can be installed via the following command:
sudo apt-get install cppcheck ccache curl flex bison rpm doxygen ninja-build graphviz libssl-dev libunwind-dev -y
Alongside installing these dependencies, it must be ensured that the system on which Zeek Agent is being installed, has CMake installed on it. It is also recommended to install the clang compiler and use that for building this project. If cmake is not installed, use the following command to install it:
sudo apt-get install cmake
If clang is not installed, install it via the following command:
sudo apt-get install clang
Regardless of whether clang existed previously within the system or it was recently installed via the above command, it needs to be made the default compiler of c/c++ for Zeek Agent to be properly installed. This can be done via the following commands:
sudo update-alternatives --set cc /usr/bin/clang
sudo update-alternatives --set c++ /usr/bin/clang++
The Linux Audit System is used for collecting system wide logs, which are then extracted by Zeek Agent to be stored in its internal Virtual Tables. Hence, the audit system must be enabled and running. First, check if auditd, the userspace component to the linux audit system is installed on the system or not. This can be done by checking the version of auditctl, the utility used for controlling the linux audit system, by using the following command:
sudo auditctl -v
If the command is not found, auditd needs to be installed first, which can be done using the following command:
sudo apt install auditd
Now that auditd has been installed, enable it by using the following command:
sudo systemctl enable --now auditd
Now define a rules file that contains rules about the type of system calls that auditd should capture. This will wary across use cases. As a starting point, enable the following system calls:
execve, execveat, fork, vfork, clone, connect, bind, open, openat, write
This can be done by creating a .rules file within the /etc/audit/rules.d folder and then adding the following lines to that file:
-a exit,always -F arch=b64 -S execve
-a exit,always -F arch=b64 -S execveat
-a exit,always -F arch=b64 -S fork
-a exit,always -F arch=b64 -S vfork
-a exit,always -F arch=b64 -S clone
-a exit,always -F arch=b64 -S connect
-a exit,always -F arch=b64 -S bind
-a exit,always -F arch=b64 -S open
-a exit,always -F arch=b64 -S openat
-a exit,always -F arch=b64 -S write
Next, set the AF UNIX plugin to active in /etc/audisp/plugins.d/af_unix.conf file.
Once, the AF UNIX plugin has been set to active and the rules file has been configured, restart auditd by running the following command:
service auditd restart
To ensure that all the rules have been successfully written, type the following command and verify if it lists all the rules exactly as they had been written in the .rules file created previously:
auditctl -l
In order to configure Zeek Agent, create a file called config.json at /etc/zeek-agent directory. Before creating the file, make sure that the directory /etc/zeek-agent already exists. If it does not exist, create the directory first before creating the configuration file. Make sure not to add any comments inside the file to avoid any errors. The following fields are compulsory in the configuration file for Zeek Agent to properly execute:
| Key | Explanation |
|---|---|
| server_address | This is the address of the server running the Zeek Agent scripts where all the logs collected from the end host will be sent to. These Zeek Agent scripts query the end host for event logs and upon receiving these logs, the scripts store them on the server. |
| server_port | Port number at which the Zeek server is listening to responses sent by the end hosts. |
| log_folder | This is the directory where all the logs of the end point system, generated by Zeek Agent, will be stored locally. Make sure this directory already exists before entering its name as the value to the log_folder key within the configuration file. If it does not, create the directory first. |
| max_queued_row_count | Maximum number of rows each of the three event tables within the virtual database can hold before they start dropping rows based on the first come first drop model. |
| group_list | List of Zeek groups the end host joins when Zeek Agent is started. |
| excluded_syscall_list | List of system calls to exclude. Of all the system calls that Zeek Agent can store, these will be excluded. |
| store_local_logs | If the answer is no, then Zeek Agent will not store file, process and socket events generated, locally within the end point system. If the answer is yes, it will locally store these event logs within the end point system. |
An example config.json file is shown below:
{
"server_address": "127.0.0.1",
"server_port": 9999,
"log_folder": "/var/log/zeek",
"max_queued_row_count": 5000,
"group_list": [],
"excluded_syscall_list": [],
"store_local_logs": "no"
}
Use the directory which was assigned as the value to the log_folder key within the configuration file, for storing Zeek Agent's own logs, that contain debug information related to Zeek Agent, such as any errors, announcements being made by Zeek Agent, starting/stopping of Zeek Agent services etc. Please note that these logs are not the logs of the system where Zeek Agent is running, but are the logs of Zeek Agent itself.
Next, go to the directory where you want to install Zeek Agent and run the following commands to configure, build, test, and install the system alongside building the documentation:
git clone https://github.com/Wajihulhassan/zeek-agent.git --recursive
cd zeek-agent/
mkdir ./build/
cd build
cmake -DCMAKE_BUILD_TYPE:STRING=RelWithDebInfo -DZEEK_AGENT_ENABLE_INSTALL:BOOL=ON -DZEEK_AGENT_ENABLE_TESTS:BOOL=ON -DZEEK_AGENT_ZEEK_COMPATIBILITY:STRING="3.1" ../
cmake --build . -j2
nohup ./zeek-agent &
bg_pid=$!
echo "${bg_pid}" > zeek-agent.pid
cmake --build . --target zeek_agent_tests -- -v
cmake --build . --target doxygen -- -v
cmake --build . --target install -- -v
cd packaging
cmake -G Ninja -DZEEK_AGENT_ZEEK_COMPATIBILITY:STRING="3.1" -DZEEK_AGENT_INSTALL_PATH:PATH=../build ../
To be able to run Zeek Agent globally from anywhere, set the path of Zeek Agent to point to the build directory. This can be done by running the following commands:
echo export PATH=$PATH_TO_ZEEK_AGENT >>~/.bashrc
source ~/.bashrc
Now Zeek Agent can be executed from anywhere throughout the system by running the following command:
sudo zeek-agent
All the steps for MacOS remain the same as the ones for Linux except for step 2. Instead of Configuring Audit Daemon, Endpointsecurity and OpenBSM need to be configured to collect system wide logs and deliver them to Zeek Agent.
Zeek Agent supersedes an earlier osquery extension for Zeek that focused on providing osquery's tables to Zeek.
Zeek Agent comes with a BSD license, allowing for free use with virtually no restrictions. You can find it in LICENSE.