SentinelAI — Autonomous SOC Analyst

SentinelAI is an autonomous cybersecurity analyst agent that runs a detect → investigate → decide → act → report loop over Elasticsearch security logs. It is built on Google's Agent Development Kit (ADK) with Gemini 2.5 Flash, connects to an Elasticsearch MCP server for its tools, and ships with a real‑time React dashboard featuring human‑in‑the‑loop approval for high‑impact actions (blocking an IP).

┌────────────┐     /chat (NDJSON stream)     ┌──────────────────────────┐
│  React UI  │  ───────────────────────────▶ │  FastAPI + ADK (backend) │
│ (frontend) │  ◀─────────────────────────── │      Gemini 2.5 Flash    │
└────────────┘     /confirm (approve block)   └────────────┬─────────────┘
                                                            │ MCP (HTTP)
                                                            ▼
                                              ┌──────────────────────────┐
                                              │  Elasticsearch MCP server │
                                              │ search_logs, get_threat_  │
                                              │ intel, block_ip,          │
                                              │ create_incident_report,   │
                                              │ health_check              │
                                              └──────────────────────────┘

Project structure

.
├── backend/          # Python FastAPI + ADK agent (deploy to Cloud Run)
│   ├── agent.py          # SentinelAI ADK agent + MCP toolset
│   ├── main.py           # FastAPI app: /chat (stream) + /confirm (HITL)
│   ├── requirements.txt
│   ├── Dockerfile
│   └── .env.example
├── frontend/         # React + TypeScript + Vite dashboard
│   ├── components/
│   ├── context/
│   ├── services/api.ts   # streamChat() + resumeToolCall() (HITL)
│   ├── Dockerfile        # nginx static build
│   └── .env.example
├── proxy/            # OPTIONAL legacy Vertex AI Node.js proxy (not required)
├── docs/             # COMPLIANCE_REPORT.md, DEPLOYMENT_GUIDE.md
├── docker-compose.yml
├── LICENSE
└── README.md

Note: proxy/ is the original Vertex AI Studio Node.js proxy that shipped with the scaffold. SentinelAI does not depend on it. Keep it only if you still need the Vertex shim; otherwise it can be deleted.

The 5 agent tools (via Elasticsearch MCP)

Tool	Purpose
search_logs	Query security logs (always called first).
get_threat_intel	Look up external threat intel for an IP.
block_ip	Block a malicious IP — gated by human approval unless Auto‑Act is on.
create_incident_report	Persist an incident — always called as the final step.
health_check	System status check.

Local development

1. Backend (FastAPI + ADK)

cd backend
python -m venv .venv
# Windows: .venv\Scripts\activate   |   macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env          # then set GOOGLE_API_KEY
uvicorn main:app --reload --host 0.0.0.0 --port 8000

You need a Gemini API key in backend/.env:

GOOGLE_API_KEY=your_gemini_api_key_here
MCP_SERVER_URL=https://elastic-mcp-532167373013.us-central1.run.app

2. Frontend (React + Vite)

cd frontend
npm install
cp .env.example .env          # VITE_API_BASE_URL=http://localhost:8000
npm run dev                   # http://localhost:3000

Open Settings in the UI and turn Demo Mode (Mock API) OFF to talk to the real backend. Toggle Auto‑Act to let the agent block without approval.

3. Run both with Docker Compose

cp backend/.env.example backend/.env   # set GOOGLE_API_KEY
docker compose up --build
# frontend: http://localhost:3000   backend: http://localhost:8000

Deployment

Backend → Cloud Run

cd backend
gcloud run deploy sentinelai-backend \
  --source . \
  --region us-central1 \
  --port 8080 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_API_KEY=YOUR_KEY,MCP_SERVER_URL=https://elastic-mcp-532167373013.us-central1.run.app"

Cloud Run injects $PORT (8080); the container's CMD honours it.

Frontend → static hosting

cd frontend
# point the build at the deployed backend
echo "VITE_API_BASE_URL=https://sentinelai-backend-XXXX.run.app" > .env
npm run build            # outputs dist/

Deploy dist/ to Firebase Hosting, Vercel, Netlify, or Cloud Storage + CDN. You can also deploy the included nginx Dockerfile to Cloud Run.

Human‑in‑the‑loop flow

1. UI sends the operator prompt to POST /chat; the backend streams NDJSON events (tool_start, tool_end, pause, verdict, …).
2. When the agent calls block_ip and Auto‑Act is off, the backend emits a pause event and suspends tool execution (ADK before_tool_callback).
3. The operator approves/denies in the modal; the UI calls POST /confirm, which resolves the pending action and lets ADK either run or skip the block.
4. The agent always finishes by calling create_incident_report and returns a strict‑JSON verdict.

License

MIT