EveBox Suricata Alert Console on AWS User Guide

Overview

This image runs EveBox 0.26.0, a web based event viewer and alert triage console for Suricata, together with Suricata 7.0.3, the open source intrusion detection engine that produces the alerts.

EveBox on its own is a viewer over an event stream it does not produce, so this image ships the complete appliance. Suricata captures traffic on the instance's primary network interface, matches it against the Emerging Threats open ruleset, and writes alerts along with flow, DNS, TLS and HTTP metadata to /var/log/suricata/eve.json. EveBox indexes that stream into a local SQLite datastore, so there is no Elasticsearch cluster to run, and presents it as a searchable analyst inbox in the browser.

The cloudimg image is secure by default. EveBox runs bound only to the loopback interface and is fronted by nginx on port 80 using HTTP Basic authentication. The password is a unique value generated on first boot for each instance and written to a root only file. No credential is baked into the image, and no two deployments share one. Because EveBox is bound to loopback, that authentication cannot be bypassed by reaching the application port directly.

What is included:

• EveBox 0.26.0 installed from the official upstream release, running as a dedicated non root evebox service bound to 127.0.0.1:5636
• Suricata 7.0.3 configured for af-packet capture on the instance's primary interface, with the Emerging Threats open ruleset loaded at build time
• A self contained SQLite datastore at /var/lib/evebox with no external search cluster required
• nginx on port 80 reverse proxying the console and its JSON API with HTTP Basic authentication, plus an unauthenticated /healthz endpoint for load balancer probes
• A one shot evebox-firstboot.service that pins the capture interface to this instance's NIC, generates a per instance password on first boot and writes it to /root/evebox-info.txt (mode 0600)
• A shipped pipeline self test signature so you can prove the whole capture, index and display chain with one command
• A fully patched Ubuntu 24.04 LTS base with unattended security upgrades enabled
• 24/7 cloudimg support

EveBox is published by the EveBox project under the MIT licence, and Suricata is published by the Open Information Security Foundation under the GPL 2.0 licence. This image is packaged by cloudimg and is not affiliated with or endorsed by the EveBox or Suricata projects.

Prerequisites

An active AWS account, an EC2 key pair in the target region, and a VPC with a subnet. m5.large (2 vCPU / 8 GiB RAM) is a sensible starting size; increase CPU and memory for busier links or a larger ruleset. Security group inbound: allow 22/tcp from your management network and 80/tcp for the console. EveBox serves plain HTTP on port 80; for production or shared access, terminate TLS in front of it with your own domain using a reverse proxy, an Application Load Balancer or Amazon CloudFront.

A note on what this sensor sees: Suricata inspects traffic arriving at this instance's own network interface. That makes it an excellent host based sensor and a working monitoring point for anything routed through it. To inspect traffic for other machines, route or mirror that traffic through this instance, for example with a VPC traffic mirror session or by making it a NAT or gateway hop.

Connecting to your instance

Connect over SSH on port 22 as the default login user for the AMI variant you launched:

Step 1 - Subscribe from AWS Marketplace

Sign in to the AWS Marketplace, search for EveBox by cloudimg, and choose Continue to Subscribe, then Continue to Configuration. Pick the software version and your region, then Continue to Launch. Launch through EC2, choosing your instance type, VPC and subnet, your key pair, and a security group that allows inbound 22 and 80.

Step 2 - Launch from the AWS CLI

aws ec2 run-instances \
  --image-id <evebox-ami-id> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <sg-allowing-22-and-80> \
  --subnet-id <your-subnet> \
  --associate-public-ip-address \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=evebox}]'

Find the AMI id for your region on the product's Launch page in AWS Marketplace.

Step 3 - Connect to your instance

ssh ubuntu@<instance-public-ip>

Step 4 - Confirm the services are running

The appliance is three cooperating units: suricata.service captures and detects, evebox.service indexes and serves the console on the loopback interface, and nginx.service fronts it on port 80. A one shot evebox-firstboot.service runs once on first boot to pin the capture interface and generate the per instance password. Confirm all four are active:

systemctl is-active suricata evebox nginx evebox-firstboot

active
active
active
active

Then confirm that nginx is listening on port 80 while EveBox stays private on 127.0.0.1:5636:

ss -tlnp | grep -E ':80 |:5636 '

LISTEN 0  128    127.0.0.1:5636   0.0.0.0:*  users:(("evebox",pid=4032,fd=61))
LISTEN 0  511      0.0.0.0:80      0.0.0.0:*  users:(("nginx",pid=4082,fd=5),...)

This is the security check that matters: EveBox must appear only on 127.0.0.1:5636. If it were bound to 0.0.0.0, the console would be reachable without passing through nginx authentication.

Step 5 - Retrieve your per instance credentials

The first boot service writes the console URL, username and generated password to /root/evebox-info.txt, readable only by root:

sudo cat /root/evebox-info.txt

evebox_url=http://<instance-public-ip>/
evebox_username=evebox
evebox_password=****************************

The file also records where Suricata is writing events, how to refresh the ruleset, and how to rotate the password. Copy the password somewhere safe, such as a password manager. To change it later:

sudo htpasswd -B /etc/nginx/evebox.htpasswd evebox

Step 6 - Confirm the console is secure by default

Without credentials, nginx refuses the request. With the per instance password, the same endpoint returns the EveBox version:

curl -s -o /dev/null -w 'HTTP %{http_code} (authentication required)\n' http://127.0.0.1/api/version

HTTP 401 (authentication required)

curl -s -u evebox:<evebox-password> http://127.0.0.1/api/version | python3 -m json.tool

{
    "revision": "70e9fc5a",
    "version": "0.26.0"
}

The unauthenticated /healthz endpoint stays open so a load balancer can probe the instance without credentials:

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1/healthz

HTTP 200

Step 7 - Prove the detection pipeline end to end

The image ships a narrow self test signature, sid 9000001, that matches only ICMP carrying the ASCII marker cloudimg. It fires only when you send the probe deliberately, so it adds no noise to ordinary traffic, and it proves every link in the chain at once: the wire, Suricata, eve.json, the SQLite index, and the authenticated web API.

First confirm the Emerging Threats ruleset is loaded:

grep -cE '^[[:space:]]*(alert|drop|reject|pass)[[:space:]]' /var/lib/suricata/rules/suricata.rules

52051

Now send the probe at your default gateway and confirm Suricata wrote the alert. The gateway does not need to reply; the probe only has to leave the monitored interface:

GW=$(ip -o -4 route show to default | awk '{print $3}' | head -1); ping -c 3 -W 1 -p 636c6f7564696d67 "$GW" >/dev/null 2>&1; for i in $(seq 1 10); do grep -q '"signature":"cloudimg EveBox pipeline self-test"' /var/log/suricata/eve.json && break; sleep 2; done; grep -m1 -o '"signature":"cloudimg EveBox pipeline self-test"' /var/log/suricata/eve.json

"signature":"cloudimg EveBox pipeline self-test"

Finally, confirm EveBox has indexed it and will serve it through the authenticated API:

curl -s -u evebox:<evebox-password> http://127.0.0.1/api/alerts | python3 -c "import sys,json;d=json.load(sys.stdin);print(json.dumps(sorted(set(e['_source']['alert']['signature'] for e in d.get('events',[]))), indent=2))"

[
  "ET DROP Dshield Block Listed Source group 1",
  "GPL ATTACK_RESPONSE id check returned root",
  "SURICATA Applayer Mismatch protocol both directions",
  "SURICATA STREAM Packet with invalid timestamp",
  "cloudimg EveBox pipeline self-test"
]

The self test signature appears alongside any real signatures Suricata has already matched against live traffic reaching the instance.

Step 8 - Sign in to the EveBox console

Open http://<instance-public-ip>/ in a browser. Sign in with the username evebox and the password from Step 5. EveBox opens on the Inbox, its main triage view: every alert Suricata has raised, newest first, grouped by signature with a count, the source and destination addresses, and the time.

From here you can Archive an alert you have dealt with, Escalate one that needs follow up (escalated alerts get their own view), or use the search box to filter by signature, address or any field in the event.

Step 9 - Investigate an alert

Click any alert to open the full record behind it. EveBox shows the timestamp, protocol, source and destination with ports, the capture interface and flow ID, alongside the signature, its category, severity and signature ID. Where Suricata captured related context, such as DNS hostnames, HTTP transactions or extracted files, it appears in the tabs at the bottom, so you can see not just that something matched but what the traffic actually was.

Use Escalate to flag an alert for follow up, Archive to clear it once handled, and Add Comment to leave a note for whoever picks it up next.

Step 10 - Browse the raw event stream

The Events view shows everything Suricata is writing, not only alerts. Flow records, HTTP transactions, DNS queries, TLS handshakes and file metadata all appear here, and the Event Type filter narrows to one kind. This is where you go to understand normal traffic on the instance, or to find the surrounding context for an alert you are investigating. The Alerts view is the complementary one: every alert regardless of inbox state, grouped by signature, which is the quickest way to see what is matching most often.

Keeping the ruleset current

The image ships the Emerging Threats open ruleset as it stood when the image was built. New signatures are published continually, so refresh it regularly:

sudo suricata-update
sudo systemctl restart suricata

To automate it, add a weekly systemd timer or cron entry that runs those two commands. You can also add other rule sources with sudo suricata-update enable-source <name>; list what is available with sudo suricata-update list-sources.

Your own local rules can go in /var/lib/suricata/rules/, added to the rule-files list in /etc/suricata/suricata.yaml. The shipped self test rule at /var/lib/suricata/rules/cloudimg-selftest.rules is a working example of the format.

Where the data lives

Suricata writes its event stream to /var/log/suricata/eve.json and EveBox indexes it into /var/lib/evebox. Both grow with traffic volume, so on a busy sensor watch disk usage and consider attaching a larger EBS volume. Suricata's own logrotate configuration manages eve.json; EveBox applies its own retention to the indexed events.

To confirm both sides are healthy at any time:

systemctl is-active suricata evebox && ls -lh /var/log/suricata/eve.json

active
active
-rw-r--r-- 1 root root 952K Jul 25 04:44 /var/log/suricata/eve.json

Enabling HTTPS for production

The console is served over plain HTTP on port 80. For anything beyond a trusted network, put TLS in front of it: point a DNS name at the instance and terminate TLS with an Application Load Balancer or Amazon CloudFront, or install a certificate directly in the nginx site at /etc/nginx/sites-available/cloudimg-evebox. Keep the Basic authentication in place; TLS protects the credentials in transit, it does not replace them.

Support

cloudimg provides 24/7 support for this image. Contact support@cloudimg.co.uk.