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

For external access, use port-forwarding:

​
Authentication

Authentication is opt-in bearer-token auth, off by default. Set the BROKER_AUTH_TOKEN environment variable on the broker and every endpoint except /health and /metrics requires an Authorization: Bearer <token> header; a missing or invalid token returns 401.
Without BROKER_AUTH_TOKEN set, the API is unauthenticated and should only be reachable within the cluster network. For production deployments, enable token auth and/or restrict access with NetworkPolicies, a service mesh, or an API gateway.
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

Version

Running broker + chart versions, latest known releases, and update availability

​
Response Format

All responses are JSON with standard HTTP status codes:
  • 200 OK - Success
  • 400 Bad Request - Invalid parameters
  • 401 Unauthorized - Missing or invalid bearer token (only when BROKER_AUTH_TOKEN is set)
  • 404 Not Found - Resource not found
  • 500 Internal Server Error - Server error

​
Common Patterns

​
Pagination

The high-volume endpoints support a limit query parameter: /pod/traffic defaults to 5000 rows (clamped to [1, 20000], most-recent-first) and /audit/verdicts defaults to 100 (clamped to [1, 500]), both ordered newest-first with the primary key as a tiebreak for stable cursor-style traversal. Only /pod/traffic/{name} remains unbounded. The /pod/info and /svc/info endpoints return all rows but have stable ordering — see each page for the sort key.

​
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.