EveBox Agent¶

The EveBox “agent” is a tool for sending eve events directly to an EveBox server without the need for tools like Filebeat and/or Logstash. Events sent with the agent are handled by the EveBox server and stored in the database by the server.

Example Usage¶

Command Line Only¶

If your EveBox Server is setup without any authentication all options can be provided on the command line. Example:

evebox agent --server http://hostname:5636 /var/log/suricata/eve*.json

This will process all eve log files in /var/log/suricata and send them to an EveBox Server hosted over at hostname.

Note

This will store bookmark information (the last location processed in each log file) in the current directory. This is OK if you will always be lanching EveBox Agent from the same working directory, however it is recommended to use the -D option to set the data directory to a consistent location.

With a Configuration File¶

If you need options such as a username/password for the EveBox server, want to add additional fields to the Suricata EVE records or add the rules to the EVE records it is recommended to use a configuration file.

A starter configuration file can be created with the following command:

evebox print agent.yaml

You may want to redirect this to a file:

evebox print agent.yaml > agent.yaml

Then the EveBox can be started like:

evebox agent -c /path/to/agent.yaml

By default the EveBox Agent will first look in the current directory for agent.yaml then /etc/evebox/agent.yaml.

Command Line Options¶

-c, --config <FILENAME>¶: Path to configuration file. If not provided the agent will look for a configuration named in agent.yaml in the current directory then look for /etc/evebox/agent.yaml.

-D, --data-directory <DIR>¶: Provide a directory where the Agent can store data and other state information. There is no default, but providing a directory like /var/lib/evebox/agent and making sure that directory is writable by the agent is highly recommended.

--enable-geoip¶: Enables MaxMind GeoIP lookups and will add GeoIP information for events. This depends on the GeoIP database being up to date and available in standard locations.

server <URL>¶: The EveBox server to connect to. Specified like http://1.1.1.1:5636 or https://my-evebox-server.domain.com:5636. Note that if using https, the URL must use a hostname and not an IP address.

--stdout¶: Prints events to stdout. Useful for debugging.

-v, --verbose¶: Specify once for debug level logging, and 2 or more times for trace level logging.

FILENAMES...¶: Any filenames provided on the command line will be read by the Agent and sent to the EveBox server. If filenames are specified on the command the input files in the configuration file will be ignored.

Environment Variables¶

Some configuration files can be provided with environment variables. The order or precedence is:

Command line arguments
Environment variables
Configuration file

EVEBOX_SERVER_URL¶: The EveBox server URL to connect to. See the documentation for the –server command line option for more information.

Configuration File¶

A default configuration can be generated with the command:

evebox print agent.yaml

Default Configuration File¶

# EveBox Agent configuration file - subject to change.

# Server information.
server:
  url: http://10.16.1.10:5636

  # Username and password. Note that at this time even with
  # authentication enabled on the EveBox server, agents can still
  # submit events without authenticating. You will need to supply and
  # username and password if running behind a reverse proxy
  # implementing authentication.
  #username: username
  #password: password

# Directory to store data and state information required by the agent. This
# isn't always required. If the agent has write access to the log directory it
# can store bookmark information along side the eve log files.
#data-directory: "/var/lib/evebox"

# If the EveBox server is running behind TLS and the certificate is
# self signed, certificate validation can be disabled.
#disable-certificate-check: true

# Path to log file. Only a single path is allowed at this time.
input:
  #filename: "/var/log/suricata/eve.json"

  # The filename parameter can also contain a wildcard.
  filename: "/var/log/suricata/eve*.json"

  # If multiple paths are required, use "paths" instead of filename.
  #paths:
  #  - "/var/log/suricata/sensor1/eve.json"
  #  - "/var/log/suricata/sensor2/eve.*.json"

# Additional fields that will be added to each event. This is currently limited
# to strings at this time.
additional-fields:
  #sensor-name: "my super secret sensor"

# 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