Documentation

📚 Documentation - full technical documentation for this package.

🛡️ Guard Core - the engine's reference documentation.

🤖 Monitoring Agent Integration - monitor your Guard instance with a monitoring agent.

Guard Agent is an enterprise-grade, framework-agnostic telemetry and monitoring agent for the Guard security ecosystem. It integrates with fastapi-guard, flaskapi-guard, djangoapi-guard, and tornadoapi-guard to provide centralized security intelligence, real-time policy updates, and comprehensive event collection across any Python web framework.

Website · Docs · Playground · Dashboard · Discord

Framework-agnostic security telemetry for Python web apps.
Feeds the Guard dashboard with events, metrics, and dynamic rules from any supported adapter.

Renamed from fastapi-guard-agent. As of guard-agent 2.0.0, the package has been renamed to reflect its multi-framework scope. The Python import path (from guard_agent import ...) is unchanged. Existing pip install fastapi-guard-agent commands continue to work via a meta-package that transitively pulls the renamed distribution.

Documentation & Platform

• 🌐 guard-core.com — marketing site & product overview
• 📚 Documentation — full technical documentation
• 🎮 Playground — try the Guard stack in-browser, no install required
• 📊 Dashboard — real-time security events, metrics, and dynamic rules for your projects
• 💬 Discord — community & maintainer support

Ecosystem

Guard Core is the Python engine. Framework adapters are thin wrappers that translate native request/response types into Guard Core's protocols. The telemetry agents ship security events and metrics to the monitoring backend. Parallel engine implementations exist for Go, PHP, TypeScript (on npm), and Rust (on crates.io) - all ports of the same reference semantics, conformance-tested against the shared adversarial corpus.

Python

Package	Role	PyPI
guard-core	Framework-agnostic security engine
guard-agent	Telemetry agent
fastapi-guard	FastAPI / Starlette adapter
flaskapi-guard	Flask adapter
djapi-guard	Django adapter
tornadoapi-guard	Tornado adapter

Go

Go modules published via GitHub releases. Production-ready.

Package	Role	Release
guard-core-go	Go engine
nethttp-guard	net/http adapter
gin-guard	Gin adapter
echo-guard	Echo (v4) adapter
fiber-guard	Fiber (v3) adapter
guard-agent-go	Telemetry agent

PHP

Published on Packagist under the rennf93 vendor. Production-ready.

Package	Role	Packagist
guard-core-php	PHP engine
laravel-guard	Laravel adapter
symfony-guard	Symfony adapter
psr15-guard	PSR-15 adapter
slim-guard	Slim 4 adapter
guard-agent-php	Telemetry agent

TypeScript / JavaScript

Published under the @guardcore npm scope; source in the guard-core-ts monorepo. Production-ready.

Package	Role	npm
	@guardcore/core	Core engine
@guardcore/express	Express adapter
@guardcore/nestjs	NestJS adapter
@guardcore/fastify	Fastify adapter
@guardcore/hono	Hono (edge) adapter
guardagent	Telemetry agent

Rust

Published on crates.io. Production-ready.

Package	Role	crates.io
guard-core-engine	Core engine crate
guard-core-rs	Facade crate (consumer entry point)
actix-guard-rs	Actix Web adapter
axum-guard-rs	Axum adapter
tower-guard-rs	Tower adapter
rocket-guard-rs	Rocket adapter
guard-agent-rs	Telemetry agent

AI Coding Agents

Package	Role	PyPI
guard-core-mcp	MCP server: config validation, docs search, detection sandbox

Key Features

• Framework-Agnostic Core: One agent, one dashboard — works with every Guard adapter (FastAPI, Flask, Django, Tornado) through a shared wire protocol.
• Automatic Integration: Adapters wire the agent into their middleware automatically. Enable it through the adapter's SecurityConfig — no glue code required.
• 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.
• Instrumentation-Safe by Default: Mutes pydantic plugin instrumentation (e.g. logfire.instrument_pydantic()) on its own telemetry models at import, so a host app doesn't get a validation span per security event without doing anything itself.

Installation

uv add guard-agent

Alternatives:

poetry add guard-agent

pip install guard-agent

The legacy name fastapi-guard-agent is still published as a meta-package that installs guard-agent transitively — existing installs keep working, but new projects should use guard-agent directly.

Optional extras:

uv add "guard-agent[redis]"    # Enable Redis-backed event buffer

Getting Started

Guard Agent is embedded by your framework's adapter — you enable it through the adapter's SecurityConfig and drive its lifecycle appropriately for that framework. Each adapter's doc page covers the exact pattern; the FastAPI pattern below is the canonical async integration.

FastAPI example

With fastapi-guard, the SecurityMiddleware owns the agent lifecycle: enable it through SecurityConfig and the middleware starts and stops the flush loop on the app's event loop for you. Do not construct an AgentConfig, call guard_agent(), or wire a lifespan hook here --- that creates a second agent that never receives traffic.

import os

from fastapi import FastAPI
from guard import SecurityConfig, SecurityDecorator, SecurityMiddleware

api_key = os.environ.get("GUARD_API_KEY", "")
project_id = os.environ.get("GUARD_PROJECT_ID", "")
core_url = os.environ.get("GUARD_CORE_URL", "https://api.guard-core.com")

security_config = SecurityConfig(
    auto_ban_threshold=5,
    auto_ban_duration=300,
    enable_agent=bool(api_key),
    agent_api_key=api_key,
    agent_endpoint=core_url,
    agent_project_id=project_id,
    agent_buffer_size=100,
    agent_flush_interval=2,
    enable_dynamic_rules=bool(api_key),
    dynamic_rule_interval=60,
)

guard = SecurityDecorator(security_config)

app = FastAPI()
app.add_middleware(SecurityMiddleware, config=security_config)
SecurityMiddleware.configure_cors(app, security_config)
app.state.guard_decorator = guard


@app.get("/")
async def root() -> dict[str, str]:
    return {"message": "Hello World"}

Flask is synchronous and handles start/stop internally; Tornado uses await security_middleware.initialize() / reset(); Django wires the middleware via settings. See docs/adapters for the canonical pattern per framework.

With enable_agent=True, the agent automatically:

• Captures security violations (IP bans, rate-limit breaches, 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
• Recovers automatically from transient network failures

Advanced Configuration

For standalone use or custom event handling with no adapter middleware in the same process, instantiate the agent directly:

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)

Do not do this in a process that also runs an adapter with enable_agent=True. guard_agent() dispatches to SyncGuardAgentHandler from sync module-load context but to GuardAgentHandler from the middleware's async init, so the two are separate singletons and only the middleware's instance receives traffic. Configure agent_* fields on SecurityConfig instead.

Configuration Parameters

Authentication & Identification

• api_key: str (Required): Authentication key for the 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.guard-core.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)
• buffer_overflow_policy: Literal["drop", "block", "raise"]: Behavior when the in-memory buffer is full (Default: "drop")
  • "drop": silently evict the oldest entry; production-safe for high-throughput, loses events when the SaaS endpoint is unreachable
  • "block": backpressure the caller until a flush frees space; appropriate when event integrity matters more than request latency
  • "raise": throw BufferFullError so callers can react; appropriate in tests or strict environments

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"])

Migration from fastapi-guard-agent

No code changes required. The import path was always guard_agent:

# This worked before and still works:
from guard_agent import GuardAgentHandler, AgentConfig

To switch your install command:

# Old (still works via shim)
uv add fastapi-guard-agent

# New (preferred)
uv add guard-agent

Equivalent in other package managers:

# Poetry
poetry remove fastapi-guard-agent && poetry add guard-agent

# pip (or pip-tools)
pip uninstall fastapi-guard-agent && pip install guard-agent

The legacy fastapi-guard-agent name is maintained as a meta-package pointing to guard-agent>=2.0.0,<3.0.0, so pinned environments keep resolving correctly.

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 - contact@guard-core.com

Acknowledgements

• FastAPI
• Flask
• Django
• Tornado
• Redis
• httpx
• Pydantic