Tutorial on CPEX Documentation

Setup & orientation

Mon, 01 Jan 0001 00:00:00 +0000

Module 0: Setup & orientation#

You are in the CPEX tutorial. This module gets you oriented and checks your setup. It changes nothing on your system.

Goal: understand what CPEX is, confirm your toolchain, and know which modules need the IdP.

What CPEX is#

CPEX is a policy enforcement runtime for AI agents. It is a deterministic reference monitor between an agent and every capability it invokes: tools, prompts, resources, inference providers. Each capability defines its own enforcement pipeline (authorization, delegation, redaction, information-flow control, audit), written declaratively in APL and run at the boundary.

Hello, enforcement

Mon, 01 Jan 0001 00:00:00 +0000

Module 1: Hello, enforcement#

You are in the CPEX tutorial. No IdP needed for this module.

Goal: stand up the smallest possible CPEX enforcement point and see a route allow one call and deny another, with no application logic making the decision.

The problem#

You have tools an agent can call. Some should be gated, some open. You do not want that decision scattered through handler code, where it drifts and is hard to audit. You want it in one place, declarative, at the boundary.

Who's calling?

Mon, 01 Jan 0001 00:00:00 +0000

Module 2: Who’s calling? (Identity)#

You are in the CPEX tutorial. This module needs the IdP. Start it first: docker compose -f examples/tutorial/idp/docker-compose.yml up -d

Goal: resolve a real bearer token into a subject (an id, roles, and permissions) so authorization predicates have something to read.

The problem#

In module 1, require(role.hr) denied everyone because nobody had a role. Roles and permissions come from identity: a verified token the caller presents. CPEX turns that token into attributes policy can gate on, and it must do so without trusting anything the caller could forge.

Shaping data

Mon, 01 Jan 0001 00:00:00 +0000

Module 3: Shaping data#

You are in the CPEX tutorial. Runs without the IdP (redaction fires for anonymous callers). The full contrast needs it.

Goal: return a different view of the same backend record per caller, by transforming the result on the way out with redact and mask, gated by permission.

The problem#

An HR analyst with clearance should see an employee’s SSN. One without should get the record with the SSN removed. Not a different endpoint, not a second query: the same call with a field stripped. The backend returns the full record, so policy must shape it before it leaves the boundary.

Effects & sequencing

Mon, 01 Jan 0001 00:00:00 +0000

Module 4: Effects & sequencing#

You are in the CPEX tutorial. Runs without the IdP.

Goal: compose several effects in an ordered pipeline that halts on the first denial, run a side-effecting plugin (audit), and emit your own machine-readable denial code.

The problem#

Real routes do more than one thing. They audit the attempt, apply a business rule, then check authorization, in a specific order, where a denial stops everything after it but not the side effects before it. You need to see and control that ordering.

Delegating decisions (PDP)

Mon, 01 Jan 0001 00:00:00 +0000

Module 5: Delegating decisions (PDP)#

You are in the CPEX tutorial. This module needs the IdP.

Goal: hand an authorization decision to a policy engine (a PDP) instead of writing it as a list of require() predicates, then let CPEX enforce the engine’s verdict.

The problem#

Some rules mix several inputs at once: “engineers may search internal repos only; security may search anything.” Expressing that as separate require() lines is awkward and easy to get wrong. A rule engine expression states it directly.

Scoped credentials (Delegation)

Mon, 01 Jan 0001 00:00:00 +0000

Module 6: Scoped credentials (Delegation)#

You are in the CPEX tutorial. This module needs the IdP.

Goal: mint a narrow, downstream-scoped credential for a call with a real OAuth 2.0 token exchange (RFC 8693), instead of forwarding the caller’s full token.

The problem#

When your agent calls a downstream API, handing it the caller’s original token is over-broad: that token works everywhere, for everything the caller can do. You want a token minted for this one downstream call, scoped to a single audience, so a leak is contained. Token exchange does that, and CPEX makes it a policy step rather than integration code.

Information flow (Tainting)

Mon, 01 Jan 0001 00:00:00 +0000

Module 7: Information flow (Tainting)#

You are in the CPEX tutorial. This module needs the IdP.

Goal: carry security state across a session so a later request can be denied because of what an earlier one did. This is how CPEX stops write-down.

The problem#

Most authorization systems judge each request alone. That misses a whole class of leaks: a caller reads sensitive data, then sends it out through a channel that looks harmless on its own. You want the second call blocked because of the first, even though nothing about the second call is suspicious in isolation.

Human in the loop

Mon, 01 Jan 0001 00:00:00 +0000

Module 8: Human in the loop (Elicitation)#

You are in the CPEX tutorial. This module needs the IdP.

Goal: suspend a sensitive operation until a human approves it, then resume it. The agent cannot proceed on its own.

The problem#

Some actions are too consequential to run on the agent’s say-so: a large transfer, an irreversible change, an outbound message to a client. You want policy to pause the call, ask a human, and only continue once they approve. That means the operation must be able to suspend and resume, not just allow or deny.

Write your own plugin

Mon, 01 Jan 0001 00:00:00 +0000

Module 9: Write your own plugin#

You are in the CPEX tutorial. Runs without the IdP.

Goal: write a plugin for a check the builtins do not ship, register it, and reference it from policy by name, exactly like a builtin.

The problem#

The bundled plugins cover common needs, but your domain has its own rules. You need a way to drop custom logic into the pipeline without forking CPEX, and to wire it from policy the same way you wire a builtin.

Testing your policy

Mon, 01 Jan 0001 00:00:00 +0000

Module 10: Testing your policy#

You are in the CPEX tutorial. Runs without the IdP.

Goal: test policy the way you test code. Load a policy, drive routes with a fake backend, and assert the outcome, so a policy change that breaks a rule fails CI.

The problem#

Policy decides who sees what. A careless edit can silently open a route or over-redact a field. You want the allow and deny matrix pinned by tests that run on every change, without standing up an IdP or a real backend for the cases that do not need one.

Capstone

Mon, 01 Jan 0001 00:00:00 +0000

Capstone: the three-backend agent#

You are in the CPEX tutorial. This needs the IdP.

Goal: assemble everything into the full scenario from the Overview: one agent, three backends, three callers, one policy. See identity, permission, delegation, redaction, information flow, and audit compose.

The scenario#

One policy (policies/capstone.yaml) defines three routes:

get_compensation (HR): authorize by role, mint a scoped downstream token, taint the session as having read secret data, audit, and redact fields by permission on the way out.
search_repos (repos): hand the decision to CEL: engineers read internal only, security reads any.
send_email (email): refuse if the session already touched secret data, and audit every attempt.

get_compensation is the densest route, and it runs each control you built in order: