OpenPort Protocol: A Security Governance Specification for AI Agent Tool Access
Organizations: Accentrust · Georgia Institute of Technology · University of Illinois Urbana-Champaign · Duke University ·
Abstract
AI agents increasingly require direct, structured access to application data and actions, but production deployments still struggle to express and verify the governance properties that matter in practice: least-privilege authorization, controlled write execution, predictable failure handling, abuse resistance, and auditability. This paper introduces OpenPort Protocol (OPP), a governance-first specification for exposing application tools through a secure server-side gateway that is model- and runtime-neutral and can bind to existing tool ecosystems. OpenPort defines authorization-dependent discovery, stable response envelopes with machine-actionable agent.* reason codes, and an authorization model combining integration credentials, scoped permissions, and ABAC-style policy constraints. For write operations, OpenPort specifies a risk-gated lifecycle that defaults to draft creation and human review, supports time-bounded auto-execution under explicit policy, and enforces high-risk safeguards including preflight impact binding and idempotency. To address time-of-check/time-of-use drift in delayed approval flows, OpenPort also specifies an optional State Witness profile that revalidates execution-time preconditions and fails closed on state mismatch. Operationally, the protocol requires admission control (rate limits/quotas) with stable 429 semantics and structured audit events across allow/deny/fail paths so that client recovery and incident analysis are deterministic. We present a reference runtime and an executable governance toolchain (layered conformance profiles, negative security tests, fuzz/abuse regression, and release-gate scans) and evaluate the core profile at a pinned release tag using artifact-based, externally reproducible validation.
Figures & tables
| Threat | Required protocol controls |
|---|---|
| Token leakage | Revocation, short-lived execution windows, rate limits, audit on every decision |
| Cross-tenant access | Server-side tenant resolver; deny-by-default; policy constraints; no client-trusted tenant IDs |
| Tool enumeration | AuthZ-dependent manifest; schema and error redaction; deny-by-default exposure |
| Destructive write misuse | Draft-first default; step-up confirmation; human approval chain; explicit risk tiers |
| Replay / duplicates | Idempotency keys; execution de-duplication per app and key |
| Audit gaps | Structured allow/deny/fail audit events with stable reason codes and request metadata |
| Reason code | Recommended client action |
|---|---|
| agent.token_invalid agent.token_expired | Stop; request a new key/token; refresh discovery after re-authentication. |
| agent.scope_denied | Refresh /manifest ; request additional scopes only if explicitly approved. |
| agent.policy_denied agent.forbidden | Surface to operator; adjust query/window/resource selection; do not retry blindly. |
| agent.action_unknown agent.action_invalid | Do not retry blindly; refresh /manifest and validate tool name and input schema. |
| agent.preflight_required agent.preflight_mismatch agent.preflight_not_found | Run /preflight and retry with returned hash (or a valid preflightId ); treat mismatch as a change in impact and do not execute blindly. |
| agent.precondition_failed (State Witness profile) | Treat as state change (TOCTOU); rerun /preflight to obtain a fresh witness/hash and require renewed operator approval before execution. |
| Status | Meaning | Transitions (trigger) |
|---|---|---|
| draft | Pending operator decision; no side effects have been executed. | confirmed (approve or eligible auto-execute), canceled (reject). |
| confirmed | Approved for execution; a successful execution outcome should be recorded for completion. | failed (execution attempt fails). |
| canceled | Rejected by operator; terminal. | none. |
| failed | Execution attempted and failed; terminal. | none. |
| Field | Meaning / usage |
|---|---|
| id , created_at | Server-generated event identifier and timestamp for ordering and retention. |
| action , status | Stable event name and outcome ( success , denied , failed ). |
| code | Stable reason code for denials (for example, agent.scope_denied ) and for protection outcomes (for example, agent.rate_limited ). |
| app_id , key_id | Integration identifiers for attribution, revocation correlation, and blast-radius analysis. |
| actor_user_id | Subject identity under which domain reads/writes are performed (service user or user). |
| performed_by_user_id | Approving operator identity for admin actions and write approvals (separation of duties). |
| Invariant (reference) | Black-box check (observable) |
|---|---|
| Envelope stability | All endpoints return the standard envelope; errors are parseable and include a stable code . |
| AuthZ-dependent discovery (Eq. ( 1 )) | With insufficient scopes/policy, /manifest omits restricted tools/fields; adding scopes changes the visible set without breaking schema. |
| Immediate revocation | After revocation, requests across endpoints (including /manifest ) return 401 with a stable token denial code (for example, agent.token_invalid ). |
| Allow/deny determinism (Eq. ( 6 ), Eq. ( 7 )) | For a given request shape, denial code matches the first failing predicate in the prescribed order; codes remain stable across versions. |
| Preflight binding (Eq. ( 2 )) | When preflight is required, missing hash yields a required denial; mismatched hash yields a mismatch denial; an unresolvable preflightId yields agent.preflight_not_found ; matching hash permits progression to draft/execute. |
| State witness preconditions (Eq. ( 3 ); optional profile) | If a draft is bound to stateWitnessHash , execution revalidates current witness state; mismatch yields 409 with agent.precondition_failed and no side effects. |
| Component | Responsibility |
|---|---|
| HTTP gateway ( /api/agent/v1/* ) | Route registration, schema validation, and standardized success/error envelopes. |
| Auth + admission control | Bearer token parsing, app/key resolution, revocation and expiry checks, IP allowlists, and fixed-window rate limiting before any tool logic. |
| Policy engine | Scope checks and ABAC constraints (resource allowlists, bounded query windows, redaction), plus tenant/workspace boundary enforcement. |
| Tool registry | Authorization-dependent discovery output ( /manifest ) and tool bindings (metadata + input/output schemas + optional impact computation for high-risk tools). |
| Draft/execution store | Write intent tracking (drafts), execution results, and idempotent replay mapping by . |
| Audit service | Structured allow/deny/fail events with correlation identifiers (app/key/actor/draft/execution); pluggable sinks. |
| Property / invariant | Artifact(s) | Status |
|---|---|---|
| Envelope stability | Core conformance runner; OpenAPI contract test | Covered |
| Unauthenticated discovery denied | Core conformance unauthorized /manifest | Covered |
| Policy boundaries (tenant/IP/max-days) | Security controls tests; policy tests | Covered |
| Draft-first pipeline + approval | App tests (draft + admin approve); conformance draft retrieval | Covered |
| Preflight hash produced | Conformance /preflight ; app high-risk flow | Covered |
| State witness preconditions | Optional profile; execution-time revalidation regression planned | Future |
Tool Access Control for LLM Agents
Tool access control for LLM agents limits which tools, resources, and actions agents may use, and under what conditions.
See all 219 papers