Quick Start: Full Packet Capture with EveBox

Since 0.27, EveBox can download full packet captures (FPC) right from the web interface. Open an event and download the packets around it, or request a custom time range and BPF filter. EveBox extracts the packets on demand from a capture spool and returns them to your browser as a .pcap file.

This quick start covers the typical agent/server deployment, with an EveBox Agent on each sensor serving its local captures to a central EveBox Server. First we'll get a capture spool going. If a tool like Suricata or netsniff-ng is already writing capture files for you, jump ahead to Configuring EveBox.

This post has been updated for EveBox 0.29.0, where an agent's identity comes from its agent key and the old agent-id setting is no longer used.

Set Up a Capture Spool

EveBox does not capture packets itself. Instead it extracts packets from a spool, a directory of rotated capture files written by another tool. Any tool that puts a rotation timestamp in the filename will work, but Suricata's pcap-log output is the most common choice.

With Suricata

Add a pcap-log entry under the outputs section of suricata.yaml:

- pcap-log:
    enabled: yes
    mode: multi
    dir: /var/log/suricata/pcap
    filename: log.%n.%t.pcap
    file-size: 256mb
    max-files: 100

Restart Suricata and capture files should start showing up in the directory.

Notes:

• A file-size of 256mb is recommended, as a smaller file size helps EveBox prune files with no matching packets based on time.
• Suricata takes care of rotating and removing old files, so no separate retention job is needed.

With netsniff-ng

Suricata is not required though. Any capture tool that writes rotated, timestamped files will work. For example, netsniff-ng:

netsniff-ng -i lan0 -o /mnt/data/capture -F 256MiB -s

writes size-rotated dump-<timestamp>.pcap files that EveBox recognizes. Unlike Suricata, netsniff-ng does not clean up old files, but EveBox includes a retention tool that can be left running as a service:

evebox pcap purge --max-size 100G --interval 60 --force /mnt/data/capture

Whichever tool you use, make sure the spool directory is readable by the EveBox Agent that will be serving it.

Configuring EveBox

1. Upgrade to 0.29.0 or Newer

Full packet capture first appeared in EveBox 0.27.0, but this guide is written for EveBox 0.29.0 or newer on the server and on any agents. See the installation documentation for installing or upgrading on your platform.

2. Create an Agent Key on the Admin Page

The EveBox Agent serves its capture spool to the EveBox Server over a persistent connection, authenticated with an agent key. The key's name is also the agent's identity: it names the capture source, and it is stamped on the events the agent submits.

In the EveBox web interface, go to Administration → Agents and create a new agent key. When possible, name the key after the sensor name stored in events (the EVE host value), for example firewall-east, so event downloads route to this agent automatically. Copy the key value (eba_...) for the next step. It can be revealed again later if you lose it.

If you prefer the command line, keys can also be created on the server host:

evebox config agents add firewall-east

3. Configure the Agent

On the sensor, give the agent the server URL, the key, and the spool directory. In agent.yaml:

server:
  url: https://evebox.example
  key: eba_...

pcap:
  directory: /var/log/suricata/pcap
  prefix: log.

Or with command line arguments. The key itself has no command line option, so it is passed in the EVEBOX_SERVER_KEY environment variable:

EVEBOX_SERVER_KEY=eba_... evebox agent \
  --server https://evebox.example \
  --pcap-directory /var/log/suricata/pcap \
  --pcap-prefix log.

Notes:

• There is no separate agent ID to configure. If you are upgrading from 0.27 or 0.28, the agent-id setting and --agent-id flag are now ignored and can be removed.
• The agent can continue to import EVE files as before, or run PCAP-only with no EVE inputs at all.

Restart the agent, and if all goes well it will show up with a live status on the Administration → Agents page.

Download Some Packets

Open an alert or event in EveBox and use the packet capture download control to grab the packets around it. For everything else, the custom download page lets you pick a time range, a BPF filter, and the capture source if there is more than one.

Quick per-event downloads are capped at 8 MB to keep them fast. The custom download page can raise the cap, or remove it entirely.

Where to Go Next

The packet capture documentation covers the rest: serving a spool local to the EveBox Server without an agent, routing rules for mapping sensors to capture sources, agent key management and rotation, serving limits, PCAP-only agents, and the evebox pcap extract command for extracting from a spool directly on the command line.