Skip to content

Guard Core

Guard Core Logo

PyPI version Release License: MIT CI CodeQL

guard-core is the framework-agnostic security engine that provides IP control, rate limiting, penetration detection, security headers, and behavioral analysis through a protocol-based architecture. It is designed to be consumed by framework-specific adapters -- not directly by end users.

graph TD
    GC["guard-core"]
    GC --> FG["fastapi-guard"]
    GC --> FlG["flaskapi-guard"]
    GC --> DG["djapi-guard"]
    FG --> FA["FastAPI App"]
    FlG --> FlA["Flask App"]
    DG --> DA["Django App"]

Adapter developers implement three protocols -- GuardRequest, GuardResponse, and GuardResponseFactory -- to bridge their framework's native objects into guard-core's security pipeline. Everything else (17 security checks, the detection engine, Redis state management, event telemetry) works out of the box.

What it's useful for

It catches the HTTP-layer attacks an automated, AI-orchestrated attacker runs at scale:

  • Polymorphic payloads — variation-based SQLi/XSS that defeats signature WAFs (token-overlap scoring catches them)
  • Reconnaissance — endpoint enumeration, 404 spam, honeypot probing, banner grabbing
  • Distributed attacks — when paired with behavioral patterns enabled (per-IP rate limits alone are not enough)
  • Known bad actors — country/cloud/tor blocking, IP reputation
  • Layer-7 abuse — auto-ban thresholds, custom rate limits per route, CORS enforcement, security headers

It does not cover prompt injection against LLM endpoints, model-output exfiltration, application-logic vulnerabilities (auth bypass, IDOR, business-logic flaws), or network-layer DDoS — those are out-of-scope by design and belong to other layers of your stack.

If you're integrating into FastAPI, jump straight to the fastapi-guard Integration Guide — it has the decision tree across standalone / SaaS / encrypted-SaaS paths and the common pitfalls.

Key Design Properties

  • Protocol-based contracts: GuardRequest, GuardResponse, and GuardResponseFactory are typing.Protocol classes with @runtime_checkable. Your adapter implements them; guard-core consumes them.
  • 17 security checks in a chain-of-responsibility pipeline: Each check is an independent SecurityCheck subclass. The SecurityCheckPipeline executes them in order and short-circuits on the first blocking response.
  • Dependency injection via context dataclasses: Every core module receives its dependencies through a typed context object (ResponseContext, RoutingContext, ValidationContext, BypassContext, BehavioralContext).
  • Singleton handlers with async initialization: ip_ban_manager, cloud_handler, rate_limit_handler, sus_patterns_handler, and redis_handler are module-level singletons initialized through HandlerInitializer.
  • Detection engine: Regex-based and semantic attack pattern detection with configurable thresholds, timeouts, and content length limits.
  • Redis-backed distributed state: Rate limits, IP bans, cloud IP ranges, and suspicious pattern counts persist across instances when Redis is enabled. Falls back to in-memory storage automatically.
  • Event system: SecurityEventBus dispatches security events and MetricsCollector tracks request metrics, both feeding into the optional guard-agent telemetry platform.

Install

uv add guard-core

poetry add guard-core

pip install guard-core

Python 3.10+

guard-core requires Python 3.10 or higher.

Documentation

For Adapter Developers

API Reference

Upgrading