How echenim/argus works
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: event-bus Event Bus · agent-runtime Agent Runtime · sensor-agent Sensor Agent · api-gateway API Gateway
Components 31
Configs
Agent configs, NATS settings, and canonical event schemas.
- Event Schemas · Canonical envelope and typed domain event contracts.
configs/schemas - Agent Configs · Per-agent deployment and runtime configuration files.
configs/agents - NATS Config · Authorization and TLS settings for distributed event transport.
configs/nats
Shared Crates
Core domain libraries and runtime infrastructure reused by services.
- Telemetry · Raw packet parsing and DNS observation for network evidence.
crates/telemetry - Event Bus · Canonical event fabric with in-memory and NATS transport.
crates/event-bus - Agent Runtime · Shared lifecycle, config, validation, envelope, logging, metrics, and HTTP observability.
crates/agent-runtime - Inventory · Device identity, discovery, and OUI vendor context.
crates/device-inventory - Flow Engine · Session reconstruction and normalized flow records.
crates/flow-engine - Features · Windowed statistical feature computation.
crates/feature-extraction - Behavior Model · Baselines and normal-behavior scoring logic.
crates/behavior-model - Anomaly Detection · Beaconing, exfiltration, lateral movement, classification, and safeguards.
crates/anomaly-detection - Investigation · Timelines, evidence aggregation, and incident risk scoring.
crates/investigation-engine - Policy Engine · Decides whether a response is allowed and what action class is appropriate.
crates/policy-engine - Containment · Applies and rolls back defensive actions.
crates/containment-engine - Explanation · Templates and prompts for human-readable investigation explanations.
crates/explanation-engine - Event Store · Durable immutable event and audit storage.
crates/event-store - Storage · SQLite-backed operational persistence with migrations.
crates/storage
Services
Thin deployable agent binaries and control-plane entrypoints.
- Sensor Agent · Ingress service for raw network evidence.
services/sensor-agent - API Gateway · External control surface with authentication and WebSocket support.
services/api-gateway - Anomaly Agent · Deployable anomaly-detection worker.
services/anomaly-agent - Behavior Agent · Deployable behavior-model worker.
services/behavior-agent - Containment Agent · Deployable containment worker.
services/containment-agent - DNS Agent · Deployable DNS observation worker.
services/dns-agent - Flow Agent · Deployable flow reconstruction worker.
services/flow-agent - Inventory Agent · Deployable device discovery worker.
services/inventory-agent - Investigation Agent · Deployable investigation worker.
services/investigation-agent - Policy Agent · Deployable policy-evaluation worker.
services/policy-agent - Explanation Agent · Deployable narrative-generation worker.
services/explanation-agent
Operator UI
Dashboard for analyst and operator workflows.
- Dashboard · 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 · End-to-end validation of event flow and full-system behavior.
tests/integration
Deployment
Containerized local deployment assets.
- Docker Deploy · Container image and compose-based local deployment path.
deploy/docker
Connections 36
- 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.