From 64dc8108de945aaa8b6ffbd4055a0a21e713f66a Mon Sep 17 00:00:00 2001 From: pandego <7780875+pandego@users.noreply.github.com> Date: Mon, 2 Mar 2026 15:05:19 +0100 Subject: [PATCH 1/3] docs: add security best practices guide for agents --- docs/docs.json | 3 +- .../advanced/security-best-practices.mdx | 139 ++++++++++++++++++ 2 files changed, 141 insertions(+), 1 deletion(-) create mode 100644 docs/en/guides/advanced/security-best-practices.mdx diff --git a/docs/docs.json b/docs/docs.json index 2f657a674b..b7257f93cb 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1726,7 +1726,8 @@ "icon": "gear", "pages": [ "v1.14.7/en/guides/advanced/customizing-prompts", - "v1.14.7/en/guides/advanced/fingerprinting" + "v1.14.7/en/guides/advanced/fingerprinting", + "v1.14.7/en/guides/advanced/security-best-practices" ] }, { diff --git a/docs/en/guides/advanced/security-best-practices.mdx b/docs/en/guides/advanced/security-best-practices.mdx new file mode 100644 index 0000000000..89bc965ac9 --- /dev/null +++ b/docs/en/guides/advanced/security-best-practices.mdx @@ -0,0 +1,139 @@ +--- +title: Security Best Practices for CrewAI Agents +description: Practical guidance for configuring CrewAI agents and crews safely in production. +icon: shield +--- + +## Overview + +This guide focuses on **CrewAI-native controls** you can use to reduce security risk in production systems. + +The goal is simple: keep agent behavior bounded, least-privileged, and reviewable. + +## 1) Bound execution to prevent runaway behavior + +Use execution limits on agents and crews so failures degrade predictably instead of spiraling. + +### Recommended controls + +- `max_rpm`: cap request rate to providers +- `max_iter`: cap iterative reasoning/tool cycles +- `max_execution_time`: hard timeout for long-running work + +```python +from crewai import Agent + +analyst = Agent( + role="Security Analyst", + goal="Investigate and summarize incidents", + backstory="Careful and methodical", + max_rpm=30, + max_iter=12, + max_execution_time=180, +) +``` + +## 2) Apply least privilege to tools + +Avoid giving every tool to every agent. Give each agent only the tools required for its task. + +### Why this matters + +- Reduces blast radius for prompt injection or logic errors +- Prevents accidental access to unrelated systems +- Improves traceability of who can do what + +```python +from crewai import Agent +from crewai.tools import FileReadTool, SerperDevTool + +researcher = Agent( + role="Researcher", + goal="Collect external facts", + backstory="Finds reliable sources", + tools=[SerperDevTool()], +) + +auditor = Agent( + role="Document Auditor", + goal="Review internal policy documents", + backstory="Checks compliance language", + tools=[FileReadTool()], +) +``` + +## 3) Treat delegation as a trust boundary + +When `allow_delegation=True`, an agent can route work to other agents. That can be useful, but it is also a security boundary. + +### Safe delegation patterns + +- Keep delegation disabled by default +- Enable it only for roles that truly need orchestration +- Pair delegation with clear task constraints and bounded execution + +```python +coordinator = Agent( + role="Coordinator", + goal="Route specialized tasks", + backstory="Delegates carefully", + allow_delegation=True, + max_iter=8, +) +``` + +## 4) Constrain outputs with schemas and expectations + +Use structured outputs whenever possible to reduce ambiguous or unsafe free-form responses. + +### Recommended controls + +- `output_pydantic` for schema-validated task output +- `expected_output` to describe strict acceptance criteria + +```python +from pydantic import BaseModel +from crewai import Task + +class RiskSummary(BaseModel): + severity: str + findings: list[str] + recommendation: str + +security_task = Task( + description="Review tool configuration for least privilege", + expected_output="A structured risk summary with severity, findings, and recommendation.", + output_pydantic=RiskSummary, +) +``` + +## 5) Add human oversight for high-stakes actions + +For sensitive operations (for example financial actions, production mutations, or customer-impacting changes), add explicit human approval before execution. + +### Common oversight checkpoints + +- Before running irreversible tools +- Before external side effects (emails, tickets, writes) +- Before policy/security exceptions + +You can implement approvals in your flow logic by pausing before a sensitive step, collecting reviewer input, and resuming only on approval. + +## Operational checklist + +Use this quick checklist before production rollout: + +- [ ] Every agent has bounded execution (`max_rpm`, `max_iter`, `max_execution_time`) +- [ ] Tool access is scoped per role (no broad shared tool list) +- [ ] Delegation is disabled unless explicitly required +- [ ] High-impact tasks use `output_pydantic` and precise `expected_output` +- [ ] Human approval gates exist for sensitive actions + +## Related resources + +- [Agents](/en/concepts/agents) +- [Tasks](/en/concepts/tasks) +- [Flows](/en/concepts/flows) +- [Human-in-the-loop](/en/learn/human-in-the-loop) +- [Tool Hooks](/en/learn/tool-hooks) +- [Tracing and observability](/en/observability/overview) From 3f1700654a5973419fe1f5c5836a97ff59cfe7c7 Mon Sep 17 00:00:00 2001 From: pandego <7780875+pandego@users.noreply.github.com> Date: Wed, 25 Mar 2026 12:35:30 +0100 Subject: [PATCH 2/3] docs: expand security guide oversight examples --- .../guides/advanced/security-best-practices.mdx | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/en/guides/advanced/security-best-practices.mdx b/docs/en/guides/advanced/security-best-practices.mdx index 89bc965ac9..166f650c7a 100644 --- a/docs/en/guides/advanced/security-best-practices.mdx +++ b/docs/en/guides/advanced/security-best-practices.mdx @@ -117,7 +117,19 @@ For sensitive operations (for example financial actions, production mutations, o - Before external side effects (emails, tickets, writes) - Before policy/security exceptions -You can implement approvals in your flow logic by pausing before a sensitive step, collecting reviewer input, and resuming only on approval. +CrewAI supports human approval at the task layer with `human_input=True`, which is a good fit for sensitive steps that should pause for review before completion. + +```python +from crewai import Task + +sensitive_task = Task( + description="Execute production database migration", + expected_output="Migration result confirmation", + human_input=True, +) +``` + +For reviewability after the fact, consider enabling `verbose=True` on agents involved in sensitive flows so execution details are easier to inspect during debugging and incident review. ## Operational checklist @@ -128,6 +140,7 @@ Use this quick checklist before production rollout: - [ ] Delegation is disabled unless explicitly required - [ ] High-impact tasks use `output_pydantic` and precise `expected_output` - [ ] Human approval gates exist for sensitive actions +- [ ] Agent runs are logged or traced for post-incident review ## Related resources From 2bc8439b64105993882f8d4bf22e3406df6ce1b4 Mon Sep 17 00:00:00 2001 From: pandego <7780875+pandego@users.noreply.github.com> Date: Sat, 6 Jun 2026 18:16:07 +0200 Subject: [PATCH 3/3] docs: add Agent import to delegation example --- docs/docs.json | 6 +++--- .../en/guides/advanced/security-best-practices.mdx | 2 ++ 2 files changed, 5 insertions(+), 3 deletions(-) rename docs/{ => edge}/en/guides/advanced/security-best-practices.mdx (99%) diff --git a/docs/docs.json b/docs/docs.json index b7257f93cb..dc98cf8572 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -138,7 +138,8 @@ "icon": "gear", "pages": [ "edge/en/guides/advanced/customizing-prompts", - "edge/en/guides/advanced/fingerprinting" + "edge/en/guides/advanced/fingerprinting", + "edge/en/guides/advanced/security-best-practices" ] }, { @@ -1726,8 +1727,7 @@ "icon": "gear", "pages": [ "v1.14.7/en/guides/advanced/customizing-prompts", - "v1.14.7/en/guides/advanced/fingerprinting", - "v1.14.7/en/guides/advanced/security-best-practices" + "v1.14.7/en/guides/advanced/fingerprinting" ] }, { diff --git a/docs/en/guides/advanced/security-best-practices.mdx b/docs/edge/en/guides/advanced/security-best-practices.mdx similarity index 99% rename from docs/en/guides/advanced/security-best-practices.mdx rename to docs/edge/en/guides/advanced/security-best-practices.mdx index 166f650c7a..20e41927d7 100644 --- a/docs/en/guides/advanced/security-best-practices.mdx +++ b/docs/edge/en/guides/advanced/security-best-practices.mdx @@ -73,6 +73,8 @@ When `allow_delegation=True`, an agent can route work to other agents. That can - Pair delegation with clear task constraints and bounded execution ```python +from crewai import Agent + coordinator = Agent( role="Coordinator", goal="Route specialized tasks",