Architecture & Components
Bhairava is an event-driven, horizontally-scalable platform. Telemetry streams continuously through Kafka into the AI agent tiers and back out to the dashboard — every stage independently scalable and every event traceable.
Architecture overview
Traefik terminates TLS on :443 and load-balances two active-active FastAPI API servers — pinning each session with a sticky bhairava_session cookie — while also serving the compiled React frontend. The API layer never talks to workers directly: it publishes and reads events on a 3-node Kafka cluster, and the worker tiers consume those events independently.
Durable state is split across purpose-built stores: Postgres for relational data, OpenSearch for event & timeline search, Redis for caching and coordination, and MinIO for object storage. The animated diagram on the home page shows this flow — from ingress, through Kafka, into the agent tiers, and back to the dashboard.
Core components
Every service runs as an independent container, so each tier scales on its own. The table below maps each component to the role it plays in the stack.
| Component | Role |
|---|---|
Traefik | Ingress reverse proxy — TLS termination and active-active load balancing. |
API (api-1, api-2) | FastAPI app servers exposing REST, GraphQL and WebSocket. |
Frontend | React SPA served by nginx. |
PostgreSQL (pgvector) | Primary database plus ML embedding vectors. |
Redis | Cache, rate-limiting, enrichment cache, and pub/sub event bus. |
Kafka (3-node KRaft) | Event backbone, no ZooKeeper. |
OpenSearch | Event & timeline search and analytics. |
MinIO | S3-compatible object storage for evidence and artifacts. |
Keycloak | OIDC identity provider (optional; local JWT auth is the fallback). |
Prometheus / Grafana / Loki | Metrics, dashboards, log aggregation. |
Wazuh Manager 4.9 | SIEM/HIDS/FIM data source; an alert-bridge tails Wazuh's alerts.json into Kafka. |
The entire stack runs from a single Docker Compose file (or Helm chart) and is fully multi-tenant — one deployment cleanly isolates many customer organizations, so MSSPs can serve every client from the same install.
AI agent tiers
Three tiers of autonomy do the analytical work. Each tier consumes events from Kafka, uses the same integrations your analysts would, and hands off to the next tier — L1 triages, L2 investigates, and the executors run long-horizon operations.
L1 · Triage
The L1 pipeline runs a fixed sequence for every alert: classify → deduplicate → false-positive check → enrich → correlate → score → match playbook → execute → ticket → notify → escalate. It is backed by three sub-agents — a classifier (Claude Haiku), a playbook matcher, and a result cache that short-circuits repeat work.
L2 · Investigation
L2 runs multi-turn Claude sessions with tool use to investigate incidents escalated from L1. Its sub-agents include the investigator, MITRE mapper, kill-chain reconstructor, root-cause analyzer, scope analyzer, timeline builder, TTP profiler, and narrator — plus a tool executor that bridges Claude tool calls to real integrations.
Executors
Four autonomous planner → executor → worker pipelines carry out long-running operations: hunt, detection, forensics (a 15-step pipeline), and compliance (a 15-step pipeline). Each plans its own steps, executes them, and reports results back to the platform.
Framing all of this is a framework layer. An orchestrator manages the agent pool, handling routing and load-balancing across tiers. It is supported by a decision engine, confidence scoring, L1→L2 escalation rules, human-in-the-loop gates, an audit trail, metrics, and an LLM fallback provider for resilience when a model endpoint is unavailable.
Data pipeline
Before any agent sees an alert, raw telemetry passes through a streaming ingestion pipeline that turns vendor-specific events into a single canonical form. The stages run in order:
- Consume — an aiokafka consumer pulls events in batches.
- Normalize — a normalizer maps raw Wazuh/Zabbix/etc. events to a canonical alert using YAML field mappings (siem, edr, firewall, identity, router, sigma, suricata, database, forensics).
- Deduplicate — Redis + in-memory dedup over the stream.
- Enrich — pipeline enrichment plus alert-enrich derives human-readable, self-explanatory metadata and IOC reputation.
- Index — an alert indexer writes ECS documents to date-partitioned OpenSearch indices.
- Hand off — persists results, auto-forms incidents, and hands alerts to the L1 tier.
Each worker tier runs its own Kafka consumer group — bhairava-l1, bhairava-l2, bhairava-hunt, bhairava-detection, bhairava-forensics, and bhairava-compliance — so tiers scale and fail independently without losing their place in the stream.
MCP servers
Bhairava exposes its integrations to the AI agents through 15 Model Context Protocol (MCP) tool servers, so an agent can query a SIEM, isolate an endpoint, or look up an IOC as a native tool call during an investigation — no bespoke glue per capability.
The servers are: siem, noc, threatintel, itsm, firewall, notify, identity, edr, yara, sigma, forensics, cloud_aws, cloud_azure, cloud_gcp, and btrl (threat-research lab).