API

No Stability Guarantees

The EveBox API is currently under active development and may change without notice. Endpoints, request parameters, and response formats are not subject to semantic versioning or backward compatibility guarantees.

/api/sensors

Returns a list of all sensor names in your data.

Method: GET

Example:

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

Response:

{
  "data": ["sensor-1", "sensor-2", "sensor-3"]
}

/api/alerts

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

Method: GET

Parameters:

Parameter	Description	Example
sensor	Filter by sensor name	sensor=my-sensor
time_range	Time window to query	time_range=24h, time_range=7d
query_string	Additional search filters	query_string=src_ip:192.168.1.1
tags	Filter by tags (comma-separated)	tags=evebox.escalated

Example:

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

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

Response:

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

/api/events

Returns individual events with optional filtering.

Method: GET

Parameters:

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

Example:

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

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

/api/agg

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

Parameters:

Parameter	Description	Default	Example
field	Field name to group over	(required)	field=event_type
time_range	Time range to search over	24h	time_range=7d
size	Number of results to return	10	size=20
order	Sort order (desc or asc)	desc	order=asc
q	Optional query string filter		q=src_ip:192.168.1.1

Example:

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

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

Response:

{
  "rows": [
    {"key": "alert", "count": 1234},
    {"key": "dns", "count": 567},
    {"key": "http", "count": 89}
  ]
}