crewai-agentlock

Per-tool authorization for CrewAI agents. Every tool call gated, logged, and cryptographically signed.

The Problem

CrewAI registers tools permissively by default. If an agent has a tool in its tools=[...] list, it can invoke it on any input the model produces. When one agent delegates to another, permissions are not enforced at the tool level: the receiving agent runs the call with whatever role its own configuration grants. There is no runtime layer that evaluates whether this specific call, with these parameters, by this caller, at this point in the session, should be allowed.

Benchmark

AgentLock core ships 1041 tests as of tag v1.4.0. The v1.2.1 benchmark scored 99.5/A against 222 adversarial attack vectors across 35 categories, with a single remaining failure at the model layer. Full benchmark methodology at agentlock.dev.

Install

pip install crewai-agentlock

Quick Start

from agentlock import AgentLockPermissions, AuthorizationGate
from crewai import Agent, Crew, Task
from crewai.tools import tool
from crewai_agentlock import agentlock_session, lock_crew

@tool
def web_search(query: str) -> str:
    """Search the web."""
    return f"results for {query}"

@tool
def write_summary(topic: str) -> str:
    """Write a summary."""
    return f"summary of {topic}"

researcher = Agent(role="researcher", goal="research", backstory="A researcher.",
                   tools=[web_search, write_summary], allow_delegation=False)
writer = Agent(role="writer", goal="write", backstory="A writer.",
               tools=[write_summary], allow_delegation=False)

crew = Crew(
    agents=[researcher, writer],
    tasks=[
        Task(description="research", expected_output="notes", agent=researcher),
        Task(description="write", expected_output="text", agent=writer),
    ],
)

gate = AuthorizationGate()
lock_crew(crew, gate, permissions={
    "web_search": AgentLockPermissions(
        risk_level="medium",
        allowed_roles=["researcher"],
        rate_limit={"max_calls": 5, "window_seconds": 60},
        scope={"data_boundary": "authenticated_user_only", "max_records": 50},
    ),
    "write_summary": AgentLockPermissions(
        risk_level="low",
        allowed_roles=["researcher", "writer"],
    ),
})

with agentlock_session(user_id="u1", role="researcher", session_id="s1"):
    crew.kickoff()

The writer agent cannot call web_search even though the function is importable in the same process. Authorization is enforced at the gate, not at tool registration.

Delegation Enforcement

When Agent A delegates to Agent B, Agent B inherits the intersection of its own permissions and Agent A's permissions. A child agent can never exceed the permissions of the parent that spawned it. This is enforced through the active agentlock_session() and the role bound to it for the duration of the delegated call.

from crewai_agentlock import agentlock_session

with agentlock_session(user_id="u1", role="researcher"):
    # Researcher delegates to writer. The session role stays "researcher",
    # so the writer subtask can call any tool the researcher can call,
    # but tools whose allowed_roles exclude "researcher" still deny.
    result = crew.kickoff()

The session role is the upper bound. Even if the writer's own allowed_roles would permit a sensitive tool, the session role gates the call. Delegation cannot escalate.

Untrusted Tool Output

A tool's output is recorded in the session's provenance log. By default every wrapped tool records ContextSource.TOOL_OUTPUT, which the gate resolves to DERIVED authority: trusted. Tools that return attacker-reachable text should say so, via context_source:

from agentlock import ContextSource
from crewai_agentlock import wrap_tool

fetch = wrap_tool(
    web_fetch, gate, fetch_perms,
    context_source=ContextSource.WEB_CONTENT,  # gate resolves to UNTRUSTED
)

Use an untrusted source for web fetch, document retrieval, and peer-agent output (WEB_CONTENT, RETRIEVED_DOCUMENT, PEER_AGENT). This is what arms the gate's lineage checks: with a lineage policy enabled on the sink tool, a parameter value that traces back to that tool's output but not to the user's own request is denied on provenance, not on content.

The setting is per-tool and opt-in. The default is unchanged, so existing deployments keep their current behavior.

Scope, stated plainly. The wrapper passes each call's input arguments to the provenance write, so the engine's containment linker records a cross-hop parent link whenever a call's parameters carry a prior entry's content. Decision-time checks walk those recorded links. A value laundered through an intermediate tool that was itself called with the untrusted content is therefore denied with reason param_lineage, and the denial cites the relay entry the value came through rather than the original fetch. Enforcement is no longer single-hop.

What still bounds it, stated as plainly:

• An uncarried value produces no link. If the intermediate tool is invoked without the untrusted content, nothing was carried, no parent is recorded, and the rewritten value reaches the sink.
• Linking requires whole-content carriage. A prior entry's entire recorded content has to appear inside one of the call's argument values and clear the engine's containment floor. A partial quotation, or a summary the model composed rather than passed through, does not link.
• Encoded forms are measured at the engine, not here. No encoded corpus runs through this adapter, so no adapter-level claim about encoded values is made. See the engine's own limitations record.

Both directions are pinned by tests/test_carriage.py, which measures the carried session against the uncarried one rather than asserting either alone.

Decision Types

Every gate.authorize() call returns one of five decisions:

• ALLOW: the call meets every policy. The gate issues a single-use, parameter-bound execution token and the tool runs.
• DENY: the call fails one or more policies (role, scope, rate limit, data classification, hardening). The tool body never executes.
• MODIFY: the call is allowed but parameters or output are transformed first. Used when a policy can sanitize the request rather than reject it.
• DEFER: the gate cannot decide without out-of-band human review. The tool is suspended and a deferral id is returned to the caller.
• STEP_UP: the call requires fresh authentication beyond the existing session. Triggered on first use of high-risk tools, post-denial retries, and accumulated PII access in one session.

Example of MODIFY rewriting a path before execution:

from agentlock import AgentLockPermissions

write_file_perms = AgentLockPermissions(
    risk_level="high",
    allowed_roles=["admin"],
    modify_policy={
        "enabled": True,
        "transformations": [
            {
                "type": "regex_replace",
                "field": "path",
                "pattern": r"^\.\./",
                "replacement": "",
            },
        ],
    },
)

A request with path="../etc/passwd" is rewritten to path="etc/passwd" and runs. A whitelisted-only field that fails its allowlist escalates MODIFY to DENY automatically.

Audit Trail

Every authorization decision produces an Ed25519 signed receipt:

{
  "receipt_id": "rcpt_a3f7c91b2d4e6f80",
  "timestamp": 1745776800.123456,
  "decision": "allow",
  "tool_name": "web_search",
  "user_id": "u1",
  "role": "researcher",
  "parameters_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "reason": "",
  "policy_version_hash": "c2b1...",
  "context_hash": "5e88...",
  "trust_ceiling": "derived",
  "signing_key_id": "key_0a1b2c3d",
  "signature": "f3a2..."
}

Receipts are hash-chained. Tamper with one and the entire chain breaks.

Related

• AgentLock core: github.com/webpro255/agentlock
• langchain-agentlock: github.com/webpro255/langchain-agentlock
• openai-agentlock: github.com/webpro255/openai-agentlock
• awesome-ai-agent-attacks: github.com/webpro255/awesome-ai-agent-attacks

License

This package is Apache 2.0.

It depends on AgentLock, which is licensed AGPL-3.0-or-later from v1.3.0 onward, and this package requires agentlock>=1.7. Installing it therefore pulls in AGPL code, and combined use is subject to the AGPL: if you run it in a network service or distribute software built on it, the AGPL's terms apply to the combined work. Commercial licenses for AgentLock that remove the AGPL obligations are available at [email protected].

Read the AGPL and take your own advice on what it requires of you. This note is a pointer, not legal advice.