Skip to main content

Try EveBox

To quickly try EveBox, first download a binary package from the below links and unzip:

Then run EveBox directly against an eve.json file from Suricata:

./evebox oneshot /path/to/eve.json

If a browser doesn't load, open http://localhost:5636 in your browser. This is called oneshot mode where a single eve.json file is loaded for inspection into a temporary database which is destroyed when you close EveBox.

Coming in EveBox 0.28.0

EveBox 0.28.0 adds two oneshot conveniences:

  • EVE events can be read from stdin by using - as the input, for example: curl https://example.com/eve.json | ./evebox oneshot -. Events are imported as they arrive rather than waiting for end of input.
  • While events are still being imported, CTRL-C stops the import, keeping the events read so far for review. A further CTRL-C exits.

Process a PCAP in Oneshot Mode​

New in EveBox 0.27.0

Oneshot PCAP processing is available starting in EveBox 0.27.0.

On Linux, oneshot mode can process a local, uncompressed PCAP or PCAPNG file with containerized Suricata before loading the generated EVE events:

./evebox oneshot --pcap /path/to/capture.pcap

PCAP mode requires network access and a local Podman or Docker engine. EveBox tries Podman first and then Docker; remote container engines are not supported. It uses the stock Suricata configuration and updates ET/Open, PAW Patrules, and The Hunters Ledger rules before each capture. The rule download cache is kept in the user's cache directory so unchanged rules do not need to be downloaded again. The capture is processed locally and is not sent to a remote service.

The default image is docker.io/jasonish/suricata:8.0. EveBox downloads it if it is missing. If a cached image contains Suricata older than 8.0.6, an interactive run offers to pull an update; a non-interactive run warns and continues with the cached image.

Useful PCAP options include:

  • --container-runtime podman|docker to select a runtime instead of automatic detection.
  • --suricata-image IMAGE to use a compatible custom image. It must provide /usr/bin/suricata, /usr/bin/suricata-update, /bin/sh, a suricata user, and an entrypoint that runs the supplied command, like the default image.
  • --force to allow captures larger than 4 GiB. EveBox normally rejects them because it stages a full copy in its temporary workspace.
  • --limit NUMBER to limit imported EVE events. Suricata still processes the complete capture.

PCAP mode is unavailable on Windows and macOS. Ordinary eve.json oneshot mode continues to work on those platforms.

Coming in EveBox 0.28.0

EveBox 0.28.0 adds a local Suricata backend to PCAP mode, running a locally installed Suricata (8.0.0 or newer) instead of a container. Select it with --suricata-backend local, or by pointing --suricata (and optionally --suricata-update) at the executables. Rules are updated with suricata-update when available, otherwise they are downloaded directly from the rule feeds, with the same download caching as the container backend. Suricata runs in a temporary workspace and the installed Suricata configuration is left untouched.

The local backend reads the capture in place, so the 4 GiB limit and --force only apply to the container backend. With both backends, rules that fail to load are now logged and skipped instead of aborting the run.

The local backend is the default on Windows and macOS, making PCAP mode available on those platforms, and is used on Linux as a fallback when no usable container runtime is found. On Windows, rules using the file.magic or filemagic keywords are removed, as the Windows Suricata builds do not support them, and packet extraction from the input PCAP is not available.

EveBox Deployment Options​

EveBox was initially developed to connect directly to Elasticsearch being fed Suricata events with Logstash, however the deployment options have changed over time and can complicate things a little.

The current deployment options are:

  • Elasticsearch with Suricata events being added with Logstash. Note that transforming events can break EveBox's expectations of what a Suricata event looks like
  • Elasticsearch with Suricata events being added with Filebeat and the Filebeat plugin
  • EveBox Server (and optional agent) with Elasticsearch as a backend
  • EveBox server (and optional agent) with built-in SQLite backend

The first two Elasticsearch options are ideal if you are already ingesting Suricata events with Logstash or Filebeat.

The 3rd option, where EveBox is managing events is mostly compatible with the Logstash method and is ideal if you have a rather large event load and are capable of managing Elasticsearch yourself.

The SQLite option is ideal for small deployments such as home networks and is mostly self-managing, and also the simplest way to run EveBox.

info

SQLite is better for smaller loads, such as low bandwidth sensors or home networks, especially if you're willing to set limits on the database size or its age, such as 14 days and/or 40 gigabytes.

So Which Deployment Option Should I Use?​

If you are still asking this question after reading the options above, I suggest you try the built-in SQLite database. There is no "stack" to support and it just works to start. This will at least get you familiar with EveBox with little effort, then you could decide to use Elasticsearch if you have higher loads.

info

EveBox attempts to keep feature parity with different backends, however Elasticsearch would allow you to also use Kibana for infinite custom report options.