EveBox

https://evebox.org/docs
Admin
EveBox is an open-source tool for viewing and analyzing Suricata Eve JSON events, providing a web...
Tokens:8,322
Snippets:119
Trust Score:7.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install EveBox on Linux using Zip

Source: https://evebox.org/docs/install/zip

Download the zip package using curl, extract it with unzip, navigate into the extracted directory, and start the EveBox server. Use the --help flag to see available server options.

```bash
curl -OL https://evebox.org/files/release/latest/evebox-0.26.0-linux-x64.zip
unzip evebox-0.26.0-linux-x64.zip
cd evebox-0.26.0-linux-x64
./evebox server --help
```

--------------------------------

### Start EveBox Server with Systemd

Source: https://evebox.org/docs/install/rpm

Starts the EveBox server service using systemd.

```bash
systemctl start evebox
```

--------------------------------

### Add Stable Repository and Install EveBox

Source: https://evebox.org/docs/install/debian

Installs the stable version of EveBox by adding the official APT repository. Ensure curl is installed first.

```bash
sudo apt-get install curl
```

```bash
curl -fsSL https://evebox.org/files/evebox.asc -o /etc/apt/keyrings/evebox.asc
```

```bash
echo "deb [signed-by=/etc/apt/keyrings/evebox.asc] https://evebox.org/files/debian stable main" | sudo tee /etc/apt/sources.list.d/evebox.list
```

```bash
sudo apt-get update
```

```bash
sudo apt-get install evebox
```

--------------------------------

### EveBox Server Login Credentials Example

Source: https://evebox.org/docs/server

If this is your first time starting EveBox, you will need to note the auto-generated administrator username and password to log in to the web interface.

```text
2023-09-04 16:38:33  WARN evebox::server::main: Created administrator username and password: username=admin, password=7lCBEu74kQUQ  
```

--------------------------------

### Install Stable EveBox RPM Repository

Source: https://evebox.org/docs/install/rpm

Installs the stable release repository for EveBox. Use this for production environments.

```bash
rpm -Uvh https://evebox.org/files/rpm/stable/evebox-release.noarch.rpm

yum install evebox
```

--------------------------------

### Enable EveBox Server on Boot with Systemd

Source: https://evebox.org/docs/install/rpm

Configures the EveBox server service to start automatically on system boot using systemd.

```bash
systemctl enable evebox
```

--------------------------------

### Add Development Repository and Install EveBox

Source: https://evebox.org/docs/install/debian

Installs a development build of EveBox from the unstable branch. Use with caution as these builds may be unstable.

```bash
sudo apt-get install curl
```

```bash
curl -fsSL https://evebox.org/files/evebox.asc -o /etc/apt/keyrings/evebox.asc
```

```bash
echo "deb [signed-by=/etc/apt/keyrings/evebox.asc] https://evebox.org/files/debian unstable main" | sudo tee /etc/apt/sources.list.d/evebox.list
```

```bash
sudo apt-get update
```

```bash
sudo apt-get install evebox
```

--------------------------------

### EveBox Agent YAML Configuration Example

Source: https://evebox.org/docs/agent/configuration

A comprehensive example of an EveBox Agent configuration file in YAML format. It includes settings for server connection, Elasticsearch output, data directory, and input log paths.

```yaml
# EveBox Agent configuration file - subject to change.  

# Server information.  
server:
  url: http://127.0.0.1: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  
  
# Enable output to Elasticsearch. If enabled, the above server section  
# will not be used.  
elasticsearch:
  enabled: true
  url: http://127.0.0.1:9200
  index: logstash
  
  # Set to true if the index is a datastream.  
  #nodate: false  
  
  #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 Suricata Eve log files.  
input:
  paths:
    - "/var/log/suricata/eve.json"
    - "/var/log/suricata/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  

```

--------------------------------

### Configure EveBox with Systemd (SQLite)

Source: https://evebox.org/docs/install/rpm

Sets command-line options for the EveBox server by creating or modifying the /etc/sysconfig/evebox file. This example configures EveBox to use SQLite as the database.

```bash
EVEBOX_OPTS="--database sqlite"
```

--------------------------------

### Install Development EveBox RPM Repository

Source: https://evebox.org/docs/install/rpm

Installs the development build repository for EveBox. These packages are built from the main git branch and may be unstable.

```bash
rpm -Uvh https://evebox.org/files/rpm/development/evebox-development-release.noarch.rpm

yum install evebox
```

--------------------------------

### Configure EveBox with Systemd (SQLite and Suricata Logs)

Source: https://evebox.org/docs/install/rpm

Sets command-line options for the EveBox server by creating or modifying the /etc/sysconfig/evebox file. This example configures EveBox to use SQLite and consume Suricata log files.

```bash
EVEBOX_OPTS="--database sqlite /var/log/suricata/eve.json"
```

--------------------------------

### Configure EveBox with Systemd (Suricata Logs)

Source: https://evebox.org/docs/install/rpm

Sets command-line options for the EveBox server by creating or modifying the /etc/sysconfig/evebox file. This example configures EveBox to consume Suricata log files directly.

```bash
EVEBOX_OPTS="/var/log/suricata/eve.json"
```

--------------------------------

### Example Docker Compose for EveBox

Source: https://evebox.org/docs/install/docker

This configuration sets up EveBox using the latest Docker image, configures port mapping, and ensures the container restarts automatically.

```yaml
version: "3"  

services:
  evebox:
    image: jasonish/evebox:latest
    restart: unless-stopped
    ports:
      - "5636:5636"
    command: evebox server  

```

--------------------------------

### Get All Sensor Names

Source: https://evebox.org/docs/api

Retrieves a list of all sensor names configured in EveBox. This endpoint requires no parameters.

```bash
curl "http://localhost:5636/api/sensors"
```

--------------------------------

### Standalone EveBox Server with SQLite

Source: https://evebox.org/docs/server

This is a basic setup for running the EveBox Server using SQLite as the database and reading EVE records directly from a specified JSON log file. It's the simplest configuration, requiring no external database or event transport.

```bash
evebox server --sqlite /var/log/suricata/eve.json  
```

--------------------------------

### Get All Sensor Names

Source: https://evebox.org/docs/api

Retrieves a list of all sensor names present in the data. This endpoint is useful for understanding the sources of your data.

```APIDOC
## GET /api/sensors

### Description
Returns a list of all sensor names in your data.

### Method
GET

### Endpoint
/api/sensors

### Response
#### Success Response (200)
- **data** (array) - An array of strings, where each string is a sensor name.

### Response Example
```json
{
  "data": ["sensor-1", "sensor-2", "sensor-3"]
}
```
```

--------------------------------

### Get Last 50 Alert Events

Source: https://evebox.org/docs/api

Retrieves the most recent 50 alert events. Use `event_type=alert`, `size=50`, and `order=desc`.

```bash
# Get the last 50 alerts
curl "http://localhost:5636/api/events?event_type=alert&size=50&order=desc"
```

--------------------------------

### Get Alert Events by Sensor

Source: https://evebox.org/docs/api

Fetches individual alert events filtered by a specific sensor. The `query_string` parameter uses `host` to specify the sensor.

```bash
# Get alert events from a specific sensor
curl "http://localhost:5636/api/events?event_type=alert&query_string=host:my-sensor"
```

--------------------------------

### Disable Authentication and TLS for Testing

Source: https://evebox.org/docs/server

To simplify testing and avoid the overhead of authentication and TLS, you can disable them using command-line options. This is useful for initial setup or development environments.

```bash
evebox server --no-auth --no-tls --sqlite /var/log/suricata/eve.json  
```

--------------------------------

### Get Top Source IPs

Source: https://evebox.org/docs/api

Aggregates and counts source IPs over the last 7 days, returning the top 20. Use `field=src_ip`, `time_range=7d`, and `size=20`.

```bash
# Get top 20 source IPs in the last 7 days
curl "http://localhost:5636/api/agg?field=src_ip&time_range=7d&size=20"
```

--------------------------------

### Get Top Event Types

Source: https://evebox.org/docs/api

Aggregates and counts event types within the last 24 hours. The `field` parameter is set to `event_type`.

```bash
# Get top 10 event types in the last 24 hours
curl "http://localhost:5636/api/agg?field=event_type"
```

--------------------------------

### Get Aggregated Field Counts

Source: https://evebox.org/docs/api

Groups events over a specified field and returns the counts for each unique value. Useful for generating statistics and summaries.

```APIDOC
## GET /api/agg

### Description
Groups events over a field and returns the counts for each value. Similar to an SQL query like: `SELECT COUNT(event_type), event_type FROM events GROUP BY event_type ORDER BY count DESC;`

### Method
GET

### Endpoint
/api/agg

### Parameters
#### Query Parameters
- **field** (string) - Required - Field name to group over. Example: `field=event_type`
- **time_range** (string) - Optional - Time range to search over. Default: `24h`. Example: `time_range=7d`
- **size** (integer) - Optional - Number of results to return. Default: `10`. Example: `size=20`
- **order** (string) - Optional - Sort order (`desc` or `asc`). Default: `desc`. Example: `order=asc`
- **q** (string) - Optional - Additional query string filter. Example: `q=src_ip:192.168.1.1`

### Response
#### Success Response (200)
- **rows** (array) - An array of objects, where each object contains a `key` (the value of the grouped field) and a `count` (the number of events for that key).

### Response Example
```json
{
  "rows": [
    {"key": "alert", "count": 1234},
    {"key": "dns", "count": 567},
    {"key": "http", "count": 89}
  ]
}
```
```

--------------------------------

### Get Alerts for a Specific Sensor

Source: https://evebox.org/docs/api

Retrieves aggregated alerts filtered by a specific sensor name and time range. Use the `sensor` and `time_range` parameters.

```bash
# Get alerts from a specific sensor
curl "http://localhost:5636/api/alerts?sensor=my-sensor&time_range=24h"
```

--------------------------------

### Get Individual Events

Source: https://evebox.org/docs/api

Retrieves individual events with optional filtering capabilities. Supports filtering by event type, query string, time range, and sorting.

```APIDOC
## GET /api/events

### Description
Returns individual events with optional filtering.

### Method
GET

### Endpoint
/api/events

### Parameters
#### Query Parameters
- **event_type** (string) - Optional - Filter by event type. Example: `event_type=alert`
- **query_string** (string) - Optional - Key:value filters (sensor uses `host` field). Example: `query_string=host:my-sensor`
- **from** (string) - Optional - Start timestamp (ISO 8601). Example: `from=2025-12-28T00:00:00Z`
- **to** (string) - Optional - End timestamp (ISO 8601). Example: `to=2025-12-29T00:00:00Z`
- **size** (integer) - Optional - Maximum number of results. Example: `size=100`
- **order** (string) - Optional - Sort order (`asc` or `desc`). Example: `order=desc`
- **sort_by** (string) - Optional - Field to sort by. Example: `sort_by=timestamp`

### Response
#### Success Response (200)
- The response will contain an array of event objects, with fields depending on the event type.

### Response Example
```json
// Example response structure will vary based on event type and filters applied.
// For alert events, it might include fields like signature, src_ip, dest_ip, etc.
```
```

--------------------------------

### Get Aggregated Alerts

Source: https://evebox.org/docs/api

Retrieves aggregated alerts, grouped by signature, source IP, and destination IP. Allows filtering by sensor, time range, query string, and tags.

```APIDOC
## GET /api/alerts

### Description
Returns aggregated alerts grouped by signature, source IP, and destination IP.

### Method
GET

### Endpoint
/api/alerts

### Parameters
#### Query Parameters
- **sensor** (string) - Optional - Filter by sensor name. Example: `sensor=my-sensor`
- **time_range** (string) - Optional - Time window to query. Example: `time_range=24h`, `time_range=7d`
- **query_string** (string) - Optional - Additional search filters. Example: `query_string=src_ip:192.168.1.1`
- **tags** (string) - Optional - Filter by tags (comma-separated). Example: `tags=evebox.escalated`

### Response
#### Success Response (200)
- **events** (array) - An array of alert events.
- **took** (integer) - The time in milliseconds the query took.
- **timed_out** (boolean) - Indicates if the query timed out.
- **min_timestamp** (string) - The minimum timestamp of the returned alerts in ISO 8601 format.
- **max_timestamp** (string) - The maximum timestamp of the returned alerts in ISO 8601 format.

### Response Example
```json
{
  "events": [...],
  "took": 42,
  "timed_out": false,
  "min_timestamp": "2025-12-28T00:00:00Z",
  "max_timestamp": "2025-12-29T00:00:00Z"
}
```
```

--------------------------------

### Get Alerts with Time Range Filter

Source: https://evebox.org/docs/api

Fetches aggregated alerts within a specified time range. The `time_range` parameter accepts values like `24h` or `7d`.

```bash
# Get alerts from the last 24 hours
curl "http://localhost:5636/api/alerts?time_range=24h"
```

--------------------------------

### Configure EveBox Server to use SQLite (Command Line)

Source: https://evebox.org/docs/server/sqlite

Use this command to configure the EveBox server to use SQLite. Specify the data directory and the --sqlite flag.

```bash
evebox server -D /path/to/data --sqlite
```

--------------------------------

### Specify Agent Configuration File

Source: https://evebox.org/docs/agent/configuration

Use the -c flag to specify the path to the agent's configuration file. This is necessary if not using the default location.

```bash
evebox agent -c /etc/evebox/agent.yaml
```

--------------------------------

### Configure EveBox Server via Configuration File

Source: https://evebox.org/docs/agent

Configure the EveBox Agent to send logs to an EveBox server using a configuration file. Specify the server URL and input paths.

```yaml
server:
  url: http://127.0.0.1:5636
input:
  paths:
    - "/var/log/suricata/eve.json"
```

--------------------------------

### Send Logs to EveBox Server via Command Line

Source: https://evebox.org/docs/agent

Use this command to send Suricata EVE logs to an EveBox server. Specify the server URL and the path to the EVE JSON log file.

```bash
evebox agent --server http://127.0.0.1:5636 \
    /var/log/suricata/eve.json
```

--------------------------------

### EveBox Server Startup with Auto-Generated Credentials

Source: https://evebox.org/docs/server

On first startup, EveBox generates a self-signed TLS certificate and creates an admin user with a random password. Monitor the server's standard output for these credentials.

```text
2023-09-03 18:32:20  WARN evebox::server::main: Created administrator username  

    and password: username=admin, password=eFWMpzQVoVED  
```

--------------------------------

### Run EveBox Server Processing Local Suricata Logs

Source: https://evebox.org/docs/server/elastic-stack

Use this command to have EveBox Server directly process a local Suricata eve.json file and send events to Elasticsearch.

```bash
evebox server -e http://elasticsearch:9200 --input /var/log/suricata/eve.json
```

--------------------------------

### Run EveBox in Oneshot Mode

Source: https://evebox.org/docs

Use this command to run EveBox directly against a local eve.json file for immediate inspection. EveBox will load the data into a temporary database that is destroyed upon closing.

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

--------------------------------

### Run EveBox Server with Elasticsearch (Filebeat)

Source: https://evebox.org/docs/server/elastic-stack

Connect EveBox to Elasticsearch using Filebeat with the Suricata module, specifying the ECS compatibility and index name.

```bash
evebox server -e http://elasticsearch:9200 --ecs --index filebeat
```

--------------------------------

### Send Logs to Elasticsearch via Command Line

Source: https://evebox.org/docs/agent

Use this command to send Suricata EVE logs to Elasticsearch. Enable Elasticsearch output, specify the Elasticsearch URL, index name, and the EVE JSON log file path.

```bash
evebox agent --elasticsearch \
    --elasticsearch-url http://elasticsearch:9200 \
	--elasticsearch-index logstash \
	/var/log/suricata/eve.json
```

--------------------------------

### Run EveBox Server with Elasticsearch (Logstash)

Source: https://evebox.org/docs/server/elastic-stack

Use this command to connect EveBox to an Elasticsearch instance that is receiving Suricata events via Logstash with a default index prefix.

```bash
evebox server -e http://elasticsearch:9200
```

--------------------------------

### Configure Elasticsearch Output via Configuration File

Source: https://evebox.org/docs/agent

Configure the EveBox Agent to send logs to Elasticsearch using a configuration file. Enable Elasticsearch, specify the URL, and the index name.

```yaml
elasticsearch:
  enabled: true
  url: http://elasticsearch:9200
  index: logstash
```

--------------------------------

### Configure EveBox Server to use SQLite (Configuration File)

Source: https://evebox.org/docs/server/sqlite

Configure EveBox to use SQLite by setting the database type to 'sqlite' in the configuration file. Event retention can also be specified.

```yaml
data-directory: /var/lib/evebox

database:
  type: sqlite
  
  # Automatically delete events older than 7 days.
  retention:
    days: 7
```

--------------------------------

### Enable GeoIP Enrichment

Source: https://evebox.org/docs/agent

Enable GeoIP information for Suricata events by adding the --enable-geoip flag to the command line. Ensure GeoIP2 databases are available in specified locations.

```bash
--enable-geoip
```

--------------------------------

### EveBox Configuration for Direct Log Processing

Source: https://evebox.org/docs/server/elastic-stack

Configure EveBox Server to read Suricata logs from a specified file and send them to Elasticsearch.

```yaml
database:
  type: elasticsearch
  elasticsearch:
    url: http://elasticsearch:9200
input:
  filename: "/var/log/suricata/eve.json"
```

--------------------------------

### EveBox Command to Display Elasticsearch Information

Source: https://evebox.org/docs/server/elastic-stack

This command retrieves and displays information about the connected Elasticsearch server, including relevant indices.

```bash
evebox elastic info [OPTIONS]
```

--------------------------------

### Configure Rule Inclusion for Alerts

Source: https://evebox.org/docs/agent

Optionally include Suricata rule information in alert events by specifying rule file paths in the configuration. Avoid enabling if Suricata already logs the rule.

```yaml
# 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
```

--------------------------------

### EveBox Configuration for Elasticsearch (Filebeat)

Source: https://evebox.org/docs/server/elastic-stack

Configure EveBox to use an Elasticsearch index populated by Filebeat with the Suricata module, including ECS compatibility.

```yaml
database:
  type: elasticsearch
  elasticsearch:
    url: http://elasticsearch:9200
    index: filebeat
    ecs: true
```

--------------------------------

### Stop EveBox Server with Systemd

Source: https://evebox.org/docs/install/rpm

Stops the EveBox server service using systemd.

```bash
systemctl stop evebox
```

--------------------------------

### Convert EVE JSON to PCAP

Source: https://evebox.org/docs/utilities/eve2pcap

Converts a Suricata EVE JSON file to a PCAP file. Ensure the output file path is specified.

```bash
evebox util eve2pcap --output output.pcap /var/log/suricata/eve.json
```

--------------------------------

### Add EveBox User to Suricata Group

Source: https://evebox.org/docs/install/rpm

Grants the 'evebox' user read access to Suricata log files by adding it to the 'suricata' group. This is necessary if EveBox is configured to consume Suricata logs directly.

```bash
sudo usermod -a -G suricata evebox
```

--------------------------------

### EveBox Configuration for Elasticsearch (Logstash)

Source: https://evebox.org/docs/server/elastic-stack

This configuration file specifies the Elasticsearch URL for EveBox when using Logstash for event ingestion.

```yaml
database:
  type: elasticsearch
  elasticsearch:
    url: http://elasticsearch:9200
```

--------------------------------

### Configure Event Retention in EveBox SQLite

Source: https://evebox.org/docs/server/sqlite

Configure event retention by days or maximum database size in the EveBox configuration file. By default, events older than 7 days are deleted.

```yaml
# Database configuration. 
database:
  type: sqlite
  
  retention:
    # Only keep events for the past 7 days.
    # - SQLite only
    # - Default 7 days
    # - Set to 0 to disable
    days: 7
  
    # Maximum database size.
    # - SQLite only
    # - No default
    #size: "20 GB"
```

--------------------------------

### EveBox Command to Increase Elasticsearch Field Limit

Source: https://evebox.org/docs/server/elastic-stack

Use this command to increase the default field limit in Elasticsearch indices, which is typically 1000. This command defaults to setting the limit to 5000.

```bash
evebox elastic set-field-limit [OPTIONS]
```

--------------------------------

### Extract Payload to PCAP

Source: https://evebox.org/docs/utilities/eve2pcap

Extracts only the payload field from EVE JSON records instead of the full packet when creating the PCAP file. Requires specifying the output file.

```bash
evebox util eve2pcap --payload --output output.pcap /var/log/suricata/eve.json
```

--------------------------------

### Change Admin Password

Source: https://evebox.org/docs/server

You can change the administrator password to a custom value using the `evebox config users passwd` command.

```bash
evebox config users passwd admin  
```
Tokens:
Raw