Platform Architecture | Contexa Docs

Platform Overview

Contexa is an AI Native Zero Trust security platform for Spring Boot. Rather than relying solely on perimeter-based security, Contexa provides continuous verification after authentication through AI-driven security decisions. Contexa applies continuous verification after authentication through request-time enforcement and asynchronous analysis that use session context, behavioral patterns, and threat signals.

The platform is composed of four core modules, each handling a distinct security concern, plus auto-configuration and starter support for seamless Spring Boot integration.

Code-backed bootstrap chain. The OSS entry point is @EnableAISecurity in contexa-common. That annotation imports AiSecurityImportSelector, which loads AiSecurityConfiguration. From there, IdentitySecurityCoreAutoConfiguration and the module-specific auto-configurations wire the request-time runtime control path, the asynchronous analysis path, and the IAM integration points.

contexa-core AI Engine

The AI-powered security brain of the platform. Communicates with LLMs to make autonomous security decisions.

LLM communication and orchestration
Risk analysis and threat evaluation
HCAD anomaly detection
SecurityPlaneAgent with tiered analysis
Autonomous event pipeline with handler chain
RAG-based context retrieval
Behavioral embeddings

contexa-identity Authentication

Manages all authentication flows with a custom DSL built on top of Spring Security.

Form login and REST API authentication
Adaptive MFA, passkey/WebAuthn, OTT
OAuth2 integration
Zero-trust challenge filters
Custom security DSL configuration

contexa-iam Authorization

Dynamic policy-based access control using XACML with AI-driven method-level security.

XACML engine (PAP/PDP/PEP/PIP/PRP)
@Protectable annotation for AI-driven method security
Admin console for policy management
SpEL-based dynamic URL authorization
Resource scanning and discovery

contexa-common Shared

Common entities, services, and domain models shared across all modules.

Shared entity models
Cache service abstraction
Central audit facade
Common annotations
Domain value objects

Additionally, contexa-autoconfigure wires the OSS modules together for Spring Boot, and spring-boot-starter-contexa is the starter dependency that brings the core modules into an application.

AI Native Zero Trust Flow

Contexa processes every HTTP request through two distinct pipelines: a synchronous filter chain that runs on every request, and an asynchronous AI pipeline that analyzes events in the background. The enforced action is persisted through ZeroTrustActionRepository and applied on the next request; in distributed mode that shared state is backed by Redis and Redisson. This non-blocking design keeps analysis off the direct request path.

Primary code anchors. Request-time enforcement flows through AISessionSecurityContextRepository.loadDeferredContext(...), AbstractZeroTrustSecurityService.applyZeroTrustToContext(...), ZeroTrustAccessControlFilter.doFilterInternal(...), and ZeroTrustChallengeFilter.doFilterInternal(...). Asynchronous analysis flows through ZeroTrustEventPublisher.publishMethodAuthorization(...), ZeroTrustEventListener.handleZeroTrustEvent(...), SecurityEventProcessor.process(...), and SecurityDecisionEnforcementHandler.handle(...).

Synchronous Filter Chain

The Spring Security filter chain processes every HTTP request in order. Filters inspect, gate, or enrich the request but never call the LLM directly.

HTTP Request

HCADFilter Host & Context Anomaly Detection — extracts session, device, and behavioral signals and sets request attributes. Never blocks.

ZeroTrustAccessControlFilter Reads the current action from ZeroTrustActionRepository for this user — in distributed mode the shared state is Redis-backed, and the filter enforces decisions made by the asynchronous pipeline on a previous request.

ALLOW —continue BLOCK —403 ESCALATE —423 PENDING —wrap response

ZeroTrustChallengeFilter If CHALLENGE authority detected —initiate MFA challenge

CustomDynamicAuthorizationManager URL-level authorization —evaluates policies from DB as SpEL expressions

AuthorizationManagerMethodInterceptor AOP interceptor —intercepts @Protectable method calls before execution. Evaluates access decision.

GRANTED DENIED

ZeroTrustEventPublisher Called via publishMethodAuthorization() —publishes via Spring ApplicationEventPublisher ZeroTrustSpringEvent

@Protectable Method Execution The actual annotated method executes only if authorization was granted by the interceptor above.

Application Logic

Asynchronous AI Pipeline

ZeroTrustEventListener receives the ZeroTrustSpringEvent synchronously via @EventListener, acting as the bridge into the asynchronous processing pipeline. The AI evaluates threats in the background and persists the enforced action through ZeroTrustActionRepository; in distributed mode Redis-backed storage and Redisson propagation make that state visible to the user's next request.

ZeroTrustEventListener (@EventListener) ZeroTrustSpringEvent Receives event synchronously —bridges sync and async. Routes to SecurityEventPublisher (Kafka or in-memory).

SecurityPlaneAgent Orchestrates batch processing via SecurityEventProcessor

ColdPathEventProcessor AI analysis entry point —orchestrates Layer1/Layer2 tiered analysis with context collection

Layer1ContextualStrategy

Session context + RAG + behavior analysis

Layer2ExpertStrategy

Extended forensics + SOAR integration

SecurityPromptTemplate

UnifiedLLMOrchestrator Spring AI ChatClient —model selection, advisor chain, retry logic ExecutionContext

ALLOW BLOCK CHALLENGE ESCALATE

SecurityDecisionEnforcementHandler (order=55) Persists the enforced action through ZeroTrustActionRepository. On BLOCK: sets blocked state and can broadcast via Redisson RTopic in distributed mode.

Stored in ZeroTrustActionRepository (Redis or in-memory) —enforced on next request

Zero Trust Enforcement (Next Request)

Everything above —synchronous event publication, asynchronous AI analysis, LLM decisions —converges here. Every subsequent request from this user is now governed by the AI's verdict. The decision is not a suggestion; it is fused into Spring Security's Authentication itself.

Every User Request Every HTTP request passes through this pipeline —not just the next one. The AI decision persists until a new analysis overrides it.

AISessionSecurityContextRepository

Session-based login

AIOAuth2ZeroTrustFilter

JWT / OAuth2

Spring SecurityContext Loading

ZeroTrustSecurityService Reads the current action from ZeroTrustActionRepository — in distributed mode this state is Redis-backed — and replaces Authentication with ZeroTrustAuthenticationToken AI Decision —Spring Security Authority

Action already assigned to this user

ALLOW BLOCK CHALLENGE ESCALATE

This action governs every request until a new AI analysis overrides it

ZeroTrustAccessControlFilter BLOCK —403 Forbidden, session invalidated, cross-instance broadcast
ESCALATE —423 Locked, Retry-After: 30s, auto-promotes to BLOCK on TTL expiry
PENDING —wraps response with BlockableResponseWrapper for mid-stream termination

ZeroTrustChallengeFilter CHALLENGE —initiates MFA via ChallengeMfaInitializer
Max 2 attempts in 1hr window —failure auto-promotes to BLOCK

ALLOW —request reaches application code | all others —blocked before reaching controller

For detailed enforcement mechanics including BlockableResponseWrapper, BlockingSignalBroadcaster, and cross-instance propagation, see Zero Trust Flow —Enforcement Infrastructure.

Module Dependencies

The modules form a layered dependency graph. Higher-level modules depend on the core AI engine and shared infrastructure, while the starter aggregates everything.

Module	Depends On
`contexa-identity`	`contexa-core`, `contexa-common`
`contexa-iam`	`contexa-core`, `contexa-common`
`contexa-core`	`contexa-common`
`contexa-autoconfigure`	All modules
`spring-boot-starter-contexa`	All modules

Infrastructure Modes

Contexa supports two infrastructure modes, allowing you to start with a zero-dependency setup for development and scale to a distributed architecture for production.

Code anchor. Infrastructure mode is bound through ContexaProperties.InfrastructureMode under contexa.infrastructure.mode. Distributed-specific beans are activated by conditional auto-configuration, while standalone mode remains the default path with in-memory implementations.

STANDALONE

In-memory implementations for all services. Zero external dependencies —ideal for development, testing, and rapid prototyping.

contexa.infrastructure.mode=STANDALONE

In-memory ZeroTrustAction storage
In-memory cache service
In-memory event bus
No Redis or Kafka required

DISTRIBUTED

Redis + Kafka backed services for production deployments. Supports horizontal scaling and multi-instance coordination.

contexa.infrastructure.mode=DISTRIBUTED

Redis-backed ZeroTrustAction storage
Redis cache with TTL management
Kafka event streaming
Cluster-aware session management

Shadow Mode

Contexa supports a Shadow Mode for safe, progressive adoption. Controlled by a single property, security.zerotrust.mode, it determines whether AI decisions are enforced or only logged.

Code anchor. Shadow and enforce behavior is controlled by SecurityZeroTrustProperties.SecurityMode. In SHADOW mode the analysis path still runs, but enforcement handlers do not persist or apply runtime actions; in ENFORCE mode the same analysis output is written to the action repository and consumed by the runtime filters.

SHADOW

The full AI pipeline still runs — HCAD analysis, tiered LLM evaluation, and risk scoring — but the runtime remains in observation mode. The analysis path continues to record decisions and evidence, while request-time blocking and escalation are not activated as live user enforcement in this mode.

security.zerotrust.mode: SHADOW

ENFORCE

Default mode. The enforced action is persisted through ZeroTrustActionRepository and applied by ZeroTrustAccessControlFilter and companion zero-trust filters on subsequent requests. BLOCK, CHALLENGE, and ESCALATE are active in the live request path.

security.zerotrust.mode: ENFORCE

See Shadow Mode Migration Guide for a detailed walkthrough of the recommended adoption timeline and rollback strategy.

AI Integration Points

AI and LLM capabilities are deeply integrated throughout the platform. The following are the primary points where AI-driven decisions are made.

Code anchors for this section. The items below are backed by runtime components such as SecurityPlaneAgent, Layer1ContextualStrategy, Layer2ExpertStrategy, UnifiedLLMOrchestrator, AIAdaptiveMfaPolicyProvider, ApprovalService.requestApproval(...), AuditingHandler, and CentralAuditFacade.

1

Zero-Trust Threat Evaluation SecurityPlaneAgent uses a tiered LLM strategy —Layer 1 for fast contextual analysis, Layer 2 for deep expert investigation —to evaluate suspicious requests and produce a SecurityDecision whose proposed action and effective autonomous action feed the zero-trust enforcement path.
2

@Protectable Method Authorization Methods annotated with @Protectable trigger AI-driven authorization decisions at the method level, going beyond static role checks to evaluate request context dynamically.
3

HCAD Baseline Learning & Anomaly Scoring The Host & Context Anomaly Detection system learns normal behavioral baselines and scores each request for deviation, feeding anomaly data into the threat evaluation pipeline.
4

Adaptive MFA Policy Decisions AIAdaptiveMfaPolicyProvider uses AI analysis to determine when additional authentication factors should be required, adapting challenge strength based on risk context.
5

AI-Assisted XACML Policy Context The platform combines XACML evaluation with AI-derived runtime context and method-level security signals, helping operators refine policy intent without presenting automatic policy generation as the primary enforcement model.
6

Behavior Analytics Behavioral embeddings capture user interaction patterns as vectors, enabling the AI engine to detect subtle anomalies that rule-based systems would miss.
7

SOAR Orchestration Layer 2 Expert Investigation integrates with SOAR workflows via SoarApprovalNotifier. High-risk decisions can require human approval before enforcement, bridging automated analysis with operational oversight.
8

Central Audit Logging Every AI decision is recorded by AuditingHandler through CentralAuditFacade —regardless of whether enforcement is active (ENFORCE mode) or observation-only (SHADOW mode). Provides a complete audit trail for compliance and forensics.