contexa-core

Decision Engine: How a Decision Is Made

How Contexa looks at a request again after it was handled, makes a decision and stores it. You will learn which requests are analyzed, when the AI model decides a second time, when the model's answer is changed, when a decision starts to apply, and what is learned.

At a glance

A decision is not made while the request waits. It is made in the background after a protected method (@Protectable) has run, stored, and applied from the same user's next request. Only a method that needs a decision inside the request itself uses @Protectable(sync=true) for an immediate decision.

The AI model chooses the action (allow, step-up authentication, block, hold for review). The engine gathers facts such as what differs from usual, the company's records (Company Records) and past decisions, and sends them to the model; it does not choose the action.

The path of one decisionSteps 1–5 happen after the response has left; step 6 happens on the same user's next request.
  1. 1
    Create an analysis eventWhen a protected method finishes, the request's facts are sent as an event (ZeroTrustEventPublisher)
  2. 2
    FilterIf this user already has a decision in force, nothing new is analyzed (ZeroTrustEventListener)
  3. 3
    QueueOne line per user and session, handled one at a time (SecurityPlaneAgent)
  4. 4
    Make the decisionLayer 1 decides; if it cannot, Layer 2 decides again (AI model)
  5. 5
    Enforce and recordStore the decision, seal the evidence, write the audit record
  6. 6
    Apply on the next requestThe stored decision changes that user's authorities (request-time enforcement)

Which requests are analyzed

Not every request goes to the AI model. Only the cases marked "analyzed" below produce a decision.

CaseWhat happens
A protected method call (default)Analyzed after the method has run. The method does not wait for the decision.
An immediate-decision method (@Protectable(sync=true))Decided right inside the request by the same engine, without the queue.
Enforcement mode is disabled or observe (DISABLED · OBSERVE), or contexa.security.zerotrust.enabled=falseNot analyzed. The AI model is not called.
The user already has a block, step-up or hold in forceRefused before the method runs, not analyzed.
A stored decision is still valid (not pending analysis)Not analyzed again; recorded only as a request that was not analyzed.
The same user calls the same scope again within 5 secondsLet through, not analyzed (contexa.security.zerotrust.protectable.rapid-reentry-window-ms, default 5000).
An authorization policy (XACML · URL) deniesNot analyzed; recorded only as a session fact.
The same event is about to be processed twice (several servers, requeued)Each event's processing right is claimed once (an identity made of tenant, user, context, event, resource and method). An event already processed, or being processed elsewhere, is skipped.
One agent sends the same request many times at onceWith decision merging on, the same question is analysed once (off by default).

The order of a decision: Layer 1 and Layer 2

A decision is made in two layers. Most end in Layer 1; only a request Layer 1 answered with "these facts cannot decide it (ESCALATE)" goes to Layer 2.

Layer 1 and Layer 2Layer 2 runs only when Layer 1 answered ESCALATE.
  1. Gather factsSession flow, differences from the behavioral baseline, company records, past decision records (the search starts first and is awaited)
  2. Layer 1The AI model decidesTime limit 90 s (contexa.security.tiered.layer1.timeout.llm-ms)
  3. Only when the answer is ESCALATE ↓ (any other answer is the final decision)
  4. Layer 2The same request is decided againGets Layer 1's prompt and first decision and asks again. Time limit 30 s (contexa.security.tiered.layer2.timeout-ms)

Final decision

  • AllowALLOW
  • Step-up authenticationCHALLENGE
  • BlockBLOCK
  • Held for reviewESCALATE

Past decision records are found in two ways at once, and both are drawn in the PAST RECORDS block.

SearchLayer 1Layer 2
Exact lookupThe person's allowed records of the same action, same target first, newest first, looked up without an embedding (PastRecord lines)Reuses the records Layer 1 found, and looks up again only when there are none
Similarity searchUp to 12 records similar in meaning (contexa.security.tiered.layer1.vector-search-limit), relevance 0.5 or more (layer1.rag.similarity-threshold), drawn as SimilarCase lines. A prompt version that deletes the part "Similar case reading" turns it offReuses the records Layer 1 found, and searches again only when there are none (up to 5, layer2.rag-top-k, relevance 0.5 or more)
Overload protection. When the last 100 Layer 1 decisions of the same scope (the organization, else the user) hold at least 11 decisions and more than half of them are ESCALATE, Layer 2 is not called and the request ends with step-up authentication. It keeps Layer 2 calls from surging when the model answers "I cannot tell" for everything. The ratio and count are fixed in the code.

A different model for each layer

Layer 1 and Layer 2 can use different models, for example a fast, inexpensive model for Layer 1 and a more careful one for Layer 2.

contexa:
  security:
    tiered:
      llm:
        layer1:
          model: gpt-4o-mini   # empty: the primary chat model
        layer2:
          model: gpt-4o        # empty: the primary chat model

The example works as is when the primary chat model is OpenAI (only the name changes within the same provider).

  • Model order: the layer's model → (if set) the layer's backup model (layerN.backup.model) → the primary chat model.
  • A model name with no connection setting (contexa.llm.bindings.chat) runs on a copy of the primary chat model with only the name changed. The copy works for OpenAI chat models (mutate()) and for Anthropic chat models (Contexa builds the copy again with the same client and default options). A model that cannot be copied, such as Ollama, needs its own connection setting.
  • If a layer model cannot be made, the application still starts. One ERROR line at start names the layer, the model that was set and the model that runs in its place (the backup model, else the primary chat model), so check the start log. A wrong model name of the same provider cannot be told at start and fails at the first call of that layer.

After the decision: five steps

Once a decision is made, five steps follow in a fixed order. The numbers are the execution order.

Handler orderIf a step fails, the steps after it do not run.
  1. 50Make the decision
  2. 55Enforce
  3. 56Seal evidence
  4. 60Audit
  5. 65SaaS forwarding
OrderStepWhat it doesWhen it runs
50Make the decision (ProcessingExecutionHandler)Makes the decision with Layer 1 and Layer 2.Always. Without a chat model and a vector store no decision can be made and the user stays pending.
55Enforce (SecurityDecisionEnforcementHandler)Writes the observation record for the audit first, then stores the decision in enforce mode. On a block it signals in-flight responses to stop.When there is a decision result
56Seal evidence (SealedEvidenceCaptureHandler)Seals the prompt exactly as sent to the model, with the decision. It never changes the decision. By default the first 1,000 after a server starts and after the version decisions run changes are all sealed, otherwise 1%, kept 90 days. Sealed evidence and official verificationWhen the AI model decided (contexa.pqa.oss.sealed-evidence.capture-enabled, on by default)
60Audit (AuditingHandler)Writes the decision to the audit log (ctxa_audit_log), in shadow mode too.When there is a decision result
65SaaS forwarding (SaasForwardingHandler)Puts decisions other than allow and pending into the box sent to Contexa SaaS. Connecting Contexa SaaSOnly with contexa.saas.enabled=true (off by default)

How a decision is stored and applied

In enforce mode (ENFORCE) the decision is stored in the user decision store: memory in standalone mode, Redis in distributed mode. Each decision has a fixed lifetime.

DecisionLifetimeWhere it applies
Allow (ALLOW)15 minutes (set with contexa.security.zerotrust.allow-validity)Only in the same session, IP and browser it was made for
Step-up authentication (CHALLENGE)1,800 seconds (30 minutes)Every session of the user
Held for review (ESCALATE)300 seconds (5 minutes)Every session of the user
Block (BLOCK)No expiry (until an administrator releases it or the block-release MFA is passed)Every session of the user
Pending analysis (PENDING_ANALYSIS)No stored decisionThe request goes through and analysis starts
  • A stricter decision is never overwritten by a weaker one. In the order block > hold > step-up, a weaker new decision is not stored while a stricter one is in force.
  • Shadow mode (SHADOW) stores nothing. Only the observation record is written; no block signal and no learning.
  • An event carries the enforcement mode it was made under (decisionBoundaryMode). An event made in shadow mode is not enforced even if the mode became ENFORCE by the time its decision is ready.
  • Without the observation record (database) nothing is enforced. The decision stays pending, and new analyses of the same context pause for 30 seconds (contexa.security.zerotrust.analysis.audit-failure-cooldown-ms).

How a stored decision changes authorities on the next request is described in request-time enforcement.

When the model's answer is changed

The action the model chose is the final decision except in the cases below.

CaseFinal decision
No answer from the model (provider outage, call timeout, output or context limit)Step-up authentication. Even in Layer 1 it is not sent to Layer 2.
No action value, or an unknown oneStep-up authentication; DENY-like values are read as block and REVIEW as hold.
The answer breaks the output contract and still does after one corrective retryHeld for review (from Layer 1 it goes to Layer 2). In a prompt version with the prepared part "Decision rules", a boundary still broken turns it into the boundary's action (block or allow).
Layer 1 itself fails (no result, Layer 1 time limit exceeded)Turned into hold and sent to Layer 2.
Layer 2 chooses hold (ESCALATE)Replaced with contexa.security.tiered.layer2.escalate-fallback-action (default CHALLENGE).
Layer 2 fails technically (exception, over 30 seconds)Hold is stored as the final decision (5 minutes).
Overload protection (the box above)Step-up authentication
The minimum-action rule in enforce mode (contexa.security.zerotrust.minimum-action.mode=ENFORCE) and an answer weaker than the floorOne corrective retry, then hold if still weaker. The default OBSERVE only records it.

What is learned

The engine learns two things from decisions: each person's behavioral baseline (usual hours, devices, networks, targets and so on) and past decision records. Both become facts of the prompt in later analyses.

  • Only allow decisions that were actually applied are learned into the baseline. Decisions in shadow mode, an allow not stored because a stricter decision was in force, and late results of deleted accounts are not learned. Learning is an exponential moving average (factor 0.1); for a person's request the organization baseline is updated too.
  • When a baseline counts as established: a personal baseline needs 20 or more learned requests, on 5 or more different days, with no more than 20% unseen values in its last 10 learnings. An organization baseline must learn from 3 or more people. Items that keep several values, such as IP ranges, push out the least used value when full (older values count less, with a 14-day half-life).
  • An unexplained new value is held, not learned at once. For a resource of sensitive class or above, an unexplained difference in hour, day, network or device is held until the same value is seen at least twice on at least two days, or is verified. For agents a first-seen value is held whatever the resource class.
  • Requests that passed a check are learned too. A request stopped by step-up, hold or block is kept, and learned with weight 0.5 once the user passes MFA or an administrator releases the block.
  • Past decision records are stored in the vector store only for decisions that were applied; records older than 90 days (contexa.rag.etl.behavior.retention-days) are deleted every day at 03:45. Zero or less keeps them forever.
  • The behavioral baseline is deleted after 30 days (contexa.security.zerotrust.baseline.retention) without new learning.

Settings you will change most

SettingDefaultMeaningWhen to change it
contexa.security.zerotrust.modeENFORCEWhether decisions are made and applied (DISABLED · OBSERVE · SHADOW · ENFORCE)Start with SHADOW, then switch to ENFORCE. Enforcement modes
contexa.security.tiered.llm.layer1.model
contexa.security.tiered.llm.layer2.model
none (primary chat model)The model of each layerTo use a fast model for Layer 1 and a careful one for Layer 2
contexa.security.tiered.layer1.timeout.llm-ms90000Layer 1 time limit (ms)When a slow model often exceeds Layer 1's limit
contexa.security.tiered.layer2.timeout-ms30000Layer 2 time limit (ms)When a slow Layer 2 model leaves holds
contexa.security.tiered.layer2.escalate-fallback-actionCHALLENGEThe action used when Layer 2 also chooses holdTo treat undecided requests more strictly (BLOCK)
contexa.security.plane.agent.event-timeout-ms180000The whole budget for analyzing one event (ms)When long model calls end events without a decision
contexa.rag.etl.behavior.retention-days90Retention of past decision records (days)When your retention policy differs

Every setting is listed in Configuration.

Good to know in operation

  • Seeing decisions: decisions are kept in the observation table (ctxa_ai_security_decision_observation) and the audit log, and shown in the Zero Trust console's decision records (/contexa/admin/zero-trust/decisions) and the admin console's security event log (/contexa/admin/security-monitor).
  • If no decision appears and users stay pending, check first: the enforcement mode is not OBSERVE or DISABLED, chat model and vector store beans exist, and the observation record database can be written.
  • The analysis queue holds up to 10,000 events (contexa.security.plane.monitor.queue-size).
  • One event has a 180-second budget. Waiting more than 60 seconds in the analysis thread pool (default core 32, max 64, queue 256) or exceeding the budget ends the event without a decision; it is queued again at most 3 times.
  • In distributed mode (contexa.infrastructure.mode=distributed) events go to the Kafka topic ctxa.<application name>.security.events.<category>.<type> (for example ctxa.order-service.security.events.authorization.method; the application name is spring.application.name, and without one the prefix is just ctxa.), and events that could not be handled go to the DLQ topic (ctxa.<application name>.security-events-dlq, or the name set in contexa.security.kafka.topic.dlq).
  • contexa.security.tiered.layer2.enable-soar has no effect in the OSS today: no code fills the playbook a blocking decision would carry, so no SOAR runs (SOAR).