Architecting a Resource-Constrained Host-Based Security Agent for Behavioral Detection
This article discusses the architectural evolution of Agentix Lite Sentinel, a lightweight Linux security agent designed to detect suspicious behavior on small VPS instances without relying on extensive logging, AI, or cloud infrastructure. It highlights design choices focused on predictability under pressure, resource boundedness, and non-blocking telemetry to ensure the security system does not become a performance bottleneck.
Read original on Dev.to #architectureAgentix Lite Sentinel is presented as an alternative to large-scale SIEMs or cloud-based security platforms, specifically targeting small Linux VPS instances. Its core philosophy revolves around observing suspicious behavior, recognizing patterns, accumulating evidence, and reacting, all while maintaining strict resource limits and avoiding the overhead of excessive logging and complex infrastructure.
Architectural Principles for a Lightweight Security Agent
The design emphasizes several key principles to achieve its lightweight, performant, and predictable nature:
- Bounded Event Buffer & Compact State: Instead of collecting all raw data, Agentix uses finite rolling buffers for events, limited ingest queues, and caps on persistent state (e.g., per-IP state, SQLite size). This prevents the agent from consuming excessive resources under attack.
- Non-blocking Telemetry: A critical architectural change in v0.2.2 is the shift to non-blocking telemetry. If the security engine is overloaded, events are dropped rather than blocking the protected application. This prioritizes application availability over perfect security telemetry capture.
- Decoupled Ingestion & Processing: The system separates socket reading and event ingestion from subsequent processing. A bounded queue acts as a buffer, preventing the socket consumer from becoming directly bottlenecked by database operations or pattern detection.
- Honeypot & Honey API: The agent includes decoy endpoints (`/debug/env`, `/api/v2/admin/config`) and a dedicated honeypot TCP port. Interactions with these decoys provide high-signal events, reducing the noise from legitimate traffic and allowing targeted behavioral analysis without extensive data retention.
Predictability Under Pressure
The article stresses that the limits (e.g., 1000 events/600s, 100MiB SQLite) are not promises of DDoS survival, but guardrails to make the defender predictable under pressure. This means the system will degrade gracefully by dropping events rather than crashing or consuming all resources.
Key Architectural Changes in v0.2.2
Version 0.2.2 introduced several significant changes based on adversarial reviews, primarily focusing on resource management and resilience:
- Bounded Ingestion: Separating socket reading from event processing using a bounded queue to prevent backpressure.
- Smaller Scan and Rate State: Using fixed-size hash sketches and fixed-window counters instead of storing raw lists of attacker-controlled paths or timestamps, ensuring predictable memory usage.
- SQLite Limits & Pruning: Hard upper bounds on persistent actors and database size, with a mechanism to prune older, non-banned actors when capacity is reached.
- Firewall Action Budget: Implementing a rate limit on `nft` command execution (e.g., 60 actions/minute) to prevent the defense mechanism from becoming a denial-of-service vector itself.
- Explicit Proxy Trust: Requiring explicit configuration for trusted proxy networks to honor `X-Forwarded-For` headers, enhancing security posture.
Unix datagram
↓
socket reader
↓
bounded queue
↓
worker
↓
pattern detection
↓
SQLite