Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/samkit511/SAW---Security-Analyst-Workspace/llms.txt

Use this file to discover all available pages before exploring further.

SAW exposes three boolean feature flags that let you tune how much of the processing pipeline is active. Each flag defaults to true in .sampleenv, giving you the full hybrid execution model out of the box. You can disable any combination of them to isolate subsystems for testing, reduce external API calls, or constrain behavior in restricted environments. The flags are read once at process startup — restart the server after changing them.
Start with all three flags set to true in production. Disable them only when you have a specific operational reason (air-gapped deployment, quota constraints, or controlled rollout). Disabling multiple flags simultaneously can significantly change system behavior; review the interaction notes at the bottom of this page before doing so.

​
The three flags

ASA_ENABLE_HEURISTICS — fast deterministic pre-filter

Default: true | Variable: ASA_ENABLE_HEURISTICSWhen this flag is true, the threat detector (threat_detector.py) runs a set of fast regex and string-match rules against the canonicalized log signal before any LLM call. If a rule matches, the threat type, severity, and confidence are set immediately and the LLM is skipped entirely for that event.Patterns covered by the heuristic layer:
PatternDetected threatConfidenceSeverity
or '1'='1, union select, drop table, sleep(, benchmark(, xp_cmdshellSQL Injection0.95HIGH
<script>, javascript:, onerror=, onload=XSS0.90HIGH
../, ..\Path Traversal0.92HIGH
login failed, invalid passwordBrute Force0.85MEDIUM
Heuristic matches set detection_mode: deterministic and reason_source: heuristic_rule. In the confidence calibration step, this combination maps raw confidence ≥ 0.9 to the VERY_HIGH bucket and anything lower to HIGH. Both buckets produce risk scores above the default ASA_EXECUTE_THRESHOLD (2.5) for HIGH-severity threats, meaning they reach EXECUTE without touching the LLM.When disabled: heuristic_detect returns None for every signal, and all events are routed to the Gemini-based LLM path (or the fallback path if GOOGLE_API_KEY is not set). This increases latency and Gemini API usage but can be useful when you want to evaluate LLM behavior independently of the rule engine.
Default: true | Variable: ASA_ENABLE_ADK_ADVISORYWhen this flag is true, the RiskAgent calls the ADK coordinator (ASAAgent.run) for any event where the confidence bucket is LOW or MEDIUM, or where detection_mode is fallback. The ADK coordinator reviews the current deterministic decision and may recommend an override if the low-confidence classification warrants a different action.The advisory flow:
  1. DetectionAgent produces a classification with confidence_bucket: LOW or MEDIUM.
  2. RiskAgent calls asa_agent.run(prompt) with full incident context.
  3. If the ADK response includes a valid recommended_decision (EXECUTE, OBSERVE, or IGNORE) and the event is eligible for override, RiskAgent replaces the deterministic decision.
  4. decision_source is updated to ADKCoordinator and decision_authority to llm_override.
  5. adk_review.influenced_outcome: true is set in the response trace.
ADK responses are cached for ASA_ADK_CACHE_TTL_SECONDS seconds (default 120). Repeated identical prompts within the TTL window return the cached result with cache_hit: true and no new Gemini call.When disabled: The adk_review block in every response is set to status: skipped with eligible_for_override: false. The deterministic result from the threshold comparison in decision_engine.py is always final. This mode eliminates all ADK-related latency and external calls, at the cost of lower accuracy for ambiguous or novel threats.
ADK advisory only applies to LOW/MEDIUM confidence cases. HIGH and VERY_HIGH confidence detections — which typically come from heuristic matches — are never sent to the ADK coordinator, even when this flag is true.
Default: true | Variable: ASA_ENABLE_ESCALATIONWhen this flag is true, the RiskAgent maintains per-IP event memory and evaluates two escalation patterns after each event:Burst escalation — triggered when a single source IP generates 3 or more events within any 15-second window. This pattern typically indicates an automated scanner or active exploit attempt.Sustained escalation — triggered when a source IP accumulates 5 or more events within 60 seconds and the severity-weighted score across those events reaches 9 or above. The severity weights are LOW = 1, MEDIUM = 2, HIGH = 3.When either condition is met, escalation.status is set to true, the classification behavior field is overridden to Aggressive Attacker, and the decision engine receives escalated=True. This forces an EXECUTE decision regardless of the computed risk score.Escalation state is stored in an in-process dictionary with a 1-hour TTL per IP. It resets on server restart.When disabled: The evaluate_escalation call is skipped and the escalation block in the response always reads status: false, profile: disabled. Each event is evaluated independently with no memory of prior activity from the same IP. This is appropriate when SAW sits behind a proxy that masks source IPs, or when escalation logic is handled by an upstream SIEM.

​
Flag interactions

The three flags are independent switches, but their combination determines which execution path each event takes:
ASA_ENABLE_HEURISTICSASA_ENABLE_ADK_ADVISORYASA_ENABLE_ESCALATIONEffective mode
truetruetrueFull hybrid — default, recommended for production
truefalsetrueHeuristics + escalation only; no LLM advisory
falsetruetrueLLM-first with escalation; slower, higher API usage
truetruefalseHeuristics + ADK advisory; no burst/sustained detection
falsefalsefalsePure deterministic — all events scored only by thresholds; no LLM, no escalation
Running with both ASA_ENABLE_HEURISTICS=false and ASA_ENABLE_ADK_ADVISORY=false puts SAW in pure deterministic mode. Every event is classified by whatever the base LLM result produces (or the fallback Unknown / LOW if no Gemini key is configured), then scored directly against the EXECUTE/OBSERVE thresholds with no further reasoning. This mode is useful for benchmarking threshold behavior in isolation.

​
Setting flags at runtime

All three flags accept only true or false (case-insensitive). The server reads them once at import time, so you must restart the process for changes to take effect. 
# Disable ADK advisory (no LLM review, deterministic only)
ASA_ENABLE_ADK_ADVISORY=false uvicorn app.main:app --host 0.0.0.0 --port 8080

# Run in pure deterministic mode
ASA_ENABLE_HEURISTICS=true ASA_ENABLE_ADK_ADVISORY=false ASA_ENABLE_ESCALATION=false \
  uvicorn app.main:app --host 0.0.0.0 --port 8080
The current flag state is visible at runtime on the /metrics-json endpoint under the feature_flags object, and in every triage response under meta.feature_flags.

Build docs developers (and LLMs) love

Get started for freeTalk to us