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 a configured server-local spool or a connected PCAP-capable EveBox Agent.

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.
`source`	Optional source name: `(server)` or a connected agent. Event requests normally route automatically.

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. Successful responses include X-EveBox-PCAP-Source with the source that served the request.

GET /api/pcap/sources lists the sources currently available to the source parameter:

{
  "sources": [
    {"name": "(server)", "kind": "server"},
    {"name": "firewall-east", "kind": "agent"}
  ]
}

/api/filestore

New in EveBox 0.30.0

This endpoint is only available in EveBox 0.30.0 and newer.

Downloads a file extracted by Suricata's file-store (version 2) output from a configured server-local file store or a connected filestore-capable EveBox Agent. See Extracted Files.

Method: GET

Parameter	Description
`event_id`	EveBox datastore ID of a `fileinfo` event or an alert with `files`.
`sha256`	SHA-256 of the file. With `event_id`, it must be a file the event references, and may be omitted when the event references only one.
`source`	Optional source name: `(server)` or a connected agent. Requests normally route automatically.

At least one of event_id or sha256 is required. A sha256 without an event downloads the file by digest alone.

curl --fail --get 'http://localhost:5636/api/filestore' \
  --data-urlencode 'sha256=<sha256>' \
  --data-urlencode 'source=(server)' \
  --output extracted.bin

Files are returned as application/octet-stream attachments named by their SHA-256 digest. Successful responses include X-EveBox-File-Source with the source that served the request.

Errors are returned as JSON with an error code and message. When an event references several files and no sha256 is given, the response is 409 Conflict with code ambiguous-file and the digests to choose from in candidates. A file that is not in the file store returns 404 Not Found with code file-not-found.

GET /api/filestore/validate accepts the same parameters and performs the same event lookup, file selection and routing without downloading. For the server-local store it also checks that the file exists and returns its size. For a remote agent, validation does not check whether the file exists; a preview or download can still fail with a missing-file error.

GET /api/filestore/sources lists the sources currently available to the source parameter, in the same format as /api/pcap/sources.

/api/filestore/preview

Method: GET (EveBox 0.30.0 and newer)

Accepts the same event_id, sha256, and source parameters as the full download endpoint, with the same file selection and routing. Returns at most the first 65,536 bytes (64 KiB) of the file. The cap is fixed; there are no offset, length, or range options.

Successful responses contain raw bytes, not JSON, with these headers:

Header	Description
`Content-Type`	`application/octet-stream`
`Content-Length`	Number of bytes in the returned prefix.
`X-EveBox-File-Size`	Size of the complete file in bytes.
`X-EveBox-File-Source`	Source that served the request.
`X-Content-Type-Options`	`nosniff`
`Content-Security-Policy`	`sandbox`
`Cache-Control`	`no-store`

Unlike a full download, the preview has no Content-Disposition header. The web interface fetches these bytes and displays derived information, hex, decoded text, and strings rather than rendering the file itself. Errors use the same JSON error object as the full download endpoint.

Remote previews and downloads share a limit of 16 concurrent file jobs across all agents. Each agent has separate single-request slots for preview and download. A busy source returns 429 Too Many Requests with code source-busy; local file requests bypass these limits.

/api/agents

Returns the currently connected EveBox Agents and their advertised capabilities. The server-local PCAP spool is not an agent and is not included here; use /api/pcap/sources for the complete PCAP source list.

Method: GET

[
  {
    "name": "firewall-east",
    "hostname": "sensor01",
    "version": "0.27.0-dev",
    "capabilities": ["pcap"],
    "connected_at": "2026-07-15T18:00:00Z",
    "last_seen": "2026-07-15T18:01:00Z",
    "rtt_ms": 2
  }
]

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

/api/pcap​

/api/filestore​

/api/filestore/preview​

/api/agents​

/api/sensors​

/api/alerts​

/api/events​

/api/agg​

/api/pcap

/api/filestore

/api/filestore/preview

/api/agents

/api/sensors

/api/alerts

/api/events

/api/agg