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 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

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 16 iterations covering URL (including percent-U escapes and overlong-UTF-8 percent runs), HTML entities, base64, hex, Unicode escapes, and LDAP hex escapes, then a final SQL-comment strip.
2. Decoded content is matched against 157 regex patterns across 19 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/Guard-Core/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 - contact@guard-core.com

Acknowledgements

• Pydantic
• Redis
• aiohttp
• cachetools
• MaxMind DB