fastapi-guard-agent 1.1.1

Telemetry and monitoring agent for FastAPI Guard security middleware

---

FastAPI Guard Agent is an enterprise-grade telemetry and monitoring solution that seamlessly integrates with FastAPI Guard to provide centralized security intelligence. The agent automatically collects security events, performance metrics, and enables real-time security policy updates through a cloud-based management platform.

---

Documentation

🌐 Website - Check out the website!

🎮 Join our Discord Community - Connect with other developers!

📚 Documentation - Full technical documentation and deep dive into its inner workings.

---

Key Features

• Automatic Integration: Seamlessly integrates with FastAPI Guard through a unified configuration interface, requiring minimal setup for comprehensive security monitoring.
• High-Performance Architecture: Built on asynchronous I/O principles to ensure zero performance impact on your application while maintaining real-time data collection capabilities.
• Enterprise-Grade Reliability: Implements industry-standard resilience patterns including circuit breakers, exponential backoff with jitter, and intelligent retry mechanisms to guarantee data delivery.
• Intelligent Data Management: Features multi-tier buffering with in-memory and optional Redis persistence, ensuring zero data loss during network interruptions or application restarts.
• Real-Time Security Updates: Supports dynamic security policy updates from the centralized management platform, enabling immediate threat response without service interruption.
• Extensible Architecture: Designed with protocol-based abstractions, allowing seamless integration with custom transport layers, storage backends, and monitoring systems.
• Comprehensive Security Intelligence: Captures granular security events and performance metrics, providing actionable insights for security operations and compliance requirements.

---

Installation

To install fastapi-guard-agent, use pip:

pip install fastapi-guard-agent

---

Getting Started

Basic Integration

The FastAPI Guard Agent is designed for effortless integration with your existing FastAPI Guard security setup. The following example demonstrates the recommended configuration approach:

from fastapi import FastAPI
from guard import SecurityConfig, SecurityMiddleware

# Configure FastAPI Guard with built-in agent support
config = SecurityConfig(
    # Basic security settings
    auto_ban_threshold=5,
    auto_ban_duration=300,
    
    # Enable agent for telemetry
    enable_agent=True,
    agent_api_key="YOUR_API_KEY",
    agent_project_id="YOUR_PROJECT_ID",
    agent_endpoint="https://api.fastapi-guard.com",
    
    # Agent configuration
    agent_buffer_size=100,
    agent_flush_interval=30,
    agent_enable_events=True,
    agent_enable_metrics=True,
    
    # Enable dynamic rules from SaaS
    enable_dynamic_rules=True,
    dynamic_rule_interval=300,
)

app = FastAPI()

# Add security middleware - events are sent automatically
middleware = SecurityMiddleware(app, config=config)

@app.get("/")
async def root():
    return {"message": "Hello World"}

With this configuration, the agent automatically:

• Captures all security violations including IP bans, rate limit breaches, and suspicious request patterns
• Collects performance telemetry for security operations monitoring
• Synchronizes security policies from the centralized management platform
• Implements intelligent buffering for optimal network utilization
• Provides fault-tolerant operation with automatic recovery mechanisms

---

Advanced Configuration

For advanced use cases requiring direct agent control, the FastAPI Guard Agent can be configured using the AgentConfig model. This approach is typically used for custom event handling or standalone deployments:

from guard_agent.client import guard_agent
from guard_agent.models import AgentConfig

config = AgentConfig(
    api_key="YOUR_API_KEY",
    project_id="YOUR_PROJECT_ID",
)

agent = guard_agent(config)

Configuration Parameters

Authentication & Identification

• api_key: str (Required): Authentication key for the FastAPI Guard management platform
• project_id: str | None: Unique project identifier for data segregation and multi-tenancy support

Network Configuration

• endpoint: str: Management platform API endpoint (Default: https://api.fastapi-guard.com)
• timeout: int: HTTP request timeout in seconds (Default: 30)
• retry_attempts: int: Maximum retry attempts for failed requests (Default: 3)
• backoff_factor: float: Exponential backoff multiplier for retry delays (Default: 1.0)

Data Management

• buffer_size: int: Maximum events in memory buffer before automatic flush (Default: 100)
• flush_interval: int: Automatic buffer flush interval in seconds (Default: 30)
• max_payload_size: int: Maximum payload size in bytes before truncation (Default: 1024)

Feature Control

• enable_metrics: bool: Enable performance metrics collection (Default: True)
• enable_events: bool: Enable security event collection (Default: True)

Security & Privacy

• sensitive_headers: list[str]: HTTP headers to redact from collected data (Default: ["authorization", "cookie", "x-api-key"])

---

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Author

Renzo Franceschini - [e-mail]

---

Acknowledgements

• FastAPI
• Redis
• httpx
• Pydantic