AI-powered defensive cybersecurity agent for Incident Response and Proactive Threat Hunting.
BTagent combines a LangGraph multi-agent orchestrator, 9 MCP connectors for SIEM/EDR/CTI platforms, and a React analyst dashboard into a single platform that automates alert triage, IOC enrichment, SIEM query generation, SOAR playbook execution, and incident reporting -- with full human-in-the-loop controls at every stage.
| Category | Feature | Description |
|---|---|---|
| Core | PunchList Dashboard | Single-pane analyst workspace with live investigation status |
| Core | AI-Powered Triage | Automated alert classification, severity scoring, MITRE ATT&CK mapping |
| Core | Query Generator | Natural language to SIEM/EDR queries (Splunk SPL, Elastic KQL, Sentinel KQL, CrowdStrike) |
| Core | Human-in-the-Loop | Autonomy levels L0--L4 with approval workflows for containment actions |
| Intelligence | IOC Enrichment | 5-stage pipeline with multi-source confidence scoring and deduplication |
| Intelligence | Knowledge Base (RAG) | Hybrid search with pgvector, auto-indexing of investigation findings |
| Automation | SOAR Playbooks | Visual builder, YAML-defined playbooks compiled to LangGraph subgraphs |
| Reporting | Document Assistance | 4 report templates, audience-aware remediation, detection content generation |
Security controls: TLP-aware LLM routing, SHA-256 chained audit trail, scope enforcement, prompt injection defenses, JWT + RBAC (4 roles).
Analyst Browser External Systems
+-----------+ +-----------+
| React SPA | <--- WebSocket (events) --- | SIEM/EDR |
| Zustand | --- REST (CRUD, auth) ----> | Webhooks |
+-----------+ +-----------+
| |
v v
+-----------------------------------------------------+
| FastAPI Backend |
| /api/v1/* /ws /webhooks/* /health /metrics |
| Auth(JWT) RBAC Rate Limiter RequestID |
+-----------------------------------------------------+
| | |
v v v
+----------+ +-----------+ +-----------+
| Postgres | | Redis | | MinIO |
| pgvector | | pub/sub | | evidence |
+----------+ +-----------+ +-----------+
^
|
+-----------------------------------------------------+
| LangGraph Agent Engine |
| Orchestrator -> Worker Subgraphs |
| Triage | Query | Enrich | Knowledge | Playbook |
| 7 Hooks | 7 Plugins | 4-layer context cascade |
+-----------------------------------------------------+
| |
v v
+-----------+ +-------------+
| LiteLLM | | MCP Servers |
| 6 providers| | Splunk | CrowdStrike
| TLP-aware | | Sentinel | Elastic
| routing | | VirusTotal | Shodan
+-----------+ | GreyNoise | AbuseIPDB
| MISP |
+-------------+
git clone https://github.com/nickatnight96/BTagent.git
cd BTagent
./infra/scripts/dev-setup.sh # prereq check + docker infra + venv + migrations + seedThen in two terminals:
# Terminal A — backend
source .venv/bin/activate
BTAGENT_ENV=test \
BTAGENT_JWT_SECRET="dev-secret-for-local-only" \
BTAGENT_DATABASE_URL="postgresql+asyncpg://btagent:btagent_dev_password@localhost:5432/btagent" \
BTAGENT_REDIS_URL="redis://localhost:6379" \
uvicorn btagent_backend.main:app --reload --port 8000 --app-dir backend
# Terminal B — frontend
cd frontend && npm run devOpen http://localhost:3000 and log in with admin / admin (seeded by dev-setup.sh in test mode).
git clone https://github.com/nickatnight96/BTagent.git
cd BTagent
cp infra/.env.example infra/.env # edit with your API keys
make dev # docker infra
uv venv .venv --python 3.12 && source .venv/bin/activate
uv pip install -e shared/ -e engine/ -e agents/ -e "backend/[dev]"
cd frontend && npm install && cd ..
make db-migrate
BTAGENT_ENV=test python infra/scripts/seed-data.py
# then the two terminal commands from the one-command path aboveBackend: http://localhost:8000 | Frontend: http://localhost:3000 | API docs: http://localhost:8000/api/docs
Note: See docs/GETTING_STARTED.md for the full step-by-step guide with environment variable walkthrough.
| Dashboard | Investigation | Playbook Builder |
|---|---|---|
 |
 |
 |
| Layer | Technology |
|---|---|
| Frontend | React 18, TypeScript, Vite, Zustand, TailwindCSS, React Flow |
| Backend | FastAPI, Python 3.12, SQLAlchemy (async), Alembic, Pydantic v2 |
| Agent Engine | LangGraph, LangChain, LiteLLM (6 LLM providers) |
| Tool Protocol | Model Context Protocol (MCP) -- 9 connectors |
| Database | PostgreSQL 16 + pgvector |
| Cache/Pubsub | Redis 7 |
| Object Storage | MinIO (S3-compatible) |
| Local LLM | Ollama |
| Observability | OpenTelemetry, Prometheus, Grafana, LangFuse |
| Infrastructure | Docker Compose, Helm (Kubernetes), Terraform (AWS) |
| CI/CD | GitHub Actions |
| Document | Description |
|---|---|
| Getting Started | Full setup guide with environment walkthrough |
| Architecture | System design, data flows, agent topology |
| API Reference | REST, WebSocket, and webhook endpoint reference |
| Deployment | Docker Compose, Kubernetes, and AWS deployment |
| Deployment Plan | Production deploy blockers, readiness, and roadmap sequencing |
| Air-Gapped Deployment | Offline install: bundle-and-transfer, digest pinning, local models, offline ATT&CK refresh |
| Controls Mapping | Implemented controls cross-referenced to NIST 800-53 / ISO/IEC 42001, with code citations |
| SIEM Setup | Splunk, CrowdStrike, Sentinel, and Elastic connector guides |
| Playbook Schema | SOAR playbook YAML reference |
| Knowledge Base | RAG pipeline architecture and configuration |
| Troubleshooting | Common issues and solutions |
| Security Audit | Phase 1 security findings and remediations |
| Security Audit (Phase 2) | Phase 2 security findings |
| Contributing | Development setup, plugin guide, PR process |
| Changelog | Version history |
We welcome contributions. Please read CONTRIBUTING.md for:
- Development environment setup
- How to add new plugins, MCP connectors, and hooks
- Code style guidelines (ruff, ESLint, mypy strict)
- PR process and CI pipeline
If you discover a security vulnerability, please report it responsibly. See SECURITY.md for our disclosure policy.
For the latest audit results, see:
- Phase 1 Security Audit -- 21 findings, 8 critical/high fixed
- Phase 2 Security Audit -- 18 findings, 4 critical fixed
MIT License. See LICENSE for details.