Proposal: opt-in application-layer security (attack screening, bans, per-route policies, IP allow/block lists) for the Go API and admin servers

[rennf93]

Disclosure: I maintain gin-guard and guard-core-go, the two libraries this proposal builds on.

Problem

RAGFlow API servers are often exposed to the internet, and the Go API server (internal/server/api/server.go) has no inbound limiter: no per-IP rate limit, no IP allow or block list, and nothing that drops scanner traffic before it reaches a handler. Two things make this matter for RAGFlow in particular:

• Several endpoints aren't cheap. Chat completions, retrieval and embedding paths call paid LLM and embedding providers, so an unauthenticated or leaked-key client looping on them turns straight into provider cost and load on the doc engine.
• Unauthenticated routes like login, registration and password reset are the usual targets for brute force and enumeration, and nothing slows a single address down today.

The trusted proxy work (the fix for #19549, the spoofed X-Forwarded-For bypass of the agent webhook IP whitelist) already gives the server a correct client address. I build on that address instead of adding a second notion of it.

Proposal

An optional middleware, default off, built on gin-guard v1.5.0 (MIT) and guard-core-go v4.4.0. When api.guard.enabled isn't set nothing is registered and behavior is byte for byte unchanged.

When it's on:

• Optional attack-pattern screening of the URL path, query string and headers (separate switch, default off, answers 400). Request bodies are never scanned: documents, chat messages and prompts are free text and would only give false positives. Query parameters that carry free text can be excluded by name.
• Optional IP allow and block lists (IPs or CIDRs, answers 403).
• A per-client rate limit (default 600 requests per 60 seconds, answers 429).
• No response header changes, no auto-banning, no geo or cloud-provider rules in this first version.

The choices I made on purpose:

• Client address: the guard gets the same api.trusted_proxies list that common.ConfigureTrustedProxies gives gin (loopback by default, the bundled nginx), so it resolves the client the same way c.ClientIP() does. A spoofed X-Forwarded-For from an untrusted peer is ignored by both, and a rotating header can't evade the limit. The guard side is covered by tests (loopback peer honored, other peers ignored, rotating header can't evade the limit). The gin side is already covered by trusted_proxies_test.go.
• Ordering: the guard is registered right after gin.Recovery() and before the routes. The Go API has no CORS middleware today (a few handlers set headers themselves), so there's nothing to keep outside of it. If one is added later and registered before the guard, 429 and 403 responses carry its headers, and the tests exercise that ordering with a stand-in middleware.
• Health endpoints (/health, /api/v1/system/ping, /api/v1/system/healthz) skip the guard entirely, so probes are never limited or blocked.
• Streaming and uploads: the guard doesn't buffer responses (SSE flushes reach the client while the handler is still running) and doesn't read request bodies, so large uploads pass untouched. Both are tested.
• Shared state: counters are in process memory by default. api.guard.use_kvrocks: true keeps them in the Kvrocks instance the Go services already use, so replicas share them. It fails open if Kvrocks is unreachable.

What else the engine offers

I kept the branch to a small, safe subset. The rest is already in gin-guard and I can wire whatever you find useful:

• Per-route policies: an IP allowlist only on the admin server (/api/v1/admin/*, including user management), a strict budget with bans on POST /api/v1/admin/login, request size and content-type limits on document uploads, and per-client budgets on /api/v1/chats and dataset search.
• Behavior rules, for example banning clients that keep hitting 404s (scanners) or repeat suspicious request patterns.
• Country allow and block lists, blocking cloud-provider IP ranges, user-agent filtering.
• Emergency mode, which locks the instance down to an allowlist during an incident, and a passive (log-only) mode to try everything before enforcing it.
• Optionally, rules changed at runtime without a restart (bans, country blocks, budgets, a lockdown) and security events for monitoring, through a separate agent that is off by default and not part of this proposal.

Configuration

Under the existing api: section of service_conf.yaml, next to trusted_proxies, with RAGFLOW_API_GUARD_* environment overrides (same mechanism as RAGFLOW_API_HTTP_PORT):

api:
  guard:
    enabled: false
    rate_limit: 600
    rate_limit_window: 60
    ip_allowlist: []
    ip_blocklist: []
    screen_requests: false
    screen_excluded_params: []
    use_kvrocks: false

Documented in docs/administrator/configurations/configurations.md, conf/service_conf.yaml and docker/service_conf.yaml.template. It applies to the API server and, with its own counters, to the admin server.

Tests

Unit tests in internal/guard and internal/server/config: disabled registers nothing; a burst returns 429 and the response keeps the outer middleware's CORS header; allowlist returns 403; spoofed and rotating X-Forwarded-For from an untrusted peer is ignored; an attack in the query is blocked while the same text in a body or an excluded parameter passes; screening is off unless asked for; an SSE stream is delivered incrementally; a 64 MiB upload passes; config defaults, YAML and environment parsing. I couldn't start the full server locally (it needs MySQL, a doc engine, MinIO and the native libraries), so I also ran the real middleware in a small standalone gin server and probed it with curl: 429 after the limit, health unaffected, SSE ticks arriving 700 ms apart, attack query rejected.

Dependency impact

go.mod gains github.com/rennf93/gin-guard v1.5.0 and github.com/rennf93/guard-core-go/v4 v4.4.0 plus one transitive module, github.com/oschwald/maxminddb-golang v1.13.1 (GeoIP reader, unused unless country rules are configured). It also raises modules already there: go-redis/v9 9.18.0 to 9.23.0, zeebo/xxh3 1.0.2 to 1.1.0, dlclark/regexp2 1.10.0 to 1.12.0, klauspost/cpuid/v2 2.3.0 to 2.4.0, go.uber.org/atomic 1.11.0 to 1.12.0 and go.yaml.in/yaml/v3 3.0.4 to 3.0.5, and drops the now-unneeded indirect dgryski/go-rendezvous. Everything else the libraries need is already in the module graph (gin v1.12.0 matches).

One known follow-up: guard-core-go v4.4.0 prints a few log lines on every request through the standard log package (for example "No countries blocked or whitelisted"). The fix that routes them through slog at Debug level (hidden by default) is merged upstream (Guard-Core/guard-core-go#111) and not released yet, and I'll bump the dependency in the PR once it ships. I didn't work around it, and it only affects deployments that turn the guard on.

Alternatives

• Reverse proxy limits (nginx limit_req, a WAF or a CDN): they protect the edge and I'd document them either way, but it's a different layer. This is the application layer inside the Go server, using the same client-address resolution as the rest of the Go code, so the two complement each other. It also gives deployments that run the bundled stack as is a default they can switch on.
• In-house middleware: a simple limiter is a few dozen lines, but IP policy with CIDRs, the screening rules, shared state and the trusted-proxy handling are what I'd rather not maintain here. The trade-off is a new dependency, which is why it's default off and isolated in one package.

Status

A tested branch is ready: https://github.com/rennf93/ragflow/tree/feat/gin-guard-security-middleware. I'll open a PR referencing this discussion if there's interest. I'm happy to trim it (drop screening or the Kvrocks option, say) or move the wiring elsewhere in the server if you want a different shape.

Who I am: I'm rennf93. I wrote fastapi-guard, public since August 2024 (first PyPI release, 0.1.0, on 2024-08-26), now at 825 GitHub stars, 65 releases and about 62,000 PyPI downloads last month (pypistats.org). The engines and adapters for other languages and frameworks came later and run the same detection rules, checked in CI against shared conformance fixtures.

[JinHai-CN]

Hi rennf93,

Thanks for the proposal — it's a well-thought-out design, and we're happy to work with it. We had discussed this before, and we're on board with building it on gin-guard v1.5.0 and guard-core-go.

One thing to consider: RAGFlow may run multiple Go API services. If the guard settings are configured through config files, that means every Go API service's config file would need to be modified, and some of those settings can't be changed dynamically.

With that in mind, here are my thoughts on your proposal:

• Dynamic configuration via the Admin service. Rather than static config files, the guard settings should be configured through the heartbeat between the Admin service and the API services, with the Admin service also providing a UI for managing them.

• Shared state. If the state doesn't need to be persisted and is global, I'd prefer to have the Admin service provide a dedicated KV storage service, rather than tying it to Kvrocks or another existing store.

Best,
Jin Hai

[rennf93]

Thanks, @JinHai-CN ! I'm glad it fits. Both points make sense. I'm thinking of something like:

1. Settings through the Admin service

• Stored as system_settings entries, the same table and validation the admin variables already use (internal/admin/service.go:1103-1125), with a Security page in the admin UI.
• Admin returns them, with a version number, in the heartbeat response. Today that response data goes to UpdateClient, an empty stub in this repo (internal/service/admin_client_ee.go:28).
• When an API server sees a newer version, it builds a new guard from it and swaps it in atomically; running requests finish on the old one. The admin server reads the settings directly.
• service_conf.yaml keeps only api.trusted_proxies, which is already there.

Trade-off: with in-process state, counters and bans reset when the settings change. I think that's fine for a change made by hand in the UI.

2. Shared state

Two things need sharing, neither persisted: per-client request counters (one update per request) and active bans. guard-core-go reaches its shared store through the Redis protocol: a Lua script or sorted-set pipeline for counters (RateLimitRedis, guardcore/ratelimit.go:86-90 in v4.4.1) and TTL keys for bans (RedisHandler, guardcore/redis.go:59-69). So an Admin KV service would have to speak that protocol, or I add a pluggable store interface to guard-core-go, which means an engine release on my side.

It also puts a round trip to Admin on every API request. Today an unreachable Admin only flips the local admin status (internal/server/bootstrap/runtime.go:83-88).

For the first version I'd keep counters and bans per process (with N API servers a client gets up to N times the limit, documented), and do the Admin KV as a follow-up once we agree on its interface, if you agree.

Questions

1. Can the settings travel as their own guard key in the heartbeat data, read in admin_client.go before UpdateClient (:172), so the EE implementation stays untouched?
2. After a successful heartbeat the client skips the next 10 ticks (admin_client.go:91-97) and the default interval is 3 s (internal/server/config/general_config.go:41), so a change reaches every server within about 33 s. Is that acceptable, emergency lockdown included?
3. Is per-server counting ok for the first PR?
4. For the Admin KV, do you have a protocol in mind (HTTP, gRPC, something planned), or should I propose one?

guard-core-go v4.4.1 shipped on 2026-10-19 with the logging fix I mentioned, so the PR uses it.