Metadata-Version: 2.5
Name: fastapi_guard
Version: 8.1.1
Summary: Production-ready security middleware for FastAPI — IP filtering, rate limiting, penetration detection, and 20+ per-route security decorators.
Project-URL: Homepage, https://guard-core.com
Project-URL: Documentation, https://guard-core.github.io/fastapi-guard/latest/
Project-URL: Repository, https://github.com/Guard-Core/fastapi-guard
Project-URL: Changelog, https://github.com/Guard-Core/fastapi-guard/blob/master/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/Guard-Core/fastapi-guard/issues
Project-URL: Cloud Dashboard, https://app.guard-core.com
Project-URL: Live Playground, https://playground.guard-core.com
Author-email: Renzo Franceschini <rennf93@guard-core.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api-security,fastapi,ip-filtering,middleware,penetration-detection,rate-limiting,security,waf
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.10
Requires-Dist: fastapi>=0.109.0
Requires-Dist: guard-core>=4.4.0
Requires-Dist: starlette>=0.35.0
Requires-Dist: uvicorn
Provides-Extra: agent
Requires-Dist: guard-agent; extra == 'agent'
Provides-Extra: dev
Requires-Dist: aiohttp; extra == 'dev'
Requires-Dist: bandit[toml]; extra == 'dev'
Requires-Dist: deptry; extra == 'dev'
Requires-Dist: guard-agent; extra == 'dev'
Requires-Dist: httpx; extra == 'dev'
Requires-Dist: httpx2; extra == 'dev'
Requires-Dist: matplotlib; extra == 'dev'
Requires-Dist: mkdocs; extra == 'dev'
Requires-Dist: mkdocs-material; extra == 'dev'
Requires-Dist: mkdocstrings; extra == 'dev'
Requires-Dist: mkdocstrings-python; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: numpy; extra == 'dev'
Requires-Dist: pip-audit; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pymarkdownlnt; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-mock; extra == 'dev'
Requires-Dist: radon; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: safety; extra == 'dev'
Requires-Dist: types-cachetools; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Requires-Dist: vulture; extra == 'dev'
Requires-Dist: xenon; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
    <a href="https://guard-core.github.io/fastapi-guard/latest/">
        <img src="https://raw.githubusercontent.com/Guard-Core/fastapi-guard/master/docs/assets/fastapi_guard_legend.svg" alt="FastAPI Guard">
    </a>
</p>

<p align="center">
  <a href="https://badge.fury.io/py/fastapi-guard"><img src="https://badge.fury.io/py/fastapi-guard.svg?cache=none" alt="PyPI version"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://github.com/Guard-Core/fastapi-guard/actions/workflows/ci.yml"><img src="https://github.com/Guard-Core/fastapi-guard/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/Guard-Core/fastapi-guard/actions/workflows/release.yml"><img src="https://github.com/Guard-Core/fastapi-guard/actions/workflows/release.yml/badge.svg" alt="Release"></a>
  <a href="https://github.com/Guard-Core/fastapi-guard/actions/workflows/code-ql.yml"><img src="https://github.com/Guard-Core/fastapi-guard/actions/workflows/code-ql.yml/badge.svg" alt="CodeQL"></a>
  <a href="https://guard-core.github.io/fastapi-guard/latest/"><img src="https://img.shields.io/badge/Docs-latest-blue.svg" alt="Docs"></a>
  <a href="https://pepy.tech/project/fastapi-guard"><img src="https://pepy.tech/badge/fastapi-guard" alt="Downloads"></a>
</p>

<p align="center">
  <a href="https://guard-core.com">Website</a> &middot;
  <a href="https://guard-core.github.io/fastapi-guard/latest/">Docs</a> &middot;
  <a href="https://playground.guard-core.com">Playground</a> &middot;
  <a href="https://app.guard-core.com">Dashboard</a> &middot;
  <a href="https://discord.gg/ZW7ZJbjMkK">Discord</a>
</p>

<p align="center">
    <a href="https://peerpush.com/p/guard-core" target="_blank" rel="noopener" style="width: 230px;"><img src="https://peerpush.com/p/guard-core/badge.png" alt="Guard Core badge" style="width: 230px;" /></a>
</p>

<p align="center">
  Production-ready security middleware for FastAPI.<br>
  IP filtering, rate limiting, signature-based attack-pattern detection, and 20+ per-route security decorators.
</p>

---

<table align="center">
<tr>
<td align="center" width="50%">

### 📋 Using this in production?

**[Tell me what is working and what is not →](https://forms.gle/ZpjkQgT7KGWgRoQP7)**

Six minutes. It decides what gets built next.<br>
Anonymous unless you choose otherwise.

</td>
<td align="center" width="50%">

### 📊 State of FastAPI Security 2026

**[Take the survey →](https://forms.gle/7npRKzN8BZLfZj326)**

Five minutes, nothing to sign up for.<br>
Results published publicly, free for everyone.

</td>
</tr>
</table>

---

## Quick Start

```bash
uv add fastapi-guard        # uv (recommended)
pip install fastapi-guard    # pip
poetry add fastapi-guard     # poetry
```

---

## Example

```python
from fastapi import FastAPI
from guard import SecurityMiddleware, SecurityConfig

app = FastAPI()

config = SecurityConfig(
    enable_rate_limiting=True,
    rate_limit=100,
    rate_limit_window=60,
    enable_ip_banning=True,
    auto_ban_threshold=5,
    auto_ban_duration=86400,
    custom_log_file="security.log",
    enforce_https=True,
    enable_cors=True,
    cors_allow_origins=["*"],
    cors_allow_methods=["GET", "POST"],
    cors_allow_headers=["*"],
    cors_allow_credentials=True,
    cors_expose_headers=["X-Custom-Header"],
    cors_max_age=600,
    block_cloud_providers={"AWS", "GCP", "Azure"},
)

app.add_middleware(SecurityMiddleware, config=config)
```

For production, wire `guard.lifespan.guard_lifespan` into `FastAPI(lifespan=...)` so initialization runs at app startup instead of on the first request, see [Eager initialization](https://guard-core.github.io/fastapi-guard/latest/tutorial/first-steps/#eager-initialization-with-fastapi-lifespan).

A connection with no client address (a Unix domain socket, some serverless ASGI adapters) is rejected with 403 by default (`fail_secure=True`); set `fail_secure=False` to run the pipeline with identity `"unknown"` instead, allowed unless a whitelist or a country allow-list is configured (blacklist, country, and cloud checks cannot match without an address; detection and the shared rate-limit bucket still apply). Add the literal string `"unix"` to `trusted_proxies` to resolve the real client from `X-Forwarded-For` on such a connection, see [Proxy Security](https://guard-core.github.io/fastapi-guard/latest/tutorial/security/proxy-security/#unix-sockets-and-serverless-adapters).

`SecurityMiddleware` protects HTTP requests only; it never runs for WebSocket connections. Secure a `@app.websocket` route explicitly with `Depends(guard_websocket)`, see [WebSockets](https://guard-core.github.io/fastapi-guard/latest/tutorial/websockets/).

---

## Per-Route Security Decorators

Apply security rules at the endpoint level with composable decorators:

```python
from guard import SecurityConfig, SecurityDecorator

config = SecurityConfig(
    auth_verifier=lambda request, credential: {"user": "demo"} if credential else None,
)
guard = SecurityDecorator(config)


@app.get("/api/payments")
@guard.require_auth(type="bearer")
@guard.rate_limit(requests=10, window=60)
@guard.block_countries(["CN", "RU"])
@guard.require_https()
async def process_payment():
    return {"status": "ok"}
```

`require_auth` and `api_key_auth` require a verifier (per-route `verifier=` or global `SecurityConfig.auth_verifier`); without one the request is rejected with 401. For a presence-only `Authorization` header gate, use `require_authorization_header(scheme="bearer")` instead. See [the authentication tutorial](https://guard-core.github.io/fastapi-guard/latest/tutorial/decorators/authentication/) for the full migration.

**Available decorator categories:**

- **Access** --- `require_ip`, `block_countries`, `allow_countries`, `block_clouds`, `bypass`
- **Auth** --- `require_https`, `require_auth`, `api_key_auth`, `require_headers`
- **Rate Limiting** --- `rate_limit`, `geo_rate_limit`
- **Content** --- `block_user_agents`, `content_type_filter`, `max_request_size`, `require_referrer`, `custom_validation`, `detection_exclusion`
- **Behavioral** --- `usage_monitor`, `return_monitor`, `suspicious_frequency`, `behavior_analysis`
- **Advanced** --- `time_window`, `honeypot_detection`, `suspicious_detection`

[Full decorator reference](https://guard-core.github.io/fastapi-guard/latest/api/decorators/)

---

## Cloud Dashboard

FastAPI Guard has a centralized cloud platform for real-time monitoring and threat analysis across all your applications.

- **[Dashboard](https://app.guard-core.com)** --- real-time security events, threat intelligence, attack pattern analytics
- **[Playground](https://playground.guard-core.com)** --- try every security feature in-browser with real attack data from a live server
- **Dynamic Rules** --- update security configuration from the dashboard without redeploying
- **GDPR Tools** --- consent management, data export, account deletion

Connect your existing setup in 2 minutes:

```bash
uv add guard-agent    # or: pip install guard-agent
```

```python
from fastapi import FastAPI
from guard import SecurityConfig, SecurityMiddleware

security_config = SecurityConfig(
    enable_agent=True,
    agent_api_key="your-api-key",
    agent_endpoint="https://api.guard-core.com",
    agent_project_id="your-project-id",
    agent_buffer_size=100,
    agent_flush_interval=2,
    agent_enable_events=True,
    agent_enable_metrics=True,
    enable_dynamic_rules=True,
    dynamic_rule_interval=60,
)

app = FastAPI()
app.add_middleware(SecurityMiddleware, config=security_config)
```

That is the entire integration. The middleware drives the agent's lifecycle for you --- **do not** import `guard_agent`, construct an `AgentConfig`, or wire a `lifespan` hook when using fastapi-guard; doing so spins up a second agent that never sees traffic.

Free tier includes 10,000 events/month --- no credit card required.

> The core library is fully self-contained and MIT licensed. The cloud dashboard is optional.

### Monitoring agent buffer health

When `enable_agent=True`, the middleware exposes an `agent_stats` property that returns the current buffer drop counters and transport circuit-breaker state without needing to reach into the agent directly:

```python
middleware: SecurityMiddleware = ...

stats = middleware.agent_stats
# {"enabled": True, "buffer_stats": {"events_dropped": 0, "metrics_dropped": 0, ...},
#  "transport_stats": {"circuit_breaker_state": "CLOSED", ...}, ...}
```

When the agent is disabled or failed to initialize, the property returns `{"enabled": False}`. Read it on each scrape; it reflects live counters and is not cached.

---

## 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](https://github.com/Guard-Core/guard-core) | Framework-agnostic security engine | [![PyPI](https://img.shields.io/pypi/v/guard-core)](https://pypi.org/project/guard-core/) |
| [guard-agent](https://github.com/Guard-Core/guard-agent) | Telemetry agent | [![PyPI](https://img.shields.io/pypi/v/guard-agent)](https://pypi.org/project/guard-agent/) |
| [fastapi-guard](https://github.com/Guard-Core/fastapi-guard) | FastAPI / Starlette adapter | [![PyPI](https://img.shields.io/pypi/v/fastapi-guard)](https://pypi.org/project/fastapi-guard/) |
| [flaskapi-guard](https://github.com/Guard-Core/flaskapi-guard) | Flask adapter | [![PyPI](https://img.shields.io/pypi/v/flaskapi-guard)](https://pypi.org/project/flaskapi-guard/) |
| [djapi-guard](https://github.com/Guard-Core/djapi-guard) | Django adapter | [![PyPI](https://img.shields.io/pypi/v/djapi-guard)](https://pypi.org/project/djapi-guard/) |
| [tornadoapi-guard](https://github.com/Guard-Core/tornadoapi-guard) | Tornado adapter | [![PyPI](https://img.shields.io/pypi/v/tornadoapi-guard)](https://pypi.org/project/tornadoapi-guard/) |

### Go

Go modules published via GitHub releases. **Production-ready.**

| Package | Role | Release |
|---|---|---|
| [guard-core-go](https://github.com/Guard-Core/guard-core-go) | Go engine | [![release](https://img.shields.io/github/v/tag/Guard-Core/guard-core-go?label=tag)](https://github.com/Guard-Core/guard-core-go/releases) |
| [nethttp-guard](https://github.com/Guard-Core/nethttp-guard) | net/http adapter | [![release](https://img.shields.io/github/v/tag/Guard-Core/nethttp-guard?label=tag)](https://github.com/Guard-Core/nethttp-guard/releases) |
| [gin-guard](https://github.com/Guard-Core/gin-guard) | Gin adapter | [![release](https://img.shields.io/github/v/tag/Guard-Core/gin-guard?label=tag)](https://github.com/Guard-Core/gin-guard/releases) |
| [echo-guard](https://github.com/Guard-Core/echo-guard) | Echo (v4) adapter | [![release](https://img.shields.io/github/v/tag/Guard-Core/echo-guard?label=tag)](https://github.com/Guard-Core/echo-guard/releases) |
| [fiber-guard](https://github.com/Guard-Core/fiber-guard) | Fiber (v3) adapter | [![release](https://img.shields.io/github/v/tag/Guard-Core/fiber-guard?label=tag)](https://github.com/Guard-Core/fiber-guard/releases) |
| [guard-agent-go](https://github.com/Guard-Core/guard-agent-go) | Telemetry agent | [![release](https://img.shields.io/github/v/tag/Guard-Core/guard-agent-go?label=tag)](https://github.com/Guard-Core/guard-agent-go/releases) |

### PHP

Published on [Packagist](https://packagist.org/) under the `rennf93` vendor. **Production-ready.**

| Package | Role | Packagist |
|---|---|---|
| [guard-core-php](https://github.com/Guard-Core/guard-core-php) | PHP engine | [![Packagist](https://img.shields.io/packagist/v/rennf93/guard-core-php)](https://packagist.org/packages/rennf93/guard-core-php) |
| [laravel-guard](https://github.com/Guard-Core/laravel-guard) | Laravel adapter | [![Packagist](https://img.shields.io/packagist/v/rennf93/laravel-guard)](https://packagist.org/packages/rennf93/laravel-guard) |
| [symfony-guard](https://github.com/Guard-Core/symfony-guard) | Symfony adapter | [![Packagist](https://img.shields.io/packagist/v/rennf93/symfony-guard)](https://packagist.org/packages/rennf93/symfony-guard) |
| [psr15-guard](https://github.com/Guard-Core/psr15-guard) | PSR-15 adapter | [![Packagist](https://img.shields.io/packagist/v/rennf93/psr15-guard)](https://packagist.org/packages/rennf93/psr15-guard) |
| [slim-guard](https://github.com/Guard-Core/slim-guard) | Slim 4 adapter | [![Packagist](https://img.shields.io/packagist/v/rennf93/slim-guard)](https://packagist.org/packages/rennf93/slim-guard) |
| [guard-agent-php](https://github.com/Guard-Core/guard-agent-php) | Telemetry agent | [![Packagist](https://img.shields.io/packagist/v/rennf93/guard-agent-php)](https://packagist.org/packages/rennf93/guard-agent-php) |

### TypeScript / JavaScript

Published under the [`@guardcore`](https://www.npmjs.com/org/guardcore) npm scope; source in the [guard-core-ts](https://github.com/Guard-Core/guard-core-ts) monorepo. **Production-ready.**

| Package | Role | npm |
|---|---|---|
| | [@guardcore/core](https://github.com/Guard-Core/guard-core-ts/tree/master/packages/core) | Core engine | [![npm](https://img.shields.io/npm/v/@guardcore%2Fcore)](https://www.npmjs.com/package/@guardcore/core) |
| [@guardcore/express](https://github.com/Guard-Core/guard-core-ts/tree/master/packages/express) | Express adapter | [![npm](https://img.shields.io/npm/v/@guardcore%2Fexpress)](https://www.npmjs.com/package/@guardcore/express) |
| [@guardcore/nestjs](https://github.com/Guard-Core/guard-core-ts/tree/master/packages/nestjs) | NestJS adapter | [![npm](https://img.shields.io/npm/v/@guardcore%2Fnestjs)](https://www.npmjs.com/package/@guardcore/nestjs) |
| [@guardcore/fastify](https://github.com/Guard-Core/guard-core-ts/tree/master/packages/fastify) | Fastify adapter | [![npm](https://img.shields.io/npm/v/@guardcore%2Ffastify)](https://www.npmjs.com/package/@guardcore/fastify) |
| [@guardcore/hono](https://github.com/Guard-Core/guard-core-ts/tree/master/packages/hono) | Hono (edge) adapter | [![npm](https://img.shields.io/npm/v/@guardcore%2Fhono)](https://www.npmjs.com/package/@guardcore/hono) |
| [guardagent](https://github.com/Guard-Core/guard-agent-ts) | Telemetry agent | [![npm](https://img.shields.io/npm/v/guardagent)](https://www.npmjs.com/package/guardagent) |

### Rust

Published on crates.io. **Production-ready.**

| Package | Role | crates.io |
|---|---|---|
| [guard-core-engine](https://github.com/Guard-Core/guard-core-rs) | Core engine crate | [![crates.io](https://img.shields.io/crates/v/guard-core-engine)](https://crates.io/crates/guard-core-engine) |
| [guard-core-rs](https://github.com/Guard-Core/guard-core-rs) | Facade crate (consumer entry point) | [![crates.io](https://img.shields.io/crates/v/guard-core-rs)](https://crates.io/crates/guard-core-rs) |
| [actix-guard-rs](https://github.com/Guard-Core/actix-guard-rs) | Actix Web adapter | [![crates.io](https://img.shields.io/crates/v/actix-guard-rs)](https://crates.io/crates/actix-guard-rs) |
| [axum-guard-rs](https://github.com/Guard-Core/axum-guard-rs) | Axum adapter | [![crates.io](https://img.shields.io/crates/v/axum-guard-rs)](https://crates.io/crates/axum-guard-rs) |
| [tower-guard-rs](https://github.com/Guard-Core/tower-guard-rs) | Tower adapter | [![crates.io](https://img.shields.io/crates/v/tower-guard-rs)](https://crates.io/crates/tower-guard-rs) |
| [rocket-guard-rs](https://github.com/Guard-Core/rocket-guard-rs) | Rocket adapter | [![crates.io](https://img.shields.io/crates/v/rocket-guard-rs)](https://crates.io/crates/rocket-guard-rs) |
| [guard-agent-rs](https://github.com/Guard-Core/guard-agent-rs) | Telemetry agent | [![crates.io](https://img.shields.io/crates/v/guard-agent-rs)](https://crates.io/crates/guard-agent-rs) |

### AI Coding Agents

| Package | Role | PyPI |
|---|---|---|
| [guard-core-mcp](https://github.com/Guard-Core/guard-core-mcp) | MCP server: config validation, docs search, detection sandbox | [![PyPI](https://img.shields.io/pypi/v/guard-core-mcp)](https://pypi.org/project/guard-core-mcp/) |

---

## Documentation

- [Installation](https://guard-core.github.io/fastapi-guard/latest/installation/)
- [First Steps](https://guard-core.github.io/fastapi-guard/latest/tutorial/first-steps/)
- [Configuration Reference](https://guard-core.github.io/fastapi-guard/latest/tutorial/configuration/security-config/)
- [Decorator Reference](https://guard-core.github.io/fastapi-guard/latest/api/decorators/)
- [API Reference](https://guard-core.github.io/fastapi-guard/latest/api/overview/)
- [Example App](https://guard-core.github.io/fastapi-guard/latest/tutorial/examples/example-app/)
- [Redis Integration](https://guard-core.github.io/fastapi-guard/latest/tutorial/redis-integration/caching/)

---

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

New security features (checks, detection patterns, handlers) should be contributed to [guard-core](https://github.com/Guard-Core/guard-core). This repo covers the FastAPI/Starlette adapter layer.

---

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

---

## Author

[Renzo Franceschini](https://github.com/Guard-Core)
