# echenim/argus architecture

> Architecture diagram of the GitHub repository echenim/argus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/echenim/argus
- Repository: https://github.com/echenim/argus

## Overview

1. **Monorepo shape**
   - This is a Rust workspace built as a swarm of small binaries plus shared crates.
   - The architectural center is not a single monolith; it is a set of agent services coordinated by a common runtime and an event bus.

2. **Edge observation layer**
   - `services/sensor-agent` and the `crates/telemetry` library are the ingress boundary for raw network evidence.
   - The telemetry crate includes packet parsing and DNS monitoring, which suggests packet- and DNS-derived signals are normalized before entering the rest of the system.

3. **Canonical event fabric**
   - `crates/event-bus` is the primary communication boundary between agents.
   - It supports both in-memory and NATS-backed transport, matching the repo’s local-first and distributed deployment story.
   - The `configs/schemas/*.schema.json` files define the canonical event contract, with an envelope schema plus typed domain events such as device discovery, flow creation/closure, anomaly detection, investigation, containment, and response decisions.

4. **Device and traffic understanding**
   - `crates/device-inventory` models discovered devices and identity metadata, including OUI-based vendor context.
   - `crates/flow-engine` reconstructs and tracks communication sessions and normalized flow records.
   - Together these form the “what is on the network” and “who talked to whom” substrate for downstream analysis.

5. **Behavioral analytics path**
   - `crates/feature-extraction` computes statistical features over time windows.
   - `crates/behavior-model` maintains baselines and scoring logic for normal device behavior.
   - `crates/anomaly-detection` layers specialized detectors on top of those baselines, with modules for beaconing, exfiltration, lateral movement, classification, and circuit-breaker style safeguards.

6. **Investigation and risk layer**
   - `crates/investigation-engine` aggregates evidence into timelines, risk scores, and investigation state.
   - This is the analytical pivot point where raw anomaly signals become an incident candidate or an opened investigation, rather than an automatic response.

7. **Policy and containment boundary**
   - `crates/policy-engine` decides whether a response is allowed and what class of action is appropriate.
   - `crates/containment-engine` is the actuation layer that applies or rolls back defensive actions.
   - The separation matters: policy decides, containment executes. That keeps enforcement safety and rollback concerns out of the detection path.

8. **Explanation / narrative layer**
   - `crates/explanation-engine` turns investigation output into human-readable prompts and templates.
   - Per the README, this is an optional LLM reasoning layer used for narratives and analyst-style explanations, not for deciding detections or containment.

9. **Persistence and audit**
   - `crates/storage` provides SQLite-backed persistence with migrations for core operational data.
   - `crates/event-store` handles durable event/audit storage, separating immutable event history from queryable state.
   - This split supports both forensic replay and operational reads.

10. **Shared agent runtime**
   - `crates/agent-runtime` is the common execution framework for all agents.
   - It contains configuration loading, lifecycle management, validation, event envelope handling, logging, metrics, and HTTP observability hooks.
   - In architecture terms, it is the standard shell around each specialized agent.

11. **Service entry points**
   - The `services/*` binaries are the deployable nodes: anomaly, behavior, containment, DNS, explanation, flow, inventory, investigation, policy, API gateway, and sensor.
   - These are intentionally thin wrappers around the shared crates, which keeps the domain logic reusable while allowing independently deployable roles.

12. **Operator/control plane**
   - `services/api-gateway` is the external control surface, with authentication and WebSocket support.
   - The `web/dashboard` app is the operator UI for device inventory, anomaly timelines, containment logs, investigations, and system health.
   - This is the main human-facing boundary into the swarm.

13. **End-to-end data flow**
   - Network telemetry enters at the sensor/telemetry layer.
   - It is normalized into events and published on the bus.
   - Specialized agents consume those events, enrich state, build baselines, detect anomalies, open investigations, score risk, and, if policy allows, trigger containment.
   - Results are persisted and surfaced through the API gateway and dashboard.

14. **Deployment and validation**
   - `configs/` holds agent configs, NATS authorization/TLS, and all event schemas.
   - `deploy/docker` and `docker-compose.dev.yml` indicate a containerized local deployment path.
   - `tests/integration` plus fixture data provide pipeline-level verification of event flow, storage, and full-system behavior.

Main entry points: [`crates/event-bus`](https://github.com/echenim/argus/tree/main/crates/event-bus) (Event Bus), [`crates/agent-runtime`](https://github.com/echenim/argus/tree/main/crates/agent-runtime) (Agent Runtime), [`services/sensor-agent`](https://github.com/echenim/argus/tree/main/services/sensor-agent) (Sensor Agent), [`services/api-gateway`](https://github.com/echenim/argus/tree/main/services/api-gateway) (API Gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configs["Configs"]
  node_configs_schemas["Event Schemas<br/>schema set"]
  node_configs_agents["Agent Configs<br/>runtime config"]
  node_configs_nats["NATS Config<br/>transport config"]
end

subgraph group_crates["Shared Crates"]
  node_telemetry["Telemetry<br/>ingress lib"]
  node_event_bus[("Event Bus<br/>message bus")]
  node_agent_runtime["Agent Runtime<br/>runtime framework"]
  node_device_inventory["Inventory<br/>device model"]
  node_flow_engine["Flow Engine<br/>flow tracker"]
  node_feature_extraction["Features<br/>feature lib"]
  node_behavior_model["Behavior Model<br/>baseline/scoring"]
  node_anomaly_detection["Anomaly Detection<br/>detectors"]
  node_investigation_engine["Investigation<br/>evidence/risk"]
  node_policy_engine["Policy Engine<br/>guardrails"]
  node_containment_engine["Containment<br/>actuation"]
  node_explanation_engine["Explanation<br/>narrative layer"]
  node_event_store[("Event Store<br/>audit store")]
  node_storage[("Storage<br/>sqlite persistence")]
end

subgraph group_services["Services"]
  node_sensor_agent["Sensor Agent<br/>edge collector"]
  node_api_gateway["API Gateway<br/>control plane"]
  node_anomaly_agent["Anomaly Agent"]
  node_behavior_agent["Behavior Agent"]
  node_containment_agent["Containment Agent"]
  node_dns_agent["DNS Agent"]
  node_flow_agent["Flow Agent"]
  node_inventory_agent["Inventory Agent"]
  node_investigation_agent["Investigation Agent"]
  node_policy_agent["Policy Agent"]
  node_explanation_agent["Explanation Agent"]
end

subgraph group_web["Operator UI"]
  node_dashboard["Dashboard<br/>web app"]
end

subgraph group_tests["Integration Tests"]
  node_pipeline_tests["Pipeline Tests<br/>integration tests"]
end

subgraph group_deploy["Deployment"]
  node_docker["Docker Deploy<br/>deployment"]
end

node_telemetry -->|"ingests"| node_sensor_agent
node_sensor_agent -->|"publishes"| node_event_bus
node_configs_schemas -->|"defines contract"| node_event_bus
node_configs_nats -->|"configures transport"| node_event_bus
node_agent_runtime -->|"wraps"| node_sensor_agent
node_agent_runtime -->|"wraps"| node_anomaly_agent
node_agent_runtime -->|"wraps"| node_behavior_agent
node_agent_runtime -->|"wraps"| node_containment_agent
node_agent_runtime -->|"wraps"| node_dns_agent
node_agent_runtime -->|"wraps"| node_flow_agent
node_agent_runtime -->|"wraps"| node_inventory_agent
node_agent_runtime -->|"wraps"| node_investigation_agent
node_agent_runtime -->|"wraps"| node_policy_agent
node_agent_runtime -->|"wraps"| node_explanation_agent
node_event_bus -->|"consumed by"| node_flow_agent
node_event_bus -->|"consumed by"| node_inventory_agent
node_event_bus -->|"consumed by"| node_behavior_agent
node_event_bus -->|"consumed by"| node_anomaly_agent
node_event_bus -->|"consumed by"| node_investigation_agent
node_event_bus -->|"consumed by"| node_policy_agent
node_event_bus -->|"consumed by"| node_containment_agent
node_event_bus -->|"consumed by"| node_explanation_agent
node_device_inventory -->|"models"| node_inventory_agent
node_flow_engine -->|"builds"| node_flow_agent
node_feature_extraction -->|"feeds"| node_behavior_model
node_behavior_model -->|"baselines"| node_anomaly_detection
node_investigation_engine -->|"requests decision"| node_policy_engine
node_policy_engine -->|"approves action"| node_containment_engine
node_explanation_engine -->|"narrates"| node_api_gateway
node_event_store -->|"persists to"| node_storage
node_storage -->|"serves"| node_api_gateway
node_api_gateway -->|"serves ui"| node_dashboard
node_pipeline_tests -.->|"verifies"| node_event_bus
node_pipeline_tests -.->|"verifies"| node_storage
node_docker -->|"deploys"| node_sensor_agent
node_docker -->|"deploys"| node_api_gateway

click node_configs_schemas "https://github.com/echenim/argus/tree/main/configs/schemas"
click node_configs_agents "https://github.com/echenim/argus/tree/main/configs/agents"
click node_configs_nats "https://github.com/echenim/argus/tree/main/configs/nats"
click node_telemetry "https://github.com/echenim/argus/tree/main/crates/telemetry"
click node_event_bus "https://github.com/echenim/argus/tree/main/crates/event-bus"
click node_agent_runtime "https://github.com/echenim/argus/tree/main/crates/agent-runtime"
click node_device_inventory "https://github.com/echenim/argus/tree/main/crates/device-inventory"
click node_flow_engine "https://github.com/echenim/argus/tree/main/crates/flow-engine"
click node_feature_extraction "https://github.com/echenim/argus/tree/main/crates/feature-extraction"
click node_behavior_model "https://github.com/echenim/argus/tree/main/crates/behavior-model"
click node_anomaly_detection "https://github.com/echenim/argus/tree/main/crates/anomaly-detection"
click node_investigation_engine "https://github.com/echenim/argus/tree/main/crates/investigation-engine"
click node_policy_engine "https://github.com/echenim/argus/tree/main/crates/policy-engine"
click node_containment_engine "https://github.com/echenim/argus/tree/main/crates/containment-engine"
click node_explanation_engine "https://github.com/echenim/argus/tree/main/crates/explanation-engine"
click node_event_store "https://github.com/echenim/argus/tree/main/crates/event-store"
click node_storage "https://github.com/echenim/argus/tree/main/crates/storage"
click node_sensor_agent "https://github.com/echenim/argus/tree/main/services/sensor-agent"
click node_api_gateway "https://github.com/echenim/argus/tree/main/services/api-gateway"
click node_anomaly_agent "https://github.com/echenim/argus/tree/main/services/anomaly-agent"
click node_behavior_agent "https://github.com/echenim/argus/tree/main/services/behavior-agent"
click node_containment_agent "https://github.com/echenim/argus/tree/main/services/containment-agent"
click node_dns_agent "https://github.com/echenim/argus/tree/main/services/dns-agent"
click node_flow_agent "https://github.com/echenim/argus/tree/main/services/flow-agent"
click node_inventory_agent "https://github.com/echenim/argus/tree/main/services/inventory-agent"
click node_investigation_agent "https://github.com/echenim/argus/tree/main/services/investigation-agent"
click node_policy_agent "https://github.com/echenim/argus/tree/main/services/policy-agent"
click node_explanation_agent "https://github.com/echenim/argus/tree/main/services/explanation-agent"
click node_dashboard "https://github.com/echenim/argus/tree/main/web/dashboard"
click node_pipeline_tests "https://github.com/echenim/argus/tree/main/tests/integration"
click node_docker "https://github.com/echenim/argus/tree/main/deploy/docker"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_configs_schemas,node_configs_agents,node_configs_nats toneBlue
class node_telemetry,node_event_bus,node_agent_runtime,node_device_inventory,node_flow_engine,node_feature_extraction,node_behavior_model,node_anomaly_detection,node_investigation_engine,node_policy_engine,node_containment_engine,node_explanation_engine,node_event_store,node_storage toneAmber
class node_sensor_agent,node_api_gateway,node_anomaly_agent,node_behavior_agent,node_containment_agent,node_dns_agent,node_flow_agent,node_inventory_agent,node_investigation_agent,node_policy_agent,node_explanation_agent toneMint
class node_dashboard toneRose
class node_pipeline_tests toneIndigo
class node_docker toneTeal
```

## Components

### Configs

Agent configs, NATS settings, and canonical event schemas.

- [Event Schemas](https://github.com/echenim/argus/tree/main/configs/schemas): schema set · Canonical envelope and typed domain event contracts. · `configs/schemas`
- [Agent Configs](https://github.com/echenim/argus/tree/main/configs/agents): runtime config · Per-agent deployment and runtime configuration files. · `configs/agents`
- [NATS Config](https://github.com/echenim/argus/tree/main/configs/nats): transport config · Authorization and TLS settings for distributed event transport. · `configs/nats`

### Shared Crates

Core domain libraries and runtime infrastructure reused by services.

- [Telemetry](https://github.com/echenim/argus/tree/main/crates/telemetry): ingress lib · Raw packet parsing and DNS observation for network evidence. · `crates/telemetry`
- [Event Bus](https://github.com/echenim/argus/tree/main/crates/event-bus): message bus · Canonical event fabric with in-memory and NATS transport. · `crates/event-bus`
- [Agent Runtime](https://github.com/echenim/argus/tree/main/crates/agent-runtime): runtime framework · Shared lifecycle, config, validation, envelope, logging, metrics, and HTTP observability. · `crates/agent-runtime`
- [Inventory](https://github.com/echenim/argus/tree/main/crates/device-inventory): device model · Device identity, discovery, and OUI vendor context. · `crates/device-inventory`
- [Flow Engine](https://github.com/echenim/argus/tree/main/crates/flow-engine): flow tracker · Session reconstruction and normalized flow records. · `crates/flow-engine`
- [Features](https://github.com/echenim/argus/tree/main/crates/feature-extraction): feature lib · Windowed statistical feature computation. · `crates/feature-extraction`
- [Behavior Model](https://github.com/echenim/argus/tree/main/crates/behavior-model): baseline/scoring · Baselines and normal-behavior scoring logic. · `crates/behavior-model`
- [Anomaly Detection](https://github.com/echenim/argus/tree/main/crates/anomaly-detection): detectors · Beaconing, exfiltration, lateral movement, classification, and safeguards. · `crates/anomaly-detection`
- [Investigation](https://github.com/echenim/argus/tree/main/crates/investigation-engine): evidence/risk · Timelines, evidence aggregation, and incident risk scoring. · `crates/investigation-engine`
- [Policy Engine](https://github.com/echenim/argus/tree/main/crates/policy-engine): guardrails · Decides whether a response is allowed and what action class is appropriate. · `crates/policy-engine`
- [Containment](https://github.com/echenim/argus/tree/main/crates/containment-engine): actuation · Applies and rolls back defensive actions. · `crates/containment-engine`
- [Explanation](https://github.com/echenim/argus/tree/main/crates/explanation-engine): narrative layer · Templates and prompts for human-readable investigation explanations. · `crates/explanation-engine`
- [Event Store](https://github.com/echenim/argus/tree/main/crates/event-store): audit store · Durable immutable event and audit storage. · `crates/event-store`
- [Storage](https://github.com/echenim/argus/tree/main/crates/storage): sqlite persistence · SQLite-backed operational persistence with migrations. · `crates/storage`

### Services

Thin deployable agent binaries and control-plane entrypoints.

- [Sensor Agent](https://github.com/echenim/argus/tree/main/services/sensor-agent): edge collector · Ingress service for raw network evidence. · `services/sensor-agent`
- [API Gateway](https://github.com/echenim/argus/tree/main/services/api-gateway): control plane · External control surface with authentication and WebSocket support. · `services/api-gateway`
- [Anomaly Agent](https://github.com/echenim/argus/tree/main/services/anomaly-agent): service · Deployable anomaly-detection worker. · `services/anomaly-agent`
- [Behavior Agent](https://github.com/echenim/argus/tree/main/services/behavior-agent): service · Deployable behavior-model worker. · `services/behavior-agent`
- [Containment Agent](https://github.com/echenim/argus/tree/main/services/containment-agent): service · Deployable containment worker. · `services/containment-agent`
- [DNS Agent](https://github.com/echenim/argus/tree/main/services/dns-agent): service · Deployable DNS observation worker. · `services/dns-agent`
- [Flow Agent](https://github.com/echenim/argus/tree/main/services/flow-agent): service · Deployable flow reconstruction worker. · `services/flow-agent`
- [Inventory Agent](https://github.com/echenim/argus/tree/main/services/inventory-agent): service · Deployable device discovery worker. · `services/inventory-agent`
- [Investigation Agent](https://github.com/echenim/argus/tree/main/services/investigation-agent): service · Deployable investigation worker. · `services/investigation-agent`
- [Policy Agent](https://github.com/echenim/argus/tree/main/services/policy-agent): service · Deployable policy-evaluation worker. · `services/policy-agent`
- [Explanation Agent](https://github.com/echenim/argus/tree/main/services/explanation-agent): service · Deployable narrative-generation worker. · `services/explanation-agent`

### Operator UI

Dashboard for analyst and operator workflows.

- [Dashboard](https://github.com/echenim/argus/tree/main/web/dashboard): web app · Operator UI for inventory, anomalies, investigations, containment, and health. · `web/dashboard`

### Integration Tests

End-to-end validation of bus, storage, and pipeline behavior.

- [Pipeline Tests](https://github.com/echenim/argus/tree/main/tests/integration): integration tests · End-to-end validation of event flow and full-system behavior. · `tests/integration`

### Deployment

Containerized local deployment assets.

- [Docker Deploy](https://github.com/echenim/argus/tree/main/deploy/docker): deployment · Container image and compose-based local deployment path. · `deploy/docker`

## Connections

- Telemetry → Sensor Agent: ingests · Raw packets and DNS observations enter through the sensor boundary.
- Sensor Agent → Event Bus: publishes · Normalized evidence is emitted as canonical events.
- Event Schemas → Event Bus: defines contract · Schemas define the event envelope and typed domain events.
- NATS Config → Event Bus: configures transport · NATS auth and TLS support distributed delivery.
- Agent Runtime → Sensor Agent: wraps · Shared runtime provides lifecycle, validation, logging, metrics, and observability.
- Agent Runtime → Anomaly Agent: wraps · Shared runtime provides lifecycle, validation, logging, metrics, and observability.
- Agent Runtime → Behavior Agent: wraps · Shared runtime provides lifecycle, validation, logging, metrics, and observability.
- Agent Runtime → Containment Agent: wraps · Shared runtime provides lifecycle, validation, logging, metrics, and observability.
- Agent Runtime → DNS Agent: wraps · Shared runtime provides lifecycle, validation, logging, metrics, and observability.
- Agent Runtime → Flow Agent: wraps · Shared runtime provides lifecycle, validation, logging, metrics, and observability.
- Agent Runtime → Inventory Agent: wraps · Shared runtime provides lifecycle, validation, logging, metrics, and observability.
- Agent Runtime → Investigation Agent: wraps · Shared runtime provides lifecycle, validation, logging, metrics, and observability.
- Agent Runtime → Policy Agent: wraps · Shared runtime provides lifecycle, validation, logging, metrics, and observability.
- Agent Runtime → Explanation Agent: wraps · Shared runtime provides lifecycle, validation, logging, metrics, and observability.
- Event Bus → Flow Agent: consumed by · Flow agents reconstruct sessions from bus events.
- Event Bus → Inventory Agent: consumed by · Inventory agents discover and update device state.
- Event Bus → Behavior Agent: consumed by · Behavior agents build baselines from flow and device events.
- Event Bus → Anomaly Agent: consumed by · Anomaly agents score and classify suspicious behavior.
- Event Bus → Investigation Agent: consumed by · Investigation agents aggregate evidence and risk.
- Event Bus → Policy Agent: consumed by · Policy agents decide whether response is permitted.
- Event Bus → Containment Agent: consumed by · Containment agents execute approved response actions.
- Event Bus → Explanation Agent: consumed by · Explanation agents generate analyst-facing narratives.
- Inventory → Inventory Agent: models · Device identity and vendor context feed discovery.
- Flow Engine → Flow Agent: builds · Session tracking and normalized flows are produced here.
- Features → Behavior Model: feeds · Windowed features drive baseline maintenance and scoring.
- Behavior Model → Anomaly Detection: baselines · Detection layers compare behavior against learned norms.
- Investigation → Policy Engine: requests decision · Risk and incident state feed response authorization.
- Policy Engine → Containment: approves action · Policy determines whether containment may proceed.
- Explanation → API Gateway: narrates · Generated explanations are exposed to operators through the control plane.
- Event Store → Storage: persists to · Durable event history complements operational SQLite state.
- Storage → API Gateway: serves · Queryable state is surfaced through the API gateway.
- API Gateway → Dashboard: serves ui · External control surface supports the operator dashboard.
- Pipeline Tests → Event Bus: verifies · Integration tests validate event transport and schema flow.
- Pipeline Tests → Storage: verifies · Integration tests validate persistence behavior.
- Docker Deploy → Sensor Agent: deploys · Docker assets support local containerized deployment.
- Docker Deploy → API Gateway: deploys · Docker assets support local containerized deployment.