Skip to main content

​
Overview

The kguardian Broker exposes a REST API for querying collected telemetry data. The CLI uses this API internally, but you can also integrate directly with it for custom workflows.

​
Base URL

http://kguardian-broker.kguardian.svc.cluster.local:9090
For external access, use port-forwarding: 
kubectl port-forward -n kguardian svc/kguardian-broker 9090:9090

​
Authentication

The broker currently has no authentication. The API should only be accessible within the cluster network. For production deployments, consider using NetworkPolicies, service mesh, or an API gateway with authentication.
For the broker’s current released version, see broker/VERSION — component versions evolve independently per the release strategy.

​
API Endpoints

Pods

Add and retrieve pod metadata

Traffic

Query network traffic data

Syscalls

Retrieve syscall observations

Services

Service IP to metadata mapping

Audit Verdicts

Query Would-Deny / Allow verdicts from the audit evaluator

​
Response Format

All responses are JSON with standard HTTP status codes:
  • 200 OK - Success
  • 400 Bad Request - Invalid parameters
  • 404 Not Found - Resource not found
  • 500 Internal Server Error - Server error

​
Common Patterns

​
Pagination

Most endpoints return all matching rows without paging — fine for small / medium clusters but unbounded on busy ones. /audit/verdicts is the exception: it supports a limit query parameter (default 100, max 500) and orders by (observed_at DESC, id DESC) for stable cursor-style traversal. The /pod/info, /svc/info, /pod/traffic and /pod/traffic/{name} endpoints have stable ordering too — see each page for the sort key — but no LIMIT yet.

​
Filtering

/audit/verdicts supports server-side filtering by policy, namespace, verdict, and direction (index-backed; see the endpoint page for the full contract). The pod-name- and IP-scoped GETs already filter at the URL: prefer GET /pod/traffic/{name} over GET /pod/traffic + client-side filter on any non-trivial cluster.

​
Rate Limiting

No rate limiting is currently enforced at the broker. The audit forwarder bounds concurrent in-flight /evaluate calls via the AUDIT_INFLIGHT_PERMITS semaphore (default 16) and exposes the gauge as broker_audit_inflight_available on /metrics so operators can spot saturation.