Docker deployment and management tool for Zeek

The Docker image comes with:

• Zeekctl cluster with AF_Packet
• Automatic process recovery if a worker crashes
• ja3 and ja4+ TLS fingerprinting
• zeek-open-connections for logging long-lived connections

Requires Docker to be installed.

Download the CLI for your architecture from the latest release, then:

tar xzf zeek-linux-amd64.tar.gz
sudo mv zeek /usr/local/bin/zeek
sudo zeek start

On first run, the CLI prompts you to pick a network interface. Zeek logs are written to /opt/zeek/logs/.

zeek start       Start the Zeek container
zeek stop        Stop the Zeek container
zeek restart     Restart the Zeek container
zeek status      Show container and process status
zeek readpcap    Process a pcap file offline

sudo zeek readpcap /path/to/capture.pcap [output-dir]

Logs default to /opt/zeek/manual-logs/.

To re-run the interface selection:

sudo rm /opt/zeek/etc/node.cfg
sudo zeek start

The image comes with ja3, ja4, and zeek-open-connections. There are two ways to add more.

For permanent additions, build a custom image that includes the package.

For trying a script-only package at runtime, you can install it directly in the running container with zkg install:

sudo docker exec zeek zkg install --skiptests <package>
sudo docker exec zeek zeekctl deploy

Compiled-plugin packages (those with C++ code) can't be installed at runtime because the final image doesn't include a compiler, so zkg install fails. Use a custom image instead.

In v6 and earlier, the zeek-zkg-script, zeek-zkg-plugin, and zeek-zkg-state volumes held packages installed at runtime via zkg. v8 doesn't use those volumes.

The image already includes ja3, ja4, and zeek-open-connections. If you installed any other packages with zkg install, follow the custom image steps above to recreate them.

Then remove the old volumes:

sudo docker volume rm zeek-zkg-script zeek-zkg-plugin zeek-zkg-state

Add custom scripts as .zeek files in /opt/zeek/share/zeek/site/autoload/. The container loads everything in that directory on each start. Use any filename other than local.zeek, which is regenerated automatically.

sudo cp custom.zeek /opt/zeek/share/zeek/site/autoload/210-custom.zeek
sudo zeek restart

Zeek logs are written to /opt/zeek/logs/ (or $ZEEK_TOP_DIR/logs/ if customized).

Zeek files live in /opt/zeek/ by default. Change it with:

export ZEEK_TOP_DIR=/your/path

Stop the running container, replace the CLI binary, and start again:

zeek stop
tar xzf zeek-linux-amd64.tar.gz
sudo mv zeek /usr/local/bin/zeek
sudo zeek start

Your node.cfg and networks.cfg are preserved. If you customized zeekctl.cfg or 100-default.zeek, your previous version is saved as .bak. Reapply your changes to the new file.

If the CLI warns about orphaned zkg volumes from an older version: if you installed custom Zeek packages with zkg install, see Migrating from older versions first. Otherwise, remove them:

sudo docker volume rm zeek-zkg-script zeek-zkg-plugin zeek-zkg-state

After confirming the new container is working, free up disk space by removing the old image:

sudo docker images activecm/zeek      # show what's installed
sudo docker rmi activecm/zeek:6.2.1   # replace with the tag you had

make build              # build the CLI
make test               # run unit tests
make test-integration   # run integration tests
make lint               # run linter
make docker-build       # build the Docker image
make release            # build release artifacts