guard-core is the framework-agnostic security engine that powers the Guard ecosystem. It provides IP control, rate limiting, signature-based attack-pattern detection, security headers, and threshold-based behavior tracking through a protocol-based architecture. Framework-specific adapters (fastapi-guard, flaskapi-guard, djapi-guard) consume this library.

Website · Docs · Playground · Dashboard · Discord

Documentation

📚 Documentation - Full technical documentation for adapter developers.

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

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 agent ships security events and metrics to the monitoring backend. Parallel implementations exist for TypeScript (on npm) and Rust (on crates.io).

Python

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

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 adapter

Rust

Published on crates.io. 🚧 Placeholder crates — implementation in progress.

Package	Role	crates.io
guard-core	Core engine
actix-guard-rs	Actix adapter
axum-guard-rs	Axum adapter
rocket-guard-rs	Rocket adapter
tower-guard-rs	Tower adapter

AI Coding Agents

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

An MCP server that answers questions about Guard Core from the version installed in your project, rather than from a model's memory of it. It validates a config against the real SecurityConfig model — catching silently-ignored typos like redis_failopen — looks up any field's type, default and description, searches the bundled docs, and runs a payload through the real detection engine to show whether it would be blocked and by which pattern.

uv add --dev guard-core-mcp
claude mcp add guard-core -- uv run guard-core-mcp

Install it into the same environment as Guard Core — it introspects what is actually installed there, so an isolated run (uvx) has nothing to read.

Adapter developers implement three protocols (GuardRequest, GuardResponse, and GuardResponseFactory) to bridge their framework into the security pipeline. Everything else (the 17-check catalogue, detection engine, Redis state, event telemetry) works out of the box.

Features

• IP Whitelisting and Blacklisting: Control access based on IP addresses and CIDR ranges.
• User Agent Filtering: Block requests from specific user agents.
• Rate Limiting: Sliding window algorithm with in-memory and Redis-backed storage.
• Automatic IP Banning: Threshold-based banning with configurable duration.
• Penetration Attempt Detection: SQL injection, XSS, command injection, path traversal detection with semantic analysis.
• HTTP Security Headers: CSP, HSTS, X-Frame-Options, and OWASP best practices.
• Cloud Provider IP Blocking: Block requests from AWS, GCP, Azure IP ranges.
• IP Geolocation: Country-based access control via GeoIP databases.
• Threshold-Based Behavior Tracking: Per-IP request counting, response-pattern matching, suspicious-frequency triggers (deterministic threshold matching, not learning-based).
• Security Decorators: Route-level security with composable decorator mixins.
• Detection Engine: Multi-layered threat detection with regex, semantic analysis, and performance monitoring.
• Distributed State Management: Redis integration for shared state across instances.
• Protocol-Based Architecture: Framework-agnostic via GuardRequest/GuardResponse protocols.

How Detection Works

1. Request inputs (query, headers, body) are decoded through up to 7 iterations covering URL, HTML entities, base64, hex, and Unicode escapes, then a final SQL-comment strip.
2. Decoded content is matched against 88 regex patterns across 18 attack categories, with patterns context-filtered to relevant input zones.
3. Matched payloads receive a multi-metric semantic score combining keyword overlap, Shannon entropy, encoding-layer count, and obfuscation indicators.
4. ReDoS protection rejects any custom pattern whose validation probe runs longer than 50ms, and caps every custom pattern's live match at detection_compiler_timeout (default 2.0s, configurable 0.1-10.0s). Built-in patterns match directly with no per-match timeout.

The engine is signature-based with multi-metric semantic scoring on top. It is not machine-learning-based and does not learn from traffic.

Installation

pip install guard-core

For Adapter Developers

If you're building a framework adapter, add guard-core as a dependency:

[project]
dependencies = [
    "guard-core",
]

Then implement the three protocols:

from guard_core.protocols import GuardRequest, GuardResponse, GuardResponseFactory

class MyFrameworkRequest:
    """Wraps your framework's request into GuardRequest protocol."""

    def __init__(self, native_request):
        self._request = native_request

    @property
    def url_path(self) -> str:
        return self._request.path

    @property
    def method(self) -> str:
        return self._request.method

    @property
    def client_host(self) -> str | None:
        return self._request.remote_addr

    @property
    def headers(self):
        return dict(self._request.headers)

    # ... implement remaining protocol properties

See the Building Adapters Guide for the complete walkthrough.

Security Pipeline

Guard Core ships a catalogue of 17 security checks, run in this fixed order:

1. Route configuration extraction
2. Emergency mode
3. HTTPS enforcement
4. Request logging
5. Size/content validation
6. Required headers
7. Authentication
8. Referrer validation
9. Custom validators
10. Time windows
11. Cloud IP refresh
12. IP security (whitelist/blacklist)
13. Cloud provider blocking
14. User agent filtering
15. Rate limiting
16. Suspicious activity detection
17. Custom request checks

A deployment's actual pipeline is usually a subset: each check declares an applies_to(config, route_configs) classmethod, and only checks whose effective configuration can trigger them are built. IpSecurityCheck is never eliminated. A default SecurityConfig() with no route decorators registered builds just route_config, ip_security, rate_limit, and suspicious_activity. See the Pipeline Architecture for the elimination rules.

Each check returns None (pass) or a GuardResponse (block). The pipeline short-circuits on the first blocking response.

SecurityConfig

All behavior is controlled through SecurityConfig:

from guard_core.models import SecurityConfig

config = SecurityConfig(
    whitelist=["192.168.1.0/24"],
    blacklist=["10.0.0.1"],
    blocked_user_agents=["curl", "wget"],
    auto_ban_threshold=5,
    auto_ban_duration=86400,
    rate_limit=100,
    rate_limit_window=60,
    enforce_https=True,
    block_cloud_providers={"AWS", "GCP", "Azure"},
    enable_redis=True,
    redis_url="redis://localhost:6379",
)

See the SecurityConfig Reference for all fields.

Migration: fail_secure default flipped

SecurityConfig.fail_secure now defaults to True. When a security check raises an unexpected exception, the request is blocked with HTTP 500 instead of falling through.

Why: the old fail-open default silently masked check bugs. The new default surfaces them so they can be fixed instead of leaking past the security layer.

Migration: to restore the previous fail-open behavior, opt in explicitly:

config = SecurityConfig(fail_secure=False)

Recommended path: keep the new default and fix any check exceptions that surface. The old default could mask genuine bugs.

Detection Engine

Multi-layered threat detection:

• PatternCompiler: ReDoS-safe regex compilation with LRU caching and timeout protection.
• ContentPreprocessor: Unicode normalization, encoding detection, attack-region-aware truncation.
• SemanticAnalyzer: Attack probability scoring, entropy analysis, obfuscation detection.
• PerformanceMonitor: Slow-pattern detection via execution-time statistics (mean/stddev thresholds), not anomaly learning.

See the Detection Engine Internals for details.

Redis Integration

Distributed state management across multiple instances:

config = SecurityConfig(
    enable_redis=True,
    redis_url="redis://prod-redis:6379/1",
    redis_prefix="myapp:security:",
)

Provides atomic rate limiting, distributed IP ban tracking, cloud IP range caching, and pattern storage.

Development

# Clone and install
git clone https://github.com/rennf93/guard-core.git
cd guard-core
make install-dev

# Run tests (100% coverage)
make local-test

# Run all quality checks
make check-all

# Serve documentation
make serve-docs

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 - rennf93@users.noreply.github.com

Acknowledgements

• Pydantic
• Redis
• aiohttp
• cachetools
• MaxMind DB