AI Application Protection — Admin Configuration

This page covers all administrative configuration for AI Application Protection. For a feature overview, see AI Application Protection. For a detailed description of each threat category and its detection logic, see Threat Categories.

Enabling AI Application Protection

AI Application Protection is disabled by default. It requires explicit opt-in at the application level.

Set the following environment variable in your application’s deployment configuration:

APPGUARD_ENABLED=true

Until this variable is set to true, the protection sidecar runs but all requests pass through uninspected. This allows you to deploy the sidecar and validate connectivity before activating enforcement.

Service connectivity

Environment variables

Variable	Default	Description
`APPGUARD_ENABLED`	`false`	Master enable switch. Must be `true` for inspection to occur.
`APPGUARD_SERVICE_URL`	`http://localhost:8400`	URL of the protection sidecar. For sidecar deployments sharing a network namespace, the default `localhost` address is correct. Adjust if the sidecar runs in a separate pod or host.
`APPGUARD_SERVICE_TIMEOUT`	`500`	Timeout in milliseconds for inspection requests. If the sidecar does not respond within this window, the `appguard.fail_mode` policy applies.

Circuit breaker

The circuit breaker protects your application from cascading failures when the sidecar is degraded or unresponsive.

Config key	Default	Description
`appguard.circuit_breaker_failure_threshold`	`5`	Number of consecutive sidecar failures before the circuit opens.
`appguard.circuit_breaker_recovery_window_ms`	`30000`	Time in milliseconds the circuit remains open before attempting recovery. After this window, one probe request is sent; if it succeeds, the circuit closes.

When the circuit is open, the appguard.fail_mode policy applies to all requests — no inspection occurs until the circuit closes.

Fail-open vs fail-closed

When the protection sidecar is unreachable (timeout, circuit open, or crash), the application must decide whether to allow or reject the request. This is controlled by appguard.fail_mode.

Config key	Default	Options	Description
`appguard.fail_mode`	`open`	`open` \| `closed`	`open`: requests pass through when the sidecar is unavailable. `closed`: requests are rejected when the sidecar is unavailable.

Fail-open (open): Application availability is preserved during sidecar outages. Prompts are not inspected during the outage window. Appropriate for most production deployments where availability is the primary concern.

Fail-closed (closed): Requests are rejected if inspection cannot be completed. Application becomes unavailable during sidecar outages. Appropriate for high-security deployments where uninspected prompts are not acceptable under any circumstances.

Set appguard.fail_mode in your system configuration:

POST /api/v1/admin/orgs/{org_id}/system-config
Content-Type: application/json

{
  "key": "appguard.fail_mode",
  "value": "closed"
}

ML classifier configuration

These settings control which detection stages run and how their scores are combined.

Config key	Default	Description
`appguard.classifier_mode`	`ensemble`	Detection mode: `heuristic`, `ml`, or `ensemble`.
`appguard.ml_weight`	`0.6`	Weight applied to the ML classifier score in ensemble mode. Must be between 0.0 and 1.0.
`appguard.heuristic_weight`	`0.4`	Weight applied to the heuristic analyzer score in ensemble mode. Must be between 0.0 and 1.0.

Classifier modes:

Mode	Behavior
`heuristic`	Heuristic pattern matching only. Sub-millisecond latency per request. No ML inference overhead. Best for latency-sensitive deployments with lower adversarial risk.
`ml`	ML classifier only. Higher semantic accuracy for novel attack patterns. Higher per-request latency. Use when false-positive tolerance is high and adversarial sophistication is the primary concern.
`ensemble`	Combined scoring (default). Heuristics run first; the ML classifier is invoked for ambiguous cases. Balances accuracy and latency.

The ensemble final score is computed as:

final_score = (heuristic_score × heuristic_weight) + (ml_score × ml_weight)

The two weights do not need to sum to 1.0, but it is recommended for score interpretability.

Detection thresholds

Thresholds control at what score level each policy action activates.

Config key	Default	Description
`appguard.log_threshold`	`0.5`	Messages scoring at or above this value are recorded as suspicious in the audit log, regardless of whether they are blocked.
`appguard.block_threshold`	`0.85`	Messages scoring at or above this value trigger the configured block action for their threat category (typically `BLOCK`).
`appguard.session_terminate_threshold`	`0.95`	Messages scoring at or above this value — or sessions whose cumulative risk score crosses this value — trigger session termination.

Set thresholds via the system configuration API:

POST /api/v1/admin/orgs/{org_id}/system-config
Content-Type: application/json

{
  "key": "appguard.block_threshold",
  "value": "0.85"
}

Threshold tuning guidance:

Start with default thresholds and LOG actions for all categories during initial rollout.
Review audit events for false positives (legitimate requests scored above log_threshold) before promoting categories to BLOCK.
Lower block_threshold values increase sensitivity but raise false-positive risk.
Raise log_threshold if audit log volume is excessive due to low-risk ambiguous messages.

Multi-turn escalation (Crescendo) settings

These settings control how conversation-level risk accumulates for multi-turn attack detection.

Config key	Default	Description
`appguard.crescendo_window`	`10`	Number of most recent turns included in the session risk calculation. Turns older than this window do not contribute to the current session risk score.
`appguard.crescendo_decay`	`0.9`	Risk decay factor applied per turn. A value of `0.9` means each turn retains 90% of the previous turn’s accumulated risk before the current turn’s contribution is added. Lower values weight recent turns more heavily; higher values retain historical risk longer.

A session is terminated when its cumulative risk score crosses appguard.session_terminate_threshold.

Per-category policy overrides

By default, each threat category uses its built-in default action (see Threat Categories — Policy Actions). You can override the action for any category individually.

Available actions: LOG, BLOCK, TERMINATE_SESSION.

POST /api/v1/admin/orgs/{org_id}/system-config
Content-Type: application/json

{
  "key": "appguard.policy.prompt_injection",
  "value": "BLOCK"
}

Full set of per-category keys and recommended values:

appguard.policy.prompt_injection        = BLOCK
appguard.policy.encoding_evasion        = LOG
appguard.policy.jailbreak               = BLOCK
appguard.policy.insider_exfil           = TERMINATE_SESSION
appguard.policy.xml_json_puppetry       = BLOCK
appguard.policy.multi_turn_escalation   = BLOCK
appguard.policy.supply_chain            = TERMINATE_SESSION
appguard.policy.system_prompt_extraction = BLOCK

These are the defaults. Set any key explicitly to override the default for that category.

Rollout pattern: During a new deployment, set all categories to LOG first. After a monitoring period, promote high-confidence categories to BLOCK or TERMINATE_SESSION once you have validated the false-positive rate for your application’s traffic patterns.

Monitoring and audit events

Audit event types

AI Application Protection emits three event types into the standard audit log pipeline:

Event	Emitted when
`appguard.threat_detected`	A message is classified as adversarial (regardless of policy action). Includes threat category, score, session risk, and turn number.
`appguard.request_blocked`	A request is rejected due to a `BLOCK` policy action.
`appguard.session_terminated`	A session is ended due to a `TERMINATE_SESSION` policy action. Includes the triggering turn, category, and final session risk score.

Event payload fields

Field	Type	Description
`event_type`	string	One of the three event types above.
`session_id`	string	Session identifier provided by your application.
`turn`	integer	Turn number within the session.
`threat_category`	string	Detected threat category (e.g., `prompt_injection`, `jailbreak`).
`threat_score`	float	Per-message threat score (0.0–1.0).
`session_risk`	float	Cumulative session risk score at the time of detection.
`action_taken`	string	`LOG`, `BLOCK`, or `TERMINATE_SESSION`.
`classifier_mode`	string	Mode active at detection time: `heuristic`, `ml`, or `ensemble`.

Threat scores in conversation metadata

Each session’s threat score history is available in the conversation metadata API. This allows you to review the score trajectory for a session after the fact, which is useful for incident analysis and threshold tuning.

SIEM integration

AI Application Protection audit events flow through the standard Arbitex audit log pipeline. If a SIEM connector is configured, these events are forwarded automatically alongside other audit events. No additional configuration is required to include these events in SIEM exports.

See Audit Log for connector configuration and the full event schema reference.

Complete system-config reference

Config key	Type	Default	Description
`appguard.fail_mode`	string	`open`	`open` or `closed` — behavior when sidecar is unavailable
`appguard.classifier_mode`	string	`ensemble`	`heuristic`, `ml`, or `ensemble`
`appguard.ml_weight`	float	`0.6`	ML score weight in ensemble mode
`appguard.heuristic_weight`	float	`0.4`	Heuristic score weight in ensemble mode
`appguard.log_threshold`	float	`0.5`	Score at which suspicious events are logged
`appguard.block_threshold`	float	`0.85`	Score at which block action triggers
`appguard.session_terminate_threshold`	float	`0.95`	Score at which session termination triggers
`appguard.crescendo_window`	integer	`10`	Number of turns in the multi-turn risk window
`appguard.crescendo_decay`	float	`0.9`	Per-turn risk decay factor
`appguard.circuit_breaker_failure_threshold`	integer	`5`	Consecutive failures before circuit opens
`appguard.circuit_breaker_recovery_window_ms`	integer	`30000`	Circuit recovery window in milliseconds
`appguard.policy.prompt_injection`	string	`BLOCK`	Per-category policy override
`appguard.policy.encoding_evasion`	string	`LOG`	Per-category policy override
`appguard.policy.jailbreak`	string	`BLOCK`	Per-category policy override
`appguard.policy.insider_exfil`	string	`TERMINATE_SESSION`	Per-category policy override
`appguard.policy.xml_json_puppetry`	string	`BLOCK`	Per-category policy override
`appguard.policy.multi_turn_escalation`	string	`BLOCK`	Per-category policy override
`appguard.policy.supply_chain`	string	`TERMINATE_SESSION`	Per-category policy override
`appguard.policy.system_prompt_extraction`	string	`BLOCK`	Per-category policy override