Skip to main content

Crate guard_agent_rs

Crate guard_agent_rs 

Source
Expand description

guard-agent-rs: telemetry and monitoring agent for the Guard ecosystem.

This crate is the Rust counterpart of the Python guard-agent and TypeScript guardagent telemetry agents. It ships security events, metrics, and agent status to the Guard ingestion API (POST /api/v1/events, /api/v1/metrics, /api/v1/status) with the same reliability semantics:

  • bounded per-kind buffers with drop (evict oldest), block, and raise overflow policies;
  • flush triggers on buffer high watermark and on a fixed interval;
  • at-least-once flush handshake: drain, send, confirm (delete persisted records) or requeue in original order;
  • transport retries with exponential backoff, honoring Retry-After on 429;
  • 413 split-or-drop with binary halving and a singleton drop threshold;
  • permanent rejection (400, 404, 422) drops the batch without retrying;
  • per-kind failure streaks with capped backoff and a computed degraded state;
  • optional Redis persistence with TTL and startup reload.

Telemetry failures never propagate into the caller’s request path: GuardAgent::send_event and GuardAgent::send_metric cannot fail, and every error is observable through GuardAgent::get_stats, the computed AgentStatus, logs, and the optional on_error hook.

§Usage

use guard_agent_rs::{AgentConfig, GuardAgent, SecurityEvent};

let mut config = AgentConfig::new("your-api-key-at-least-10-chars");
config.endpoint = "https://api.guard-core.com".to_owned();
config.install_id = Some("6f0a2880-1a2b-4c3d-9e4f-aabbccddeeff".to_owned());
let agent = GuardAgent::new(config).expect("valid configuration");

agent
    .send_event(
        SecurityEvent::new("rate_limited")
            .with_ip_address("10.0.0.1")
            .with_endpoint("/api/users")
            .with_action_taken("blocked"),
    )
    .await;

let stats = agent.get_stats().await;
assert_eq!(stats.events_buffered, 1);

See the repository README for the full reliability contract and the persistence feature documentation for Redis-backed buffering.

Re-exports§

pub use agent::AgentStats;
pub use agent::GuardAgent;
pub use agent::LoopFailures;
pub use bridge::GuardAgentTelemetry;guard-core
pub use circuit_breaker::CircuitBreakerState;
pub use config::AgentConfig;
pub use config::BufferOverflowPolicy;
pub use config::DEFAULT_BACKOFF_FACTOR;
pub use config::DEFAULT_BUFFER_SIZE;
pub use config::DEFAULT_COMPRESSION_THRESHOLD;
pub use config::DEFAULT_DYNAMIC_RULE_INTERVAL_SECS;
pub use config::DEFAULT_ENDPOINT;
pub use config::DEFAULT_FLUSH_INTERVAL_SECS;
pub use config::DEFAULT_HIGH_WATERMARK_RATIO;
pub use config::DEFAULT_MAX_PAYLOAD_SIZE;
pub use config::DEFAULT_RETRY_ATTEMPTS;
pub use config::DEFAULT_SENSITIVE_HEADERS;
pub use config::DEFAULT_STATUS_INTERVAL_SECS;
pub use config::DEFAULT_TIMEOUT_SECS;
pub use config::MIN_API_KEY_LEN;
pub use config::MIN_DYNAMIC_RULE_INTERVAL_SECS;
pub use config::MIN_STATUS_INTERVAL_SECS;
pub use config::DEFAULT_REDIS_KEY_PREFIX;persistence
pub use config::RedisConfig;persistence
pub use encryption::PayloadEncryptor;
pub use encryption::canonical_json;
pub use encryption::urlsafe_base64_encode;
pub use error::ConfigError;
pub use error::ErrorStage;
pub use error::GuardAgentError;
pub use models::AgentHealth;
pub use models::AgentStatus;
pub use models::DynamicRules;
pub use models::KNOWN_EVENT_TYPES;
pub use models::MetricType;
pub use models::SecurityEvent;
pub use models::SecurityMetric;
pub use persistence::RedisClientHandler;persistence
pub use persistence::InMemoryRedisStore;
pub use persistence::NAMESPACE_EVENTS;
pub use persistence::NAMESPACE_METRICS;
pub use persistence::PERSIST_TTL_SECONDS;
pub use persistence::RedisHandler;
pub use rate_limiter::RateLimiter;
pub use utils::hash_ip;
pub use utils::truncate_payload;

Modules§

agent
The GuardAgent: buffered telemetry ingestion with at-least-once flush, per-kind failure backoff, degraded-state computation, and optional durable persistence.
bridgeguard-core
The guard-core-rs engine seam: GuardAgentTelemetry implements the facade’s TelemetryHandler sink trait.
circuit_breaker
Client-side circuit breaker guarding the ingestion endpoint.
config
Agent configuration and validation.
encryption
AES-256-GCM payload encryption, mirroring guard_agent/encryption.py byte-for-byte on the wire.
error
Typed errors for the guard-agent-rs telemetry agent.
install_id
Process-scoped install identifier resolution.
logging_utils
The agent’s log-record formatters, ported from the reference logging_utils.py (JsonFormatter + the text layout).
models
Wire models mirroring the Python agent’s SecurityEvent, SecurityMetric, and AgentStatus payloads.
persistence
Optional buffer persistence.
rate_limiter
Local client-side send rate limiter.
signing
HMAC-SHA256 request signing for the X-Payload-Signature header.
transport
HTTP transport: gzip compression, HMAC signing, retries with backoff, 429 Retry-After handling, 413 split-or-drop, and permanent-rejection classification.
utils
Shared helpers: backoff math, Retry-After parsing, payload redaction, batch identifiers, and gzip compression.

Constants§

AGENT_VERSION
Version of this agent, reported in batch payloads and the User-Agent.