contexa-core Agent security

Stop, Confirm, Limit

How Contexa stops an agent, asks the accountable person to confirm its request, and limits its pace and scope, according to the decision and the settings. It also covers the answers an agent receives and how to handle them, how administrators release a stop, and the console screens.

At a glance

The agent request gateThe gate checks from the top down and answers at the first check that applies. A person's request does not go through it.
  1. Agent request
  2. ①Call limitsPast the calls allowed per minute: 429 AGENT_CALL_LIMIT
  3. ②Ended delegationRevoked: 403 DELEGATION_REVOKED; expired or not started: a confirmation is asked for
  4. ③CHALLENGE decisionA confirmation is asked for (403 AGENT_CONFIRMATION_REQUIRED); an approved confirmation lets it through once
  5. ④Narrowed scopeWhile only reading is allowed after a risky decision, other operations get 403 AGENT_SCOPE_NARROWED
  6. ⑤Before a @Protectable methodDecided in place when there is no decision; an ALLOW in force is reused for a few requests only
  7. Runs

What works under each ownership

The gate (① to ④) runs in both ownership modes: inside the security chain Contexa builds under CONTEXA_OWNED, and as a servlet filter right after the application's Spring Security chain by default (HOST_OWNED), behind the authentication bridge that stamps the delegation. The @Protectable methods (⑤) and the handling after a decision work in both.

ControlCONTEXA_OWNED
(@EnableAISecurity(mode = SecurityMode.FULL))
HOST_OWNED (default)
Enforcing stored decisions (BLOCK, CHALLENGE, ESCALATE)At the URL and at @ProtectableAt the URL (filters right after the application's chain) and at @Protectable
Deciding an agent request with no decision in place, limiting ALLOW reuse, decision mergingWorksWorks (@Protectable)
Stopping after a BLOCK (delegation revoked, tokens revoked, notice)WorksWorks. Tokens are revoked only with an AgentTokenRevoker
Confirmation by the accountable person (CHALLENGE, ended delegation)WorksWorks. An agent's CHALLENGE is answered with 403 AGENT_CONFIRMATION_REQUIRED and the confirmation status address
Refusing revoked delegations, call limits and denial alarm, refusing outside a narrowed scopeWorksWorks
Policy expression agentRequestConfirmed()WorksWorks
Refusing a suspended agent's tokenContexa resource server and authorization serverUp to your resource server
Evaluating again as the delegatorURL and method policiesMethod policies

Answers an agent receives

The agent (or its framework adapter) must understand and handle these answers. The body is JSON; the fields below come with error, message and path.

Status, errorWhenWhat the agent does
429 AGENT_CALL_LIMITPast a call limit. Body scope (DELEGATION or AGENT), limit, retryAfterSecondsSends again after Retry-After seconds
403 DELEGATION_REVOKEDThe request runs under a revoked delegation. Body delegationIdStops. The person must delegate again
403 AGENT_CONFIRMATION_REQUIREDThe decision is a CHALLENGE, or the delegation expired or has not startedPolls statusUrl and sends the same request again once it is APPROVED (confirmation)
403 AGENT_SCOPE_NARROWEDAn operation outside the narrowed scope. Body allowed, until, operationDoes only the allowed operations until until, or gets the request confirmed
413 AGENT_CONFIRMATION_UNBINDABLEA confirmation is needed but the body is larger than a confirmation can be bound to (1 MB by default)Sends it in smaller parts
429 ZERO_TRUST_ANALYSIS_BUSYDecision merging is on and every analysis place and queue slot is takenSends again after Retry-After seconds

Confirmation by the accountable person

On a CHALLENGE decision a person is asked to step up (MFA), but an agent cannot do MFA. So Contexa asks the person accountable for that agent to confirm that request.

The confirmation exchangeAn approval is used by that one request, once.
  1. Agent→AppRequest
  2. Contexa→Agent403 AGENT_CONFIRMATION_REQUIRED with the confirmation ID, status URL and expiry
  3. Contexa→PersonA notice (mail, else the console) with a link to the confirmation page
  4. Person→ContexaApprove, refuse or report
  5. Agent→ContexaGET statusUrl → APPROVED
  6. Agent→AppSends the same request again → runs once (USED)
{
  "status": "PENDING",
  "error": "AGENT_CONFIRMATION_REQUIRED",
  "trigger": "DECISION_CHALLENGE",
  "confirmationId": "6f1c2a90-…",
  "statusUrl": "/contexa/api/agent-confirmations/6f1c2a90-…",
  "expiresAt": "2026-11-02T06:15:00Z",
  "confirmationHeader": "Contexa-Agent-Confirmation",
  "message": "The person accountable for this agent must confirm this request; …",
  "path": "/api/reports/export"
}
  • Who confirms: the delegator for a delegated agent, the sponsor for an autonomous agent. Without an accountable person no confirmation is made and the request is refused (the body has no confirmationId).
  • A confirmation is bound to its request: tenant, user, agent, method, path, query string and the body's SHA-256. It is used only by that same request and becomes USED once used. The agent may name the confirmation ID in the Contexa-Agent-Confirmation header when sending again.
  • Time: the person's answer is awaited for confirmation-timeout (15 minutes by default), and an approval must be used within the same time. Past it the confirmation is EXPIRED (refused); expired ones are swept every minute.
  • Report: when the person reports the request, it is refused and the agent is stopped at once (as in stopping, with a BLOCK stored right away).
  • An approval is kept as a verifiable record. With Contexa's authorization server it is an OAuth2 authorization, without it a signature with the evidence signing key, verified again when used. What was confirmed also goes into the decision context (the Confirmation line).
  • On the confirmation page only the person the confirmation is for decides, in their own session. A request from an agent is refused there even with that person's token.
Confirmation statusMeaning
PENDINGWaiting for the person
APPROVEDApproved, not used yet
USEDApproved and used by its request
REJECTED, EXPIRED, REPORTEDRefused, timed out, reported (all final refusals; refused is true in the status)

An agent asking for confirmation first

With the policy !delegationRequiresApproval() or agentRequestConfirmed() on work whose delegation requires approval, the agent can ask for a confirmation itself before it runs (trigger REQUESTED).

POST /contexa/api/agent-confirmations
Content-Type: application/json

{ "method": "POST", "target": "/api/reports/export?month=2026-10",
  "bodySha256": "9f86d081…", "reason": "Monthly report export" }

It returns 202 with the confirmation's status (409 without an accountable person, 403 when the caller is not an agent). target is the path with the query, starting with /; bodySha256 is the SHA-256 (hexadecimal) of the body it will send. Poll the status at GET /contexa/api/agent-confirmations/{id}. This too needs the gate that consumes confirmations, so it works only under CONTEXA_OWNED.

The start of the confirmation link in notices is set with confirmation-link-base-url (for example https://app.example.com). Left empty, the link is relative, with the application's path only. The Host header the agent sent is never used in the link.

Stopping and releasing

When a BLOCK is decided on an agent's request, that agent only is stopped. It is not added to the people's block list, and the person's own work goes on.

What happens after a BLOCKEach step is kept in the decision record, in order.

A delegated agent is blocked

  • The decision is stored under the agent's key (<user>::agent::<agent>)
  • The delegation is revoked
  • The tokens it holds for that person are revoked
  • The delegator is told

An autonomous agent is blocked

  • Its registration is suspended (SUSPENDED): every token issued to it is refused
  • Its tokens are revoked
  • Its sponsor is told

A report by the accountable person and a call limit set to STOP stop the agent the same way. A stop is released through the admin API or console, or on the accountable person's confirmation page (a kill switch stop by administrators only).

actionFieldsWhat it does
RELEASE_DELEGATIONuserId, agentIdClears the agent's decisions for that person so its next request is decided again. The revoked delegation stays revoked; the person delegates again
RELEASE_AGENTagentId (tenantId optional)Puts the registration back in service and clears the agent's decisions
KILL_SWITCHagentType, tenantId (optional)Stops every agent in service of that type (all types when empty) at once
KILL_SWITCH_RELEASEThe samePuts back only the agents the kill switch stopped; agents stopped for other reasons stay stopped
POST /contexa/admin/api/agents/stops
Content-Type: application/json

{ "action": "KILL_SWITCH", "agentType": "AGENT", "reason": "Prompt injection incident" }

reason is required and the ADMIN role is needed. GET shows the stopped agents and delegations. Without the service that stops agents (AgentContainmentService) it answers 503 (the autonomous security plane is off). A scope a BLOCK narrowed stays narrowed after the release until its period ends.

Scope narrowing

After a risky decision on an agent's request, the agent's next requests may only read for a while.

  • When: after a CHALLENGE, ESCALATE or BLOCK, or an ALLOW whose risk reaches risk-threshold (0.7 by default).
  • How long: duration (1 hour by default). A scope is only narrowed, never widened.
  • The operation is read from the method and the words of the path (READ, WRITE, EXPORT, DELETE, ADMIN, EXECUTE). A GET /api/exports, for example, is an export (EXPORT).
  • A request outside the scope gets 403 AGENT_SCOPE_NARROWED; it passes once its accountable person confirms it. A person's request is never narrowed.

Call limits and the denial alarm

LimitDefaultCounted for
One delegation120 per minuteOne person's work (the agent's decision key)
The whole agent600 per minuteEveryone the agent acts for
  • Past a limit, on-exceed decides: THROTTLE (default, 429 with Retry-After) or STOP (the agent is stopped; the request's own answer is still 429).
  • Denial alarm: when at least 10 requests in 5 minutes were refused at a rate of 50% or more, an audit record is written and the accountable person is told (once per window).
  • When the enforcement mode is not ENFORCE (SHADOW and so on), a request past a limit goes on and is only recorded. The counts are per instance.

Requests with no decision, and ALLOW reuse

  • No decision yet: a person's request goes on and is analysed afterwards, but an agent's request is decided in the request, even at an asynchronous @Protectable method (protectable.unrecorded-agent-request: DECIDE_IN_PLACE, default). With PROCEED it goes on as a person's does.
  • An ALLOW in force: for a person it answers later requests for its validity, but for an agent only the same operation, 3 distinct resources and 10 requests; for a sensitive resource (SENSITIVE or CRITICAL) only 1 resource. Past that the request is decided again in place, so an agent that reads a customer list one record at a time cannot read it all on its first ALLOW.

Decision merging (off by default)

When one agent sends many requests at once, the model is not called for each: the same question is analysed once. While the first request is analysed, the others wait for its verdict and are answered by it.

Setting (contexa.security.zerotrust.agent.flight.*)DefaultMeaningWhen to change
enabledfalseTurns it onWhen one agent sends bursts of the same request and model calls pile up
max-in-flight-analyses3Analyses one agent may have running at onceTo match model throughput
queue-capacity20Requests that may wait for a placeWhen 429 answers are frequent
wait40sThe longest wait. Past it: 429 ZERO_TRUST_ANALYSIS_BUSYWith slower models (Layer 2 included)
pass-budget3Requests that may pass before the first verdict (0 for none)0 to let nothing pass before the first decision
pass-families[READ]Operations that may pass first; only for resources your application declared non-sensitiveTo change which operations may pass first
  • No request is let through for lack of a verdict; pass-budget above is the only exception.
  • A restriction (BLOCK, ESCALATE, CHALLENGE) stored for the agent while requests wait answers them at once.
  • A failure of decision merging itself is not a decision: each request is then analysed on its own. The state is kept in memory per instance.

In modes that do not enforce (SHADOW and so on)

When the enforcement mode is not ENFORCE (SHADOW, OBSERVE, DISABLED, or contexa.security.zerotrust.enabled=false), the gate records ended delegations, narrowed scopes and call limits and lets the request on. The re-evaluation as the delegator is only recorded too. A CHALLENGE in force still waits for its confirmation.

Policy expressions

ExpressionMeaning
agentRequestConfirmed()Whether the accountable person confirmed this very request (true only for an agent's request)
agentCallsInLastMinuteAtMost(n)Whether this delegation made at most n requests in the last minute, this one included; true for a person and when nothing counted them

The delegation expressions are in Delegation and Objective Contracts.

Decision records and tamper checks

Each decision leaves one decision record in the audit log (ctxa_audit_log, category SECURITY_DECISION). For a person's request the agent and delegation fields are empty.

FieldContent
SubjectThe subject kind, the agent, the delegator, the delegation id
Operation asked forThe request's action family
Risk factsThe reason codes the decision cited, with their fact IDs
EnforcementThe response enforced and why. The outcome is APPLIED, KEPT_STRICTER (a stricter response already in force was kept), OBSERVED_ONLY (recorded only, in a mode that does not enforce) or DISCARDED (the processing lost ownership and the result was dropped)
Request context hashThe SHA-256 of the time, tenant, user, agent, delegation, operation, method, path, target, requested items and argument summary

With a signer (the signing key of sealed evidence), decision records are chained in the order they are saved: each record's fields and the previous record's hash are hashed together with SHA-256 and signed. The admin console's security event log shows the check result of each record.

ResultMeaning
VERIFIEDAs sealed
MISMATCHA field changed, the hash was computed again so the signature fails, or a record in the middle of the chain was removed
UNVERIFIABLEWritten before records were sealed, or signed with a key no longer held (for example a temporary key before a restart)

The oldest records removed by the audit log retention (default 90 days, System Settings) do not count as MISMATCH.

A decision record keeps the time of its event, and the save does not write it again, so the record is verified as it was sealed. A decision record saved before this was fixed had its time written again by the save and stays MISMATCH; it is not sealed again, so that a mismatch keeps meaning a record was altered (Old decision records mismatch after an upgrade).

Console screens and APIs

Screen or APIPathWhat it does
Agent list, detail, registration/contexa/admin/agents (/detail, /new)Registry, status, delegations, decision records
Agent stops tab/contexa/admin/blacklist/agentsStopped agents and delegations, release, kill switch
Confirmation page/contexa/agent-confirmationsMy confirmations and notices; approve, refuse, report; release my stopped agents (reason required)
Learning control API/contexa/admin/api/agents/learningQUARANTINE (kept but never read, nothing more learned), RELEASE or REMOVE the learning of an agent or of one delegation. Other agents' and people's learning is never touched

Stops, releases, confirmations and delegation records are all kept in the audit log (AGENT_* categories).

Settings

All under contexa.security.zerotrust.agent. (except the last row).

SettingDefaultMeaningWhen to change
confirmation-timeout15mHow long a confirmation is awaited, and how long an approval may be usedWhen accountable people need longer to answer, or waits should be shorter
confirmation-sweep-interval1mHow often expired confirmations are sweptRarely
confirmation-link-base-urlNoneThe absolute start of the link in noticesWhen notice links must be absolute (opened from mail)
confirmation-max-body-bytes1048576The largest body a confirmation is bound toWhen requests that need confirmation carry bodies over 1 MB
scope-narrowing.enabled / .duration / .risk-thresholdtrue / 1h / 0.7Scope narrowingTo fit the period or risk threshold to your work, or to turn it off
call-limit.enabled / .per-delegation-per-minute / .per-agent-per-minute / .on-exceedtrue / 120 / 600 / THROTTLECall limitsWhen normal traffic nears the limits, or past them the agent should be stopped (STOP)
denial-alarm.enabled / .window / .min-requests / .ratetrue / 5m / 10 / 0.5Denial alarmWhen alarms are too frequent or too rare
allow-reuse.max-requests / .max-distinct-resources / .sensitive-max-distinct-resources10 / 3 / 1How far an ALLOW is reusedTo widen or narrow what one ALLOW answers (wider: fewer decisions, more risk)
flight.*The table aboveDecision mergingThe table above
contexa.security.zerotrust.protectable.unrecorded-agent-requestDECIDE_IN_PLACEAn agent request with no decision (PROCEED: as a person's)When agent requests should go on while analysed, as a person's do (PROCEED)

Extension points

BeanWhen you need itDefault
AgentNoticeChannelTo notify through chat, push or tickets instead of mailMail when a mail sender exists (the person's account needs an address), else kept in the console only
AgentTokenRevokerTo revoke an external authorization server's tokens on a stopWith Contexa's authorization server it revokes there; otherwise nothing is revoked (stop and BLOCK are relied on)
AgentConfirmationAuthorizerTo keep approvals in your authorization serverA Contexa authorization server grant, else a signature with the evidence signing key
AgentScopeNarrower / AgentScopeStoreTo narrow differently or store elsewhereRead only for 1 hour / JDBC or memory
AgentConfirmationStore / AgentNoticeStoreTo change the storeJDBC (ctxa_agent_confirmation and ctxa_agent_notice tables) or memory

Operations notes

  • Several instances: call limit counts and decision merging state are in memory per instance. In-memory registries and stores are lost on restart, so use the Contexa database in production.
  • Without the stop service (AgentContainmentService) there is no stop after a BLOCK and no narrowing, and the stop API answers 503. contexa.autonomous.enabled: false does not produce this state; it turns all of Contexa off.
  • An agent's decision is the model's; the engine only computes facts (Decision Engine).