Skip to main content

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.

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"

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

agent-id: firewall-east

pcap:
  enabled: true
  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> — using the agent's agent-id as the name — and set the printed key as server.key (or the EVEBOX_SERVER_KEY environment variable).

agent-id should normally match the sensor name stored in EVE events so event downloads route to the correct agent. It defaults to the system hostname when omitted.

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.

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

Footnotes​

  1. https://www.maxmind.com/en/geoip2-services-and-databases ↩