guard-core 2.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, penetration detection, security headers, and behavioral analysis 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.
• Behavioral Analysis: Usage monitoring, return pattern detection, frequency analysis.
• 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.

---

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.

---

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: Anomaly detection, slow pattern tracking, statistical analysis.

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