Zeekurity Zen – Part I: How to Install Zeek on Ubuntu

Zeekurity Zen Zeries: How To Install Zeek On Ubuntu

This is part of the Zeekurity Zen Zeries on building a Zeek (formerly Bro) network sensor.

Overview

This guide assumes you’ll be installing Zeek on Ubuntu 22.04 LTS.  However, the guide should work for any reasonably recent versions of Ubuntu.

Kicking things off, we’ll optimize Ubuntu to efficiently capture packets and then compile Zeek from source to start monitoring network traffic.

To do this, we’ll walkthrough these steps:

  1. Minimize packet loss and ensure Zeek sees full packet data by applying network sniffing optimizations: settings max ring parameters, disabling NIC offloading, and enabling promiscuous mode.
  2. Build Zeek from source with optimizations.
  3. Create a non-root Zeek user to minimize impact in the event that Zeek is compromised.
  4. Deploy and run Zeek to start analyzing traffic.
  5. Create a cron job to perform Zeek maintenance tasks.

Set max ring parameters

  1. Use ethtool to determine the maximum ring parameters for your sniffing interfaces.  The example below assumes an interface named enp2s0.
    sudo ethtool -g enp2s0
    Ring parameters for enp2s0:
    Pre-set maximums:
    RX:             4096
    RX Mini:        0
    RX Jumbo:       0
    TX:             4096
    Current hardware settings:
    RX:             256
    RX Mini:        0
    RX Jumbo:       0
    TX:             256
  2. As root/sudo, create a new file in /etc/networkd-dispatcher/routable.d/10-set-max-ring and add the following lines for each sniffing interface.
    #!/bin/sh
    # Set ring rx parameters for all sniffing interfaces
    ethtool -G enp2s0 rx 4096
  3. Save the file and set its permissions to 755.
    sudo chmod 755 /etc/networkd-dispatcher/routable.d/10-set-max-ring

Disable NIC offloading functions

  1. As root/sudo, create a new file in /etc/networkd-dispatcher/routable.d/20-disable-checksum-offload and add the following lines for each sniffing interface.
    #!/bin/sh
    # Disable checksum offloading for all sniffing interfaces
    ethtool -K enp2s0 rx off tx off sg off tso off ufo off gso off gro off lro off
  2. Save the file and set its permissions to 755.
    sudo chmod 755 /etc/networkd-dispatcher/routable.d/20-disable-checksum-offload

Set sniffing network interfaces to promiscuous mode

  1. As root/sudo, create a new file in /etc/networkd-dispatcher/routable.d/30-enable-promisc-mode and add the following lines for each sniffing interface.
    #!/bin/sh
    # Enable promiscuous mode for all sniffing interfaces
    ip link set enp2s0 arp off multicast off allmulticast off promisc on
  2. Save the file and set its permissions to 755.
    sudo chmod 755 /etc/networkd-dispatcher/routable.d/30-enable-promisc-mode

Confirm changes are persistent

  1. Reboot your system and verify all the changes made thus far have persisted.Verify max ring parameters under Current hardware settings RX matches the configured maximum.
    sudo ethtool -g enp2s0
    Ring parameters for enp2s0:
    Pre-set maximums:
    RX:             4096
    RX Mini:        0
    RX Jumbo:       0
    TX:             4096
    Current hardware settings:
    RX:             4096
    RX Mini:        0
    RX Jumbo:       0
    TX:             256

    Verify NIC offloading features are turned off (this list is likely much longer on your system).

    sudo ethtool -k enp2s0
    Features for enp2s0:
    rx-checksumming: off
    tx-checksumming: off

    Verify that PROMISC is listed in the network interface status.

    ip a show enp2s0 | grep -i promisc
    2: enp2s0: < BROADCAST,NOARP,PROMISC,UP,LOWER_UP > mtu 1500 qdisc mq state UP group default qlen 1000

Install Zeek Dependencies

  1. Run the following apt command to download the required dependencies.
    sudo apt-get install cmake make gcc g++ flex bison libpcap-dev libssl-dev python3 python3-dev python3-git python3-semantic-version swig zlib1g-dev libjemalloc-dev
  2. Ensure all your packages are up to date and reboot your system.
    sudo apt-get update
    sudo apt-get dist-upgrade
    sudo reboot

Create the zeek user and directory to install and run Zeek

  1. Create the zeek user and group and set a password.
    sudo adduser zeek
    Adding user `zeek' ...
    Adding new group `zeek' (1001) ...
    Adding new user `zeek' (1001) with group `zeek' ...
    Creating home directory `/home/zeek' ...
    Copying files from `/etc/skel' ...
    New password:
    Retype new password:
    passwd: password updated successfully
    Changing the user information for zeek
    Enter the new value, or press ENTER for the default
    	Full Name []:
    	Room Number []:
    	Work Phone []:
    	Home Phone []:
    	Other []:
    Is the information correct? [Y/n] Y
  2. As root/sudo, create the /opt/zeek directory and set ownership to the zeek user.
    sudo mkdir /opt/zeek
    sudo chown -R zeek:zeek /opt/zeek
    sudo chmod 750 /opt/zeek

Download, Compile, and Install Zeek

  1. Switch to the zeek user.
    su zeek
  2. We will download zeek to the /home/zeek directory. Then we will configure Zeek to install in the /opt/zeek directory and enable jemalloc to improve memory and CPU usage.  As of this writing, the latest feature release is version 6.2.1.  If the download URL referenced in the wget command below no longer works, you can download the latest stable release directly from the Get Zeek download page.
    cd
    wget https://download.zeek.org/zeek-6.2.1.tar.gz
    tar -xzvf zeek-6.2.1.tar.gz
    cd zeek-6.2.1
    ./configure --prefix=/opt/zeek --enable-jemalloc --build-type=release
    make
    make install

    Note: This will take *a while* to compile.

  3. Switch back to your normal user by closing the zeek session.
    exit
  4. Since the zeek user is not root, give the Zeek binaries permissions to capture packets.
    sudo setcap cap_net_raw=eip /opt/zeek/bin/zeek
    sudo setcap cap_net_raw=eip /opt/zeek/bin/capstats

Add Zeek to PATH

  1. Switch back to the zeek user.
    su zeek
  2. As the zeek user, create ~/.bashrc and add the following lines.
    # Add Zeek to PATH
    export PATH="/opt/zeek/bin:$PATH"
  3. Save the file and apply the new path to the zeek user.
    source ~/.bashrc

Configure Zeek

  1. Edit /opt/zeek/etc/node.cfg to configure the number of nodes.  It is recommended to use a maximum of one or two less workers than the total number of CPU cores available on your sensor.  In the example configuration below we are configuring a total of two workers, analyzing one sniffing interface.
    Note: The following node configuration does not use Zeek’s out of the box support for AF_PACKET (as of version 5.2). It is recommended to configure Zeek to use AF_PACKET for optimal packet capture and the configuration is covered in Part II.

    # Example ZeekControl node configuration.
    # Below is an example clustered configuration on a single host.
    [logger]
    type=logger
    host=localhost
    [manager]
    type=manager
    host=localhost
    [proxy-1]
    type=proxy
    host=localhost
    [worker-1]
    type=worker
    host=localhost
    interface=enp2s0
    [worker-2]
    type=worker
    host=localhost
    interface=enp2s0

    In the event you have two or more sniffing interfaces (e.g. enp2s0 and enp3s0), see the example configuration below which assigns each interface its own worker.

    # Example ZeekControl node configuration.
    # Below is an example clustered configuration on a single host.
    [logger]
    type=logger
    host=localhost
    [manager]
    type=manager
    host=localhost
    [proxy-1]
    type=proxy
    host=localhost
    [worker-1]
    type=worker
    host=localhost
    interface=enp2s0
    [worker-2]
    type=worker
    host=localhost
    interface=enp3s0
  2. Edit /opt/zeek/share/zeek/site/local.zeek to enable or disable scripts as needed.

Start Zeek

  1. As the zeek user, run zeekctl deploy to apply configurations and run Zeek.
    zeekctl deploy
    checking configurations ...
    installing ...
    removing old policies in /opt/zeek/spool/installed-scripts-do-not-touch/site ...
    removing old policies in /opt/zeek/spool/installed-scripts-do-not-touch/auto ...
    creating policy directories ...
    installing site policies ...
    generating cluster-layout.zeek ...
    generating local-networks.zeek ...
    generating zeekctl-config.zeek ...
    generating zeekctl-config.sh ...
    stopping ...
    stopping workers ...
    stopping proxy ...
    stopping manager ...
    stopping logger ...
    starting ...
    starting logger ...
    starting manager ...
    starting proxy ...
    starting workers ...
  2. If your output looks similar to what’s shown above, you should be good to go. To verify Zeek is running successfully, you can run zeekctl status.
    zeekctl status
    Name         Type    Host             Status    Pid    Started
    logger       logger  localhost        running   1774   10 Oct 23:15:31
    manager      manager localhost        running   1820   10 Oct 23:15:32
    proxy-1      proxy   localhost        running   1865   10 Oct 23:15:33
    worker-1-1   worker  localhost        running   1950   10 Oct 23:15:35
    worker-1-2   worker  localhost        running   1951   10 Oct 23:15:35
    worker-2-1   worker  localhost        running   1955   10 Oct 23:15:35
    worker-2-2   worker  localhost        running   1954   10 Oct 23:15:35

    If you see the following errors:

    zeekctl deploy
    Error: worker-1-1 terminated immediately after starting; check output with "diag"
    Error: worker-1-2 terminated immediately after starting; check output with "diag"
    Error: worker-2-1 terminated immediately after starting; check output with "diag"
    Error: worker-2-2 terminated immediately after starting; check output with "diag"

    Then try re-running the sudo setcap commands from earlier.

    sudo setcap cap_net_raw=eip /opt/zeek/bin/zeek
    sudo setcap cap_net_raw=eip /opt/zeek/bin/capstats
  3. You should now see logs being generated in /opt/zeek/logs/current.
    ls -l
    total 2276
    -rw-rw-r--. 1 zeek zeek   1573 Oct 10 23:15 broker.log
    -rw-rw-r--. 1 zeek zeek    593 Oct 10 23:45 capture_loss.log
    -rw-rw-r--. 1 zeek zeek   1970 Oct 10 23:15 cluster.log
    -rw-rw-r--. 1 zeek zeek 673435 Oct 10 23:52 conn.log
    -rw-rw-r--. 1 zeek zeek 580865 Oct 10 23:52 dns.log
    -rw-rw-r--. 1 zeek zeek   3830 Oct 10 23:49 dpd.log
    -rw-rw-r--. 1 zeek zeek   1406 Oct 10 23:47 files.log
    -rw-rw-r--. 1 zeek zeek  26108 Oct 10 23:48 http.log
    -rw-rw-r--. 1 zeek zeek  24646 Oct 10 23:15 loaded_scripts.log
    -rw-rw-r--. 1 zeek zeek    753 Oct 10 23:18 notice.log
    -rw-rw-r--. 1 zeek zeek    187 Oct 10 23:15 packet_filter.log
    -rw-rw-r--. 1 zeek zeek    743 Oct 10 23:46 software.log
    -rw-rw-r--. 1 zeek zeek  86512 Oct 10 23:51 ssl.log
    -rw-rw-r--. 1 zeek zeek   5446 Oct 10 23:50 stats.log
    -rw-rw-r--. 1 zeek zeek      0 Oct 10 23:15 stderr.log
    -rw-rw-r--. 1 zeek zeek    188 Oct 10 23:15 stdout.log
    -rw-rw-r--. 1 zeek zeek 240866 Oct 10 23:51 weird.log
  4. If you’re running into issues, zeekctl diag can provide more detailed output for troubleshooting purposes.
    zeekctl diag

ZeekControl Cron

ZeekControl features a cron command to check for and restart crashed nodes and to perform other maintenance tasks.  To take advantage of this, let’s set up a cron job.

  1. Edit the crontab of the non-root zeek user.
    crontab -e
  2. Add the following to set up a cron job that runs every five minutes.  You can adjust the frequency to your liking.
    */5 * * * * /opt/zeek/bin/zeekctl cron

[Optional] Create systemd Zeek Service to Start on Boot

We can create a simple systemd service that enables us to start Zeek at boot time and easily start/stop whenever necessary. This particular configuration will automatically restart Zeek if the system notices it has stopped for any reason. Feel free to modify this as needed for your use case.

  1. As root/sudo, create a new service file in /etc/systemd/system/zeek.service and add the following lines.
    [Unit]
    Description=Zeek
    [Service]
    User=zeek
    Type=forking
    Restart=always
    RestartSec=1
    StartLimitAction=reboot
    ExecStart=/opt/zeek/bin/zeekctl deploy
    ExecStop=/opt/zeek/bin/zeekctl stop
    [Install]
    WantedBy=multi-user.target
  2. As root/sudo, you can now easily start, stop, or check the status of the Zeek service by running the following commands respectively.
    sudo systemctl start zeek
    sudo systemctl stop zeek
    sudo systemctl status zeek
  3. Finally, to enable Zeek to run at system boot time, run the following command.
    sudo systemctl enable zeek
    Created symlink /etc/systemd/system/multi-user.target.wants/zeek.service → /etc/systemd/system/zeek.service.

Up Next

In Part II of this series, we will install the Zeek Package Manager to extend Zeek’s functionality.

References

Zeek official documentationhttps://www.zeek.org/documentation/index.html
NIC offloading on Ubuntu with systemd-networkd: https://michael.mulqueen.me.uk/2018/08/disable-offloading-netplan-ubuntu/
NIC offloadinghttps://blog.securityonion.net/2011/10/when-is-full-packet-capture-not-full.html

Related Posts

Elastic Explained: How To Create a Cluster with Docker Compose

Elastic Explained: How To Create a Cluster with Docker Compose

Overview In this guide we'll walkthrough setting up and running an externally accessible three-node Elastic cluster using Docker Compose on Ubuntu Linux 22.04 that's suitable for a home lab or developer / test environment. Our Elastic deployment will include the...

Zeekurity Zen – Part IX: How To Update Zeek

Zeekurity Zen – Part IX: How To Update Zeek

This is part of the Zeekurity Zen Zeries on building a Zeek (formerly Bro) network sensor. Overview In our Zeek journey thus far, we've: Set up Zeek to monitor some network traffic. Used Zeek Package Manager to install packages. Configured Zeek to send logs to Splunk...

Elastic Explained: How To Guides For The Elastic Stack

Elastic Explained: How To Guides For The Elastic Stack

Elastic develops the popular log analytics platform, the Elastic Stack, which supports a variety of search, observability, and security use cases through its many out of the box integrations.  It's a great platform for collecting, analyzing, and visualizing data from...

Transform Your Business & Operate at Peak Efficiency