Vigil

Vigil is the open-source AI SOC where your playbooks are plain-text files, your agent logic is readable Python, and your integrations use an open standard (MCP). Every proprietary AI SOC on the market is a black box you rent. Vigil is a capability you own.

The inspiration for the project is in part StackStorm and the experience of some of the founders of this project had in building the Linux Foundation project StackStorm and in supporting Netflix and others who used StackStorm to achieve, carefully, very high levels of automation. You'll sometimes hear us talking about the journey towards full autonomy and lessons learned. One lesson - the system can only demote itself and only humans can promote additional autonomy. You'll find this playing out on the way Vigil is designed; for example Vigil will check thresholds for projected costs and confidence levels in completion before executing an automation. If it looks dodgy or two expensive, it'll double check with the humans before moving ahead.

The project is built on three pillars: Agents — 13 specialized AI agents you can read, fork, and rewire; Workflows — multi-agent playbooks defined as Markdown files you edit directly; and Integrations — 30+ tool connections via MCP that you configure, not a vendor. The most important pillar is YOU — this is your project. Contribute via feedback, code, a repo star, memes on Discord, or otherwise.

12 Specialized AI Agents

Every agent has access to 19 backend tools via Agent SDK and 100+ additional tools via MCP. Agents are the building blocks that Workflows orchestrate.

Workflows — One-Click Multi-Agent Workflows

Workflows are the operational core of Vigil. Each worfklow chains multiple specialized AI agents into an end-to-end playbook that executes with a single command. No manual hand-offs, no copy-pasting between tools — the agents coordinate automatically.

How it works: Say "Run incident response on finding f-20260215-abc123" and the system sequences four agents — triage scores the alert, investigator digs into root cause, responder submits containment actions with confidence-based approval, and reporter generates the final documentation.

Workflows are defined as WORKFLOW.md files in the workflows/ directory and are fully customizable. Create your own by defining the agent sequence, tools used, and phase-by-phase instructions.

workflows/
├── incident-response/WORKFLOW.md
├── full-investigation/WORKFLOW.md
├── threat-hunt/WORKFLOW.md
└── forensic-analysis/WORKFLOW.md

Create Your Own Workflow in 60 Seconds

Every workflow is a Markdown file. Here's what one looks like inside:

---
name: phishing-triage
description: "Triage and investigate phishing reports from user submissions."
agents:
  - triage
  - investigator
  - responder
tools-used:
  - get_finding
  - list_findings
  - nearest_neighbors
  - create_approval_action
use-case: "A user reports a suspicious email and the SOC needs to assess, investigate, and contain."
trigger-examples:
  - "Run phishing triage on finding f-20260401-abc123"
  - "Investigate this phishing report"
---

# Phishing Triage Workflow

## Phase 1: Assess the Report (Triage Agent)
Fetch the finding, extract sender/domain/URLs, score severity, check for known-bad indicators.

## Phase 2: Investigate (Investigator Agent)
Use nearest_neighbors to find similar reports. Correlate with detection rules. Build an evidence timeline.

## Phase 3: Contain (Responder Agent)
If confirmed malicious: block sender domain, quarantine matching emails, submit approval actions with confidence scores.

Edit this file. That's it. No vendor ticket, no professional services, no YAML/JSON schema to learn.

Scaffold a new workflow instantly with the CLI:

python scripts/create_workflow.py phishing-triage
# creates workflows/phishing-triage/WORKFLOW.md with a commented template

Integrations -

Vigil uses the Model Context Protocol to connect agents to your existing tools. These MCP servers give every agent real-time access to your SIEM, EDR, threat intel, sandbox, ticketing, and communication platforms — all through a unified interface.

Coming soon: AWS Security Hub, Azure Sentinel, GCP Security, Okta, Microsoft Defender, SentinelOne, Carbon Black, PagerDuty.

MCP servers live in mcp-servers/ and are configured via the Settings UI or mcp_config.json. Add a new integration by dropping an MCP server into the tools/ directory — or use the built-in Custom Integration Builder to generate one from API docs. If you build an integration that you find useful, chances are someone else will as well. Please contribute!

Quick Start

git clone --recurse-submodules https://github.com/Vigil-SOC/vigil.git
cd vigil
./start.sh

Note: Docker must be running before you start. The startup script handles everything else: creates the Python virtual environment, installs dependencies, starts PostgreSQL, initializes the database with a default admin user, installs frontend packages, and launches both backend and frontend servers.

Auth bypass is enabled by default (DEV_MODE=true) for quick development. Full auth is WIP and while it will turn on it is untested. To activate auth set DEV_MODE=false.

Stable build vs. development build: The Quick Start above clones main — the active development branch (latest, unreleased code). For a stable, tested build, use a released version instead: pull a published image (docker pull ghcr.io/vigil-soc/vigil-backend:<version>) or check out a release tag before running (git checkout v<version>). Find the newest version on the releases page.

Prerequisites

• Python 3.10+
• Node.js 18+ (for frontend)
• Docker Desktop (must be running — used for PostgreSQL)
• Git (with submodule support)
• An LLM provider key. Vigil supports Anthropic Claude (default), OpenAI, and Ollama (local) — configure providers in Settings → AI Config. See docker/bifrost/README.md for the multi-provider gateway. (optional for initial testing)

Default Login Credentials

Change these in production!

Manual Install

# Clone with submodules
git clone --recurse-submodules https://github.com/Vigil-SOC/vigil.git
cd vigil

# If you already cloned without --recurse-submodules:
git submodule update --init --recursive

# Environment (DEV_MODE enabled by default)
cp env.example .env
# LLM provider keys (Anthropic / OpenAI / Ollama) are configured in the
# web UI at Settings → AI / LLM Providers — not in .env.

# Backend setup
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Frontend setup
cd frontend
npm install
cd ..

Install on Kubernetes

A production-style Helm chart lives at helm/vigil/:

helm install vigil ./helm/vigil \
  --namespace vigil --create-namespace \
  --set secrets.anthropicApiKey="$ANTHROPIC_API_KEY" \
  --set secrets.postgresPassword="$(openssl rand -hex 24)" \
  --set secrets.jwtSecretKey="$(python -c 'import secrets; print(secrets.token_urlsafe(64))')"

See docs/HELM.md for the full values reference, external Postgres/Redis setup, ingress configuration, and troubleshooting.

Run

Option A: All-in-one (recommended)

# Interactive mode (keeps terminal attached, Ctrl+C to stop)
./start.sh

# OR background mode (frees terminal)
./start.sh --daemon

Option B: Manual (separate terminals)

# Terminal 1: Start database (Docker must be running)
cd docker && docker-compose up -d postgres

# Terminal 2: Initialize admin user and generate demo data
source venv/bin/activate
python scripts/init_default_user.py
python scripts/demo.py

# Terminal 3: Start backend
source venv/bin/activate
export PYTHONPATH="${PWD}:${PYTHONPATH}"
uvicorn backend.main:app --host 127.0.0.1 --port 6987 --reload

# Terminal 4: Start frontend
cd frontend && npm run dev

Shutdown

./shutdown_all.sh              # Stop native processes only (Docker keeps running)
./shutdown_all.sh -d           # Stop native processes + Docker containers
./shutdown_all.sh -d --full    # Stop + remove containers and volumes

Access

• Frontend: http://localhost:6988
• API: http://localhost:6987
• API Docs: http://localhost:6987/docs

Run with Docker (Full Stack)

cd docker && docker-compose up -d

Starts PostgreSQL, Backend API, and SOC Daemon.

Run SOC Daemon (Headless Mode)

For autonomous 24/7 monitoring without the UI:

source venv/bin/activate
python daemon/main.py

Desktop App (Standalone)

The desktop app packages the full stack into an installable bundle — no source tree required. It runs the backend as a Docker container loaded from an offline image tarball, alongside a bundled Bifrost LLM gateway, so Docker Desktop must be installed and running. Local LLMs (Ollama) work out of the box: Bifrost is configured to route any pulled/built model and to reach Ollama on the host via host.docker.internal.

Build a local DMG (Apple Silicon shown; the image tarball is arch-specific):

# 1. Build the backend image from source and stage it as an offline tarball
bash desktop/scripts/bundle-image.sh linux/arm64

# 2. Package the app (copies the Bifrost config, bundles the tarball)
cd desktop && npm run dist
# -> desktop/release/Vigil-<version>-arm64.dmg

macOS Gatekeeper (unsigned build). Locally built DMGs are ad-hoc signed, not notarized, so macOS quarantines the app and shows "Vigil is damaged and can't be opened" or "can't be opened because Apple cannot check it". Clear the quarantine attribute after installing to /Applications:

xattr -dr com.apple.quarantine /Applications/Vigil.app

Alternatively, open it once via System Settings → Privacy & Security → Open Anyway. Proper signing/notarization is pending.

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                       Workflows Layer                             │
│  Incident Response │ Full Investigation │ Threat Hunt │ Forensics │
│              (Multi-agent workflow orchestration)                  │
└──────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│                   13 Specialized AI Agents                        │
│  Triage │ Investigator │ Hunter │ Correlator │ Responder │ ...   │
└──────────────────────────────────────────────────────────────────┘
                │                              │
     Agent SDK (23 tools)              MCP (100+ tools)
                │                              │
                ▼                              ▼
┌──────────────────────────┐  ┌────────────────────────────────────┐
│     Backend Services     │  │          MCP Servers (30+)         │
│  Detections (7,200+)     │  │  Splunk │ CrowdStrike │ VirusTotal │
│  Case Management         │  │  Shodan │ Jira │ Slack │ Cribl    │
│  Approvals │ MITRE ATT&CK│  │  Timesketch │ MISP │ ANY.RUN      │
│  Similarity Search       │  │  Hybrid Analysis │ Joe Sandbox    │
└──────────────────────────┘  └────────────────────────────────────┘
                │
                ▼
┌──────────────────────────────────────────────────────────────────┐
│                  Data Sources + PostgreSQL                         │
│  Logs │ Alerts │ Findings │ Embeddings │ Cases │ Detection Rules  │
└──────────────────────────────────────────────────────────────────┘

Additional Features

• Auto-Contributor — Automated competitive research against proprietary AI security platforms. Analyzes a vendor's capabilities, maps gaps versus Vigil and the open-source ecosystem, and generates ready-to-file GitHub issues with acceptance criteria. The goal: make Vigil a superset of every proprietary AI SOC, one contribution at a time. See contrib/auto-contributor/
• Chat-Driven Case Management — Build cases through natural language. Say "add this to case XYZ" and the system handles findings, activities, timelines, and MITRE tagging. Learn more
• Detection Engineering — 7,200+ detection rules (Sigma, Splunk, Elastic, KQL) with coverage analysis, gap identification, and AI-assisted template generation. Learn more
• Case Management — Full lifecycle tracking with PDF reports
• Approval Workflow — Human-in-the-loop with confidence-based automation (auto-approve above 0.90, require review below 0.85)
• AI Enrichment — Automatic threat analysis cached per finding
• MITRE ATT&CK — Technique mapping and Navigator layer visualization

Project Structure

vigil/
├── workflows/         # WORKFLOW.md definitions (4 built-in)
├── contrib/           # Community tools: auto-contributor, benchmarking
├── mcp-servers/       # MCP server implementations (30+)
├── backend/           # FastAPI backend API + Agent SDK tools
├── frontend/          # React + MUI frontend
├── services/          # Business logic (workflows service, etc.)
├── daemon/            # Headless autonomous SOC service
├── tools/             # Additional tool implementations
├── database/          # PostgreSQL models and migrations
├── core/              # Config, rate limiting, exceptions
├── docker/            # Docker Compose setup
├── docs/              # Documentation
└── data/schemas/      # JSON validation schemas

Example Usage

Run a Workflow

You: "Run incident response on finding f-20260215-abc123"
Claude: [triage] Severity: Critical — confirmed C2 beaconing from HOST-42
        [investigate] Root cause: phishing email → macro execution → Cobalt Strike beacon
        [respond] Submitted host isolation (confidence 0.96 — auto-approved)
        [report] Incident report generated with MITRE ATT&CK layer

Proactive Threat Hunt

You: "Hunt for C2 beaconing activity across all network findings"
Claude: [hunt] Hypothesis: periodic outbound connections to rare destinations
        [network] Found 3 hosts beaconing to 185.220.101.0/24 every 300s
        [malware] Cobalt Strike beacon — extracted 4 IOCs
        [intel] IP attributed to APT28 infrastructure (confidence 0.72)
        [report] Hunt report with 12 IOCs and 3 new detection recommendations

Chat-Driven Case Building

You: "Add this to case-20260121-abc123 and note it's part of the kill chain"
Claude: ✓ Added finding to case
        ✓ Logged activity: Part of lateral movement kill chain
        ✓ Tagged with T1021.001 (RDP)

You: "Find similar findings and add them all to this case"
Claude: ✓ Found 3 similar findings via embedding search
        ✓ Added f-002, f-003, f-004 to case
        ✓ Updated timeline with lateral movement progression

Documentation

Testing with Splunk & Claude

# Generate 280 realistic security events
python3 scripts/generate_splunk_test_data.py

# Send directly to Splunk
python3 scripts/generate_splunk_test_data.py \
    --send-to-splunk \
    --hec-url https://your-splunk:8088/services/collector \
    --hec-token your-hec-token \
    --no-verify-ssl

# Test full integration (generate → create case → enrich with Claude)
python3 scripts/test_splunk_claude_integration.py \
    --generate-data \
    --create-case

Export PostgreSQL Data to Splunk

# Export everything to Splunk
python scripts/export_postgres_to_splunk.py \
    --hec-url https://your-splunk:8088/services/collector \
    --hec-token your-hec-token \
    --index deeptempo \
    --no-verify-ssl

# Save to file for review first
python scripts/export_postgres_to_splunk.py \
    --save-to-file postgres_export.json

Contributing

Contributions are welcome! Whether you're fixing bugs, adding new MCP integrations, improving agent prompts, or building new workflows or agents — we'd love your help and leadership.

Find meaningful work automatically: Vigil includes an auto-contributor tool that researches proprietary AI security platforms, identifies capability gaps, and generates ready-to-file GitHub issues. Pick a vendor, run the tool, and you'll have a scoped contribution spec in minutes.

Join the community: Connect with the Vigil community on Discord to discuss ideas, get help, and collaborate with other contributors.

To contribute:

1. Fork the repo and create a feature branch
2. Make your changes and test them
3. Submit a pull request with a clear description

See the Quick Start to get your local environment running, and CONTRIBUTING.md for the full guide.

License

Apache 2.0 — See LICENSE

References

• Vigil — Project homepage
• DeepTempo — Vigil sponsor; LogLM connects via MCP as an AI-native detection layer
• Model Context Protocol — MCP specification
• ATT&CK Navigator — MITRE visualization