CrewAI security guide

How do you secure CrewAI?

To secure a CrewAI application, screen user text before kickoff(), register a PRE_TOOL_CALL policy hook, and authorize resources inside tool handlers. Wrap standalone BaseTool.run() calls separately because they bypass the crew hook. Human confirmation and prompt screening complement these checks; neither grants access to a resource.

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.

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 following examples use Guard for both controls. They target the official Python package on PyPI – not an npm package named crewai. Review transitive dependencies and the permissions of tools added to the crew, as well as the top-level package.

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

Use this checklist to review your application:

• 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. Use a committed lockfile, audit the resolved versions, 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 do you manage CrewAI secrets?

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 supports @before_kickoff. The Arcjet adapter does not supply a dedicated inbound helper: call Guard before kickoff(), as in the following example, or inside a @before_kickoff method that stops the run on denial. 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
    deny=["EMAIL", "PHONE_NUMBER", "IP_ADDRESS", "CREDIT_CARD_NUMBER"],
14
)
15

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

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

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 do 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.

How do you verify enforcement before deployment?

Use deterministic Guard responses and a handler call counter. A DENY or unavailable evaluation must leave the counter at zero; an authorized ALLOW must call the handler once. Also test another tenant's resource identifier: application authorization must still refuse access even when Guard allows.

Exercise crew execution and standalone BaseTool.run() separately: only the first traverses the process-wide hook. Test tools outside a registrar filter and confirm every intended capability has a policy. Unregister hooks between tests. Resolve per-request identity from request-local state, never a mutable global shared by concurrent crews.

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.