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 reads all configuration from environment variables at startup. Copy .sampleenv to .env in the project root, set values for your deployment, then start the server. The table and sections below cover every variable, its default, and what it controls. None of these variables are required for a local demo — the defaults let you run immediately without any external credentials.
ASA_API_KEY defaults to demo. This key protects every authenticated endpoint via the x-api-key header. You must replace it with a strong, randomly generated value before exposing SAW to any network beyond your local machine.

​
Sample .env file

.sampleenv
# Copy this file to `.env` before running locally.
# PowerShell:
# Copy-Item .sampleenv .env

# Core server
PORT=8080
ASA_API_KEY=demo
ASA_MODE=HYBRID
ASA_DB_PATH=data/assistant.db

# Request limits and resilience
ASA_MAX_INFLIGHT=8
ASA_MAX_REQUEST_BYTES=16384
ASA_RATE_LIMIT_WINDOW_SECONDS=60
ASA_RATE_LIMIT_MAX_REQUESTS=12
ASA_REPLAY_WINDOW_SECONDS=30

# Decision thresholds
ASA_EXECUTE_THRESHOLD=2.5
ASA_OBSERVE_THRESHOLD=1.5

# Feature flags
ASA_ENABLE_ADK_ADVISORY=true
ASA_ENABLE_ESCALATION=true
ASA_ENABLE_HEURISTICS=true

# Models
ASA_ADK_MODEL=gemini-2.5-flash
ASA_DETECTION_MODEL=gemini-2.5-flash
ASA_REMEDIATION_MODEL=gemini-2.5-flash

# LLM / ADK behavior
ASA_ADK_CACHE_TTL_SECONDS=120
ASA_LLM_MAX_ATTEMPTS=2

# Gemini / Google credentials
# Set one of these if you want live Google GenAI / ADK calls.
GOOGLE_API_KEY=
GEMINI_API_KEY=

​
Core server

Default: 8080The TCP port Uvicorn binds to when you start the server with python -m uvicorn app.main:app. Change this if port 8080 is already in use or if your deployment platform assigns its own port value.
PORT=3000 uvicorn app.main:app --host 0.0.0.0
Default: demoThe shared secret sent by clients in the x-api-key request header. SAW uses a constant-time comparison to prevent timing attacks. Every protected endpoint — /assistant/request, /ingest-log, /agent-test, /tasks, and /tasks/{id}/complete — returns 401 unauthorized if this header is missing or incorrect.
Never deploy SAW in any shared or production environment with ASA_API_KEY=demo. Generate a strong key with a tool such as openssl rand -hex 32.
Default: HYBRIDControls whether LLM-assisted detection is active. Accepted values:
ValueBehavior
HYBRIDHeuristics run first; ambiguous signals escalate to Gemini.
SAFELLM calls are disabled. All events are classified deterministically and any threat that does not match a heuristic rule returns type: None with zero confidence.
Use SAFE mode in air-gapped environments or during development when you do not have a Gemini API key.
Default: data/assistant.dbRelative path to the SQLite file used for persistent incident, event, task, action, and agent-run storage. SAW creates the file and any missing parent directories automatically on first run. Point this to a volume mount in Docker deployments to survive container restarts.

​
Request limits and resilience

Default: 8Maximum number of requests that can be processed concurrently across all endpoints. When the limit is reached, SAW returns 503 overloaded with a retry_after_seconds: 1 hint. Increase this on multi-core hardware or reduce it to protect downstream LLM API quotas.
Default: 16384 (16 KB)Maximum allowed request body size in bytes. Requests larger than this limit are rejected with 413 payload_too_large before any parsing occurs. This applies to /ingest-log, /assistant/request, /agent-test, and /tasks.
Default: 60The sliding window, in seconds, over which per-IP request counts are measured. Works together with ASA_RATE_LIMIT_MAX_REQUESTS to throttle individual source IPs.
Default: 12Maximum requests a single source IP may make within one ASA_RATE_LIMIT_WINDOW_SECONDS window. Requests beyond this limit receive 429 rate_limited with a retry_after_seconds value calculated from the oldest request in the current window.
Default: 30Duration in seconds for which a seen event_id value is retained in memory. If a client sends the same x-event-id header (or event_id JSON field) within this window, SAW rejects the duplicate with 409 replay_detected. Set to 0 to disable replay protection (not recommended in production).

​
Decision thresholds

These variables control when the decision engine promotes a threat from IGNORE → OBSERVE → EXECUTE. See Tuning decision thresholds for the full scoring formula and tuning guidance.
Default: 2.5Risk score at or above which the decision engine returns EXECUTE — meaning the system applies mitigation actions automatically. Must be a float in the range (ASA_OBSERVE_THRESHOLD, 3.0].
Default: 1.5Risk score at or above which the decision engine returns OBSERVE, creating an analyst investigation task but taking no automated blocking action. Must be a float in the range (0.0, ASA_EXECUTE_THRESHOLD).

​
Feature flags

See Feature flags reference for detailed behavior of each flag, including interaction effects.
Default: trueWhen true, the RiskAgent calls the ADK coordinator for LOW and MEDIUM confidence detections. When false, the deterministic result is always final.
Default: trueWhen true, per-IP event memory tracks burst and sustained attack patterns that can escalate a decision to EXECUTE regardless of the base risk score.
Default: trueWhen true, fast regex and string matching runs before any LLM call, providing sub-millisecond classification for well-known attack patterns.

​
Model selection

Default: gemini-2.5-flashThe Gemini model used by the ADK coordinator agent (ASAAgent / root_agent) for multi-agent orchestration, workflow planning, and low-confidence decision reviews.
Default: gemini-2.5-flashThe Gemini model used by the threat detector (threat_detector.py) for LLM-assisted log classification when heuristics produce no match and ASA_MODE is HYBRID.
Default: gemini-2.5-flashThe Gemini model used by the patch generator (patch_generator.py) to produce remediation recommendations for classified threats.

​
LLM and ADK behavior

Default: 120Time-to-live in seconds for cached ADK responses. SAW caches ADK results keyed on the prompt and request context to reduce latency and avoid redundant Gemini API calls. Set to 0 to disable caching (useful during development or when debugging ADK behavior).
Default: 2Maximum number of times the threat detector retries a failed Gemini API call before falling back to a deterministic Unknown / LOW classification. Increasing this value improves resilience under transient API errors at the cost of higher tail latency.

​
Gemini credentials

Default: (empty)Either variable authenticates the Google GenAI client. SAW checks GOOGLE_API_KEY first, then falls back to GEMINI_API_KEY. You only need to set one. If neither is set and ASA_MODE is HYBRID, all LLM calls degrade gracefully to the deterministic fallback path — no crash occurs, but threat classification accuracy drops for ambiguous inputs.
Obtain a key from Google AI Studio. The gemini-2.5-flash model used by default has a generous free tier suitable for development and testing.

Build docs developers (and LLMs) love

Get started for freeTalk to us