Full Packet Capture

New in EveBox 0.27

Full packet capture downloads are a new feature first available in EveBox 0.27. The feature is still under active development and its configuration keys and behaviour may change.

The EveBox Server can offer full packet capture downloads for events directly from the web interface. Packets can come from a capture-file spool on the EveBox Server or from an EveBox Agent running on a remote sensor. EveBox extracts the requested packets on demand and returns the result to the browser as a .pcap file.

This makes it possible to download the packets for a flow, an event's surrounding time window, or an arbitrary BPF filter over a time range, without leaving EveBox.

Prerequisites

A capture spool must be written to disk, typically with Suricata's pcap-log output, though other capture tools such as netsniff-ng also work.
The spool directory must be readable by the EveBox Server or Agent process that serves it.
For a server-local source, the server must run on the host that has access to the capture files. Otherwise, run an EveBox Agent on the sensor host.
Windows builds of EveBox cannot extract packets themselves: a Windows server offers capture downloads only from connected remote agents, server-local capture and the evebox pcap commands are unavailable, and a Windows agent cannot serve capture.

Recommended Suricata Configuration

For threaded capture, add the following pcap-log entry under Suricata's outputs section:

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

Adjust file-size and max-files for the host's traffic rate and available storage. Suricata remains responsible for rotating and removing old capture files.

Other Capture Tools

Suricata is not required to write the spool. Any tool that writes rotated capture files with a rotation timestamp in the filename works. 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 and prunes by time just like a Suricata spool.

Server-Local Capture

When Suricata and the EveBox Server run on the same host, packet capture is enabled by pointing the server at the capture spool directory. This is not available on Windows, where a server offers captures through remote agents only. Configure the directory on the command line:

evebox server --pcap-directory /var/log/suricata/pcap

with the EVEBOX_PCAP_DIRECTORY environment variable, or in the configuration file:

pcap:
  directory: /var/log/suricata/pcap

Once a spool directory is configured, the download controls appear in the web interface automatically. The local source is displayed as (server) when a source must be selected.

note

If the configured directory does not exist yet, EveBox will log a warning and continue; the directory is re-checked when requests are served, so it does not need to exist at startup.

Command-Line Arguments

These options are available on the evebox server command:

--pcap-directory <DIR>

Local pcap spool directory to serve full packet capture from. This is the primary switch that enables the feature.
--pcap-prefix <PREFIX>

Only consider pcap files in the spool whose names start with this prefix. Useful when multiple capture sets share one directory.

Environment Variables

Variable	Description
`EVEBOX_PCAP_DIRECTORY`	Local pcap spool directory to serve capture from.
`EVEBOX_PCAP_PREFIX`	Only consider pcap files starting with this prefix.

Configuration File

The spool is configured under a top-level pcap section with just two keys, directory and prefix, which mirror the command line arguments above. Serving limits and timeouts are fixed and cannot be changed in the configuration file.

pcap:
  # Local capture spool directory. Setting this enables packet
  # capture downloads.
  directory: /var/log/suricata/pcap

  # Only consider pcap files starting with this prefix.
  #prefix: log

Serving Limits

These limits apply to downloads from every capture source, local or agent-served:

Behaviour	Value	Notes
Quick event download cap	`8mb`	Fixed at 8,000,000 bytes.
Custom download default	`8mb`	May be lowered, raised, or set to `unlimited`.
Scan/first-output deadline	`60s`	No output times out; an in-progress result is cut.
Client stall timeout	`60s`	Stops a stream when the browser stops reading.
Concurrent extractions	`16`	Additional requests receive a busy response.

note

unlimited removes only the output-size cap. The 60-second scan deadline, client stall timeout, and concurrency limit still apply.

Remote Agents

When the sensor and EveBox run on different hosts, an EveBox Agent on the sensor can serve its local capture spool over a persistent control connection to the EveBox Server.

1. Create an Agent Key on the Server

The control connection is authenticated with an agent key, created on the EveBox Server. Give the key the same name the agent will use as its agent-id:

$ evebox config agents add firewall-east
Agent key added: name="firewall-east"
Key: eba_...
Set this as server.key in the agent's agent.yaml (or EVEBOX_SERVER_KEY).

Run this on the server host with the server's data directory (the -D <DIR> option if the server does not use the default). Keys can also be created and revealed in the web interface under Administration → Agents. See Agent Keys below for listing, removal, and rotation.

2. Configure the Agent

Add the server URL, the key, and the capture spool to agent.yaml on the sensor:

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

# PCAP serving requires the EveBox Server connection and is not available
# when the agent writes directly to Elasticsearch.
elasticsearch:
  enabled: false

# Use the sensor name stored in events when possible so requests route to
# this source automatically. The system hostname is used when omitted.
agent-id: firewall-east

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

The key has no command-line option; use the configuration file or the EVEBOX_SERVER_KEY environment variable. The equivalent command-line form for the remaining settings is:

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

Setting a directory, in the configuration file or with --pcap-directory, is what enables PCAP serving; there is no separate enable flag.

3. Verify

Once started, the agent appears with a live status on the Administration → Agents page, and its name becomes available as a capture source for downloads. A rejected agent logs the reason on both sides; the most common causes are a missing or mistyped key and a key name that does not match the agent's agent-id.

Notes

The agent may continue importing EVE files while serving captures. It can also run as a PCAP-only agent: omit input.paths and do not pass any EVE filenames. A PCAP-only agent does not ship or stamp events, so set agent-id to the event sensor name (the EVE host value or ECS agent.name) when automatic event routing is required.

Each agent serves one configured spool. Callers cannot choose a different directory, and PCAP serving is ignored when the agent uses direct-to-Elasticsearch output.

Remote capture jobs depend on the agent's WebSocket control connection. If that connection drops or is replaced while a capture is being extracted or uploaded, EveBox interrupts the download instead of treating a partial capture as complete. The agent reconnects automatically, but the user must retry the download.

Agent Keys

Agent keys authenticate the agent control channel. They are independent of the web interface's authentication.required setting: connecting agents must present a valid key even when browser authentication is disabled.

Keys are managed on the server from the command line:

evebox config agents add <name>    # create a key, printing its value
evebox config agents list          # list keys, without key values
evebox config agents list --keys   # list keys, including key values
evebox config agents rm <name>     # remove a key

or in the web interface under Administration → Agents, which can create, reveal, and delete keys in place.

Keys are stored as-is, not hashed, in the server's configuration database (config.sqlite in the data directory) so they can be shown again on demand. Keep file permissions restrictive on that database and on each sensor's agent.yaml; both contain the live key.

Deleting a key in Administration → Agents immediately disconnects an agent authenticated with it. Any packet capture request currently using that agent is interrupted, and reconnect attempts with the deleted key are rejected. The command-line config agents rm operation edits the configuration database directly and cannot notify a running EveBox Server, so a connected agent remains online until it disconnects or the server restarts.

To rotate a key, delete the old key, add it again under the same name, update the agent's server.key, and restart the agent. When using the command-line removal, also restart the EveBox Server if the old agent is still connected. There is no dual-key grace period, so the agent's capture source is offline between deletion and the agent restart.

For lab setups the server can accept agents without keys:

agents:
  allow-unauthenticated: true

A presented key is still verified in this mode; only keyless agents are let through.

note

Agent keys protect the packet capture control channel. EVE event submission from agents is a separate path that does not require a key.

Routing

Routing decides which capture source — the server-local spool or a connected agent — serves a download.

Automatic Routing

An explicit source selection always wins. Otherwise, event downloads first match the event's sensor identity to a connected agent, followed by the exact evebox.agent.id and older agent-hostname stamps. An event ingested directly by the server uses the server-local spool when no agent identity matches. A request with no event uses the only available source automatically; when several sources are available, select one in the custom download page.

Routing Rules

When automatic routing cannot match events to the right source — for example when events reach EveBox through a central importer, so their agent stamps name the importer rather than the capture host, or when stored events carry old sensor names — routing can be taken over with explicit rules, edited on the Administration → Agents page.

Rules map an event sensor name to a capture source, with an optional default source for everything else. (server) selects the server-local spool.

As soon as any rules exist, they replace automatic routing completely. An event that matches no rule, or a custom download with no event, uses the default source; if no default is configured, the request fails with a routing error rather than falling back to automatic matching. Explicit source selection still overrides the rules.

Command-Line Extraction

The extraction engine used by the server is also available directly from the command line, along with a retention tool for spool directories. Both operate on the local filesystem and do not need the EveBox Server.

evebox pcap extract

Extract packets from a capture spool. This is useful for extracting a capture directly on a sensor host, without running the EveBox Server:

evebox pcap extract \
  --directory /var/log/suricata/pcap \
  --prefix log \
  --start-time 20260713T12:00:00+00:00 \
  --duration 300 \
  --filter 'tcp port 443' \
  --output capture.pcap

The command accepts these extraction options:

--directory <DIR>

Required. Recursively searches this directory for capture files.
--prefix <PREFIX>

Only processes files whose names start with this prefix.
--filter <EXPRESSION>

Applies a libpcap BPF expression. If omitted, all packets in the selected time range are included.
--start-time <TIME>

Includes packets at or after this time. Accepted forms are YYYYMMDD or YYYYMMDDTHH:MM:SS[.ffffff][TZ]. A time without an explicit timezone uses the local timezone.
--duration <SECONDS>

Limits extraction to this many seconds after --start-time, based on packet timestamps. This option requires --start-time.
--output <FILE>

Writes the extracted capture to a file. If omitted, output goes to standard output when it is redirected or piped; EveBox refuses to write binary PCAP data directly to a terminal.

Without --start-time, the command scans all selected files. It writes packets in timestamp order across per-thread capture streams. If no packets match, it writes a valid, header-only capture. It also refuses to overwrite an input file through a direct path, symbolic link, or hard link.

The extraction command is not available in Windows builds.

evebox pcap purge

Suricata's pcap-log max-files setting is the usual way to bound a spool's size. For spools where Suricata does not manage retention, or that are written by other tools, evebox pcap purge deletes the oldest capture files from a spool directory:

evebox pcap purge --max-size 100G /var/log/suricata/pcap

By default the command is a dry run that only reports what it would delete; add -f/--force to actually delete files. Exactly one retention mode is required:

--keep-files <N>

Keep only the newest N files.
--max-size <SIZE>

Keep the newest files that fit in this total size, for example 500M or 10G.

Files are ordered by modification time. Only the given directory itself is examined, and only regular files with recognized capture names are considered — classic rotated (log.pcap.1700000000), extension-last (log.1.1700000000.pcap). Other files are left alone, and --prefix <PREFIX> narrows the selection further when multiple capture sets share a directory.

With --interval <MINUTES> the command keeps running and repeats the purge every N minutes, so it can be left in place as a retention service. -q/--quiet limits output to warnings and errors.

Prerequisites​

Recommended Suricata Configuration​

Other Capture Tools​

Server-Local Capture​

Command-Line Arguments​

Environment Variables​

Configuration File​

Serving Limits​

Remote Agents​

1. Create an Agent Key on the Server​

2. Configure the Agent​

3. Verify​

Notes​

Agent Keys​

Routing​

Automatic Routing​

Routing Rules​

Command-Line Extraction​

evebox pcap extract​

evebox pcap purge​

Prerequisites

Recommended Suricata Configuration

Other Capture Tools

Server-Local Capture

Command-Line Arguments

Environment Variables

Configuration File

Serving Limits

Remote Agents

1. Create an Agent Key on the Server

2. Configure the Agent

3. Verify

Notes

Agent Keys

Routing

Automatic Routing

Routing Rules

Command-Line Extraction

evebox pcap extract

evebox pcap purge