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/pcap

Downloads packets from the configured server-local capture spool.

Methods: GET, POST

GET accepts query parameters and streams the capture. POST accepts the same fields as JSON, buffers the result, and cannot exceed the fixed 8,000,000-byte server limit. All request fields are strings.

Parameter	Description
event_id	EveBox datastore ID used to derive the event flow and time window.
filter	Optional libpcap BPF expression.
start	RFC 3339 start time for a free-form request.
duration	Window after start; defaults to 1m.
before	Window before an event timestamp. Requires event_id.
after	Window after an event timestamp. Requires event_id.
max_size	Output cap such as 50mb; 0, none, or unlimited removes the cap for streaming GET requests.

Use event_id by itself for an event capture, event_id with before or after for an event-relative window, or start with optional duration and filter for a free-form capture.

curl --fail --get 'http://localhost:5636/api/pcap' \
  --data-urlencode 'start=2026-07-13T12:00:00Z' \
  --data-urlencode 'duration=5m' \
  --data-urlencode 'filter=tcp port 443' \
  --output capture.pcap

GET /api/pcap/validate accepts the same query parameters and validates the request without reading capture files. It returns ok and the suggested download filename, but does not check whether packets match.

POST returns a structured error when no packets match and sets X-EveBox-PCAP-Truncated: true when its buffered result reaches a size or scan limit. A streaming GET with no matching or available packets instead returns a valid, header-only capture. If a GET reaches a limit after its response headers have been sent, the partial capture cannot be marked with a late truncation header.

/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. With no size or order, the endpoint returns up to 500 events, newest first.

Method: GET

Parameters:

Parameter	Description	Default	Example
event_type	Exact event type to return.	all types	event_type=alert
sensor	Exact sensor name to return.	all sensors	sensor=my-sensor
query_string	Additional field:value filters. The sensor field is host.	none	query_string=src_ip:192.168.1.1
from	Inclusive ISO 8601 start timestamp.	unbounded	from=2025-12-28T00:00:00Z
to	Inclusive ISO 8601 end timestamp.	unbounded	to=2025-12-29T00:00:00Z
size	Positive number of events to return.	500	size=100
order	Timestamp order: asc or desc.	desc	order=asc
sort_by	Elastic/OpenSearch field to sort by; ignored with SQLite.	@timestamp	sort_by=@timestamp

Examples:

# Get up to 500 recent alerts from a specific sensor.
curl "http://localhost:5636/api/events?event_type=alert&sensor=my-sensor"

# The equivalent sensor filter using the query string.
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"

If authentication is required, add -u username:password to the curl command or use an authenticated EveBox session.

/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}
  ]
}