Shadow Mode Migration

How Shadow Mode Works

When Contexa is first deployed into an existing application, immediately enforcing AI-driven security decisions would be risky. Shadow Mode solves this by running the full AI evaluation pipeline in parallel with your existing security, allowing you to observe and validate AI decisions before enabling enforcement.

The mode is controlled by a single property: security.zerotrust.mode. In SHADOW mode, the AI analysis pipeline runs fully (HCAD, LLM analysis, risk scoring) but the SecurityDecisionEnforcementHandler skips writing actions to Redis. In ENFORCE mode (default), actions are saved and enforced by ZeroTrustAccessControlFilter.

Stage 1: Shadow

In Shadow mode, the full Contexa AI pipeline runs alongside your existing security infrastructure without affecting any authorization decisions. Every request is analyzed through HCAD and the Zero Trust engine, and the AI produces ZeroTrustAction decisions — but SecurityDecisionEnforcementHandler skips enforcement entirely. Decisions are only recorded in audit logs.

This stage is essential for building behavioral baselines. The HCAD engine needs to observe normal user patterns before it can reliably detect anomalies.

contexa:
  enabled: true
  autonomous:
    enabled: true

security:
  zerotrust:
    enabled: true
    mode: SHADOW

hcad:
  enabled: true
  baseline:
    learning:
      enabled: true

How Shadow Mode Works Internally

The SecurityEventProcessor handler chain executes in order:

1. ProcessingExecutionHandler (order=50) — AI analysis runs normally, producing risk scores and action recommendations
2. SecurityDecisionEnforcementHandler (order=55) — When SecurityZeroTrustProperties.isEnforcementEnabled() returns false (i.e. mode = SHADOW), the handler logs the observed decision and returns without invoking ZeroTrustActionRepository.saveAction(), setBlockedFlag(), BlockingSignalBroadcaster.registerBlock(), or IBlockedUserRecorder.recordBlock(). No runtime side-effect is applied. In ENFORCE mode (default) all four side-effects run as before. Baseline learning via SecurityLearningService still runs for ALLOW decisions in both modes.
3. AuditingHandler (order=60) — Records the AI decision to audit logs, including what action would have been enforced

Since no action is written to Redis, ZeroTrustAccessControlFilter has nothing to enforce on the next request — all requests pass through normally.

What to Monitor

• HCAD baseline confidence scores stabilizing across active users
• ZeroTrustAction distribution in audit logs (ALLOW vs. BLOCK vs. CHALLENGE vs. ESCALATE)
• False positive rate: how often the AI would have blocked a legitimate request
• AI analysis latency: ensure the async pipeline does not impact request throughput

Stage 2: Enforce

In Enforce mode, the Contexa AI engine has full authority over security decisions. The SecurityDecisionEnforcementHandler saves AI-determined ZeroTrustAction decisions to Redis, and the ZeroTrustAccessControlFilter enforces them on subsequent requests. This is the default mode.

contexa:
  enabled: true
  autonomous:
    enabled: true

security:
  zerotrust:
    enabled: true
    mode: ENFORCE
    threat:
      initial: 0.3
  session:
    bearer:
      enabled: true

hcad:
  enabled: true
  baseline:
    learning:
      enabled: true

Enforcement Rules

• ALLOW — Request passes through normally
• BLOCK — Request is denied (HTTP 403). User is recorded in the blocked user registry.
• CHALLENGE — Additional verification steps are triggered
• ESCALATE — Request is held (HTTP 423) until further review is complete
• PENDING_ANALYSIS — Response is wrapped in BlockableResponseWrapper and may be aborted if the async AI pipeline determines a block is necessary

Migration Strategy

Follow this recommended timeline for a safe migration:

Rollback Strategy

You can safely roll back at any time by changing the security.zerotrust.mode property. HCAD baselines and learned patterns are preserved across mode changes.

Related Documentation