DeerFlow
DeerFlow security boundaries: bearer precedence, CSRF and sandbox authority
Understand the paired authentication and CSRF implementation, trusted proxy requirements and operational limits that survive a successful login.
What you will learn
- Authentication chooses one credential path
- Read CSRF protection together with bearer precedence
- Keep execution authority smaller than account authority
Before you start
- Basic Python, HTTP and container concepts
- An owned task with explicit acceptance criteria
Explain the chapter’s implementation boundary and apply its checklist or isolated helper exercise.
Key takeaways
- Invalid bearer credentials must not fall back to cookies.
- CSRF assumptions include the authentication and proxy layers.
- Login, tool permission and host isolation are separate boundaries.
Authentication chooses one credential path
With authentication enabled, an Authorization header takes the PAT path and an invalid token receives a hard 401 rather than falling back to a session cookie. The middleware also restricts PAT routes and intersects token scopes with resolved user permissions. A trusted internal token has a separate path. None of these identity decisions replaces per-resource authorization checks in handlers.
Some routes are public, including health and selected first-run authentication endpoints; webhook handlers have their own verification responsibility. The middleware uses a router-aligned path helper rather than an unrelated string interpretation. The backend manifest even bounds a Starlette dependency used by that helper, showing that framework routing behavior can be security-relevant.
Read CSRF protection together with bearer precedence
For protected state-changing cookie requests, the CSRF middleware compares a readable cookie with the X-CSRF-Token header using a timing-safe comparison. A present Authorization header exempts the cookie double-submit check, but this relies on the authentication middleware refusing invalid bearer credentials. Reading that exemption in isolation would miss the paired security assumption.
First-call authentication routes apply an origin check when Origin is present and permit absent Origin for non-browser clients. Origin normalization rejects credentials, paths, queries and fragments and normalizes default ports. Request-origin construction accepts forwarded headers, so the deployment proxy must strip or overwrite untrusted forwarding input; an exact CORS allowlist cannot repair a dishonest proxy boundary by itself.
Keep execution authority smaller than account authority
The local sandbox provider explicitly disclaims host-filesystem isolation when shell execution is enabled. The production base avoids host Docker socket and personal CLI credential mounts; opting into them changes the authority available to a compromised tool or malicious task. Review those capabilities separately from whether a user successfully logged in.
Use a disposable fixture to verify unauthorized access, expired credentials, cookie-write CSRF, artifact ownership and stop behavior. Redact tokens, document retention and test restoration. We inspected these branches but did not run an authentication server or penetration test. A loop cap can prevent future repeated calls; it cannot undo an external side effect that already occurred.
Implementation steps
- 1
Keep authentication enabled and public exposure behind the intended TLS proxy.
- 2
Strip untrusted forwarding headers and use exact allowed origins.
- 3
Avoid credential-directory and Docker-socket mounts unless specifically needed.
- 4
Test identity, ownership and recovery with non-sensitive fixtures.
Copy-ready example
{"authEnabled":true,"invalidBearerCookieFallback":false,"cookieWritesRequireCsrf":true,"trustedProxyRequired":true,"hostBashAllowed":false,"securityIntegrationTestExecuted":false}Frequently asked questions
Can an arbitrary Authorization header safely bypass authentication?
No. With authentication enabled, the paired authentication middleware rejects invalid bearer credentials instead of using the cookie.
Does stopping an agent roll back tool side effects?
No. Termination can suppress later calls, but external effects require their own idempotency, approval and recovery design.
Sources
- README.mdSource checked 2026-09-08
- LICENSESource checked 2026-09-08
- backend/README.mdSource checked 2026-09-08
- backend/pyproject.tomlSource checked 2026-09-08
- backend/docs/middleware-execution-flow.mdSource checked 2026-09-08
- backend/packages/harness/deerflow/agents/lead_agent/agent.pySource checked 2026-09-08
- backend/packages/harness/deerflow/agents/middlewares/loop_detection_middleware.pySource checked 2026-09-08
- backend/packages/harness/deerflow/agents/middlewares/_bounded_dict.pySource checked 2026-09-08
- backend/packages/harness/deerflow/config/loop_detection_config.pySource checked 2026-09-08
- backend/packages/harness/deerflow/sandbox/local/local_sandbox_provider.pySource checked 2026-09-08
- backend/app/gateway/auth_middleware.pySource checked 2026-09-08
- backend/app/gateway/csrf_middleware.pySource checked 2026-09-08
- docker/docker-compose.yamlSource checked 2026-09-08