Security Configuration | Contexa Docs

Zero Trust Properties

Properties under contexa.security.zerotrust, bound to SecurityZeroTrustProperties. These settings control the Zero Trust decision mode, core thresholds, hot-path handling, cache windows, and request-tracking behavior. HCAD is configured separately under the hcad prefix.

Property	Type	Default	Description
`contexa.security.zerotrust`
`.enabled`	`boolean`	`true`	Enable the Zero Trust engine
`.mode`	`SecurityMode`	`ENFORCE`	Execution mode: `SHADOW` (observe) or `ENFORCE` (block)
`.max-block-mfa-attempts`	`int`	`2`	Max MFA attempts allowed when bypassing a block
`contexa.security.zerotrust.sampling`
`.rate`	`double`	`1.0`	Request sampling ratio (0.0–1.0)
`contexa.security.zerotrust.hotpath`
`.enabled`	`boolean`	`true`	Enable hot-path fast decision
`contexa.security.zerotrust.thresholds`
`.skip`	`double`	`0.3`	Skip-evaluation threshold (below this score)
`.optional`	`double`	`0.5`	Optional authentication threshold
`.required`	`double`	`0.7`	Required authentication threshold
`.strict`	`double`	`0.9`	Strict block threshold
`contexa.security.zerotrust.protectable`
`.rapid-reentry-window-ms`	`long`	`5000`	Rapid re-entry window for protected resources (ms)
`contexa.security.zerotrust.redis`
`.timeout`	`int`	`5`	Redis operation timeout (seconds)
`.update-interval-seconds`	`int`	`30`	Redis state update interval (seconds)
`contexa.security.zerotrust.threat`
`.initial`	`double`	`0.3`	Initial threat score
`contexa.security.zerotrust.cache`
`.ttl-hours`	`int`	`24`	Decision cache TTL (hours)
`.session-ttl-minutes`	`int`	`30`	Session cache TTL (minutes)
`.invalidated-ttl-minutes`	`int`	`60`	Invalidated cache TTL (minutes)
`contexa.security.zerotrust.session`
`.tracking-enabled`	`boolean`	`true`	Enable session tracking

Related: Zero Trust Flow

HCAD Properties

Properties under the hcad prefix, bound to HcadProperties. Configures the Hierarchical Context-Aware Detection (HCAD) filter pipeline and baseline learning.

Property	Type	Default	Description
`hcad`
`.enabled`	`boolean`	`true`	Enable or disable the HCAD filter pipeline.
`.filter-order`	`int`	`100`	HCAD filter order in the servlet filter chain.
`hcad.resource`
`.sensitive-patterns`	`List<String>`	`[]`	URL patterns for sensitive resources requiring enhanced analysis.
`hcad.analysis`
`.max-age-ms`	`long`	`3600000`	Maximum age (ms) for cached analysis results.
`hcad.threshold`
`.base`	`double`	`0.7`	Base anomaly detection threshold.
`.min`	`double`	`0.3`	Minimum threshold after adaptive adjustment.
`.max`	`double`	`0.95`	Maximum threshold after adaptive adjustment.
`.adjustment-rate`	`double`	`0.01`	Rate of threshold adaptation per feedback cycle.
`.sensitivity`	`double`	`1.0`	Global sensitivity multiplier for detection.
`.warn`	`double`	`0.7`	Warning threshold before block action.
`hcad.cache`
`.max-size`	`int`	`100000`	Maximum number of cached analysis entries.
`.ttl-ms`	`long`	`300000`	Cache entry time-to-live in milliseconds.
`.clear-on-startup`	`boolean`	`false`	Clear all cache entries on application startup.
`.local.ttl-minutes`	`int`	`10`	Local cache TTL in minutes.
`hcad.baseline`
`.min-confidence`	`double`	`0.3`	Minimum confidence for baseline data.
`.update-alpha`	`double`	`0.1`	Exponential moving average alpha for baseline updates.
`.learning.enabled`	`boolean`	`true`	Enable baseline learning from live traffic.
`.learning.alpha`	`double`	`0.1`	Online baseline adaptation learning rate.
`.bootstrap.enabled`	`boolean`	`true`	Enable bootstrap mode for initial baseline building.
`.bootstrap.initial-samples`	`int`	`10`	Number of initial samples required before enforcement.
`.bootstrap.max-anomaly-score`	`double`	`0.85`	Maximum anomaly score during bootstrap phase.
`.statistical.enabled`	`boolean`	`true`	Enable statistical baseline analysis.
`.statistical.min-samples`	`int`	`20`	Minimum samples for statistical analysis.
`.statistical.z-score-threshold`	`double`	`3.0`	Z-score threshold for outlier detection.
`.redis.ttl-days`	`int`	`30`	Redis baseline data TTL in days.
`hcad.feedback`
`.learning-rate`	`double`	`0.1`	Feedback loop learning rate for threshold adjustment.
`.retrain-threshold`	`double`	`0.7`	Accuracy threshold triggering model retrain.
`.window-size`	`int`	`1000`	Sliding window size for feedback collection.
`hcad.orchestrator`
`.enabled`	`boolean`	`true`	Enable the HCAD orchestrator for coordinated analysis.
`.feedback-interval`	`int`	`300`	Feedback processing interval in seconds.
`.sync-batch-size`	`int`	`50`	Batch size for baseline synchronization.
`hcad.vector`
`.embedding-dimension`	`int`	`384`	Embedding vector dimension for behavioral analysis.
`.similarity-threshold`	`double`	`0.85`	Similarity threshold for behavioral pattern matching.
`.scenario-detection-enabled`	`boolean`	`true`	Enable scenario-based anomaly detection via vectors.
`hcad.session`
`.cookie-name`	`String`	`JSESSIONID`	Session cookie name for HCAD tracking.
`.header-name`	`String`	`X-Session-Id`	Header name for session ID in stateless mode.
`hcad.signal`
`.chi-square-threshold`	`double`	`14.07`	Chi-square threshold for signal anomaly detection.
`.history-size`	`int`	`100`	Number of historical signals to retain.
`.geoip.provider`	`String`	`api`	GeoIP provider: `api` or `local`.
`hcad.adaptive`
`.adjustment-rate`	`double`	`0.1`	Adaptive threshold adjustment rate.
`.cusum.threshold`	`double`	`5.0`	CUSUM change-point detection threshold.
`.cusum.slack`	`double`	`0.5`	CUSUM slack parameter for drift tolerance.
`.baseline.window`	`int`	`100`	Adaptive baseline window size.
`hcad.geoip`
`.enabled`	`boolean`	`false`	Enable GeoIP-based location analysis.
`.db-path`	`String`	`data/GeoLite2-City.mmdb`	Path to MaxMind GeoLite2 database file.
`hcad.redis`
`.key-prefix`	`String`	`hcad:baseline:v2:`	Redis key prefix for HCAD baseline data.

Additional HCAD Fields in Current OSS Code

Property	Default	Description
`hcad.baseline.statistical.update-interval`	`10`	Refresh interval for the statistical baseline.
`hcad.feedback.baseline.update-threshold`	`0.95`	Threshold for writing feedback into the learned baseline.
`hcad.orchestrator.performance-tracking`	`true`	Enable orchestrator performance tracking.
`hcad.vector.cache-ttl-hours`	`24`	TTL for cached behavioral embeddings.
`hcad.vector.max-cached-embeddings`	`1000`	Maximum cached embedding entries.
`hcad.signal.covariance.min-samples`	`30`	Minimum samples for covariance analysis.
`hcad.signal.geoip.api-url`	`https://ipapi.co/{ip}/json/`	Remote GeoIP API template.
`hcad.signal.timing.bucket-count`	`7`	Timing bucket count.
`hcad.signal.timing.interval.history-size`	`100`	Timing interval history size.
`hcad.sampling.random.floor`	`0.01`	Minimum random sampling rate.
`hcad.sampling.random.ceiling`	`0.03`	Maximum random sampling rate.
`hcad.sampling.composite.identifier.enabled`	`true`	Enable composite identifier sampling.
`hcad.similarity.hot-path-threshold`	`0.7`	Similarity threshold used by hot-path decisions.
`hcad.adaptive.min.trust.score`	`0.7`	Minimum trust score used by adaptive controls.
`hcad.pre-trigger.enabled`	`true`	Enable pre-trigger heuristics before full analysis.
`hcad.pre-trigger.cooldown-seconds`	`15`	Cooldown for repeated pre-triggers.
`hcad.pre-trigger.in-flight-ttl-seconds`	`15`	TTL for in-flight pre-trigger markers.
`hcad.pre-trigger.negative-cache-seconds`	`3`	Negative cache lifetime.
`hcad.pre-trigger.redline-score`	`70`	Redline score threshold.
`hcad.pre-trigger.high-risk-score`	`50`	High-risk score threshold.
`hcad.pre-trigger.medium-risk-score`	`30`	Medium-risk score threshold.
`hcad.pre-trigger.low-baseline-confidence-threshold`	`0.35`	Low baseline confidence threshold.
`hcad.pre-trigger.failed-login-burst-threshold`	`3`	Failed-login burst threshold.
`hcad.pre-trigger.request-burst-threshold`	`12`	Request burst threshold.
`hcad.pre-trigger.rapid-request-interval-ms`	`1000`	Rapid-request interval window.
`hcad.pre-trigger.sensitive-path-indicators`	`[/admin/, /export, /download, /sensitive/, /critical/]`	Sensitive path indicators (substring match).

Example Configuration

YAML

hcad:
  enabled: true
  filter-order: 100
  resource:
    sensitive-patterns:
      - /admin/api/security-test/sensitive/**
      - /admin/api/security-test/critical/**
  threshold:
    base: 0.7
    sensitivity: 1.0
  baseline:
    learning:
      enabled: true
      alpha: 0.1
    bootstrap:
      enabled: true
      initial-samples: 10
  geoip:
    enabled: false
    db-path: data/GeoLite2-City.mmdb

Session Security Properties

Properties under contexa.security.session, bound to SecuritySessionProperties. The OSS class configures token creation, header and bearer token extraction, hijack notification wiring, cookie naming, and risk thresholds used by session anomaly evaluation.

Property	Type	Default	Description
`contexa.security.session.create.allowed`	`boolean`	`true`	Allows session/token creation
`contexa.security.session.header.name`	`String`	`X-Auth-Token`	Header name for token transport
`contexa.security.session.bearer.enabled`	`boolean`	`true`	Enables bearer token parsing
`contexa.security.session.cookie.name`	`String`	`SESSION`	Cookie name used for session transport
`contexa.security.session.hijack.channel`	`String`	`security:session:hijack:event`	Hijack event channel name
`contexa.security.session.hijack.detection.enabled`	`boolean`	`true`	Hijack detection toggle
`contexa.security.session.threat.ip-change-risk`	`double`	`0.4`	Risk contribution for IP changes
`contexa.security.session.threat.ua-change-risk`	`double`	`0.3`	Risk contribution for user-agent changes
`contexa.security.session.threat.rapid-access-threshold-ms`	`int`	`100`	Rapid-access threshold window
`contexa.security.session.threat.rapid-access-risk`	`double`	`0.2`	Risk contribution for rapid access bursts
`contexa.security.session.threat.thresholds.monitoring`	`double`	`0.5`	Monitoring threshold
`contexa.security.session.threat.thresholds.grace-period`	`double`	`0.7`	Grace-period threshold
`contexa.security.session.threat.thresholds.invalidation`	`double`	`0.9`	Invalidation threshold

Related: State Management Reference

Step-Up Properties

Properties under contexa.security.stepup, bound to SecurityStepUpProperties. Defines the maximum authentication attempts and lock duration for step-up auth during high-risk actions that require multi-factor authentication (MFA) or extra approval.

Property	Type	Default	Description
`contexa.security.stepup`
`.max-attempts`	`int`	`3`	Maximum attempts allowed for step-up auth.
`.lockout-duration`	`int`	`300`	Account lockout duration (seconds) upon exceeding max attempts.

Decision Plane Properties

Properties under contexa.saas, controlling integration with the Contexa SaaS Decision Plane. Configures endpoint, intervals, retry policy, and OAuth2 client settings for forwarding local decisions, feedback, and telemetry data to the remote cloud plane.

Property	Type	Default	Description
`contexa.saas`
`.enabled`	`boolean`	`false`	Enables decision forwarding to SaaS Decision Plane.
`.endpoint`	`String`	`https://saas.ctxa.ai`	SaaS Decision Plane base endpoint URL.
`.include-reasoning`	`boolean`	`false`	Includes decision logic/reasoning in forwarded payloads.
`.include-raw-analysis-data`	`boolean`	`false`	Includes raw analysis data in forwarded payloads.
`.outbox-batch-size`	`int`	`50`	Outbox event batch size.
`.max-retry-attempts`	`int`	`10`	Maximum attempts for retrying failed dispatches.
`.retry-initial-backoff-ms`	`long`	`1000`	Initial backoff delay in milliseconds.
`.retry-max-backoff-ms`	`long`	`60000`	Maximum backoff delay in milliseconds.
`.dispatch-interval-ms`	`long`	`30000`	Outbox dispatch interval in milliseconds.
`.pseudonymization-secret`	`String`	`default-dev-secret-change-in-prod`	Secret key used for pseudonymizing data.
`.global-correlation-secret`	`String`	`default-dev-correlation-secret`	Secret key used for generating global correlation IDs.
`contexa.saas.oauth2`
`.enabled`	`boolean`	`true`	Enables OAuth2 integration.
`.registration-id`	`String`	`contexa-saas-client`	OAuth2 client registration ID.
`.token-uri`	`String`	`https://saas.ctxa.ai/oauth2/token`	OAuth2 token request URI.
`.client-id`	`String`	`dev-client`	OAuth2 client ID.
`.client-secret`	`String`	`dev-secret`	OAuth2 client secret.
`.scope`	`String`	`saas.xai.decision.ingest,...`	Comma-separated OAuth2 scopes requested.
`.expiry-skew-seconds`	`int`	`30`	Clock skew buffer (seconds) for token expiry detection.

Distributed Enforcement Properties

Properties under contexa.security.tiered, bound to TieredStrategyProperties. Configures tiered security analysis and enforcement policies between the local agent and cloud/remote agents. Fine-tunes active tiers, truncation parameters, vector search limits, and timeout thresholds.

Property	Type	Default	Description
`contexa.security.tiered`
`.enabled`	`boolean`	`true`	Enables the tiered analysis strategy.
`.native-structured-output-enabled`	`boolean`	`true`	Leverages native structured JSON schemas supported by LLMs.
`.telemetry-enabled`	`boolean`	`true`	Enables tiered security telemetry.
`.trusted-proxy-validation-enabled`	`boolean`	`true`	Enables validation of trusted proxy IPs.
`contexa.security.tiered.layer1` / `layer2` (Layer configurations)
`.layer1.enabled`	`boolean`	`true`	Enables layer-1 (local fast check) analysis.
`.layer1.default-budget-profile`	`String`	`CORTEX_L1_INTERACTIVE_STRICT`	Resource budget profile for layer-1.
`.layer2.enabled`	`boolean`	`false`	Enables layer-2 (cloud deep check) analysis.
`.layer2.default-budget-profile`	`String`	`CORTEX_L2_EXPERT_STRICT`	Resource budget profile for layer-2.
`.layer2.enable-soar`	`boolean`	`false`	Automatically triggers SOAR actions based on layer-2 decisions.
`contexa.security.tiered.security` (Decision fine-tuning)
`.security.vector-search-limit`	`int`	`3`	Maximum database matches for similar decision vectors.
`.security.max-similar-events`	`int`	`2`	Maximum past events matched to detect attack scenarios.
`.security.max-rag-documents`	`int`	`3`	Maximum documents injected via RAG to enrich decision context.
`.security.timeout-ms`	`long`	`7000`	Timeout in milliseconds for remote layer-2 requests.