Principal
Agent::"research"Who is asking? A user or an agent.
OPEN-SOURCE AUTHORIZATION CONTROL PLANEGive every AI action
Give every AI action
a policy boundary.
AgentGuard evaluates proposed tool calls against Cedar policies before your application executes them. Separate intent from permission, and keep a record of the decision.
AUTHORIZATION REQUESTILLUSTRATIVE
- PRINCIPAL
- Agent::"research"
- ACTION
- Action::"ToolCall::repo_read"
- RESOURCE
- Repository::"demo"
- CONTEXT
- session.mfa: true
01 REQUEST → 02 POLICY → 03 DECISIONALLOW
Principal, action, resource, and MFA match.
Sample audit: effect = allow
Infrastructure authorization at the tool boundary. Policy stays outside model reasoning.Follow a request ↓
01 / INTENT ≠ PERMISSIONA tool call is a proposal.
A tool call is a proposal.
Make permission explicit.
A model can choose an action. Your application still needs to decide whether that principal may perform it on that resource, in this context.
An unguarded execution path
Agent intent→Tool execution
Access follows whatever credentials the tool happens to hold.
A policy enforcement point
Agent→AgentGuard→Tool
Your adapter asks for a decision and executes only on allow.
Action
Action::"ToolCall::repo_read"What operation is being proposed?
Resource
Repository::"demo"Which object will the tool touch?
Context
session.mfa: trueWhich trusted facts apply now?
02 / REQUEST LIFECYCLEFrom proposed action
From proposed action
to an explicit decision.
The HTTP path joins policy evaluation, configured audit logging, and response handling. Your application supplies identity and owns tool execution.
Intercept
Your adapter catches the proposed tool call before execution.
Resolve identity
Authenticate the caller and derive the acting principal in trusted application code.
Build the request
Map principal, action, resource, context, and required entities.
Evaluate
The Cedar authorizer returns allow or deny with policy diagnostics.
Record
The configured server audit log receives the decision before it is returned.
Return
The PDP responds to the adapter. Errors are not permission.
Enforce
Your adapter executes only on an explicit allow.
Observe
Inspect decision metrics and trace context; connect telemetry sinks where needed.
The embedded engine returns a decision without automatically writing an audit record. The CLI logs by default unless audit is skipped. Step-up is represented in SDK response handling; the current Cedar/server decision path returns allow or deny.
03 / POLICY AS CODEReadable rules.
Policy authoring and operational limits →
Readable rules.
Reviewable authority.
Cedar gives authorization a dedicated language: explicit principals, actions, resources, and conditions. Its Rust engine and typed schema keep policy separate from your tool implementation.
01
Default deny
No matching permit means deny. A matching forbid takes precedence.
02
Validate before rollout
Keep rules in .agentguard/policies/ and run agentguard validate against schema.cedarschema.
03
Inspect policy changes
Rust library APIs provide versioned bundles, line diffs, and replay-based blast-radius analysis. Rollback requires restoring a prior bundle and reloading the authorizer.
.agentguard/policies/20_agents.cedar
permit (
principal == Agent::"research",
action == Action::"ToolCall::repo_read",
resource == Repository::"demo"
) when {
context.session has mfa &&
context.session.mfa
};One bounded grant. The principal is research, the action is repo_read, the resource is demo, and verified MFA is required. This rule uses the repository’s starter schema.
Replace both generated starter policies for this example. The standalone watcher atomically reloads a complete policy snapshot after successful parsing; malformed edits retain the last known-good snapshot.
04 / AUDITABILITYA decision you can
Record format, verification, and SIEM export →
A decision you can
come back to.
With a chain secret configured, each audit record links to the previous record using HMAC-SHA256. Verify the chain when investigating a decision or exporting evidence.
Without a secret, the log is plain JSONL. Protect the secret and preserve an independent trusted checkpoint to detect log replacement or tail truncation.
JSONLCEFLEEFECS
Verify and export
agentguard audit verify --secret-file .chain-secret
agentguard audit export --format ecs --out decisions.ecs.jsonlILLUSTRATIVE CHAIN · ABBREVIATED HASHES
RECORD #1842ALLOW
research · repo_read · demo
previous hash
7e2…record hash
a61…timestamp
sample · 12:00:00ZRECORD #1843DENY
summarizer · repo_read · demo
previous hash
a61…record hash
b03…timestamp
sample · 12:00:01ZRECORD #1844ALLOW
research · repo_read · demo
previous hash
b03…record hash
c92…timestamp
sample · 12:00:02ZIllustration only. Use the CLI for cryptographic verification.
ILLUSTRATIVE DELEGATION
PARENT
Agent::"research"Application checks the parent’s authority.
↓ Signed grant · Ed25519 JWS
Selected action + selected resource + TTL
Selected action + selected resource + TTL
SUB-AGENT
Agent::"summarizer"Action: ToolCall::repo_read
Resource: Repository::demo
TTL: 300 seconds
05 / SCOPED DELEGATIONPass a bounded grant.
Pass a bounded grant.
Keep authority explicit.
Mint signed tokens with action scopes, resource patterns, and expiry. Verify signatures, audience, and time claims with the Rust verifier.
Your integration must enforce those scopes and ensure the parent may delegate them. DPoP is a separate verifier library. The standalone PDP does not automatically consume delegation tokens, and there is no delegation revocation endpoint.
Understand delegation responsibilities →06 / IDENTITYKnow the caller.
Know the caller.
Then evaluate the action.
Authentication and authorization are separate steps. Map trusted identity into a Cedar principal before submitting a decision request.
Identity source
JWT / OIDC · API keys
SPIFFE workload identity
Validation & mapping
Your application validates identity and resolves the acting subject.
Cedar principal
User::"alice" or
Agent::"research"
Standalone PDP: API-key authentication or local disabled mode. Console: OIDC sign-in with viewer/admin roles. Rust libraries: JWT, OIDC discovery, DPoP verification, and feature-gated SPIFFE/SPIRE Workload API access. These are distinct integration surfaces.
Identity methods and trust boundaries →07 / SYSTEM ARCHITECTUREOne policy engine.
One policy engine.
Several ways in.
Expand a component to inspect its role and integration boundary. Requests flow toward the engine; decisions return to the enforcement point.
01 / APPLICATION →
Integration surfaces
Agent / tool adapter
Calls the PDP before execution and honors deny and transport failures.
TypeScript → CLI
typescript/agentguard spawns the local binary synchronously.
CLI
agentguard-cli handles local authorization, simulation, audit, and token operations.
Admin console
frontend uses HTTP for simulation and the CLI for audit and delegation.
02 / AUTHORIZATION →
AgentGuard
HTTP / gRPC server
agentguard-server maps requests to the core authorizer. API-key middleware protects decision routes.
Cedar engine
agentguard-core evaluates loaded policies against a typed request and supplied entities.
Embedded Rust
Use Authorizer directly in-process, or build_router to embed the HTTP surface.
Decision cache
LRU + TTL cache in core. Standalone startup enables it with environment overrides; embedders enable it explicitly.
03 / STATE & EVIDENCE
Local, inspectable state
Policy store → engine
.agentguard/schema.cedarschema and policies/*.cedar are local files.
Identity / auth
agentguard-auth provides validation libraries; the application binds identity to a principal.
Engine → audit
Configured server logging persists decisions; a chain secret enables HMAC-linked records.
Metrics / telemetry
Server Prometheus metrics and trace context; library sinks for stdout, JSONL, and optional OTLP.
REQUEST → PRINCIPAL · ACTION · RESOURCE · CONTEXT← ALLOW / DENY → ADAPTER → TOOL
Embedded
Use the Rust authorizer in your application when you own the process and security lifecycle.
App [ Authorizer → Tool ]
Sidecar
Keep the standalone PDP beside your agent runtime. Use a local HTTP or gRPC boundary.
Agent ⇄ local PDP → decision
Standalone PDP
Centralize HTTP decisions for multiple callers. Configure authentication, TLS, and durable audit storage.
Applications ⇄ HTTP PDP
08 / DEVELOPER EXPERIENCEStart at your
Start at your
tool boundary.
Use the same request model through your preferred interface. These examples follow the repository’s current APIs; the quickstart supplies their policy and request data.
authorize.ts
import { Client, Principal, Action } from "agentguard";
const guard = new Client({ store: ".agentguard" });
guard.check(
Principal.agent("research"),
Action.tool("repo_read"),
{ entity_type: "Repository", uid: "demo", attrs: { org: "example" } },
{ args: { repo: "demo" }, session: { mfa: true } },
);
// Permission granted. Your application may now run the tool.
// On denial, check() throws AuthorizationDenied.Node.js SDK. Spawns the installed CLI synchronously. Call your tool only after check() returns.
Local HTTP request
curl --fail-with-body http://127.0.0.1:8443/access/v1/evaluation \
-H 'Content-Type: application/json' \
-d '{
"subject": {
"type": "Agent",
"id": "research"
},
"action": {
"type": "Action",
"id": "ToolCall::repo_read"
},
"resource": {
"type": "Repository",
"id": "demo"
},
"context": {
"args": {
"repo": "demo"
},
"session": {
"mfa": true
}
}
}'
# Proceed only if the response succeeds and decision === true.For the loopback quickstart. Remote deployments need transport protection and authenticated access.
Evaluate and inspect
agentguard validate
agentguard --output json authorize request.json
agentguard sim request.json
agentguard log tail --n 10
agentguard doctorrequest.json is the CLI request from the quickstart. Exit code 2 means deny; other failures must also stop execution.
Embedded authorizer
use agentguard_core::{AgentRequest, Authorizer, PolicyStore};
use cedar_policy::Entities;
let store = PolicyStore::open(".agentguard")?;
let authorizer = Authorizer::new(store)?;
let req: AgentRequest = serde_json::from_str(request_json)?;
// This policy uses IDs and context, not entity attributes.
let entities = Entities::empty();
let decision = authorizer.authorize(&req, &entities)?;
// Check decision.effect before executing the tool.
// Append to your configured DecisionLog at this boundary.Inside a function returning Result. The embedded engine returns a decision; your application owns enforcement, identity, and audit wiring.
Repository example
import { AgentGuard, guarded } from "./guard.js";
const guard = new AgentGuard({
principal: { type: "Agent", id: "research" },
resource: { type: "Repository", id: "demo" },
});
// Wrap your tool config before registering it with Strands:
const protectedTool = guarded(guard, toolConfig);
// The callback runs only after an explicit HTTP allow.
// Tailor the schema and policy to toolConfig's input.The guarded() helper belongs to examples/strands-tool-authz. It is an example adapter, not an exported SDK method.
Strands tool authorization
An HTTP guard wraps tool execution. Transport errors and missing permission stop the callback. Includes a BeforeToolCallEvent intervention example.
Explore the Strands example ↗Embed an Axum router
Mount AgentGuard’s HTTP router in an existing Rust application. Review the nesting path and configure audit and authentication for your deployment.
Explore the Rust example ↗AuthZEN-compatible clients can call the HTTP interface. Custom frameworks, LangChain loops, and MCP tool servers can integrate through their own enforcement adapter. This is interoperability, not a claim of official adapters for those projects.
09 / STANDARDS & SURFACESProtocols with
Protocols with
a purpose.
Support is specific to a component and interface. Library primitives are not automatically enabled server features, and compatibility is not certification.
Policy language
The Rust engine evaluates typed authorization requests.
Inspect implementation ↗Decision interface
HTTP single and batch evaluation; a repository-defined gRPC mirror.
Inspect implementation ↗Request correlation
HTTP traceparent input and child span identifiers.
Inspect implementation ↗JWT validation
Library checks signatures, issuer, audience, and time claims.
Inspect implementation ↗Issuer discovery
OIDC library metadata discovery with issuer validation.
Inspect implementation ↗Proof of possession
DPoP verifier library checks binding, signature, method, URI, and replay.
Inspect implementation ↗Workload identity
Feature-gated Workload API client with trust-domain validation.
Inspect implementation ↗Delegation concepts
Actor and audience claims are building blocks; no token-exchange endpoint or resource-parameter API is exposed.
Inspect implementation ↗10 / OPERATE & INVESTIGATEFollow the decision
Follow the decision
across your system.
The server accepts W3C traceparent and returns x-agentguard-span-id. Prometheus metrics expose authorization activity; audit records preserve decision evidence.
The telemetry crate provides a Sink interface and an optional OTLP/gRPC log exporter. Connect it in your embedding application; setting an endpoint alone does not enable export in the standalone server.
Metrics, trace fields, and sink wiring →ILLUSTRATIVE REQUEST TRACE · NOT MEASURED TIMING
tool adapter
authorization
audit append
tool execution
traceparent → child span → x-agentguard-span-id
Decision · metric · audit record · optional telemetry sink
Decision · metric · audit record · optional telemetry sink
11 / EXPLORE A DECISIONA small policy.
A small policy.
A visible boundary.
Change a request and inspect the result. This browser simulation checks the four conditions below in JavaScript. It does not execute Cedar, contact a server, or create an audit record.
The only policy in this simulation
permit (
principal == Agent::"research",
action == Action::"ToolCall::repo_read",
resource == Repository::"demo"
) when {
context.session has mfa &&
context.session.mfa
};Illustrative decision
ALLOW
All permit conditions match. The adapter may execute the tool.
- ✓ Principal is research — matches
- ✓ Action is repo_read — matches
- ✓ Resource is demo — matches
- ✓ Session has MFA — matches
Inspect authorization request
{
"subject": {
"type": "Agent",
"id": "research"
},
"action": {
"type": "Action",
"id": "ToolCall::repo_read"
},
"resource": {
"type": "Repository",
"id": "demo"
},
"context": {
"args": {
"repo": "demo"
},
"session": {
"mfa": true
}
}
}Inspect sample audit fields
Illustrative fields only. No signature or chain is generated here.
{
"effect": "allow",
"principal": "research",
"action": "repo_read",
"resource": "demo",
"policies": [
"example-permit"
],
"timestamp": "illustrative timestamp"
}AGENTGUARD / CONSOLEREPRESENTATIVE UI
Audit logSimulatorDelegation
SAMPLE DATA · NOT A LIVE CONSOLE
Authorization decisions
PrincipalActionEffect
researchrepo_readallow
summarizerrepo_writedeny
Signed in as viewer · delegation issuing requires admin.
12 / OPTIONAL ADMIN CONSOLEInspect decisions.
Inspect decisions.
Test your next request.
The Next.js console offers audit browsing with filters, an HTTP-backed authorization simulator, and admin-only delegation issuing and verification.
OIDC sign-in is mandatory. Viewer/admin roles gate access, and missing authentication configuration returns 503. The console is a separate application you run in your infrastructure.
Configure and run the console ↗13 / YOUR FIRST DECISIONClone. Define.
Clone. Define.
Authorize.
Start locally with Rust 1.89+ and protoc for the server build. The guide walks from the generated schema to a narrow permit, a real allow/deny pair, an HTTP request, and audit verification.
The CLI includes init, validate, authorize, sim, delegate, verify, schema, log, audit, gen, and doctor. The server has its own binary; policy operations are Rust library APIs.
Follow the complete quickstart →First-run commands · walkthrough only
git clone https://github.com/sachncs/agent-guard.git
cd agent-guard
cargo install --path crates/agentguard-cli
cargo install --path crates/agentguard-serverBuild locally from source. These buttons display commands; they do not execute them.
14 / CONFIGURATIONExplicit settings.
Explicit settings.
Visible operating limits.
Local files define policies and audit storage. Server flags, library options, and console settings have different scopes.
Server
AGENTGUARD_LISTENLoopback HTTP by default. TLS listener for protected remote access.
Policy store
AGENTGUARD_STOREThe standalone server watches policy and schema files, then atomically reloads valid snapshots. Invalid changes retain the last known-good policy.
Audit
AGENTGUARD_CHAIN_SECRETPath to the HMAC secret. Required for a chained log.
Authentication
--auth apikeyStandalone API-key mode; console OIDC is configured separately.
Caching
Authorizer::with_cacheStandalone cache defaults to 10k entries / 60s allows / 5s denies; embedders use Authorizer::with_cache.
Telemetry
OTEL_EXPORTER_OTLP_ENDPOINTUsed when constructing the optional OTLP library sink.
gRPC
AGENTGUARD_GRPC_LISTENOptional plaintext listener, restricted to loopback.
Tracing
AGENTGUARD_TRACEPARENTCLI trace context; HTTP clients use the traceparent header.
15 / SECURITY MODELWhat AgentGuard enforces.
What AgentGuard enforces.
What your system must own.
A clear boundary is more useful than a broad security promise. Authorization is one control in your application’s security model.
The authorization layer
- Cedar allow/deny decisions over supplied request facts.
- Default deny and explicit forbid precedence.
- Configured server audit writes before returning decisions.
- Cryptographic audit chaining when a secret is configured.
- Signed delegation and identity verification primitives.
Your enforcement boundary
- Intercept every relevant tool path and honor deny or errors.
- Derive identity, MFA, and context from trusted sources.
- Protect policy files, secrets, logs, and network access.
- Enforce delegated scopes and parent authority.
- Address prompt injection, tool vulnerabilities, and actions outside the boundary.
16 / BUILT IN THE OPENThe control plane.
The control plane.
And the source behind it.
Six Rust crates, a TypeScript SDK, an optional console, and working integration examples. Inspect the implementation behind each interface.
agentguard-core ↗Cedar, entities, audit, cache, delegationagentguard-server ↗HTTP and gRPC decision interfacesagentguard-cli ↗Local policy and audit commandsagentguard-auth ↗Identity validation primitivesagentguard-policy ↗Bundles, diff, replay analysis, watcheragentguard-telemetry ↗Metrics and pluggable event sinkstypescript/agentguard ↗Node.js CLI-backed SDKfrontend ↗Optional OIDC-protected consoleexamples ↗Strands and Rust router examplesschemas ↗Starter Cedar schemasite ↗This static Astro product siteAvailable to build
Cedar authorization, HTTP/gRPC, audit export, TypeScript SDK, and the OIDC console. The shipped boundaries, compatibility notes, and current limitations are documented in the repository and versioned guides.
Operate with guardrails
Docker and Kubernetes manifests provide non-root images, health probes, resource limits, secret references, persistent audit storage, and explicit single-replica scaling limits for the current release.
Extend with confidence
Contributor setup, security response, compatibility policy, release checks, and API references are maintained alongside the implementation.
17 / BEFORE YOU BUILDTechnical questions.
Technical questions.
Direct answers.
Start with the boundary, then choose the integration and operating model that fit your application.
Is AgentGuard a hosted service?
No. It is Apache-2.0 software you deploy and operate. The public website has no hosted authorization backend.
Does it prevent prompt injection?
It constrains the actions a policy allows at an enforced tool boundary. It does not detect every malicious prompt, inspect model reasoning, or protect an unguarded execution path.
What happens if no policy matches?
Cedar denies by default. An applicable permit is required; an applicable forbid overrides permits. Replace broad generated starter policies before deployment.
Can I use my existing framework or LLM?
Yes, through an adapter that calls the HTTP PDP, CLI, or embedded Rust engine before execution. Strands has a repository example; other frameworks require integration work.
Where should authorization happen?
Immediately before a tool executes, using the actual target and arguments. Guard every relevant execution path, including retries and delegated calls.
Can it run as a sidecar or embedded?
The standalone server can run beside your application or as a shared PDP. Rust applications can use Authorizer in-process or mount build_router. Embedders own lifecycle and security configuration.
How are audit records protected?
Configure a chain secret to enable HMAC-SHA256 linked records. Protect the key, retain trusted chain checkpoints, and verify logs offline; a chain alone does not prove completeness.
How does delegation work?
The CLI and Rust primitives mint scoped, time-limited Ed25519 JWS tokens. Applications must verify tokens and enforce their action/resource scopes alongside Cedar.
What if the PDP is unavailable?
Stop execution. The Strands guard fails closed on transport errors and non-allow results. Custom adapters must implement the same behavior.
Which request context should be trusted?
Derive identity, MFA, ownership, and environment from trusted systems. API keys are bound to one User or Agent subject and the PDP rejects requests that claim a different subject. Tenant metadata is not automatically a Cedar policy attribute; encode tenant isolation explicitly in trusted entities and policies.
PUT POLICY IN THE EXECUTION PATHBetween intent and execution,