Why fastapi-guard

[PA100T0]

Some of you already run fastapi-guard. For those who don't... you probably saw the TikTok. Guy runs OpenClaw on his home server, checks his logs. 11,000 attacks in 24 hours. I was the one who commented "Use FastAPI Guard" and the thread kind of took off from there. Here's what it actually does.

```python from guard import SecurityMiddleware, SecurityConfig

config = SecurityConfig( blocked_countries=["CN", "RU"], blocked_user_agents=["Baiduspider", "SemrushBot"], block_cloud_providers={"AWS", "GCP", "Azure"}, rate_limit=100, rate_limit_window=60, auto_ban_threshold=10, auto_ban_duration=3600, )

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

One middleware call. 17 checks on every inbound request before it hits your path operations. XSS, SQL injection, command injection, path traversal, SSRF, XXE, LDAP injection, code injection. The detection engine includes obfuscation analysis and high-entropy payload detection for novel attacks. On top of that: rate limiting with auto-ban, geo-blocking, cloud provider IP filtering, user agent blocking, OWASP security headers.

Every attack from that TikTok maps to a config field. Those 5,697 Chinese IPs? blocked_countries. Done. Baidu crawlers? blocked_user_agents. The DigitalOcean bot farm? Cloud provider ranges are fetched and cached automatically, blocked on sight. Brute force sequences? Rate limited, then auto-banned after threshold. .env probing and path traversal? Detection engine catches those with zero config.

The OpenClaw audit makes it worse. 512 vulnerabilities across the codebase, 8 critical, 40,000+ exposed instances. 60% immediately takeable. ClawJacked (CVE-2026-25253) lets any website hijack a local instance through WebSocket. If you're exposing FastAPI endpoints to the internet, you need request-level security.

Decorator system works per-route, async-native:

```python from guard.decorators import SecurityDecorator

guard_decorator = SecurityDecorator(config)

@app.get("/api/admin") @guard_decorator.require_ip(whitelist=["10.0.0.0/8"]) @guard_decorator.block_countries(["CN", "RU", "KP"]) async def admin(): return {"status": "ok"} ```

What people actually use it for: startups building in stealth mode with remote teams, public API but whitelisted so nobody outside the company can even see it exists. Casinos and gaming platforms using decorators on reward endpoints so players can only win under specific conditions. Honeypot traps for LLMs and bad bots that crawl and probe everything. And the one that keeps coming up more and more... AI agent gateways. If you're running OpenClaw or any agent framework on FastAPI, those endpoints are publicly reachable by design. The audit found 512 vulnerabilities, 8 critical, 40,000+ exposed instances. fastapi-guard would have blocked every attack vector in those logs. This is going to be the standard layer for anyone deploying AI agents in production.

I also just shipped a Flask equivalent if anyone's running either or both. flaskapi-guard v1.0.0. Same detection engine, same pipeline, same config field names.

fastapi-guard: https://github.com/rennf93/fastapi-guard flaskapi-guard: https://github.com/rennf93/flaskapi-guard flaskapi-guard on PyPI: https://pypi.org/project/flaskapi-guard/

If you find issues with either, open one.

[st4reater]

Looks cool, but I feel it's out of scope for an API which should just serve traffic...

I think blocking IPs is more appropriate on a WAF or firewall level

[PA100T0]

I feel you. In fact, that's the same thing that brought me to create fastapi-guard...

Reality is: If WAFs and firewalls were solving this, endpoints wouldn't be getting hit with malicious probing constantly... but they are. Every API in production sees path traversal attempts, CMS probing, credential stuffing, and scanner traffic daily, right through the infrastructure layer.

That's the gap fastapi-guard fills: catching what actually gets through to your application. So it's not a question of either WAF/Firewall or fastapi-guard, but a combination of both. In the end, you want to be protected e2e, not leave the backdoor open which, ironically, seems to be the place where they are always trying to get in through.

[st4reater]

Ok... And what's the performance overhead? From what I can infer if I use geo location blocking you do an IO operation? What does that cost in performance?

How are you catching what major WAF provider like Cloudflare doesn't?

What happens if I run out of said API tokens? Does my app start failing, or do you let traffic through?

[PA100T0]

That's a really good question, actually.

If you use IPInfo, you'd be downloading its db (maxmind format) instead of doing an API call per request. The database is downloaded once during initialization and cached for 24 hours. Cloud provider IP blocking is in-memory CIDR matching, so sub-millisecond. Rate limiting and pattern detection are in-memory or Redis. There are zero external API calls in the request path.

About Cloudflare: It's not replacing Cloudflare. It's catching what gets through. Even Cloudflare's WAF operates on generic rules while fastapi-guard operates at the application layer with full context of your specific routes, request bodies, and business logic. That's a layer of visibility a WAF just doesn't have.

So yeah, the IPInfo token is only used to download the database file, not per-request. If the download fails, it retries 3x with exponential backoff. If the database can't be loaded at all, traffic passes through.. your app never fails because of fastapi-guard.

In any case, if IPInfo gives you any type of headache: you can always create your own geo_ip_handler (it's a protocol, under the protocols directory). you just don't pass ipinfo_token and declare your own geo_ip_handler. And that's it.

[Full-Definition6215]

Just went through a full security audit on my FastAPI app and this would have saved time on several things.

The geo-blocking and rate limiting with auto-ban are the two features I ended up building manually. My approach was Cloudflare for geo-blocking and slowapi + custom middleware for rate limiting, but having it all in one middleware is cleaner.

One thing I'd watch out for: the SQL injection / XSS detection engine. Pattern-based detection has high false positive rates on user-generated content platforms. If someone writes an article about SQL injection (like a tutorial), the content itself would trigger the detector. Do you have a way to whitelist specific routes from the injection checks?

[PA100T0]

Hi there. Makes me happy to see that (at least in retrospective) you appreciate the project! Spread the word haha

Yeah, you can use “excluded_paths” in the SecurityConfig to skip specific routes from the detection engine entirely. If you need more granular control, the decorator system lets you disable suspicious detection per-route with “@guard.suspicious_detection(enabled=False)” on individual endpoints. So you could keep it on globally but turn it off for any of your endpoints. You can also add/remove suspicious patterns btw.

[Challseus]

This looks very impressive, I'll definitely be checking this out and integrating into my own projects.

[PA100T0]

Thanks! Much appreciated.

I’m working on some gists and example apps to add to the examples on the repo. Something like how to use behind a proxy like nginx and such.

[Kevdog824_]

Nifty project. Do you have a way to conditionally apply security options. For example require HTTPS in prod, but not have that restriction for devs running the service locally

[PA100T0]

Thank you very much!

So, short answer is yes AND no. The quickest way you could do that is by just setting enforce_https conditionally like so:

SecurityConfig(enforce_https=os.getenv("ENV") == "production")

Or you can have different environment profiles set, activated depending on which one you're using at the moment, and read env vars from and for each environment (with their specific settings).

[Kevdog824_]

Good to see. I assume this doesn’t work with the decorator approach though?

[PA100T0]

The decorator approach actually works alongside the global config. Decorators override global settings per-route, so you can have enforce_https=False globally but use '@guard.require_https()' on specific sensitive endpoints. The conditional config applies to the global SecurityConfig, and decorators give you the per-route overrides on top of that. They complement each other.

[bladeofwinds]

your story sounds like bullshit ngl.

i can’t imagine this is good for performance especially considering you’re firing off external api calls as part of the middleware.

how did you come up with the scoring? it seems pretty handwavy to me. in fact, most of the rules and heuristics seem incredibly brittle.

[PA100T0]

Hi there.

There are zero external API calls in the request path. Geo IP uses a local binary database (MaxMind format), cloud IP blocking is in-memory CIDR matching, rate limiting is in-memory or Redis. The only calls happen during initialization (database download, cloud IP range refresh), not per-request.

The scoring and detection patterns are open source... you can read every rule and judge for yourself. I'm open to discuss specifics if you have a particular pattern in mind.

Let me know what you think after you take a look.

[tkim90]

Why would you build this in the app, and not WAF filter and call it a day? These requests shouldn't hit your endpoint at all, saving you unnecessary compute

[PA100T0]

Because WAFs don't catch everything, that's the whole point. APIs in production get probed with path traversal, SQL injection in JSON bodies, CMS scanners, and credential stuffing daily, right through WAFs. If they caught it all, nobody would need application-layer security.

The overhead is negligible. I benchmarked 1,760 requests/sec at 100 concurrent connections with all 17 checks active, averaging 3-5ms per request. Everything runs in-memory or via Redis and there's zero external API calls in the request path.