AADA — Autonomous Defense Agent

AADA is an AI-powered SOC agent. It takes in raw security logs, figures out what's an attack, reasons about it with an LLM that's grounded in a cybersecurity knowledge base, scores the risk, and either recommends or (within policy) executes a remediation — always with a human in the loop and everything logged.

Overview

The idea is to model what a SOC analyst actually does, as a pipeline of small services that each do one job:

ingest → detect → analyze (LLM + RAG) → enrich (threat intel) → decide → respond → report
  │         │            │                      │                  │         │         │
 logs    6 rules     SOC analyst          VT/AbuseIPDB/NVD    fuse risk   approval   PDF/JSON
 (5 fmt) +MITRE     (structured output)   (cache+ratelimit)  +confidence  +rollback  +timeline
                                                                          +guardrails
                            ▲ every step writes an immutable audit log ▲

It runs fully offline out of the box — no API keys needed, since deterministic local providers stand in for the LLM, embeddings, and threat-intel feeds. Add real keys and it switches to live providers, no code changes required.

This is an educational/research project. The remediation backends are safe in-memory simulations. Don't wire in a real firewall or account system without keeping the approval workflow in front of it.

Features

• Multi-format log ingestion (JSON, CSV, SSH, auth, web) normalized to one event schema
• Detection engine with 6 rules (SSH brute force, port scan, credential stuffing, impossible travel, privilege escalation, malware/IOC), risk scoring, and MITRE ATT&CK mapping
• RAG knowledge base (MITRE, OWASP, Sigma, NIST, IR playbooks) backed by ChromaDB, with OpenAI or offline embeddings
• SOC analyst that produces structured LLM output — summary, technical detail, MITRE tags, risk score, recommended actions — grounded in retrieved context
• Decision engine that fuses detection + LLM + threat intel + RAG into one risk/confidence score, with Monitor / Assisted / Autonomous modes
• Response engine with 5 remediation actions (alert, block IP, disable account, ticket, increase logging), an approval workflow, rollback, and guardrails that refuse to block internal IPs or disable protected accounts
• Threat intel integrations (VirusTotal, AbuseIPDB, NVD) with caching, rate limiting, retry/backoff, and graceful degradation when a provider is down
• JWT auth with three roles (viewer / analyst / admin) and a permission map
• An immutable audit log covering every user, model, and remediation action
• A React dashboard (Dashboard, Alerts, Investigations, Reports, Settings)

Architecture

The backend keeps the core logic pure — rules, signal fusion, decision policy, and report building are all plain functions over plain inputs — with I/O and provider swapping (live vs. offline) pushed to the edges. See docs/ARCHITECTURE.md for diagrams.

Installation

Prerequisites

• Docker + Docker Compose (recommended), or
• Python 3.11 + Poetry and Node.js 18+ for running things locally

Run with Docker

cp .env.example .env          # then edit .env — see Configuration below
docker compose up -d --build
docker compose ps             # services should report healthy

Log in with the DEFAULT_ADMIN_EMAIL / DEFAULT_ADMIN_PASSWORD you set in .env.

Stop with docker compose down (add -v if you also want to drop the database volume).

Configuration

Everything's set via environment variables. Copy .env.example to .env and fill in the required ones — the rest have reasonable defaults.

.env is git-ignored and should never be committed — only .env.example (placeholders) is tracked.

Usage

Once the stack is up, run the included demo to see the whole attack → detection → defense loop:

./demo_attack.sh

It stages a live SSH brute-force attack and walks through every stage: ingest, detect, AI analysis, decision, approval, block, rollback, audit. Point it at an internal IP to see the safety guardrail kick in and refuse the action:

ATTACKER_IP=10.0.0.9 ./demo_attack.sh

You can also drive things from the dashboard (http://localhost:8080) or Swagger (http://localhost:8000/docs). DEMO.md has a full walkthrough and docs/API.md has the endpoint reference.

Local development

# Backend
cd aada-backend && poetry install
uvicorn app.main:app --reload                    # http://localhost:8000/docs
pytest tests/ -q --ignore=tests/test_auth.py     # 188 offline tests

# Frontend
cd aada-frontend && npm install && npm run dev   # http://localhost:5173

Screenshots

Coming soon.

Project structure

.
├── docker-compose.yml          full-stack orchestration (db, chroma, backend, frontend)
├── demo_attack.sh              end-to-end attack → defense demo
├── docs/                       architecture + API reference
├── aada-backend/               FastAPI service
│   ├── app/
│   │   ├── api/v1/endpoints/    REST endpoints (auth, events, detection, …)
│   │   ├── services/            detection · rag · ai_analyst · decision · response · reporting
│   │   ├── integrations/        VirusTotal / AbuseIPDB / NVD clients
│   │   ├── mcp_server/          MCP tool server (6 security tools)
│   │   ├── models/               SQLAlchemy models (source of truth for the schema)
│   │   └── core/, db/, schemas/
│   └── tests/                   unit · API · attack-simulation suites
└── aada-frontend/               React + TypeScript + Tailwind dashboard

Tech stack

Contributing

PRs welcome — see CONTRIBUTING.md for setup, conventions, and
what to know before opening one.

License

MIT — see LICENSE.

Further reading

• DEMO.md — run, use, and demo the attack → defense loop
• docs/ARCHITECTURE.md — system design + diagrams
• docs/API.md — REST API reference (42 endpoints)
• aada-backend/TESTING.md — testing strategy
• DEPLOYMENT.md — deployment & operations