1. Introduction #
Suri Oculus 3.0 introduces a fully updated and significantly expanded REST API.
The backend is implemented in C++17 using the Pistache framework and optimized for high-performance network analytics, Suricata management, IoC processing, and real-time event visualization.
This document provides a complete, structured overview of all routes available in version 3.0.
Routes are grouped by subsystem:
Events
Rules & Suricata Control
Threats / IoC
Statistics
Network Map
The API is stable, backward-compatible with earlier 2.x web clients, and ready for integration with automation tools, dashboards, and SIEM pipelines.
2. Server Architecture Overview #
The backend exposes all routes through a lightweight Pistache HTTP server:
The server can be started directly:
Or managed as a systemd service:
Internally, the server:
Uses
Pistache::Rest::Routerto register endpointsHandles CORS via dedicated
OPTIONShandlersRuns with a configurable worker thread pool (default: 2 threads)
Interacts with Redis for event storage, Suricata for rule/control operations, and local file storage for IoC rule sets
All responses are JSON unless otherwise noted.
3. Events API #
Namespace: Events
Purpose: event retrieval, filtering, time-series analytics, and real-time UI dashboards.
3.1 Core Event Retrieval #
| Method | Route | Description |
|---|---|---|
| GET | /events/:event_type | Get all events of a given type (alert, flow, dns, http, tls, ssh, ftp, …) |
| GET | /events/count/:event_type | Total number of events of given type |
| GET | /events/:event_type/:event_id | Retrieve event by internal ID |
| GET | /events/search/:flow_id | Find event by flow_id |
| DELETE | /events/delete/:event_type | Delete all events of this type |
| OPTIONS | /events/delete/:event_type | CORS preflight |
| GET | /events/find/:event_type | Advanced search via query parameters (IPs, ports, timestamps, etc.) |
| GET | /events/check/:event_type | Get events for last N hours (timeshift) |
| GET | /events/fast | Exposes contents of fast.log |
3.2 Aggregated Metrics (Events per Hour) #
Used by dashboards and charts:
| Method | Route | Metric |
|---|---|---|
| GET | /events/alertsbyhours | Alerts per hour |
| GET | /events/anomaliesbyhours | Anomalies per hour (AI module) |
| GET | /events/flowsbyhours | Flow events per hour |
| GET | /events/dnsbyhours | DNS events per hour |
| GET | /events/tlsbyhours | TLS events per hour |
| GET | /events/httpbyhours | HTTP events per hour |
| GET | /events/sshbyhours | SSH events per hour |
| GET | /events/ftpbyhours | FTP events per hour |
3.3 Alerts Analytics #
| Route | Description |
|---|---|
/events/alertsmap | Compact format for dashboards and visual maps |
/events/alertssignatures | Alerts aggregated by signature |
4. Rules & Suricata Management API #
Namespace: Rules
Purpose: full lifecycle of Suricata rules, rule validation, bulk editing, and process control.
4.1 Rule Retrieval #
| Method | Route | Description |
|---|---|---|
| GET | /rules | Get all rules |
| GET | /rules/:sid | Rule by SID |
| GET | /rules/action/:action | Filter by action (alert, drop, reject) |
| GET | /rules/status/:status | Filter by active/inactive |
| GET | /rules/protocol/:proto | Filter by protocol |
| GET | /rules/search | Multi-parameter search |
| GET | /rules/signature/:signature | Search rule by signature text |
| GET | /rules/duplicated/:sid | Detect duplicate SIDs |
4.2 Rule Modification #
All require CORS options:
| Method | Route | Purpose |
|---|---|---|
| POST | /rules/toggle/ | Enable/disable a rule |
| POST | /rules/add/ | Add rule |
| POST | /rules/validate/ | Validate rule syntax |
| POST | /rules/delete/ | Delete rule(s) |
| POST | /rules/update/ | Bulk update |
4.3 Additional Rules #
| Route | Description |
|---|---|
/rules/additional/status/ | Status of local additional rule file |
/rules/additional/update/ | Overwrite/update additional rule file |
4.4 Suricata Process Management #
| Method | Route | Description |
|---|---|---|
| GET | /suricata/start/ | Start Suricata |
| GET | /suricata/stop/ | Stop Suricata |
| GET | /suricata/reload/ | Reload Suricata configuration |
| GET | /rules/reload/blocking | Blocking rule reload |
| GET | /rules/reload/nonblocking | Non-blocking rule reload |
| GET | /suricata/update/ | Update rule files + reload |
4.5 Daemon Control #
| Route | Description |
|---|---|
/daemon/start/ | Start auxiliary backend daemon |
/daemon/stop/ | Stop daemon |
5. Threats / IoC API #
Namespace: Threats
Purpose: management of Indicators of Compromise and generation of IoC-based Suricata rules.
5.1 IoC Retrieval #
| Route | Description |
|---|---|
/ioc/ | Get all IoCs |
/ioc/download/ | Fetch fresh IoCs from external feed |
/ioc/filter/:n_days | IoCs for last n days |
/ioc/ioc_type/:ioc_type | Filter by type (IP, URL, domain) |
/ioc/ioc_id/:id | Get IoC by ID |
/ioc/ioc_status/:status | Filter by status |
/ioc/toggle/ | Enable/disable IoC entry |
5.2 IoC Rule Management #
| Route | Description |
|---|---|
/ioc/fetch/ | Generate Suricata rule files from IoCs |
/ioc/rules/status/ | Rule file status |
/ioc/rules/modify/ | Modify IoC rule file states |
6. Statistics API #
Namespace: Stats
Purpose: Suricata counters, host metrics, histograms.
| Route | Description |
|---|---|
/stats/ | General stats snapshot |
/stats/pkts/ | Packet counters |
/stats/alerts/ | Alert counters |
/stats/cpu/ | CPU load |
/stats/vm/ | Virtual memory |
/stats/pm/ | Physical memory |
/stats/histogramm/ | Histogram data for charts |
/suricata/running/ | Suricata process check |
/stats/update/ | Timestamp of stats update |
7. Network Map API #
Namespace: Net
| Route | Description |
|---|---|
/net/map/ | Current network map |
/net/historicalmap/ | Historical map based on long-term flows |
8. Summary #
Suri Oculus 3.0 delivers a broad and stable API layer suitable for dashboards, SIEM integration, DevOps automation and AI-powered analysis modules. The separation into Events, Rules, Threats, Stats and Network ensures predictable structure, clarity, and future scalability.
