guard-core 3.0.0

Framework-agnostic security engine for the Guard ecosystem.

---

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

Adapter developers implement three protocols — GuardRequest, GuardResponse, and GuardResponseFactory — to bridge their framework into the security pipeline. Everything else (17 security checks, 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 layers covering URL, HTML entities, base64, hex, Unicode escapes, and SQL comments.
2. Decoded content is matched against ~64 regex patterns across 16 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 enforces a 0.1s pattern-validation timeout and a 2-5s match timeout per pattern.

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 executes 17 security checks in order for every request:

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

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_countries=["CN"],
    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 - [e-mail]

---

Acknowledgements

• Pydantic
• Redis
• httpx
• cachetools
• MaxMind DB