Dashboard
API: dashboard and system
Admin routes use AdminAuth() + RoleAuth("admin") unless noted. Source: dashboard_handler.go, system_handler.go, websocket_handler.go.
Optional query on stats and eBPF health: agent_id (positive integer). Invalid value → 400 {"error":"Invalid agent_id parameter"}.
GET /api/v1/dashboard/stats
Purpose. Aggregated console counters for agents, rules, logs, and eBPF attach counts.
Authentication. Admin.
Parameters. Query agent_id optional — scopes eBPF program/interface totals; agent online/offline totals still use the full list.
Request. Empty.
Example request.
curl -sS 'https://manager.example.com:8443/api/v1/dashboard/stats' \
-H "Authorization: Bearer TOKEN"Response (200). Flat JSON object (not V1OK). Keys written by GetDashboardStats:
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Meaning |
|---|---|
agents | map of Agent status string → count (full fleet) |
logs_24h | map of log_type → count in last 24h (from up to 10000 recent logs) |
ebpfActive / ebpf_active | online Agents with EBPFLoaded in scope |
totalPrograms / total_programs | sum of EBPFProgramsCount |
totalInterfaces / total_interfaces | attached interface counts |
total_rules | all rules |
active_rules | enabled rules |
disabled_rules | total_rules - active_rules |
online_agents / offline_agents | from status map |
registered_agents / total_agents | len(agents) |
alerts_today / alerts_this_week / alerts_this_month | recent log counts (24h / 7d / 30d) |
total_logs | GetLogCount |
ebpf_scope | "all_agents" or {"agent_id": N} |
Example response.
{
"online_agents": 1,
"offline_agents": 0,
"total_agents": 1,
"registered_agents": 1,
"total_rules": 12,
"active_rules": 10,
"disabled_rules": 2,
"ebpf_active": 1,
"total_programs": 2,
"total_interfaces": 1,
"alerts_today": 4,
"ebpf_scope": "all_agents"
}Errors. 400 invalid agent_id; 500 {"error":"Failed to get stats"} if repositories missing or list fails.
Edition. SHARED.
Security. Count-only. Do not treat as a PPS or capacity metric (no published PPS).
GET /api/v1/dashboard/ebpf-health
Purpose. Count-only eBPF / map / local-tracker health for operator dashboards.
Authentication. Admin.
Parameters. Query agent_id optional.
Request. Empty.
Response (200) (dashboardEBPFHealthResponse):
Scroll sideways to see the full table. Use the arrow keys when focused.
| Field | Type |
|---|---|
agents | array of dashboardEBPFHealthAgent |
total_agents | int |
healthy_agents / degraded_agents / unhealthy_agents / unknown_agents / active_agents | ints |
redaction | always "summary_only_no_raw_map_keys" |
Per-agent fields include agent_id, hostname, online, ebpf_loaded, program_count, attached_interfaces_count, attached_interfaces_summary, map counts, tracker counts, health_status, map_health_status, security_state_status, overall_status (healthy | degraded | unhealthy | unknown), warnings, reason_codes, reasons, maps (metadata, not raw keys).
Errors. 400 invalid agent_id; 500 {"error":"Failed to get eBPF health"}.
Edition. ENTERPRISE_ONLY handler registration. Community V1 router has no /dashboard/ebpf-health route.
Security. Summary only; redaction string is part of the contract.
GET /api/v1/dashboard/agents
Purpose. Compact Agent list for the console widget.
Authentication. Admin.
Response (200). {"agents": [...], "total": N} — API_SCHEMA_DOCUMENTATION_BLOCKED for each Agent object beyond domain Agent JSON tags; handler wraps ListAgents plus online/offline coloring. 500 {"error":"Failed to get agents"}.
Edition. SHARED.
GET /api/v1/dashboard/logs
Purpose. Recent security logs for the console.
Authentication. Admin.
Response (200). {"logs": [...], "total": N}. API_SCHEMA_DOCUMENTATION_BLOCKED for exact slice construction (gin.H); rows are SecurityLog domain objects when returned from the repo. 500 {"error":"Failed to get logs"}.
Edition. SHARED.
GET /api/v1/dashboard/system
Purpose. Local Manager process/system snapshot for the console.
Authentication. Admin.
Response (200) keys from handler: status, uptime, version, database, manager, local_ebpf (map). API_SCHEMA_DOCUMENTATION_BLOCKED for nested local_ebpf (getLocalEBPFStatus returns map[string]interface{}).
Edition. SHARED.
Security. Do not confuse with /health/ready.
GET /api/v1/dashboard/metrics
Purpose. Realtime metrics widget.
Authentication. Admin.
Response (200). {"success": true, "data": ...} from metrics service. API_SCHEMA_DOCUMENTATION_BLOCKED — data is whatever metricsService returns, not a documented DTO. 500 {"error":"Failed to retrieve system metrics"}.
Edition. SHARED.
GET /api/v1/dashboard/traffic
Purpose. Realtime traffic feed for the console (WebSocket helper handler GetRealtimeTraffic).
Authentication. Admin.
Response. API_SCHEMA_DOCUMENTATION_BLOCKED — wsHandler.GetRealtimeTraffic returns gin.H widgets, not a public streaming product.
Edition. SHARED.
GET /api/v1/dashboard/security-events
Purpose. Realtime security-event widget (GetRealtimeSecurityEvents).
Authentication. Admin.
Response. API_SCHEMA_DOCUMENTATION_BLOCKED — WebSocket helper gin.H.
Edition. SHARED.
GET /api/v1/dashboard/ws
Purpose. Dashboard WebSocket upgrade.
Authentication. Session cookie or Bearer JWT inside the upgrader (router.go registers without the admin group middleware; the handler enforces session/JWT).
Parameters. None as query contract beyond the upgrade.
Request. WebSocket handshake.
Response. Upgrade; not JSON. API_SCHEMA_DOCUMENTATION_BLOCKED for message payload map.
Edition. SHARED.
Security. Treat as admin-equivalent. Not a public streaming API.
GET /api/v1/system/sanity-check
Purpose. Run Manager sanity checks (zwallctl check uses related APIs).
Authentication. Admin (RoleAuth("admin") on the system group).
Response. API_SCHEMA_DOCUMENTATION_BLOCKED — SystemHandler returns gin.H check results. Known failure mode: 500/503 depending on check execution.
Edition. SHARED.
GET /api/v1/system/sanity-check/:check_name
Purpose. Run one named sanity check.
Authentication. Admin.
Parameters. :check_name string.
Response. API_SCHEMA_DOCUMENTATION_BLOCKED — same handler family.
Edition. SHARED.