docs: add security best practices guide for CrewAI agents

[pandego]

Summary

• add a new Advanced docs guide covering CrewAI-native security controls for production agents
• include guidance for execution bounds (max_rpm, max_iter, max_execution_time), tool least-privilege, delegation risks, output constraints, and human approval gates
• add the new guide to the English docs navigation

Closes #4651.

Validation

• uv run python -m json.tool docs/docs.json
• verified frontmatter and content structure for docs/en/guides/advanced/security-best-practices.mdx

---

Note

Low Risk
Low risk documentation-only change that adds a new page and updates navigation; no runtime or API behavior is modified.

Overview
Adds a new Advanced guide, security-best-practices.mdx, documenting CrewAI-native security controls for production agents (execution bounds, least-privilege tool access, delegation considerations, structured outputs, and human approval checkpoints).

Updates docs/docs.json to include the new guide in the English Guides → Advanced navigation.

^{Written by Cursor Bugbot for commit 13e092e. This will update automatically on new commits. Configure here.}

Summary by CodeRabbit

• Documentation
  • Added a new “Security Best Practices for CrewAI Agents” advanced guide with production-focused recommendations for bounding agent execution (rate/iteration/timeouts), applying least-privileged tool access, treating delegation as a trust boundary, validating structured outputs, and adding human approval gates for sensitive actions.
  • Updated the documentation navigation to include the new security guide alongside other advanced topics and improve cross-linking to related concepts.

[cloakmaster]

Nice work on this — it's well-structured and covers the key controls. A few suggestions that might strengthen it:

Section 5 (Human oversight): This is the only section without a code example. CrewAI has human_input=True on Tasks which could be shown here:

sensitive_task = Task(
    description="Execute production database migration",
    expected_output="Migration result confirmation",
    human_input=True,  # requires human approval before completion
)

Minor addition: Consider mentioning verbose=True on agents for audit trails — it's useful for post-incident review and fits the "reviewable" theme from the overview.

Checklist: Maybe add a line about logging/observability (e.g., "Agent runs are logged for post-incident review") since the guide links to tracing docs at the bottom.

Overall this fills a real gap — there's no security guidance in the CrewAI docs today.

[pandego]

Thanks - good catches.

I updated section 5 to include a concrete human_input=True example for a sensitive task, added a note about using verbose=True for reviewability on sensitive flows, and expanded the checklist with a logging/tracing item for post-incident review.

Pushed on the PR branch now.

[cloakmaster]

Great turnaround @pandego — the human_input=True example makes Section 5 much more concrete.

Worth noting: we ran a security scan against crewAI-examples and found real instances of the exact patterns this guide warns about — path traversal in the markdown_validator tool, prompt injection in instagram_post tasks, and SSRF in the browser tools. Details in crewAIInc/crewAI-examples#350. Validates that this guide is needed.

Quick thought — if these patterns exist in the official examples, they're almost certainly in community crews too. We'd be happy to run Inkog against any of your production or enterprise agent repos if that's useful. It takes about 30 seconds and maps everything to the controls in this guide.

Longer term, it would be powerful if CrewAI users could validate their crews against these security patterns automatically — scan on crewai deploy or as a CI pre-flight check. We built Inkog specifically for this (inkog -path ./my-crew + GitHub Action). Happy to jump on a call if there's interest in tighter CrewAI integration.

[pandego]

Thanks - that’s a really useful data point.

Seeing those exact classes of issues show up in crewAI-examples#350 makes the guide feel a lot less theoretical and a lot more necessary.

The automated validation angle is interesting too. I think that likely belongs as a broader product or maintainer discussion rather than something to fold into this docs PR directly, but I can definitely see the value in giving users a way to catch these patterns earlier in the workflow.

[cloakmaster]

Appreciate it @pandego — and yeah, CI integration is a separate conversation from this PR.

For what it's worth, these patterns aren't unique to CrewAI — we see the same kinds of issues (prompt injection, missing oversight, SSRF through tools) across LangChain, Google ADK, AutoGen, and most popular agent frameworks. It's a gap across the whole ecosystem right now, which is part of why guides like this one matter.

If it'd be useful, happy to connect with whoever on the CrewAI side is thinking about agent security or working with enterprise customers on production deployments. We've been scanning across frameworks and would be glad to share what we're finding.

Either way, solid work on this PR — looking forward to it getting merged.

[pandego]

Thanks again for the thoughtful follow-up here.

I agree the broader framework-wide security gap is real, and the examples you pointed to are exactly the kind of concrete signal that makes this guide worthwhile.

I think the integration / scanning angle is still better handled as a separate maintainer or product discussion than inside this docs PR, so I am going to keep this PR scoped to the guide itself. But the extra context is useful, and I appreciate you surfacing it.

[github-actions]

This PR is stale because it has been open for 45 days with no activity.

[cloakmaster]

Hi @pandego - we are growing fast and gaining a lot of interest, do you think someone on CrewAI would be interested in a discussion with us around a potential partnership? Can be nice to secure the agents when developing them.

[pandego]

Thanks for sharing this. I’ll leave partnership or integration discussions to the CrewAI maintainers and keep this PR focused on the docs guide.

[pandego]

Rebased this onto current main and kept the PR scoped to the security best practices docs guide.

Validation:

• python3 -m json.tool docs/docs.json
• checked docs/docs.json and docs/en/guides/advanced/security-best-practices.mdx for conflict markers

This is still a docs-only diff.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new "Security Best Practices for CrewAI Agents" advanced docs page and registers it in docs navigation; the guide explains execution bounding, least-privileged tool access, delegation trust boundaries, output constraints, human oversight, and an operational pre-rollout checklist.

Changes

Security Best Practices Guide

Layer / File(s)	Summary
Guide setup and introduction docs/docs.json, docs/en/guides/advanced/security-best-practices.mdx	Navigation entry and frontmatter metadata for the new guide page. Introduces the guide's purpose and scope.
Security control patterns docs/en/guides/advanced/security-best-practices.mdx	Five core sections with code examples: execution bounding (max_rpm, max_iter, max_execution_time), least-privileged tool scoping per agent role, delegation as a trust boundary with safe patterns, output constraints using Pydantic schemas and expected_output, and human approval for high-stakes actions.
Operational guidance and resources docs/en/guides/advanced/security-best-practices.mdx	Pre-rollout checklist covering all security controls and links to related documentation (agents, tasks, flows, human-in-the-loop, tool hooks, tracing/observability).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: add security best practices guide for CrewAI agents' directly and clearly describes the main change—adding a new security documentation guide.
Linked Issues check	✅ Passed	The PR fully implements all five objectives from issue #4651: bounding execution, tool access control, delegation risks, input/output validation, and human oversight patterns with code examples.
Out of Scope Changes check	✅ Passed	All changes are narrowly scoped to documentation: adding the new MDX file and updating docs.json navigation. No runtime code, API changes, or unrelated modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/en/guides/advanced/security-best-practices.mdx`:
- Around line 75-83: The example uses Agent(...) without importing it, which
will break copy/paste runs—add an import for the Agent symbol (e.g., add "from
crewai import Agent") at the top of the snippet so the Coordinator example can
execute; update the code surrounding the Agent instantiation (the Coordinator
example) to include this import.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ac414c2e-28bb-49d9-a265-68a8f4370130

📥 Commits

Reviewing files that changed from the base of the PR and between 913a3ab and e7a8f79.

📒 Files selected for processing (2)

• docs/docs.json
• docs/en/guides/advanced/security-best-practices.mdx

[pandego]

Rebased this branch onto the current main and force-pushed the refreshed branch.

Validation:

• python3 -m json.tool docs/docs.json >/dev/null && git diff --check

The PR should be back in a clean review state.

[pandego]

Rebased this branch onto the current main and force-pushed the refreshed branch.

Validation:

• python3 -m json.tool docs/docs.json >/dev/null && git diff --check

The PR should be back in a clean review state.

[pandego]

Rebased this branch onto the current main and force-pushed the refreshed branch.

Validation:

• jq empty docs/docs.json
• git diff --check upstream/main...HEAD
• checked for conflict markers in docs/ and docs/docs.json
• confirmed the diff only touches Edge docs, not frozen docs/v* snapshots

I also tried to run mintlify broken-links locally under Node 22 via npx; it started scanning but did not complete locally, so the full broken-link result is left to CI.

[pandego]

Rebased this branch onto the current main and force-pushed the refreshed branch.

Validation:

• python3 -m json.tool docs/docs.json >/dev/null && git diff --check

The PR should be back in a clean review state.

[pandego]

Rebased this branch onto the current main and force-pushed the refreshed branch.

Validation:

• python3 -m json.tool docs/docs.json >/dev/null && git diff --check

The PR should be back in a clean review state.

[pandego]

Rebased this branch onto the current main and force-pushed the refreshed branch.

Validation:

• python3 -m json.tool docs/docs.json >/dev/null && git diff --check

The PR should be back in a clean review state.

[pandego]

Rebased this branch onto the current main and force-pushed the refreshed branch.

Validation:

• python3 -m json.tool docs/docs.json >/dev/null && git diff --check

The PR should be back in a clean review state.

[pandego]

Rebased this branch onto the current main and force-pushed the refreshed branch.

Validation:

• python3 -m json.tool docs/docs.json >/dev/null && git diff --check

The PR should be back in a clean review state.

[pandego]

Rebased this branch onto the current main and force-pushed the refreshed branch.

Validation:

• python3 -m json.tool docs/docs.json >/dev/null && git diff --check

The PR should be back in a clean review state.

[pandego]

Rebased this branch onto the current main and force-pushed the refreshed branch.

Validation:

• python3 -m json.tool docs/docs.json >/dev/null && git diff --check

The PR should be back in a clean review state.