vigil

Vigil SOC

Vigil is an open source, agentic AI SOC released under Apache 2.0. Your playbooks are plain-text Markdown files, your agent logic is readable code, and your integrations use an open standard (MCP). It is a capability you own, not a black box you rent.

Vigil runs on its own: a local clone, Docker, and any supported LLM provider (a local Ollama model works). LogLM, DeepTempo's cybersecurity foundation model for behavioral anomaly detection, is an optional MCP integration you enable in Settings, not a prerequisite. Docs and community: vigilsoc.org.

Vigil 1.0 is coming. We believe it will be the first AI SOC built for a human on the loop rather than in it. Join the upcoming office hours for a preview.

The project draws on the founders' experience building StackStorm and supporting teams, including Netflix, that used it to reach high levels of automation carefully. One lesson carries through: the system can only demote its own autonomy, and only humans can promote it. Vigil checks projected cost and confidence before acting, and asks a human when either looks off.

Vigil rests on three parts — agents you can read, fork, and rewire; workflows defined as Markdown files you edit directly; and integrations connected over MCP — plus the most important one: you. Contribute feedback, code, a star, or memes on Discord.

Agents

Vigil ships a set of built-in specialist agents covering the core SOC roles — triage, investigation, threat hunting, correlation, response, reporting, ATT&CK mapping, forensics, threat intel, compliance, malware and network analysis — and you can add your own from the console. The set grows and changes with the project; the built-in definitions live in core/agents/builtins.py and are described at vigilsoc.org/docs/agents.

Every agent can call Vigil's backend tools (findings, cases, approvals, detections, ATT&CK, threat intel, memory, skills) and the tools of whichever MCP integrations you have connected. Each agent's tool list, prompt, model, and extended-thinking budget are visible in its definition.

Response actions are proposed as approval requests. A request from the Response agent always waits for an analyst. The daemon's auto-responder routes by confidence: by default, at or above 0.90 is auto-approved, 0.85–0.90 gets a quick review, 0.70–0.85 needs analyst review, and below 0.70 escalates (configurable). The approval pipeline records isolate_host actions but does not execute them; host isolation or quarantine happens only when an agent calls an EDR integration's tool directly.

Workflows

A workflow is a WORKFLOW.md file: YAML frontmatter that says what runs, and a Markdown body that explains it. Built-in workflows live under core/workflows/definitions/; edit them there, build your own from the Workflows screen, or disable the ones you don't use.

A workflow's run_kind decides how it executes:

Start one from chat, for example "Run incident response on finding f-20260215-abc123", or from the Workflows screen.

Create your own workflow

---
name: phishing-triage
description: "Triage and investigate phishing reports from user submissions."
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"
objectives:
  - "Decide whether the reported mail is malicious"
  - "Contain it without waiting on a second report"
phases:
  - id: assess
    agent: triage
    name: "Assess the Report"
    tools: [get_finding, list_findings]
    instructions: |
      Fetch the finding, extract sender/domain/URLs, score severity, check for
      known-bad indicators. Hand on the verdict and the indicators you found.

  - id: investigate
    agent: investigator
    name: "Investigate"
    tools: [get_finding, search_detections]
    instructions: |
      Correlate with detection rules. Build an evidence timeline. Hand on the
      timeline and related findings.

  - id: contain
    agent: responder
    name: "Contain"
    tools: [get_case, update_case]
    approval_required: true
    instructions: |
      If confirmed malicious: block the sender domain, quarantine matching emails,
      and plan remediation with confidence scores.
---

# Phishing Triage Workflow

An overview for whoever reads this file. The `phases` above are what actually
runs, in the order written.

approval_required: true holds a phase for a human before it acts. Scaffold a new file with:

python scripts/create_workflow.py phishing-triage --agents triage,investigator,responder
# creates core/workflows/definitions/phishing-triage/WORKFLOW.md

Integrations

Vigil connects agents to your existing tools through MCP. Integrations span SIEM and log search, EDR/XDR, cloud security (AWS, Azure, GCP), identity, threat intel, sandboxes, detection engineering, ticketing, chat and paging, network security, and data pipelines. The catalogue changes as vendors ship official MCP servers and contributors add new ones; mcp-config.json is the current list, and vigilsoc.org/docs/integrations describes each one.

An integration is one of two things:

• An upstream MCP server: a vendor's or community's own server, pinned to a version in mcp-config.json (npx, uvx, Docker, or a remote endpoint).
• A vendor slice: a server Vigil maintains at core/integrations/<vendor>/tool.py, used where no suitable upstream server exists. See vendor slices.

What an integration can do depends on its server: some are read-only lookups, others can act (for example, Microsoft Defender isolation or Carbon Black quarantine). The integrations docs list each one's tools.

Some integrations are marked Experimental in Settings. These are CrowdStrike Falcon, SentinelOne, Microsoft Sentinel, the official Splunk MCP server, Google SecOps, Google Threat Intelligence, Joe Sandbox, vStrike, Atomic Red Team and CAPE Sandbox. The project has no free instance of these to test against (Atomic Red Team runs an operator's own runner; CAPE needs a KVM host), so they have never been run against a live one. They may not work. If you run one, please open an issue saying whether it worked, with your Vigil version.

Enable and configure integrations under Settings → Integrations, or generate one from API docs with the Custom Integration Builder. If you build an integration you find useful, someone else will too. Please contribute it.

Vigil's own MCP server. Vigil serves its SOC operations (findings, cases, approvals, hunts) at /mcp, the same tools its agents use. The finding, case, and approval tools that mirror frozen /api/v1 operations are frozen: their names and input schemas are pinned in tools/mcp/frozen_tools.snapshot.json. The rest are served under the 0.x terms in SECURITY.md.

Detection rules. The detection-engineering integration (security-detections-mcp) indexes community rule sets (Sigma, Splunk ESCU, Elastic, KQL) for search, coverage analysis, and gap identification. Vigil does not ship the rules; fetch them with ./scripts/setup_detection_repos.sh (or SETUP_DETECTION_REPOS=1 ./setup_dev.sh).

Quick Start

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

Then open http://localhost:6988 and create the admin account on the bootstrap screen. While no account exists, the API prints a setup code in this terminal; enter it there.

Sign-in cookies are Secure by default (VIGIL_COOKIE_SECURE=true), so the console needs HTTPS: Chromium accepts them on http://localhost, but reached by IP or hostname over plain HTTP (or in Safari, even on localhost) sign-in fails. Set VIGIL_COOKIE_SECURE=false only for loopback or SSH-tunnel access (see env.example).

start.sh provisions the pinned Python with uv, installs dependencies, starts PostgreSQL, Redis, and the Bifrost LLM gateway in Docker, starts a host Ollama if one is installed (optional), initializes the schema and reference data, and launches the API, the agent layer, and the frontend. No LogLM or cloud API key is needed to reach a running UI.

• AGENT_INTERNAL_TOKEN lets the agent layer talk to the API. start.sh (and setup_dev.sh) creates .env from env.example and fills an empty token with a random one; a value already set is kept. Without it the agent layer does not start: workflow runs stay queued and chat answers 503.
• The SOC daemon (alert polling, auto-triage) runs only with ./start.sh -d; the foreground start says so. Setup's system checks show whether the daemon and the agent layer are running.
• Authentication is on by default. No account or default password ships; the first visit creates the admin, using the setup code the API prints at startup while no account exists. start.sh creates the JWT signing secret at ~/.vigil/jwt_secret. For an unauthenticated instance on your own machine, set DEV_MODE=true in .env; the backend announces the bypass on every startup.

Stable vs. development build: main is the active development branch. For a tested build, check out a release tag (git checkout v<version>) or pull a published image (docker pull ghcr.io/vigil-soc/vigil-backend:<version>). Releases are listed on the releases page.

Released images are signed keyless by .github/workflows/release.yml. To verify (the image tag drops the leading v; the certificate identity uses the git tag):

cosign verify \
  --certificate-identity https://github.com/Vigil-SOC/vigil/.github/workflows/release.yml@refs/tags/v<version> \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/vigil-soc/vigil-backend:<version>

Prerequisites

• Docker (running): PostgreSQL, Redis, and Bifrost run in containers.
• Node.js 20+: runs the agent layer and the frontend. Without Node, neither starts and workflows cannot run.
• Git.
• No system Python needed: start.sh provisions the version pinned in .python-version with uv, independent of any Python you already have.
• An LLM provider (optional to reach the UI): Anthropic (default), OpenAI, Google Vertex, or Ollama (local, no key). Configure it under Settings → AI models → Providers & Keys; see the Bifrost notes. With no provider key, scripts/local_model.sh serves a small local model Bifrost can reach and prints the model id to use.

Windows (WSL2)