AgentLock™
An adversarially benchmarked reference implementation for pre-action agent authorization.
Your AI agent needs a login screen. AgentLock is that login screen. Secure tool calls with declarative, framework-agnostic authorization blocks.
or pip install agentlock[crypto] for Ed25519 signed receipts
The Authorization Gap
Every critical computing system in history has a formal permissions layer. Except AI agents. Today, tool calls are wide open: if an LLM generates a tool call, the tool executes. This is the "Full Permission" anti-pattern.
Prompt Injection Risk
Malicious input can trick agents into calling tools they shouldn't.
Data Exfiltration
Unrestricted tool access leads to unauthorized mass data reading.
| System Layer | Auth Mechanism | State |
|---|---|---|
| Unix/Linux | User/Group (rwx) | SECURE |
| Databases | GRANT/REVOKE (CRUD) | SECURE |
| Cloud API | IAM / OAuth Scopes | SECURE |
| AI Agent Tools | None (Plain JSON) | AT RISK |
Interactive Simulation
Test the AgentLock gate yourself. Configure the context, attempt tool calls, and explore a browser simulation of the gate's decision pipeline.
Tool Permissions Block
Try it: execute send_email (allows), click Fetch web page, execute the identical call again (denies). Nothing about the call changed. Only the session's provenance did.
Gate Pipeline
Gate Response JSON
Session Audit Log (simulated)
This is a UI simulation of AgentLock's decision logic, including the provenance-lineage gate. The real engine is pip install agentlock; the quickstart below runs the same allow-then-deny flip in 15 lines.
{
"name": "send_email",
"description": "Send an email to a recipient",
"parameters": {
"to": { "type": "string" },
"subject": { "type": "string" },
"body": { "type": "string" }
},
"agentlock": {
"version": "1.4",
"risk_level": "high",
"requires_auth": true,
"allowed_roles": ["admin", "customer"],
"scope": {
"data_boundary": "authenticated_user_only",
"max_records": null,
"allowed_recipients": "known_contacts_only"
},
"rate_limit": {
"max_calls": 5,
"window_seconds": 3600
},
"data_policy": {
"output_classification": "may_contain_pii",
"prohibited_in_output": ["ssn", "credit_card"],
"redaction": "auto"
},
"context_policy": {
"source_authorities": {
"system_prompt": "authoritative",
"user_input": "user_input",
"web_search": "untrusted"
},
"reject_unattributed": true
},
"audit": { "log_level": "full" },
"human_approval": { "required": false }
}
}The AgentLock Block
A declarative metadata block that travels with every tool definition. Any agent framework can enforce security before a tool call hits your backend. No vendor lock-in required.
- 1
Declarative Security
Stop hardcoding permission checks. Declare them in the tool schema: roles, scope, data boundaries, and redaction rules.
- 2
Single-Use Tokens
Every authorized call gets a one-time token bound to the operation. Replay attacks are impossible by design.
- 3
Audit Ready
Every allow and deny produces a structured audit record, compatible with SIEM tools and compliance requirements.
The AgentLock Architecture
Layer 1: Agent
Conversation & Decision. Generates tool call intent.
Layer 2: Gate
The AgentLock Gate. Intercepts intent, validates identity and permissions.
Layer 3: Tool
Execution. Only runs if Layer 2 issues a one-time token.
Why this matters:
By separating the intent to call from the permission to call, AgentLock prevents autonomous agents from making dangerous mistakes or being manipulated by adversarial prompts. It brings Zero Trust to the AI tool ecosystem.
What AgentLock Prevents
AgentLock is designed to stop the most critical attack categories against AI agents.
| Attack Category | How AgentLock Prevents It |
|---|---|
Prompt Injection | Permission blocks are enforced at the infrastructure level, not by the LLM. Even if the agent is tricked, the gate denies unauthorized calls. |
Social Engineering | Role-based access control prevents agents from performing actions outside their assigned role, regardless of conversational manipulation. |
Data Exfiltration | Data boundary enforcement (authenticated_user_only, team, organization) and max_records limits restrict what data an agent can access. |
Privilege Escalation | Allowed roles are declared per-tool and validated by the gate. An agent cannot grant itself higher permissions. |
Tool Abuse | Rate limiting with sliding window enforcement prevents runaway loops, brute-force attacks, and excessive API consumption. |
Token Replay | Every execution token is single-use, operation-bound (SHA-256 of parameters), and time-limited. Replay attempts raise TokenReplayedError. |
Agent Impersonation | Session management with authenticated identity verification ensures agents cannot impersonate other users or roles. |
Memory Poisoning | Data policy enforcement with output classification and automatic redaction prevents sensitive data from leaking into agent memory. |
Indirect Prompt Injection (write-trailing-read) | Provenance-lineage gate: untrusted reads gate subsequent consequential writes. Deferred commit re-checks at end of turn. |
What's New in v1.5
The evidence layer: grant basis recording, execution confirmation, provenance on denials, and deferred-resolution logging. v1.5 records strictly more and decides identically, verified by A/B replay with zero decision diffs across 4542 replayable decisions.
Grant Basis Recording
Every allow now records the basis it was granted on: the block, the action class, and the lineage state that let it through. The record is written alongside the decision, so an audit can reconstruct exactly why a call was permitted, not just that it was.
Execution Confirmation
The gate captures whether a permitted call actually executed, closing the loop between authorization and action. A decision that was allowed but never ran is distinguishable in the record from one that allowed and executed.
Provenance on Denials
Denials now carry the provenance that produced them: which untrusted origin, which lineage taint, which deferred re-decision flipped the outcome. The reason a call was blocked is captured with the block itself.
Deferred-Resolution Logging
When a deferred action is re-decided at end of turn, the full resolution is logged: the initial state, the content that arrived after the call, and the final decision. Nothing about a deferred outcome is left implicit.
Integrations Extracted from Core
The LangChain and CrewAI integrations moved out of core into standalone packages, langchain-agentlock and crewai-agentlock. Core stays lean and framework-agnostic; adapters version on their own cadence.
v1.5 is an evidence and architecture release. Decision behavior is unchanged: the A/B replay confirmed zero decision diffs across 4542 replayable decisions.
What's New in v1.4
Selective action-class gating, novel lineage, action-class audit, needs_approval surfaced at the gate boundary, and schema v1.4.
Selective Action-Class Gating
Declare which action classes each tool belongs to. Deletions and membership changes stay taint-gated because no parameter value betrays them. Value-carrying writes release to parameter lineage, which covers them. The one declaration that weakens gating can only come from the tool's trusted registration block, never a caller.
Benchmarked, Pre-Registered
On AgentDojo's travel suite (gpt-4o-mini, tool_knowledge attack), selective action-class gating raised utility from 30.00% to 51.43%, which is 79% of the benign ceiling of 65.00%, while defense-effective attack success went from 2.14% to 0.00%. The defended agent outperformed the undefended agent under attack (36.43%). Predictions were pre-registered and committed before any run launched. On slack, no utility was recovered, by design: the suite has no soundly declarable value-carrying tool, and the control run confirmed the gate refuses to relax where relaxing is unsound.
Full report and pre-registrationAction-Class Audit
Run audit_action_classes() to see every tool as DECLARED, UNDECLARED, or NOT_COVERED, backed by what your traffic actually asserted. It will never confidently suggest the one declaration that weakens gating; that one requires a human.
Novel Lineage
Per-target classification of trusted, untrusted, and never-before-seen values, checked above the coarse taint gate.
v1.3: Provenance-Lineage Gating & Deferred Commit
Provenance-lineage gating, parameter lineage, deferred commit, and an external AgentDojo evaluation.
Provenance-Lineage Gating
Gates consequential writes on the provenance of what is already in the session. After an untrusted read (web content, external messages), consequential writes are blocked. The gate never inspects tool-call content, so there is nothing for an attacker to phrase around.
Parameter Lineage
Every tool-call parameter is checked against values that originated in untrusted context. An attacker-planted URL or email is denied even when the tool call itself looks legitimate. Values the user supplied themselves are always clean.
Deferred Commit
Consequential actions are queued and re-decided at end of turn against the complete session provenance. Content that arrives after the call can still deny it.
Evaluated on AgentDojo
On the write-trailing-read threat model, the provenance-lineage gate achieved 0% defense-effective attack success on the banking and workspace suites across two models (GPT-4o-mini and GPT-4o), at a measured utility cost on benign tasks.
Read the paperAll v1.3 features are backward compatible and inert unless a lineage_policy is enabled.
v1.2: Adaptive Hardening & Decision Types
Adaptive hardening, three new decision types, and multi-signal threat detection.
Adaptive Prompt Hardening
Pre-LLM threat detection scans user messages before the model processes them. Dynamic system prompt injection based on real-time session risk scoring.
MODIFY Decision Type
Transform tool outputs before the LLM sees them. PII redaction, domain restriction, path whitelisting. The tool runs but sensitive data never enters the model context.
DEFER Decision Type
Suspend ambiguous tool calls when context is insufficient. Auto-denies on timeout. Catches first-turn attacks on high-risk tools.
STEP_UP Decision Type
Require human approval when session risk is elevated. Catches multi-tool escalation patterns and post-denial retries.
5 Decision Types
ALLOW, DENY, DEFER, STEP_UP, MODIFY. Beyond binary allow/deny.
4 Signal Detectors
Behavioral velocity, tool combination anomaly, response echo detection, and pre-LLM prompt scanning.
Ed25519 Signed Receipts (AARM R5)
Every authorization decision produces a cryptographically signed receipt. Verifiable offline without gate access. Ed25519 default with HMAC-SHA256 fallback. Install with pip install agentlock[crypto].
Hash-Chained Context (AARM R2)
Every context entry includes the hash of the previous entry, forming a tamper-evident append-only chain. Modifying any entry invalidates all subsequent entries.
First-Call Deferral
Defer the first tool call in any session regardless of risk level. Catches first-turn attacks before signals accumulate.
Deny-on-Block Escalation
When a whitelist transformation blocks a parameter, MODIFY escalates to DENY. The tool does not execute.
Foundation features carried into v1.2.1
Context Provenance Tracking
Every piece of context carries source attribution, authority level, and content hash.
Trust Degradation
Session trust is monotonic. Once untrusted content enters context, trust only goes down. Requires new session to reset.
Memory Gate
Controls who can read and write to agent memory, with persistence scope (none, session, cross-session) and prohibited content rules.
3 Context Authority Levels
authoritative, derived, untrusted.
Full Backward Compatibility
v1.2.1 stays fully backward compatible with all earlier policies. Existing definitions continue to work without changes.
Independent Filter Pipeline
Injection defense and PII protection run as separate, non-interfering layers. Tuning one never degrades the other.
Tested Against 181 Adversarial Attacks
Five-way progression (v1.0 → v1.1.2), tested against a LangChain agent on Gemini 2.5 Flash-Lite. Injection failures fell from 73 (no protection) to 12; PII leaks from 3 to 0. The report includes the regressions: v1.1 broke PII protection chasing injection gains, v1.1.1 regressed injection restoring PII, v1.1.2 decoupled the two pipelines and held both.
We ran the same enterprise attack suite against a LangChain agent with and without AgentLock. Same model. Same tools. Same attacks. Only the middleware changed.
| Metric | No AgentLock | AgentLock v1.2.1 |
|---|---|---|
| Injection Failures | 73 | 12 |
| Injection Pass Rate | 56% | 93.4% |
| PII Leaks | 3 items leaked | 0 (perfect) |
| YARA Threat Signatures | 13 | 2 |
| Attack Categories Eliminated | 0 | 17 of 29 |
| Overall Security Score | 45/F | 66/D |
The 12 remaining failures are model-layer information leakage: the LLM confirms it has a system prompt while refusing to share it. No middleware can fix this. It requires model-level instruction tuning.
Tested Against 222 Adversarial Attack Vectors
Compromised-admin profile (v1.2.x), tested against Grok, where valid admin credentials pass every auth and role check, isolating behavioral and structural defenses from role-based access control. Pass rate: 30.2% (permissions only) → 81.3% (adaptive hardening + MODIFY/DEFER/STEP_UP) → 99.5% (v1.2.1).
The hardest test. The attacker has valid admin credentials with full permissions. Auth and role checks pass on every call. AgentLock must rely on adaptive hardening, output modification, and behavioral detection to stop attacks.
| Metric | Without Hardening | AgentLock v1.2.1 |
|---|---|---|
| Pass Rate | 30.2% | 99.5% |
| Grade | F | A |
| Categories at 100/A | 0 | 34 |
| Categories at 80/B+ | 0 | 35 |
| Raw PII Exfiltrated | Yes | Zero |
AgentLock v1.2.1 introduces Ed25519 signed receipts, hash-chained tamper-evident context, first-call deferral for all tool risk levels, and deny-on-block whitelist escalation. Combined with v1.2.0's adaptive hardening, MODIFY, DEFER, and STEP_UP decision types, AgentLock achieves a 99.5% pass rate with only 1 failure out of 222 adversarial attack vectors. Zero raw PII exfiltrated.
The v1.2 suite is authored and graded in this repo. The external AgentDojo evaluation is complete as of v1.3, see the paper.
AgentDojo (external evaluation, v1.3)
On the write-trailing-read threat model, the provenance-lineage gate achieved 0% defense-effective attack success on the banking and workspace suites across two models (GPT-4o-mini and GPT-4o). This result is scoped to that threat model, not a claim against all attacks or threat models. The utility cost on benign tasks is measured and disclosed in the paper.
Full methodology and results: the paperAARM Conformance
AgentLock covers 7 of 9 AARM requirements with 2 foundations shipped.
| ID | Requirement | Status |
|---|---|---|
| R1 | Action Mediation | SHIPPED |
| R2 | Context Accumulation | SHIPPED (v1.2.1) |
| R3 | Policy Engine | SHIPPED |
| R4 | Decision Types (5) | SHIPPED |
| R5 | Signed Receipts | SHIPPED (v1.2.1) |
| R6 | Identity Attribution | SHIPPED (delegation designed) |
| R7 | Drift Detection | SHIPPED |
| R8 | SIEM Export | Foundation SHIPPED |
| R9 | Least Privilege | SHIPPED |
A Reference Implementation, Not a Competing Standard
AgentLock is a reference implementation of the emerging pre-action authorization consensus: a concrete, testable instance of controls that independent specs (OAP's PAA-1 through PAA-5, OWASP Agentic Top 10) are converging on. AGPL-3.0 licensed (commercial licenses available), framework-agnostic, and designed so that any agent framework can enforce security without buying anything.
| Capability | AgentLock | MS AGT | OAP | NeMo | AgentMint |
|---|---|---|---|---|---|
| Pre-action authorization gate | ✅ | ✅ | ✅ | ❌ | ⚠️ |
| Session-level compound behavioral scoring | ✅ | ❓ | ❌ | ❌ | ❌ |
| Decision types beyond allow/deny | ✅ | ✅ | ⚠️ | ⚠️ | ❌ |
| Published adversarial benchmark with regression data | ✅ | ❌ | ⚠️ | ❌ | ❌ |
| Trust degradation within session | ✅ | ❓ | ❌ | ❌ | ❌ |
| Ed25519 signed receipts | ✅ | ✅ | ❓ | ❌ | ✅ |
| Hash-chained tamper-evident audit | ✅ | ✅ | ✅ | ❌ | ✅ |
| Framework integrations (count) | 6 | ~19 | ~7 | 1 | 5 |
| Language SDKs (count) | 1 | 5 | 1 | 1 | 2 |
Read this honestly: Microsoft's Agent Governance Toolkit is ahead of AgentLock on distribution and cryptographic surface: more framework integrations, more language SDKs, per-call Ed25519 receipts, a Merkle-chained audit log, and a peer decision model. Signed receipts and hash-chained audit are becoming table stakes, not differentiators. What's actually narrow and defensible about AgentLock is two things: a published adversarial benchmark that includes its own regressions (nobody else in this table shows their setbacks), and session-level compound behavioral scoring that fires on sequences of calls, not a single scalar trust score. A smaller, single-language reference implementation whose edge is rigor and behavioral analysis, not distribution.
Try It Yourself
Install from PyPI and protect your first tool in under a minute.
pip install agentlock
pip install agentlock[crypto] # for Ed25519 signing
# quickstart.py
from agentlock import AuthorizationGate
gate = AuthorizationGate()
gate.register_tool("send_email", {
"version": "1.4",
"risk_level": "high",
"requires_auth": True,
"allowed_roles": ["admin", "support"],
"scope": {
"data_boundary": "authenticated_user_only",
"allowed_recipients": "known_contacts_only"
},
"rate_limit": {
"max_calls": 10,
"window_seconds": 3600
},
"data_policy": {
"output_classification": "may_contain_pii",
"prohibited_in_output": ["ssn", "credit_card"],
"redaction": "auto"
},
"audit": {"log_level": "standard"},
"human_approval": {"required": False}
})
result = gate.authorize(
"send_email",
user_id="alice",
role="admin"
)
if result.allowed:
print(f"Authorized: token={result.token.token_id}")
else:
print(f"Denied: {result.denial}")Roadmap
Where AgentLock is headed.
Tool Permissions
SHIPPEDDeclarative authorization blocks, single-use tokens, rate limiting, data redaction, audit trail.
Context Authority & Memory Gate
SHIPPEDContext authority model with trust degradation, provenance tracking, memory access control. Independent injection and PII filter pipeline.
Adaptive Hardening & Decision Types
SHIPPEDAdaptive hardening, MODIFY/DEFER/STEP_UP decisions, Ed25519 signed receipts, hash-chained context, multi-signal detection. 847 tests.
Provenance-Lineage Gating & Deferred Commit
SHIPPEDSession write-gate, parameter lineage, deferred commit. Evaluated on AgentDojo. 868 tests.
Selective Action-Class Gating & Novel Lineage
SHIPPEDPer-tool action-class declarations, novel lineage, action-class audit, needs_approval at the gate boundary. Schema v1.4. 1041 tests.
Evidence Layer
SHIPPED(stable)Grant basis recording, execution confirmation, provenance on denials, deferred-resolution logging. Records strictly more and decides identically, verified by A/B replay with zero decision diffs across 4542 replayable decisions. LangChain and CrewAI integrations extracted into standalone packages (langchain-agentlock, crewai-agentlock). 1141 tests.
Execution Scope & Behavioral Policy
Restrict where agent outputs can be sent: channels, APIs, and storage destinations. Full behavioral policy engine. Constrain what agents can do, not just what tools they can call. Compliance report templates for SOC 2, HIPAA, EU AI Act, and SR 11-7.
Aligning with Global AI Safety Standards
NIST AI 100-1
Risk Management Framework
OWASP LLM01
Injection Mitigation
MITRE ATLAS
Threat Context Alignment
EU AI Act
Governance & Compliance
Research
Peer-referenced work behind AgentLock's design and evaluation.
ORCID: 0009-0005-5388-123X
Frequently Asked Questions
What is AgentLock?
AgentLock is an open-source, adversarially benchmarked reference implementation for pre-action AI agent authorization. Deny-by-default tool permissions, signed receipts, audit logging. AGPL-3.0 (commercial licenses available). pip install agentlock.
Is AgentLock free?
Yes. AgentLock is AGPL-3.0 licensed and free to use. Commercial licenses are available for organizations that cannot adopt AGPL.
Is this the same as agentlock.net or the AgentLock iOS app?
No. AgentLock (agentlock.dev), created by David Grice, is not affiliated with agentlock.net, the AgentLock iOS app on the App Store, or GiliSoft's AI Agent Lock. This project is the open-source Python framework at github.com/webpro255/agentlock and has no official mobile app.