2a97ec3e58
* docs: turn README into an index and move reference detail to docs/guide The README had grown to 393 KB because every change appended its notes there. The text moves verbatim into 18 topic guides under docs/guide/; only headings are re-leveled and relative links re-pointed. The README keeps the introduction, a quick start and a guide index. Contributor test notes move to CONTRIBUTING.md. * docs: send user docs to topic guides and budget the root README The rule 'update README.md for user-facing changes' is what grew the README. Guidance now points to docs/guide/, and check_agent_guidance.py fails when the root README exceeds 16 KiB (AG003). * chore: remove unreferenced screenshots and finished plan notes pr-build/ holds two PR screenshots (3 MB) from #1986. plans/ holds the plan for the merged #4049. docs/SKILL_NAME_CONFLICT_FIX.md is a February change note. Nothing references them. * docs: route always-loaded AGENTS.md files to scoped guides * docs(agents): cut scoped guides to scope, verify, traps, decisions Each AGENTS.md keeps four kinds of content: the scope of the directory, the verification commands, traps a local test run does not show, and decisions the code cannot state. Values, field lists, function inventories, test names, issue numbers and history are deleted, because the code, the tests and git state them. Search and fetch providers share one community guide. Four guides with no remaining content are removed. The size check now allows 6 KiB per file (hard limit 8 KiB) and 24 KiB per chain (hard limit 32 KiB). * style: format frontend guide table and guidance test imports --------- Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
5.1 KiB
⚠️ Security Notice
Improper Deployment May Introduce Security Risks
DeerFlow has key high-privilege capabilities including system command execution, resource operations, and business logic invocation, and is designed by default to be deployed in a local trusted environment (accessible only via the 127.0.0.1 loopback interface). If you deploy the agent in untrusted environments — such as LAN networks, public cloud servers, or other multi-endpoint accessible environments — without strict security measures, it may introduce security risks, including:
- Unauthorized illegal invocation: Agent functionality could be discovered by unauthorized third parties or malicious internet scanners, triggering bulk unauthorized requests that execute high-risk operations such as system commands and file read/write, potentially causing serious security consequences.
- Compliance and legal risks: If the agent is illegally invoked to conduct cyberattacks, data theft, or other illegal activities, it may result in legal liability and compliance risks.
Gateway Admin Is Equivalent to Code Execution
An admin can register stdio MCP servers, which run commands inside the Gateway
container. The API restricts them to an allowlist (npx, uvx by default,
extended via DEER_FLOW_MCP_STDIO_COMMAND_ALLOWLIST) and rejects arguments and
environment variables that would evaluate arbitrary code. That is defense in
depth, not a boundary: these launchers exist to fetch and run remote packages,
so treat Gateway admin as equivalent to code execution on the host and grant
it accordingly.
External Chat Message Roles
Gateway run requests and manual thread-state updates reject client-supplied
system / developer messages with HTTP 400, including equivalent serialized
message forms. Ordinary chat, attachments, and assistant/tool history replay
remain supported. Session or PAT authentication does not grant system-prompt
authority; trusted internal run producers retain that ability.
This check prevents new role injection; it does not rewrite existing checkpoints. If an older version accepted an injected system message, use a fresh thread or have an operator review and clean the affected state. Restarting the service does not remove persisted instructions, and restoring an older checkpoint can restore them.
For local verification, run python backend/tests/poc_external_system_message_injection.py --help.
The same opt-in PoC supports --expect vulnerable on an isolated old revision
and --expect blocked after the fix. Its help includes PAT creation, thread-ID
selection, browser follow-up, and the distinction between persistence and model
obedience. Use a fresh disposable thread for each run; the test appends messages.
On an isolated unfixed checkout, --expect vulnerable demonstrates acceptance
only when the request returns 200 and the exact injected message remains in the
checkpoint as type=system across a normal follow-up. A marker in a web answer
is model-dependent and is not evidence by itself that the role was promoted.
After applying the fix, run the same script with --expect blocked: it requires
the specific role-rejection 400, an unchanged checkpoint, a successful ordinary
follow-up, and absence of the rejected message IDs. Other 400 responses and
authentication, conflict, or server errors are inconclusive rather than passes.
The PoC does not clean up automatically. When verification is complete, delete the disposable chat with the web sidebar's delete action and revoke the short-lived PAT if one was created. Restarting the service does not remove a persisted injected instruction.
Deployment Defaults
The Docker stack publishes its entry port on 127.0.0.1 only, and local
make dev / make start bind nginx, the Gateway, and the frontend to loopback,
matching the local-trusted-environment model described above. To reach it from
another machine, set BIND_HOST in .env (e.g. BIND_HOST=0.0.0.0) — and only
after putting the security measures below in place. Local runs apply BIND_HOST
to nginx on port 2026 only; the Gateway and frontend stay on loopback behind
it.
Complete first-run setup before the host becomes reachable. A fresh
instance has no accounts yet, so create the admin account through /setup
immediately after starting any deployment that is not loopback-only.
Security Recommendations
Note: We strongly recommend deploying DeerFlow in a local trusted network environment. If you need cross-device or cross-network deployment, you must implement strict security measures, such as:
- IP allowlist: Use
iptables, or deploy hardware firewalls / switches with Access Control Lists (ACL), to configure IP allowlist rules and deny access from all other IP addresses. - Authentication gateway: Configure a reverse proxy (e.g., nginx) and enable strong pre-authentication, blocking any unauthenticated access.
- Network isolation: Where possible, place the agent and trusted devices in the same dedicated VLAN, isolated from other network devices.
- Stay updated: Continue to follow DeerFlow's security feature updates.