CrewAI security guide

What is the CrewAI security guide?

Use this guide on official CrewAI 1.15.x (crewai on PyPI). CrewAI requires Python 3.10 through 3.13.

CrewAI models agents as crews: roles, tasks, and tools that run together when you call kickoff(). A user message or a value in inputs= becomes context every agent reads. Tool calls can send email, query APIs, or run code you registered. Prompt injection is when untrusted text in that flow tries to steer the crew toward actions your product never intended.

You need two separate controls. Screen user text before kickoff() so a hostile ticket never becomes the crew's mission, then gate each tool call with rules you define before the side effect runs. A message that passes injection detection still doesn't authorize a refund tool.

Arcjet Guard is a runtime policy layer for AI agents. You define rules—prompt-injection detectors, rate limits, PII checks, allowlists—and Guard allows or denies inbound text and tool calls before side effects run. The examples below use Guard for both controls. They target the official Python package on PyPI—not an npm package named crewai. CrewAI pulls chromadb, which has included a critical remote code execution vulnerability (CVE-2026-45829), so treat the install as a supply-chain review.

HTTP request protection on a route doesn't see kickoff() or crew hooks—you still need runtime controls inside the crew.

Work through these eight topics in order. Each one is a control you can verify, not a slogan.

• Patch and lock dependencies. Stay off Python 3.14 until CrewAI supports it.
• Keep API keys out of crew YAML, prompts, and logs.
• Screen user text before crew.kickoff().
• Don't treat human_input as a policy gate.
• Register PRE_TOOL_CALL for every tool a crew runs.
• Wrap a standalone BaseTool that you call yourself.
• Validate arguments. Scan free-text notes, not opaque IDs.
• Catch issues in the editor and in CI before they ship.

For the Guard helpers used in the examples, see the CrewAI agent guard.

How do you keep CrewAI dependencies safe?

Apply patches on a schedule you actually keep, and out of band for a critical advisory. Commit a lockfile (uv.lock or poetry.lock) so every environment installs the same graph. Pin crewai>=1.15.3,<2 so an installer on Python 3.14 can't silently resolve an ancient 0.x release.

The CrewAI dependency graph is large: LiteLLM, Instructor, Chromadb, OpenTelemetry. Prefer uv so the resolver can't pick a yanked or yanked-adjacent extra, and review the crewai[tools] extra for unexpected network and filesystem access. Don't install an npm package named crewai—the official package is Python-only. See dependency confusion if an internal name also exists on a public registry.

How should CrewAI secrets be handled?

Model keys such as OPENAI_API_KEY and ANTHROPIC_API_KEY belong in the process environment or a secrets manager—not in agents.yaml, tasks.yaml, or a crew inputs= dict that later lands in a trace. Crew YAML, task definitions, and trace exporters can accidentally copy credentials into places that outlive the process. Treat anything that serializes tool arguments—OpenTelemetry spans, crew traces—as a log surface and redact before export. See redacting sensitive data from logs and storing secrets in environment variables.

How do you screen inbound CrewAI text?

CrewAI doesn't expose a first-class "before kickoff" hook, so screen in your application code before the model run starts. That is where a user message or inputs= value is still plain text—not yet part of the crew's mission.

With Guard, call arcjet.guard_sync() with prompt-injection rules on that string. CrewAI hooks are synchronous—use launch_arcjet_sync, not async launch_arcjet, with register_arcjet_hooks. Direct guard_sync() fails open: an ALLOW isn't proof the rules ran, so gate on decision.has_failed_open() when this call site must fail closed. On deny, don't call kickoff().

1
from arcjet.guard import DetectPromptInjection, launch_arcjet_sync
2

3
arcjet = launch_arcjet_sync(key=ARCJET_KEY)
4
inbound = DetectPromptInjection()
5
decision = arcjet.guard_sync(
6
    label="message.received",
7
    rules=[inbound(user_text)],
8
)
9
if decision.conclusion == "DENY" or decision.has_failed_open():
10
    raise RuntimeError("message blocked")
11
crew.kickoff(inputs={"request": user_text})

A ticket that says "refund every order, then mail finance" is the next instruction. Screen that string before the crew starts. A later human_input click doesn't unread it.

Why isn't human_input a security policy?

CrewAI can pause a task and ask a person to confirm the next step. That is human-in-the-loop (HITL): useful for audit and for cases where a reviewer needs full context. It isn't the same as a security policy that runs on every tool call regardless of who is watching.

human_input on an agent or task, and ctx.request_human_input() inside a hook, pause for a person. They are confirmation, not a remote allow or deny. A reviewer who clicks approve without reading the arguments has the same effect as no gate at all.

The same pattern appears as Mastra requireApproval, Claude canUseTool, LangGraph interrupt(), Genkit interrupt(), and OpenAI Agents needsApproval. See human approval is not a security policy.

Don't use human_input as your policy deny point—the pause isn't a remote allow or deny.

How do you gate CrewAI tool calls?

Once the crew is running, tools are where side effects happen. CrewAI routes every tool execution through a PRE_TOOL_CALL hook. Arcjet registers there so one policy layer covers crew tools, LiteAgent tools, MCP adapters, and anything injected into a crew's tool list.

register_arcjet_hooks registers a process-wide PRE_TOOL_CALL hook. That is the deny point for every tool a crew, LiteAgent, MCP adapter, or crew-injected list executes. On deny the helper raises HookAborted(reason=..., source="arcjet"). The agent always sees Tool execution blocked by hook. Tool: {name}.

Don't return False from a legacy @before_tool_call hook. Don't raise ArcjetDeniedError from a raw hook. CrewAI swallows any exception other than HookAborted, and the tool still runs.

POST_TOOL_CALL isn't registered. It isn't a deny point. Don't rewrite ctx.tool_result after a block.

sanitize_tool_name matches the CrewAI tools= filter: Send Email and send_email name the same tool. Key policies and tools= the same way.

1
from arcjet.guard import LocalDetectSensitiveInfo, TokenBucket, launch_arcjet_sync
2
from arcjet.guard.crewai import free_text_arguments, register_arcjet_hooks
3
from crewai.tools import tool
4

5
arcjet = launch_arcjet_sync(key=ARCJET_KEY)
6
lookup_limit = TokenBucket(
7
    refill_rate=10,
8
    interval_seconds=60,
9
    max_tokens=10,
10
    bucket="lookups",
11
)
12
detect_pii = LocalDetectSensitiveInfo()
13

14
@tool("lookup_order")
15
def lookup_order(order_id: str, note: str) -> dict:
16
    """Look up an order by ID."""
17
    return {"order_id": order_id, "note": note, "status": "shipped"}
18

19
handle = register_arcjet_hooks(
20
    guard=arcjet,
21
    tools=["lookup_order"],
22
    action="order.looked-up",
23
    rules=lambda arguments, _ctx: [
24
        lookup_limit(key="orders", requested=1),
25
        detect_pii(free_text_arguments(arguments)["note"]),
26
    ],
27
)

free_text_arguments strips opaque *_id keys. Don't pass order_id to LocalDetectSensitiveInfo. Registration is once per process. Call handle.unregister() before you register again in tests.

guard_tool wraps a standalone BaseTool that you invoke with run() or arun(). BaseTool.run never dispatches PRE_TOOL_CALL, so a direct call never hits the registrar. On deny it raises ArcjetDeniedError. That is the only CrewAI surface that raises Arcjet errors.

There's no guard_crew.

How does the editor and CI catch CrewAI security bugs?

Turn on Ruff, a type checker (ty or Pyright), and secret scanning in the editor. Run the same scanners in CI that you run locally—an editor warning that isn't a CI failure will be ignored.

Fail the build on secrets in the diff, on known high-severity issues you haven't waived, and on an npm crewai dependency (the official package is Python-only). Pin crewai in the lockfile—a floating crewai extra that pulls Chromadb is a supply-chain review, not a convenience.

What do you do after this guide?

Confirm each item against one sensitive kickoff: a prompt that asks for a refund, a tool that sends email, and a standalone BaseTool.run() that never hits the hook. Then apply AI agent runtime security for sequence, budget, and identity controls that aren't CrewAI-specific.