From 1f8cfe32823b9bfebd8ecb39b71a80991d975fb3 Mon Sep 17 00:00:00 2001
From: theCyberTech <84775494+theCyberTech@users.noreply.github.com>
Date: Thu, 12 Feb 2026 10:32:56 +0800
Subject: [PATCH] docs: clarify NL2SQL security model and hardening guidance

---
 docs/en/tools/database-data/nl2sqltool.mdx    | 23 +++++++++++++++++++
 .../src/crewai_tools/tools/nl2sql/README.md   | 23 +++++++++++++++++++
 2 files changed, 46 insertions(+)

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