kb aads

kb-aads — Autonomous Agentic Defense System

Language: Python · Primary Maintainer: Karthik — AI & Agentic Systems · Collaborator: Pardhu Varma — ML & Systems

Multi-agent swarm that interprets KB behavioral signals and coordinates threat response. Optional and strictly advisory — the Control Plane always has final enforcement authority; disabling AADS entirely does not stop deterministic enforcement.

Structure

kb-aads/
├── agents/         Individual agent role implementations
├── swarm/          Swarm orchestration and lifecycle management
├── consensus/       Quorum / weighted voting system
├── marl/            Multi-Agent Reinforcement Learning infrastructure
├── comms/           ZeroMQ / IPC / gRPC-over-UDS communication layer
└── tests/

Agent Roles (agents/)

Role	File	Responsibility
Patroller	patroller.py	Baseline monitoring — always active
Hunter	hunter.py	Threat investigation on SUSPICIOUS transitions
Healer	healer.py	False-positive suppression / recovery coordination
Containment	containment.py	Enforcement coordination
Idle	idle.py	Reserve/standby pool

All agents inherit from BaseAgent (base_agent.py), which provides the lifecycle (start/stop/tick), an asyncio.Queue-based message inbox, and a standard status snapshot (agent_id, role, status, uptime, anomaly_score, last_action).

Agent Lifecycle: NEW → PROFILING → BASELINE → MONITOR → CONTAINED → TERMINATED

Several agent methods (HunterAgent.investigate) currently contain explicit TODOs for querying KB process history, building evidence chains, calculating confidence, and submitting to the Jury — these are scaffolded but not fully wired end-to-end yet.

The JJE Pipeline: Judge, Jury, Executor

The primary reasoning pipeline layered above the swarm:

Role	Function	Scope
Judge	Consumes the KB event stream, correlates behavioral patterns across time windows, produces structured alerts with confidence scores	READ-ONLY
Jury	Cross-validates Judge alerts against historical process profiles, suppresses known false positives, produces validated decision records	READ-ONLY
Executor	Translates validated decisions into Control Plane API calls, within its scoped capability token — and nothing outside it	SCOPED WRITE

The swarm's five sub-agent classes (Patroller, Hunter, Healer, Containment Militia, Signal Relays) are directed by JJE and coordinate over the ZeroMQ mesh.

Swarm Orchestration (swarm/)

• SwarmOrchestrator — top-level swarm manager; creates/monitors/rebalances agents
• RoleManager — dynamic role assignment
• HealthMonitor — agent health tracking
• RogueDetector — anomalous agent detection (defense-in-depth against a compromised or malfunctioning agent, not just compromised processes) Default swarm composition (main.py): 2 patrollers, 2 hunters, 1 healer, 1 containment agent.

Consensus & Quorum (consensus/)

Weighted voting for critical swarm decisions:

• Process termination
• Agent termination (rogue management)
• Threat-level escalation
• Role redistribution
• Emergency mode activation Each agent has a weight based on role and confidence history; decisions require an M-of-N weighted vote to pass. Unresolved votes expire after a configurable timeout. Results are logged to the immutable audit trail.

MARL (marl/)

• Framework: Ray RLlib 2.x, Gymnasium environment, PyTorch policy networks
• Fine-tuned base model: Phi-3 Mini / Qwen2.5 3B (QLoRA)
• Domain: security reasoning over behavioral event sequences Reward signals:

Outcome	Reward
True Positive (correctly identified threat)	+1.0
False Positive (legitimate process contained)	-0.5
True Negative (safe process correctly ignored)	+0.1
False Negative (missed threat)	-1.0

Training pipeline: collect production outcomes → compute reward signals per agent → update policy networks via RLlib → validate new policy with kb-checker → deploy to production agents.

Communication Layer (comms/)

Architecture decision: Kafka has been dropped from the design. An external broker (plus its Docker/Compose and JVM footprint) added latency and operational weight the AADS↔Control-Plane path doesn't need — the same "no broker in the hot path" reasoning KB already applied when it rejected Kafka for kb-control-plane's L1/L2 store (see ADR-1 in kb-control-plane). AADS now applies that philosophy end to end.

Two ultra-low-latency, broker-free transports remain:

Protocol	Use
ZeroMQ (brokerless ROUTER/DEALER mesh)	Direct agent-to-agent messaging, and the general inter-agent event fan-out that previously rode on Kafka topics (role-changes, agent-updates, consensus-events, health-checks, anomaly-alerts)
gRPC-over-UDS	KB Control Plane ↔ AADS — a Unix-Domain-Socket transport, matching the style kb-core's bridge already uses toward kb-control-plane (see Wire Protocol), rather than a TCP/network hop

Messages remain Pydantic models (comms/messages.py) encoded as genuine Protobuf bytes via google.protobuf.Struct — a deliberate stopgap ahead of hand-written .proto schemas, so the wire format is real protobuf today without blocking on schema stabilization. This encoding is transport-agnostic, so the same message shapes (RoleChange, AgentUpdate, ConsensusEvent, HealthCheck, AnomalyAlert) carry over unchanged from the old Kafka topics onto ZeroMQ.

Run the smoke test (ZeroMQ direct channel):

python -m comms.smoke_test

Migration note: comms/kafka_bus.py, comms/topics.py, and docker-compose.kafka.yml reflect the previous Kafka-based design and are slated for removal/replacement with a ZeroMQ pub/sub (or PUSH/PULL) fan-out layer covering the same event categories, plus the gRPC-over-UDS bridge to kb-control-plane. If you're picking this work up: only the transport underneath KafkaBus needs to change — the event shapes in comms/messages.py don't.

Run

cd kb-aads
source venv/bin/activate
python main.py

Tests

source venv/bin/activate
pytest tests/

Coverage: per-agent-role unit tests, consensus voting simulation, MARL environment tests, integration tests against a mock KB control plane.

See also: Architecture (Layer 3), Zone Model And Scoring, kb-checker (validates agent-authored scripts before deployment).