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.

This guide walks you through installing SAW on your local machine, configuring your environment variables, starting the FastAPI server, and triaging your first security log. You’ll need Python 3.10 or later. A Google or Gemini API key is optional but recommended for live LLM-assisted triage.
1

Prepare your project folder

Clone or download the SAW repository and open a terminal in the project root. All following commands run from that directory.
2

Create a virtual environment

Create an isolated Python environment so SAW’s dependencies don’t conflict with your system packages.
python -m venv .venv
3

Activate the virtual environment

.\.venv\Scripts\Activate.ps1
If PowerShell blocks the activation script, run this first to allow it for the current session only:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
4

Install dependencies

Upgrade pip, then install the pinned requirements:
python -m pip install --upgrade pip
pip install -r requirements.txt
The requirements.txt installs these packages:
google-adk>=1.28.0,<2.0.0
google-genai>=1.69.0,<2.0.0
pydantic>=2.6.3
pydantic-settings>=2.2.1
fastapi>=0.115.0,<1.0.0
uvicorn>=0.34.0,<1.0.0
python-dotenv==1.0.1
httpx>=0.28.1,<1.0.0
5

Configure environment variables

Copy the sample configuration file to create your local .env:
Copy-Item .sampleenv .env
Open .env in a text editor. The defaults are ready to use, but add your API key to enable live Gemini-powered triage:
# Core server
PORT=8080
ASA_API_KEY=demo
ASA_MODE=HYBRID

# Gemini / Google credentials — set one for live LLM calls
GOOGLE_API_KEY=your_key_here
GEMINI_API_KEY=
Without an API key, SAW falls back to deterministic-only mode. The demo API key works for all protected endpoints during local testing. ASA_MODE=HYBRID runs the full pipeline — deterministic pre-filtering first, then LLM escalation for ambiguous events.
6

Start the server

Start the Uvicorn-based FastAPI server with hot reload enabled:
python -m uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload
Once the server is running, you can access:
  • Dashboard UI: http://127.0.0.1:8080
  • Health check: http://127.0.0.1:8080/health
  • Live metrics: http://127.0.0.1:8080/metrics-json
7

Triage your first log

Send a SQL injection log to the /ingest-log endpoint. The x-api-key header must match ASA_API_KEY in your .env (default: demo).
curl -s -X POST http://127.0.0.1:8080/ingest-log \
  -H "Content-Type: application/json" \
  -H "x-api-key: demo" \
  -H "x-event-id: manual-event-1" \
  -d '{
    "ip": "192.168.1.6",
    "method": "GET",
    "path": "/download",
    "payload": "../../etc/passwd",
    "source": "assistant_api"
  }'
A successful response includes a workflow_status, agent_summary, and a full trace object. Look for these fields to confirm the pipeline ran end to end:
{
  "workflow_status": "COMPLETED",
  "agent_summary": "...",
  "trace": {
    "agent_orchestration": { "plan": "..." },
    "stage_3b_adk_agent_review": { "status": "COMPLETED" }
  }
}
Check GET /latest at any time to retrieve the full structured result from the most recent processed incident — useful for dashboarding without storing responses client-side.

​
Common issues

ADK not producing live model responses Verify that GOOGLE_API_KEY or GEMINI_API_KEY is set in .env and that the key has Gemini quota enabled. Then reinstall dependencies: 
pip install -r requirements.txt
workflow_status is DEGRADED instead of COMPLETED The deterministic pipeline ran but the ADK agent stage was skipped or failed. Check that your API key is valid and that ASA_ENABLE_ADK_ADVISORY=true in .env.

​
Next steps

Deploy with Docker

Run SAW in a container for a consistent, portable deployment.

Architecture overview

Learn how the four-agent pipeline processes each log event.

Build docs developers (and LLMs) love

Get started for freeTalk to us