Agent Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• IMPLEMENTATION_PLAN.md
• Cargo.toml
• crates/cli/src/main.rs

The Horizon Agent is a lightweight, cross-platform component designed to automatically discover and inventory IT infrastructure assets. It operates as a critical part of the Horizon CMDB system, providing visibility into hardware, software, and network configurations with minimal overhead. The agent is built using Rust to ensure high performance, security, and a small memory footprint (under 50MB).

Sources: README.md:21-25, IMPLEMENTATION_PLAN.md:144-145

Core Responsibilities and Design

The agent is designed to function with minimal configuration while maintaining data integrity through a secure communication framework. Its primary goal is to automate the collection of comprehensive IT asset data, which is then synchronized with the central Horizon server.

Key Capabilities

• Hardware Discovery: Automated collection of CPU, memory, storage, and peripherals.
• Software Tracking: Inventory of installed packages and running services.
• Network Mapping: Discovery of interfaces, IP addresses, and flow collection.
• Platform Support: Native support for Linux, Windows, and macOS.

Sources: README.md:46-55, IMPLEMENTATION_PLAN.md:28-34

Agent Components and Data Flow

The agent architecture is modular, consisting of specialized discovery modules and a secure communication engine. The following diagram illustrates the internal logic and data transmission flow from the local system to the Horizon server.

The agent lifecycle starts with platform detection, proceeds to asset data collection, and ends with secure delivery to the server API.

Sources: IMPLEMENTATION_PLAN.md:395-460, IMPLEMENTATION_PLAN.md:154-156

Discovery Modules

Module	Features	Implementation Details
Platform Detection	OS Identification	Detects Linux, Windows, and macOS; creates system info structs.
Hardware Inventory	Device Enumeration	Collects CPU (cores/freq), Memory (slots/total), and Storage (SMART status).
Software Inventory	Package Management	Queries dpkg, rpm, brew, chocolatey, winget; detects startup items.
Network Discovery	Interface Tracking	Tracks MAC addresses, IP addresses, speeds, and network flows.

Sources: IMPLEMENTATION_PLAN.md:403-435

Security and Communication

The agent utilizes a "defense-in-depth" security model, employing modern cryptographic standards provided by the RustCrypto ecosystem. All communications are protected via mutual TLS (mTLS) with server-issued certificates.

Security Stack

• Mutual TLS (mTLS): Enforces bidirectional authentication between agent and server.
• Digital Signatures: Uses ed25519 for message signing to ensure authenticity.
• Encryption: Uses chacha20poly1305 for symmetric encryption of sensitive payloads.
• Key Exchange: Employs x25519 for forward secrecy.

Sources: IMPLEMENTATION_PLAN.md:144-146, IMPLEMENTATION_PLAN.md:674-690, Cargo.toml:49-65

Registration and Certificate Workflow

The server acts as a Certificate Authority (CA) to manage agent identities.

The registration process binds an agent instance to a unique certificate, which is used for all subsequent secure transmissions.

Sources: IMPLEMENTATION_PLAN.md:454-460, IMPLEMENTATION_PLAN.md:664-672

Data Resilience and Offline Operation

To handle network instability, the agent includes an offline queue mechanism.

• Local Storage: Uses a local SQLite database for message persistence during outages.
• Transmission Logic: Implements retry logic with exponential backoff.
• Compression: Payloads are compressed before transmission to reduce network impact.
• Message Format: Utilizes Protocol Buffers (prost) for efficient, structured serialization.

Sources: IMPLEMENTATION_PLAN.md:444-452, IMPLEMENTATION_PLAN.md:690-692

Deployment and Configuration

The agent is managed through a multi-level configuration hierarchy:

1. Environment Variables: HORIZON_* variables.
2. Configuration Files: YAML, TOML, or JSON formats.
3. Runtime API: Configuration pushed from the server.

Technical Stack

• CLI Framework: clap for command-line arguments.
• Serialization: serde and prost.
• Async Runtime: tokio.
• Configuration: figment.

Sources: IMPLEMENTATION_PLAN.md:150-152, IMPLEMENTATION_PLAN.md:395-400, Cargo.toml:85-87

Conclusion

The Horizon Agent Architecture prioritizes security, cross-platform compatibility, and resource efficiency. By leveraging Rust and a robust cryptographic stack, it provides a resilient foundation for automated IT infrastructure discovery within the CMDB ecosystem.