EveBox 0.26.0 on AWS User Guide

Overview

This guide covers launching and using the EveBox 0.26.0 on Ubuntu 24.04 AMI from cloudimg on Amazon EC2. It is one version of the cloudimg SIEM and Threat Detection listing on AWS Marketplace; you pick it as the software version when you subscribe and launch.

EveBox is a web console for the alerts and network events written by the Suricata intrusion detection engine. It gives an analyst an alert inbox (escalate, archive and comment on alerts), event search across alert, flow, DNS, TLS, HTTP and SSH records, and a detail view for every event. On its own EveBox is an empty viewer, so this image ships the engine that feeds it: Suricata 8.0.7 watches the instance's network interface and writes its EVE JSON log, and EveBox indexes that log into a local SQLite database.

The cloudimg image adds:

• A password unique to your instance, and EveBox's own login switched on. Started with authentication on and no user, upstream EveBox creates an admin user itself and writes that password into its log. This image never lets that happen: the first boot creates the admin user with a password generated on your instance (it never appears on a command line or in a log) and writes it to /root/evebox-info.txt (readable by root only), and EveBox refuses to start without a real administrator.
• Unauthenticated event submission closed. EveBox's agent endpoints /api/submit and /api/1/submit accept events without a login even when authentication is on, so anyone who can reach the console could plant fake alerts. This image runs no remote agents (Suricata on the instance feeds EveBox directly), so nginx refuses both endpoints.
• HTTPS from the first boot. nginx serves EveBox on port 443 with a certificate generated on your instance; port 80 redirects to HTTPS. Requests for a host name the instance does not serve get no answer. The login is rate limited and the session cookie is marked Secure.
• A current, patchable Suricata. Ubuntu 24.04's own Suricata package (7.0.3) has not received the security fixes released since. This image installs Suricata 8.0.7 from the Open Information Security Foundation's own suricata-stable package archive (OISF is the Suricata project), whose signing key is pinned by its fingerprint, and trusts that archive for Suricata updates: unattended upgrades install new Suricata releases from it along with Ubuntu's security updates.
• Real signatures from the start. The Emerging Threats Open ruleset (over 50,000 enabled rules) is installed at build time, plus a one-line self-test rule that lets you prove the whole pipeline with a single ping.
• Hardened defaults. EveBox listens on 127.0.0.1 only and runs as its own unprivileged user under a locked down systemd unit; Suricata drops to its own suricata user. Suricata, EveBox and nginx are blocked from the instance metadata service and the AMI requires IMDSv2. The client address comes from the connection, never from a header a client can forge. A browser request that changes something, or opens a WebSocket, from another web site is refused. Suricata's logs rotate daily.
• Fully patched Ubuntu 24.04 LTS at build time, with unattended security upgrades switched on.

What is on the image: EveBox 0.26.0 (/usr/bin/evebox), Suricata 8.0.7 with suricata-update, the Emerging Threats Open ruleset, nginx, Ubuntu 24.04 LTS, cloud-init and the AWS Systems Manager agent. EveBox's database is a local SQLite file, so there is no database port.

Default user: ubuntu · Architecture: x86_64 · Recommended instance type: m5.large

Prerequisites

• An AWS account subscribed to the listing, an EC2 key pair and a VPC subnet with a route to the internet (or a private route you use for management).
• A security group that allows TCP 443 (the EveBox console) and TCP 80 (redirects to HTTPS) from the analysts who will use it, and TCP 22 (SSH) from your own networks only.

Step 1: Launch the instance

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick EveBox 0.26.0 on Ubuntu 24.04 as the software version and your Region, then Launch through EC2. Choose m5.large, your key pair and a security group as above.

Suricata keeps seven days of compressed EVE logs and EveBox keeps its own event database, both on the root volume, so give the root volume room for your traffic (for example 50 GiB instead of the default 8 GiB). The root file system grows to fill the volume on first boot.

With the AWS CLI (replace the values in angle brackets):

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --block-device-mappings 'DeviceName=/dev/sda1,Ebs={VolumeSize=50,VolumeType=gp3}' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=evebox}]'

Step 2: Connect to your instance

ssh -i <your-key.pem> ubuntu@<public-ip>

Step 3: Check the services

The first boot takes a few seconds. Then Suricata, EveBox, nginx and the first boot unit are active:

systemctl is-active suricata evebox nginx evebox-firstboot

active
active
active
active

nginx is the only web listener; EveBox listens on 127.0.0.1 only, and Suricata opens no port at all (it reads packets from the network interface):

sudo ss -tlnp | awk 'NR==1 || /nginx|sshd|evebox/' | awk '{print $1, $4, $6}' | sed -E 's/,pid=[0-9]+,fd=[0-9]+//g'

State Local Peer
LISTEN 0.0.0.0:22 users:(("sshd"),("systemd"))
LISTEN 0.0.0.0:80 users:(("nginx"),("nginx"),("nginx"))
LISTEN 0.0.0.0:443 users:(("nginx"),("nginx"),("nginx"))
LISTEN 127.0.0.1:5636 users:(("evebox"))
LISTEN [::]:22 users:(("sshd"),("systemd"))
LISTEN [::]:80 users:(("nginx"),("nginx"),("nginx"))
LISTEN [::]:443 users:(("nginx"),("nginx"),("nginx"))

The versions:

evebox --version; suricata -V

EveBox 0.26.0
This is Suricata version 8.0.7 RELEASE

Step 4: Get your URL and password

The first boot wrote the console address (your instance's public IP address by default), the user name and the password generated on this instance to /root/evebox-info.txt. Show everything but the password:

sudo sed -E 's/^(evebox_password=).*/\1<hidden: run sudo cat to see it>/' /root/evebox-info.txt

# EveBox 0.26.0 + Suricata 8.0.7 - generated on first boot by evebox-firstboot.service.
# Unique to this instance (not baked into the image); keep it safe.
evebox_url=https://<public-ip>/
evebox_username=admin
evebox_password=<hidden: run sudo cat to see it>

# Suricata monitors ens5 and writes /var/log/suricata/eve.json; EveBox indexes it into /var/lib/evebox.
# Prove the whole pipeline:  ping -c 3 -p 636c6f7564696d67 $(ip -o -4 route show to default | awk '{print $3}')
#   then look for "cloudimg EveBox pipeline self-test" in the EveBox Alerts view.
# Change the password:       sudo evebox-set-admin-password            (prompts)
# Change the host name:      sudo evebox-set-host <dns-name>
# Refresh the ET Open rules: sudo suricata-update && sudo systemctl reload suricata

Then read the password itself:

sudo cat /root/evebox-info.txt

Step 5: Sign in

Open https://<public-ip>/ in your browser. The certificate is generated on your instance and is not signed by a public authority, so the browser warns once; accept it (or install your own certificate, Step 10). Sign in as admin with the password from Step 4.

The Inbox lists the alerts nobody has archived yet, grouped by signature, source and destination, with the number of occurrences of each group. Archive clears a group from the inbox, the star escalates it, and the drop down offers more actions.

Step 6: Prove the pipeline end to end

The image carries a self-test rule (signature ID 9000001) that fires only on ICMP packets carrying the text cloudimg, so it never triggers on ordinary traffic. Send three such pings to the subnet's gateway (a reply is not needed; the packets only have to leave through the monitored interface):

ping -c 3 -W 1 -p 636c6f7564696d67 "$(ip -o -4 route show to default | awk '{print $3}')" >/dev/null 2>&1; sleep 3
sudo tail -n 500 /var/log/suricata/eve.json | grep 'pipeline self-test' | tail -1 | python3 -c 'import json,sys; e=json.loads(sys.stdin.read()); print(e["event_type"], e["proto"], e["alert"]["signature_id"], e["alert"]["signature"])'

alert ICMP 9000001 cloudimg EveBox pipeline self-test

Within a few seconds the alert is in EveBox too. Click it to see the event detail with the flow it belongs to:

The Events view searches everything Suricata records, not only alerts: flows, DNS, TLS, HTTP, SSH and more. Pick an Event Type to narrow it down, or type a query such as src_ip:10.0.1.20 or dns.rrname:example.com in the search box.

Step 7: Watch more than this instance

Suricata watches the instance's own network interface (ens5), so out of the box it sees the traffic to and from this instance. To inspect other workloads, send their traffic to it with VPC Traffic Mirroring: create a mirror target for this instance's network interface, a filter for the traffic you want, and a mirror session on each source interface. Mirrored packets arrive VXLAN encapsulated on UDP port 4789, which Suricata decodes by default; allow UDP 4789 from the mirror sources in this instance's security group. With the AWS CLI:

aws ec2 create-traffic-mirror-target --network-interface-id <this-instance-eni>
aws ec2 create-traffic-mirror-filter --description "to EveBox"
aws ec2 create-traffic-mirror-filter-rule --traffic-mirror-filter-id <filter-id> --traffic-direction ingress \
  --rule-number 100 --rule-action accept --destination-cidr-block 0.0.0.0/0 --source-cidr-block 0.0.0.0/0
aws ec2 create-traffic-mirror-session --network-interface-id <source-eni> --traffic-mirror-target-id <target-id> \
  --traffic-mirror-filter-id <filter-id> --session-number 1

Size the instance for the mirrored traffic (Suricata uses one capture thread per vCPU).

Step 8: Rules and logs

The Emerging Threats Open ruleset is in /var/lib/suricata/rules/suricata.rules:

sudo grep -cE '^\s*(alert|drop)' /var/lib/suricata/rules/suricata.rules

53215

Refresh it whenever you like (or from a systemd timer of your own), then have Suricata reload the rules without a restart:

sudo suricata-update && sudo systemctl reload suricata

Suricata writes /var/log/suricata/eve.json (and fast.log, stats.log, suricata.log). The directory is readable by the suricata group only (EveBox reads it as a member of that group). /etc/logrotate.d/cloudimg-suricata rotates the logs daily, keeps seven compressed days and tells Suricata to reopen its files; EveBox follows the new file. EveBox ages old events out of its own database.

Step 9: Check the security model

Every EveBox API route except the version and the login answers 401 without a session; the unauthenticated event submission endpoint is refused by nginx; a host name the instance does not serve gets no answer; plain HTTP redirects to HTTPS:

H=$(sed -nE 's/^set \$evebox_host "([^"]+)";$/\1/p' /etc/nginx/evebox-host.conf)
curl -ks -o /dev/null -w 'api/alerts without a session: %{http_code}\n' --resolve "$H:443:127.0.0.1" "https://$H/api/alerts"
curl -ks -o /dev/null -w 'api/submit: %{http_code}\n' --resolve "$H:443:127.0.0.1" -X POST --data '{}' "https://$H/api/submit"
curl -ks -o /dev/null -w 'unknown Host: %{http_code}\n' --resolve "evil.example:443:127.0.0.1" https://evil.example/ ; echo "(000 = connection closed with no response)"
curl -s -o /dev/null -w 'http -> %{http_code} %{redirect_url}\n' --resolve "$H:80:127.0.0.1" "http://$H/"

api/alerts without a session: 401
api/submit: 403
unknown Host: 000
(000 = connection closed with no response)
http -> 301 https://<public-ip>/

Suricata, EveBox and nginx cannot reach the instance metadata service (and the AMI only answers IMDSv2 requests):

for u in suricata evebox nginx; do printf '%s: %s\n' $u "$(systemctl show -p IPAddressDeny --value $u.service)"; done

suricata: 168.63.129.16/32 169.254.169.254/32 fd00:ec2::254/128
evebox: 168.63.129.16/32 169.254.169.254/32 fd00:ec2::254/128
nginx: 168.63.129.16/32 169.254.169.254/32 fd00:ec2::254/128

The whole check at once, as the image's own self-test runs it (sign in with the instance password, read the alerts, submission refused, loopback only, a self-test alert indexed):

sudo /usr/local/sbin/evebox-selftest

OK: login 401/401/200, session reads alerts, /api/submit 403, evebox on 127.0.0.1:5636 only, self-test alert indexed

Step 10: Your own DNS name and certificate

Point a DNS name at the instance (an Elastic IP keeps the address stable), then make it the name EveBox is served under. This regenerates the instance certificate for that name and updates nginx and /root/evebox-info.txt:

sudo evebox-set-host evebox.example.com

To use a certificate from your own authority instead, replace /etc/nginx/ssl/evebox.crt and /etc/nginx/ssl/evebox.key (keep the key 0600 root:root) and run sudo systemctl reload nginx. For a public name you can also put the instance behind an Application Load Balancer with an AWS Certificate Manager certificate, forwarding to HTTPS port 443.

Step 11: Change the password

sudo evebox-set-admin-password

It prompts twice, stores the new password through EveBox's own tool (never on a command line), updates /root/evebox-info.txt and restarts EveBox. Add more analysts with sudo -u evebox evebox config users add --username <name> --data-directory /var/lib/evebox (it prompts for the password).

Step 12: Server components

Step 13: Security recommendations

• Restrict TCP 443 and TCP 80 to your analysts' networks and TCP 22 to your administration networks.
• Keep the instance patched (unattended upgrades are on; reboot when /var/run/reboot-required appears) and refresh the rules regularly.
• Change the administrator password if it has been shared, and give each analyst their own EveBox user.
• Use your own DNS name and certificate for production.
• Mirror only the traffic you need to inspect, and size the instance and its volume for it.

Support and licensing

cloudimg provides support for this image by email at support@cloudimg.co.uk. EveBox is licensed under the MIT licence and Suricata under the GNU General Public License version 2; both licence texts are on the image in /usr/share/doc/cloudimg/licenses/. The Emerging Threats Open ruleset is published by Proofpoint under its own open licence. EveBox, Suricata and Emerging Threats are the names of their respective projects; this image is packaged by cloudimg and is not affiliated with or endorsed by them.