Skip to content

Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.

docs: clarify NL2SQL security model and hardening guidance (#4465)

Rip&Tear0ecf5d1fb0fc
diff --git a/docs/en/tools/database-data/nl2sqltool.mdx b/docs/en/tools/database-data/nl2sqltool.mdx
index 43a3f8944..ee423e791 100644
--- a/docs/en/tools/database-data/nl2sqltool.mdx
+++ b/docs/en/tools/database-data/nl2sqltool.mdx
@@ -15,6 +15,29 @@ Along with that provides the ability for the Agent to update the database based
**Attention**: Make sure that the Agent has access to a Read-Replica or that is okay for the Agent to run insert/update queries on the database.
+## Security Model
+
+`NL2SQLTool` is an execution-capable tool. It runs model-generated SQL directly against the configured database connection.
+
+This means risk depends on your deployment choices:
+
+- Which credentials you provide in `db_uri`
+- Whether untrusted input can influence prompts
+- Whether you add tool-call guardrails before execution
+
+If you route untrusted input to agents using this tool, treat it as a high-risk integration.
+
+## Hardening Recommendations
+
+Use all of the following in production:
+
+- Use a read-only database user whenever possible
+- Prefer a read replica for analytics/retrieval workloads
+- Grant least privilege (no superuser/admin roles, no file/system-level capabilities)
+- Apply database-side resource limits (statement timeout, lock timeout, cost/row limits)
+- Add `before_tool_call` hooks to enforce allowed query patterns
+- Enable query logging and alerting for destructive statements
+
## Requirements
- SqlAlchemy
diff --git a/lib/crewai-tools/src/crewai_tools/tools/nl2sql/README.md b/lib/crewai-tools/src/crewai_tools/tools/nl2sql/README.md
index 932867c90..7c83f6d6f 100644
--- a/lib/crewai-tools/src/crewai_tools/tools/nl2sql/README.md
+++ b/lib/crewai-tools/src/crewai_tools/tools/nl2sql/README.md
@@ -8,6 +8,29 @@ This enables multiple workflows like having an Agent to access the database fetc
**Attention**: Make sure that the Agent has access to a Read-Replica or that is okay for the Agent to run insert/update queries on the database.
+## Security Model
+
+`NL2SQLTool` is an execution-capable tool. It runs model-generated SQL directly against the configured database connection.
+
+Risk depends on deployment choices:
+
+- Which credentials are used in `db_uri`
+- Whether untrusted input can influence prompts
+- Whether tool-call guardrails are enforced before execution
+
+If untrusted input can reach this tool, treat the integration as high risk.
+
+## Hardening Recommendations
+
+Use all of the following in production:
+
+- Use a read-only database user whenever possible
+- Prefer a read replica for analytics/retrieval workloads
+- Grant least privilege (no superuser/admin roles, no file/system-level capabilities)
+- Apply database-side resource limits (statement timeout, lock timeout, cost/row limits)
+- Add `before_tool_call` hooks to enforce allowed query patterns
+- Enable query logging and alerting for destructive statements
+
## Requirements
- SqlAlchemy