AI Security Engineering

AgentTrust — Least-Privilege Security for AI Agents

Identity, independently enforced authorization, MCP tool protection, audit evidence, and observability for AI-agent execution.

Public SDK enforcement is cooperative and in-process. The separately maintained gateway demonstrates an independent authorization point for protected MCP tools when deployment topology prevents direct bypass.

AI SecurityGoPythonJWT / Ed25519MCPOpenTelemetryPrometheusLeast Privilege

View Public SDK ↗Read Threat Model →

SDK

Cooperative enforcement

Public Python SDK guards first-party tool, MCP, and LangChain paths in-process.

Independent gateway

Separately maintained gateway verifies signed identity before protected MCP execution.

Audit

Lifecycle evidence

Authorization decisions and execution results correlate by request_id.

Obs

Observable enforcement

Traces, metrics, logs, and audit evidence distinguish ALLOW from DENY.

System Architecture

End-to-end architecture for least-privilege agent tool execution.

AgentTrust uses two complementary layers: the public SDK provides developer-facing, cooperative in-process controls, while the gateway provides an independently enforced authorization point before protected MCP execution.

SDK-level cooperative controls are complemented by an independently enforced gateway that reaches protected MCP tools only after authorization.

Independent enforcement assumes deployment topology prevents untrusted agents from directly bypassing the gateway and reaching protected upstreams.

Tool Execution Flow

How a protected tool request moves through AgentTrust.

A protected request is authenticated, resolved against trusted tool configuration, and exact-scope authorized before MCP execution. DENY terminates before the protected tool is invoked.

ALLOW / DENY Security Proof

Authorization decides whether MCP is reached.

The flagship demo grants deploy-agent service.status and logs.read. service_status is allowed and reaches MCP once; restart_service requires service.restart and is denied before MCP invocation.

Identity

deploy-agent

Granted scopes: service.status, logs.read

ALLOW

service_status

requires service.status -> MCP invocation count = 1

DENY

restart_service

requires service.restart -> not_executed -> MCP invocation count = 0

ALLOW

service_status

required_scope=service.status; deploy-agent has service.status.

1authenticate
2resolve service_status
3authorize ALLOW
4audit decision
5MCP execution
6execution_result ok

Demo evidence: MCP invocation count = 1.

DENY

restart_service

required_scope=service.restart; deploy-agent has service.status and logs.read.

1authenticate
2resolve restart_service
3authorize DENY
4audit not_executed
5NO MCP invocation

Demo evidence: result_status=not_executed and MCP invocation count = 0.

Key Capabilities

What this demonstrates.

A practical security layer for agent tools: cooperative SDK enforcement, independent gateway authorization, audit evidence, and observability.

Agent Identity

short-lived run identity
Ed25519 JWT verification
agent/run/token correlation

Tool Authorization

exact required-scope checks
deny-by-default unknown tools
out-of-scope calls blocked

Gateway Routing

trusted MCP endpoint
configured tool mapping
caller cannot override scope

Evidence

audit lifecycle
OpenTelemetry traces
Prometheus-compatible metrics

Engineering Trade-Offs

Key engineering decisions

Short trade-offs that keep the security claims precise and the implementation inspectable.

SDK plus independent gateway

Decision: Use one initiative with public SDK checks and a separately maintained gateway enforcement point.
Why: In-process checks are useful, but raw-client access can bypass cooperative wrappers.
Trade-off: The gateway is stronger only when topology prevents direct protected-upstream access.

Ed25519 signed run identity

Decision: Verify short-lived JWTs with issuer, agent ID, audience, run ID, scopes, issue time, expiry, and token ID.
Why: The gateway should not share a symmetric signing secret with the identity issuer.
Trade-off: Public-key verification reduces gateway secret exposure; production key rotation remains future work.

Exact scopes from trusted config

Decision: Read required scopes and MCP mappings from trusted gateway configuration and use exact string matching.
Why: The caller must not influence the policy target or route to another MCP operation.
Trade-off: Determinism improves; wildcard, prefix, inheritance, and case-folding convenience is excluded.

Lifecycle audit evidence

Decision: Emit authorization_decision and execution_result records correlated by request_id.
Why: Console consumption should not guess semantics from nullable fields.
Trade-off: Local JSONL is easy to inspect, but not durable, immutable, or tamper-proof.

Authentication And Authorization

Signed run identity, trusted routing, and exact-scope authorization.

The gateway verifies short-lived Ed25519 JWT run identity using public verification material only. Trusted claims include issuer, agent ID, audience, run ID, scopes, issued-at time, expiration, and token ID.

SDK enforcement is cooperative and in-process for AgentRun.call, AgentRun.acall, AgentRun.guarded, GuardedMCPClient, and LangChain wrappers.
Gateway enforcement independently verifies signed Ed25519 JWT run identity before protected MCP execution.
Trusted gateway configuration determines the upstream MCP URL, MCP tool mapping, required scope, timeout, and controlled headers.
Authorization is exact string matching: service.restart is not service.*, SERVICE.RESTART, or an inherited permission.
Denied restart_service requests are audited as not_executed and do not produce an MCP invocation.
Raw JWTs, Authorization headers, raw MCP arguments, keys, and sensitive payloads are excluded from telemetry and audit additions.

MCP Integration

Narrow stateless tools/call adapter, not a universal MCP gateway.

MCP gateway adapter

Narrow MCP 2026-07-28 stateless HTTP tools/call adapter; no discovery or generalized MCP proxying.

SDK adapters

MCP and LangChain wrappers keep cooperative framework integration on the same authorization path.

Protected routing

Gateway config chooses MCP destination, tool name, required scope, timeout, and trusted headers.

Verified Behavior

Evidence from tests and local demos.

The primary evidence scenario proves the gateway blocks an authenticated but unauthorized restart_service request before MCP execution while allowing service_status for the same deploy-agent identity.

Gateway demo evidence

Gateway ALLOW/DENY proof

deploy-agent is granted service.status and logs.read. service_status requires service.status and executes; restart_service requires service.restart and is denied before MCP.

Agent: deploy-agent
Scopes: service.status, logs.read
ALLOW service_status required_scope=service.status HTTP_STATUS=200
MCP counters: service_status=1
DENY restart_service required_scope=service.restart HTTP_STATUS=403 ACCESS_DENIED
Audit: decision=deny reason=scope_not_granted result_status=not_executed
MCP counters: restart_service=0

An authenticated identity without service.restart cannot reach the protected restart_service MCP tool through the gateway.

This does not claim an absolute boundary if the protected MCP server is independently reachable.

Automated test evidence

Authentication and authorization tests

Tests cover missing/invalid tokens, issuer/audience/expiry validation, exact-scope authorization, unknown tools, audit-failure behavior, and no upstream execution on deny.

go test ./...
go test -race ./...
DENY restart_service -> upstream invocation count zero

Covered invalid credential and missing-scope cases fail closed before protected tool execution.

This does not claim production key rotation, token revocation, or enterprise IAM.

Operational evidence

Audit and observability evidence

Audit lifecycle records distinguish authorization decisions from execution outcomes, while traces and metrics expose ALLOW, DENY, timeout, error, and not-executed paths.

authorization_decision decision=allow reason=scope_granted
execution_result result_status=ok reason=execution_ok
authorization_decision decision=deny reason=scope_not_granted result_status=not_executed
DENY trace: authorization span present, no MCP execution span
DENY metrics: authorization deny incremented, no MCP request increment

Operators can correlate request_id and trace_id across logs, traces, metrics, and audit evidence without counting lifecycle events as two tool calls.

Local JSONL audit is not immutable, tamper-evident, centralized, or SIEM-integrated.

Read Public SDK Evidence →

Scope And Limitations

Current scope, with the boundary named.

AgentTrust is useful as a least-privilege and audit initiative across SDK and gateway layers. Strong gateway enforcement still depends on topology preventing direct upstream bypass.

Current Scope

Public SDK for cooperative in-process enforcement.
Separately maintained gateway implementation for independently enforced MCP authorization.
Short-lived signed run identities with scoped claims.
Local JSONL audit lifecycle and operational telemetry.

Not Currently Provided / Roadmap

Production SaaS, tenant administration, SSO/RBAC, or policy editing UI.
Durable centralized or tamper-proof audit storage.
Dynamic MCP discovery or universal MCP transport gateway.
Guaranteed enforcement if protected upstreams are directly reachable outside the gateway.

Explore The Project

Get started with AgentTrust

View Public SDK ↗Read Threat Model →Back to Projects →