The EveBox Agent
The EveBox Agent processes Suricata EVE log files and sends them to an
EveBox or Elasticsearch server. The EveBox Server can then store the
events in Elasticsearch or SQLite. An agent connected to an EveBox
Server can also serve packet captures from a Suricata pcap-log spool
and extracted files from Suricata's file-store output.
See Agent Environment Variables for a complete list of the environment variables supported by the agent.
With the EveBox Server
From the command line:
evebox agent --server http://127.0.0.1:5636 \
/var/log/suricata/eve.json
Or with a configuration file:
server:
url: http://127.0.0.1:5636
input:
paths:
- "/var/log/suricata/eve.json"
The Agent can also receive EVE events directly from a Unix-domain socket. See EVE Socket Input for the matching Agent and Suricata configuration.
Full Packet Capture
An agent running on a Suricata sensor can advertise its local packet capture spool to the EveBox Server:
server:
url: https://evebox.example
key: eba_...
elasticsearch:
enabled: false
pcap:
directory: /var/log/suricata/pcap
prefix: log.
The control connection requires an agent key. Create one on the server
with evebox config agents add <name> and set the printed key as
server.key (or the EVEBOX_SERVER_KEY environment variable).
The key's name is the agent's identity: it names the capture source and
is stamped on events the agent submits. It should normally match the
sensor name stored in EVE events so event downloads route to the
correct agent. The agent-id option used before EveBox 0.29.0 is now
ignored.
The agent can import EVE files and serve captures at the same time. For
a PCAP-only agent, omit input.paths; the agent remains connected and
serves capture requests without shipping EVE events. PCAP serving
requires an EveBox Server connection and is ignored in direct
Elasticsearch mode.
See the Packet Capture page for capture spool configuration, command-line options, agent key management, and routing.
Extracted Files
Serving extracted files is only available in EveBox 0.30.0 and newer.
An agent connected to an EveBox Server can also serve previews and downloads of files extracted by Suricata's file-store (version 2) output, over the same control connection and agent key used for packet capture:
filestore:
directory: /var/log/suricata/filestore
or --filestore-directory on the command line. File serving works on
Windows without Npcap, and an agent may serve files without serving
packet captures. See Extracted Files for details.
With Elasticsearch
As of EveBox 0.17.0, the Agent is also capable of sending events to Elasticsearch in a Logstash compatibly way. It cannot send events to Elasticsearch using a schema compatible with Filebeat or Filebeat with the Suricata module. So its use is only advised if your Elasticsearch index is dedicated to EveBox, or a mix of EveBox and Logstash event processed sending to the same index.
With Elasticsearch on the command line:
evebox agent --elasticsearch \
--elasticsearch-url http://elasticsearch:9200 \
--elasticsearch-index logstash \
/var/log/suricata/eve.json
Or with a configuration file:
elasticsearch:
enabled: true
url: http://elasticsearch:9200
index: logstash
GeoIP
The EveBox Agent can optionally add GeoIP information to Suricata events using the GeoIP2 databases from MaxMind1.
It is highly recommended to create an account with MaxMind and use up to date databases. The databases including with most Linux distributions is from 2019.
To enable GeoIP, add --enable-geoip to the EveBox Agent command
line.
The GeoIP databases will be looked for in the following locations.
- /etc/evebox/GeoLite2-City.mmdb
- /usr/local/share/GeoIP/GeoLite2-City.mmdb
- /usr/share/GeoIP/GeoLite2-City.mmdb
Rules
The EveBox Agent can optionally add the Suricata rule to an alert. This can be enabled in the configuration file. Example:
# The event reader can also add the rule to alert events. Do not enable
# if you already have Suricata logging the rule.
rules:
- /var/lib/suricata/rules/*.rules
- /usr/share/suricata/rules/*.rules
- /etc/suricata/rules/*.rules