Skip to content
Back to search

vigil

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 17 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Vigil-SOC/vigil with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Vigil-SOC/vigil'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vigil-soc--vigil/badge.svg)](/listings/vigil-soc--vigil)

HTML

<a href="/listings/vigil-soc--vigil"><img src="/api/listings/vigil-soc--vigil/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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`).

Security keys (WebAuthn) are tied to the hostname the console is reached at: set `VIGIL_CONSOLE_HOSTNAME` (no scheme or port) and keep `VIGIL_COOKIE_SECURE=true`, or use `localhost`; otherwise keys stay off and sign-in by password and authenticator app is unchanged ([security keys](docs/security-keys.md)).

`start.sh` provisions the pinned Python with [uv](https://docs.astral.sh/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](https://github.com/Vigil-SOC/vigil/releases/latest). > > Released images are signed keyless by [`.github/workflows/release.yml`](.github/workflows/release.yml). To verify (the image tag drops the leading `v`; the certificate identity uses the git tag): > > ```bash > 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](https://vigilsoc.org/docs/bifrost/). 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)

> **Not yet tested inside WSL2 on a Windows machine.** `start.sh` runs end to end on Ubuntu 24.04, the distro `wsl --install` sets up, with its WSL2 branches switched on; Docker Desktop's integration and the Windows side are unverified. Please report what breaks.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines
  1. {
  2. "name": "vigil",
  3. "owner": {
  4. "name": "Vigil-SOC",
  5. "url": "https://github.com/Vigil-SOC"
  6. },
  7. "metadata": {
  8. "description": "The Claude Code client for Vigil, the open SOC platform."
  9. },
  10. "plugins": [
  11. {
  12. "name": "vigil-soc",
  13. "source": "./clients/claude-code",
  14. "description": "Work your team's Vigil from Claude Code: investigations and hunts that run in your own SOC, shared with colleagues.",
  15. "license": "Apache-2.0",
  16. "homepage": "https://vigilsoc.org"
  17. }
  18. ]
  19. }
README.md · README · 390 lines
  1. # Vigil SOC
  2. 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](https://modelcontextprotocol.io/)). It is a capability you own, not a black box you rent.
  3. Vigil runs on its own: a local clone, Docker, and any supported LLM provider (a local Ollama model works). [LogLM](https://www.deeptempo.ai/platform), DeepTempo's cybersecurity foundation model for [behavioral anomaly detection](https://www.deeptempo.ai/learning-center/behavioral-anomaly-detection), is an optional MCP integration you enable in Settings, not a prerequisite. Docs and community: [vigilsoc.org](https://vigilsoc.org).
  4. **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.
  5. The project draws on the founders' experience building [StackStorm](https://github.com/StackStorm/st2) 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.
  6. 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.
  7. ---
  8. ## Agents
  9. 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-ins are manifests in [`core/agents/manifests/`](core/agents/manifests/) and are described at [vigilsoc.org/docs/agents](https://vigilsoc.org/docs/agents/).
  10. 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 needs and prompt are visible in its manifest; every agent runs on the investigation model assignment.
  11. Response actions are proposed as approval requests. A request from the Response agent always waits for an analyst. The daemon's executor carries out an approved action within about 30 seconds unless Stop holds it, and an AutoOps investigation that proposes containment pages PagerDuty when it is enabled. 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.
  12. ## Workflows
  13. 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/`](core/workflows/definitions/); edit them there, build your own from the Workflows screen, or disable the ones you don't use.
  14. A workflow's `run_kind` decides how it executes:
  15. | `run_kind` | How it runs | Built-in examples |
  16. |---|---|---|
  17. | `compose` (default) | Walks the declared `phases` in order, each phase handled by the named agent with the listed tools | Your custom workflows |
  18. | `investigate` | A single lead agent works the objectives and narrative; no phases | Incident Response, Full Investigation, Forensic Analysis, Cloud Incident |
  19. | `root_cause` | A single agent traces a confirmed compromise backward, step by step | Root Cause Analysis |
  20. | `hunt` / `adjudicate` | A lead runs a hypothesis loop, dispatching worker agents and deciding each next move from the evidence | Threat Hunt, Shadow Adjudication |
  21. Start one from chat, for example `"Run incident response on finding f-20260215-abc123"`, or from the Workflows screen.
  22. ### Create your own workflow
  23. ```markdown
  24. ---
  25. name: phishing-triage
  26. description: "Triage and investigate phishing reports from user submissions."
  27. use_case: "A user reports a suspicious email and the SOC needs to assess, investigate, and contain."
  28. trigger_examples:
  29. - "Run phishing triage on finding f-20260401-abc123"
  30. objectives:
  31. - "Decide whether the reported mail is malicious"
  32. - "Contain it without waiting on a second report"
  33. phases:
  34. - id: assess
  35. agent: triage
  36. name: "Assess the Report"
  37. tools: [get_finding, list_findings]
  38. instructions: |
  39. Fetch the finding, extract sender/domain/URLs, score severity, check for
  40. known-bad indicators. Hand on the verdict and the indicators you found.
  41. - id: investigate
  42. agent: investigator
  43. name: "Investigate"
  44. tools: [get_finding, search_detections]
  45. instructions: |
  46. Correlate with detection rules. Build an evidence timeline. Hand on the
  47. timeline and related findings.
  48. - id: contain
  49. agent: responder
  50. name: "Contain"
  51. tools: [shell, update_case]
  52. approval_required: true
  53. instructions: |
  54. If confirmed malicious: block the sender domain, quarantine matching emails,
  55. and plan remediation with confidence scores.
  56. ---
  57. # Phishing Triage Workflow
  58. An overview for whoever reads this file. The `phases` above are what actually
  59. runs, in the order written.
  60. ```
  61. `approval_required: true` holds a phase for a human before it acts. Scaffold a new file with:
  62. ```bash
  63. python scripts/create_workflow.py phishing-triage --agents triage,investigator,responder
  64. # creates core/workflows/definitions/phishing-triage/WORKFLOW.md
  65. ```
  66. ---
  67. ## Integrations
  68. Vigil connects agents to your existing tools through [MCP](https://modelcontextprotocol.io/). 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`](mcp-config.json) is the current list, and [vigilsoc.org/docs/integrations](https://vigilsoc.org/docs/integrations/) describes each one.
  69. An integration is one of two things:
  70. - **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).
  71. - **A vendor slice**: a server Vigil maintains at `core/integrations/<vendor>/tool.py`, used where no suitable upstream server exists. See [vendor slices](https://vigilsoc.org/docs/vendor-slices/).
  72. 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.
  73. 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.
  74. 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.
  75. **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`](tools/mcp/frozen_tools.snapshot.json). The rest are served under the `0.x` terms in [`SECURITY.md`](SECURITY.md#supported-versions). To work Vigil from a Claude Code session, install [the Claude Code client](clients/claude-code/README.md): `claude plugin marketplace add Vigil-SOC/vigil@v<your Vigil version> --sparse .claude-plugin clients/claude-code`, then `claude plugin install vigil-soc@vigil`.
  76. **Detection rules.** The detection-engineering integration ([security-detections-mcp](https://www.npmjs.com/package/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`).
  77. ---
  78. ## Quick Start
  79. ```bash
  80. git clone https://github.com/Vigil-SOC/vigil.git
  81. cd vigil
  82. ./start.sh
  83. ```
  84. 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.
  85. 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`).
  86. Security keys (WebAuthn) are tied to the hostname the console is reached at: set `VIGIL_CONSOLE_HOSTNAME` (no scheme or port) and keep `VIGIL_COOKIE_SECURE=true`, or use `localhost`; otherwise keys stay off and sign-in by password and authenticator app is unchanged ([security keys](docs/security-keys.md)).
  87. `start.sh` provisions the pinned Python with [uv](https://docs.astral.sh/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.
  88. - **`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.
  89. - **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.
  90. - **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.
  91. > **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](https://github.com/Vigil-SOC/vigil/releases/latest).
  92. >
  93. > Released images are signed keyless by [`.github/workflows/release.yml`](.github/workflows/release.yml). To verify (the image tag drops the leading `v`; the certificate identity uses the git tag):
  94. >
  95. > ```bash
  96. > cosign verify \
  97. > --certificate-identity https://github.com/Vigil-SOC/vigil/.github/workflows/release.yml@refs/tags/v<version> \
  98. > --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  99. > ghcr.io/vigil-soc/vigil-backend:<version>
  100. > ```
  101. ### Prerequisites
  102. - **Docker** (running): PostgreSQL, Redis, and Bifrost run in containers.
  103. - **Node.js 20+**: runs the agent layer and the frontend. Without Node, neither starts and workflows cannot run.
  104. - **Git**.
  105. - **No system Python needed**: `start.sh` provisions the version pinned in `.python-version` with uv, independent of any Python you already have.
  106. - **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](https://vigilsoc.org/docs/bifrost/). With no provider key, `scripts/local_model.sh` serves a small local model Bifrost can reach and prints the model id to use.
  107. ### Windows (WSL2)
  108. > **Not yet tested inside WSL2 on a Windows machine.** `start.sh` runs end to end on Ubuntu 24.04, the distro `wsl --install` sets up, with its WSL2 branches switched on; Docker Desktop's integration and the Windows side are unverified. Please report what breaks.
  109. `start.sh` is a bash script, so run Vigil inside WSL2, not in PowerShell or Git Bash.
  110. - **WSL2 with Ubuntu** (`wsl --install -d Ubuntu` in an administrator PowerShell, then reboot). Inside Ubuntu: `sudo apt update && sudo apt install -y git curl`.
  111. - **Docker Desktop for Windows**, running, with **Settings → Resources → WSL integration** turned on for your Ubuntu distro. `docker ps` must work inside Ubuntu before you start.
  112. - **Node.js 20+ inside Ubuntu**, for example with [nvm](https://github.com/nvm-sh/nvm). Ubuntu's own `nodejs` package is older than 20, and a Windows Node install is not visible to the scripts. Without it, `start.sh` still starts the API but not the console or the agent layer, and its ready banner says so.
  113. - **Clone into the Linux home** (`~/vigil`), not under `/mnt/c`. On the Windows drive, auto-reload, file permissions and Docker mounts are slow or unreliable; `start.sh` warns if it finds itself there. The repo's `.gitattributes` keeps shell scripts on LF line endings even if Git for Windows made the checkout. That only applies to files checked out after it: if `start.sh` fails with `$'\r': command not found`, the clone predates it. Clone again inside Ubuntu, or run `git rm -r --cached -q . && git reset --hard` in the checkout (this discards uncommitted changes).
  114. - **Memory.** WSL2 takes up to half of the machine's RAM by default, and Docker Desktop runs inside it. On an 8 GB laptop, put this in `%UserProfile%\.wslconfig` and run `wsl --shutdown` in PowerShell:
  115. ```ini
  116. [wsl2]
  117. memory=6GB
  118. ```
  119. On 8 GB, keep the local model small (`qwen2.5:1.5b`, about 1 GB) or use a hosted provider.
  120. - **Ollama** is optional. Ollama for Windows listens on Windows' localhost, which WSL2 does not share in its default networking, so `start.sh` will report it as not found (the containers may still reach it through Docker Desktop; the model list on the host side will not). Either install Ollama inside Ubuntu, or turn on `networkingMode=mirrored` under `[wsl2]` (Windows 11 22H2 or later). Neither setup is verified. `scripts/local_model.sh` stops with an explanation under Docker Desktop.
  121. Open http://localhost:6988 in your Windows browser; `start.sh` tries `wslview`, then `explorer.exe`, and the URL is in the ready banner either way.
  122. On Windows, use `start.sh` and `shutdown_all.sh`. The desktop app has no Windows build, and `scripts/vigil-upgrade.sh` and `scripts/vigil-backup.sh` are for a Linux server running Vigil under systemd.
  123. ### Run
  124. ```bash
  125. ./start.sh # interactive; Ctrl+C to stop
  126. ./start.sh -d # background: logs/ + pidfiles, also starts the SOC daemon
  127. ./start.sh --with splunk # add a profiled service (splunk, kafka, pgadmin, jaeger,
  128. ./start.sh --all # prometheus, grafana, otel-collector), or all of them
  129. ```
  130. Core services come from `.vigil-autostart` (or `$AUTOSTART_SERVICES`), defaulting to `postgres redis bifrost ollama`.
  131. | | URL |
  132. |---|---|
  133. | Frontend | http://localhost:6988 |
  134. | API | http://localhost:6987 |
  135. | API docs | http://localhost:6987/docs |
  136. ### Shutdown
  137. ```bash
  138. ./shutdown_all.sh # stop native processes; containers keep running
  139. ./shutdown_all.sh -d # stop everything; data is kept
  140. ./shutdown_all.sh -d --full # stop everything and PERMANENTLY DELETE all data volumes
  141. ```
  142. `-d --full` runs `docker compose down -v`, which deletes every named volume in the compose file: `postgres_data` (database), `bifrost_data` (Bifrost config and keys), `vigil_home` (the Compose State Directory, including `master.key`), `vigil_investigations`, `redis_data`, `backup_repo` (the default on-box backup repository), `upgrade_state` (pre-upgrade restore points and upgrade history), and any optional-profile volumes. Keep backups outside the compose volumes (`VIGIL_BACKUP_REPO`) first. See `./shutdown_all.sh --help`.
  143. <details>
  144. <summary>Manual install (separate terminals)</summary>
  145. ```bash
  146. # Python environment (uv fetches the interpreter in .python-version)
  147. uv python install
  148. uv venv --python "$(cat .python-version)" --python-preference only-managed venv
  149. source venv/bin/activate
  150. uv pip install -r requirements.lock
  151. cp env.example .env # set AGENT_INTERNAL_TOKEN
  152. export PYTHONPATH="${PWD}:${PYTHONPATH}"
  153. # 1. Containers
  154. docker compose -f infra/docker/docker-compose.yml up -d postgres redis bifrost
  155. # 2. Schema. The upgrade one-shot creates it; the API does not.
  156. docker compose -f infra/docker/docker-compose.yml up -d upgrade
  157. # 3. API
  158. uvicorn services.api.main:app --host 127.0.0.1 --port 6987 --reload
  159. # 4. Agent layer (drains the queue workflow runs are enqueued to)
  160. scripts/agent_up.sh
  161. # optional: python -m services.worker (ARQ LLM worker)
  162. # 5. Frontend
  163. cd clients/web && npm install && npm run dev
  164. ```
  165. </details>
  166. ### Run with Docker (full stack)
  167. ```bash
  168. docker compose --env-file .env -f infra/docker/docker-compose.yml up -d
  169. ```
  170. Pass the repo-root `.env` explicitly, or `AGENT_INTERNAL_TOKEN` reaches the containers empty (`./setup_dev.sh` fills an empty one in `.env`). The `backend` container refuses to start without `JWT_SECRET_KEY`. Set it in `.env`, for example `export JWT_SECRET_KEY="$(cat ~/.vigil/jwt_secret)"` if `start.sh` has run before, or `openssl rand -base64 48`.
  171. The default set runs the database, cache, gateway, backup, API, and agent layer: everything a chat-driven workflow needs. Opt-in profiles add more: `daemon` (the SOC daemon plus the ARQ worker, for headless 24/7 monitoring), `dev`, `observability`, `splunk`, `kafka`, `elastic`, and `misp`:
  172. ```bash
  173. docker compose --env-file .env -f infra/docker/docker-compose.yml --profile daemon up -d
  174. ```
  175. On the host, `./start.sh -d` also runs the daemon (`services/daemon/main.py`), or run it alone against a running stack with `python services/daemon/main.py`.
  176. ### Install on Kubernetes
  177. ```bash
  178. helm install vigil ./infra/helm/vigil \
  179. --namespace vigil --create-namespace \
  180. --set secrets.anthropicApiKey="$ANTHROPIC_API_KEY" \
  181. --set secrets.postgresPassword="$(openssl rand -hex 24)" \
  182. --set secrets.vigilAppPassword="$(openssl rand -hex 24)" \
  183. --set secrets.jwtSecretKey="$(python -c 'import secrets; print(secrets.token_urlsafe(64))')"
  184. ```
  185. See the [Helm guide](https://vigilsoc.org/docs/helm/) for values, external Postgres/Redis, ingress, and troubleshooting.
  186. ### Desktop app
  187. The desktop app packages the stack without a source tree. It runs the backend and agent images from an offline tarball, alongside a bundled Bifrost gateway, so **Docker must be installed and running**. Bifrost reaches a host Ollama through `host.docker.internal`.
  188. ```bash
  189. bash clients/desktop/scripts/bundle-image.sh linux/arm64 # tarball is arch-specific
  190. cd clients/desktop && npm run dist # macOS DMG / Linux AppImage
  191. ```
  192. Local builds are ad-hoc signed, not notarized, so macOS may report the app as "damaged". Clear the quarantine with `xattr -dr com.apple.quarantine /Applications/Vigil.app`, or use **System Settings → Privacy & Security → Open Anyway**.
  193. ---
  194. ## Getting help: the support bundle
  195. `vigil-support.sh` writes one redacted `tar.gz` you can attach to a support request. It is POSIX `sh`, runs on Linux and macOS, and uploads nothing.
  196. ```bash
  197. sh scripts/vigil-support/vigil-support.sh # from a checkout
  198. ```
  199. Without a checkout, download `vigil-support-<version>.tar.gz` and its `.sha256` from the [release](https://github.com/Vigil-SOC/vigil/releases/latest), verify it, extract it, and run `sh vigil-support/vigil-support.sh`. Vigil Desktop shows the exact command under **Support Bundle Command…** in the tray menu. For a Helm install, run it from your own machine with your current `kubectl` context: `--mode helm [--release NAME --namespace NS]`.
  200. Re-run with `sudo` to include system logs that need elevation; the bundle still examines, and belongs to, the invoking user's install. `sudo` resets `VIGIL_DIR`, so pass `--state-dir` for a non-default State Directory.
  201. > **DATA NOTICE:** the bundle holds host information: hostname, the full process list with command lines, system logs, and disk usage. Known credential formats are redacted, but secrets in free log text cannot be guaranteed caught. Review it before you share it.
  202. When it finds a Vigil install, the bundle also collects its configuration, health output, container status, and logs. Secrets, keys, and database contents are never included; `SUMMARY.txt` lists what was left out. See [`scripts/vigil-support/README.md`](scripts/vigil-support/README.md).
  203. Pass `--medic` to also write Medic's section for the `--since` window: `medic/section.json` inside the archive, for the site's own team, and `<archive>.medic.json` beside it, the part that can go on a public defect report. Without the flag the run is unchanged, and the archive itself stays the site file the data notice describes.
  204. ---
  205. ## Architecture
  206. ```
  207. ┌──────────────────────────────────────────────────────────────────┐
  208. │ Web console (React) · Chat · Desktop app · /mcp clients │
  209. └──────────────────────────────────────────────────────────────────┘
  210. │
  211. ▼
  212. ┌──────────────────────────────────────────────────────────────────┐
  213. │ API (Python / FastAPI) │
  214. │ Findings · Cases · Approvals · Detections · ATT&CK · Workflows │
  215. └──────────────────────────────────────────────────────────────────┘
  216. │ enqueue runs (BullMQ / Redis) ▲ backend tools
  217. ▼ │
  218. ┌──────────────────────────────────────────────────────────────────┐
  219. │ Agent layer (TypeScript) │
  220. │ Workflow runtimes: compose · investigate · root cause · hunt │
  221. │ Agents call backend tools and MCP integration tools │
  222. └──────────────────────────────────────────────────────────────────┘
  223. │ model calls │ tool calls
  224. ▼ ▼
  225. ┌──────────────────────────┐ ┌────────────────────────────────────┐
  226. │ Bifrost LLM gateway │ │ MCP integrations │
  227. │ Anthropic · OpenAI · │ │ SIEM · EDR · cloud · identity · │
  228. │ Vertex · Ollama │ │ intel · sandbox · ticketing · … │
  229. └──────────────────────────┘ └────────────────────────────────────┘
  230. PostgreSQL: findings, cases, approvals, runs, settings
  231. SOC daemon (optional): alert polling and auto-enrichment
  232. ```
  233. ## Project structure
  234. ```
  235. vigil/
  236. ├── core/ # Shared Python library: domains (findings, cases, llm,
  237. │ │ # integrations, …) over a storage/platform tier
  238. │ ├── agents/ # Built-in agent definitions
  239. │ ├── integrations/ # Vendor slices and the MCP registry
  240. │ └── workflows/definitions/ # Built-in WORKFLOW.md files
  241. ├── services/
  242. │ ├── api/ # FastAPI backend
  243. │ ├── agent/ # TypeScript agent layer (workflow runtimes, worker + serve)
  244. │ ├── daemon/ # Headless autonomous SOC
  245. │ └── worker/ # ARQ LLM worker
  246. ├── clients/
  247. │ ├── web/ # React + Tailwind frontend
  248. │ └── desktop/ # Desktop app
  249. ├── tools/mcp/ # Vigil's own MCP server and frozen tool snapshot
  250. ├── mcp-config.json # MCP integration catalogue
  251. └── infra/ # Docker Compose, Helm chart, DB init
  252. ```
  253. ## Documentation
  254. Guides live at **[vigilsoc.org/docs](https://vigilsoc.org/docs/)**:
  255. | Doc | Contents |
  256. |-----|----------|
  257. | [Agents](https://vigilsoc.org/docs/agents/) | Built-in agents and how to customize them |
  258. | [Integrations](https://vigilsoc.org/docs/integrations/) | MCP integrations and setup |
  259. | [Detection engineering](https://vigilsoc.org/docs/detection-engineering/) | Rule search, coverage, and gaps |
  260. | [Chat-driven case management](https://vigilsoc.org/docs/chat-case-management/) | Building cases in natural language |
  261. | [Configuration](https://vigilsoc.org/docs/configuration/) | Environment variables, secrets, deployment |
  262. | [Helm](https://vigilsoc.org/docs/helm/) | Chart values, secrets, install |
  263. | [Splunk testing](https://vigilsoc.org/docs/splunk-testing/) · [Postgres → Splunk](https://vigilsoc.org/docs/postgres-to-splunk/) | Test data and export scripts |
  264. | [Contributing](https://vigilsoc.org/docs/contributing/) | How to contribute, DCO |
  265. | [Security keys](docs/security-keys.md) | The hostname and HTTPS rule, an internal CA for air-gapped consoles, and what "keys unavailable" means |
  266. | [Operator endpoints](docs/operator-endpoints.md) | API routes with no console screen: secrets backend status, dotenv → encrypted migration |
  267. | [Audit trail](docs/audit-trail.md) | What the trail keeps and does not rewrite, what a backup or a forwarded copy still holds, and that an account has no set end date |
  268. | [SECURITY.md](SECURITY.md) | Vulnerability reporting, supported versions, disclosure |
  269. | [VERSIONING.md](VERSIONING.md) | What is frozen, what is not, and how the contract changes |
  270. | [Adoption figures](docs/metrics.md) | Daily views, clones, stars, forks, and contributor history, published unaltered at [Vigil-SOC/metrics](https://github.com/Vigil-SOC/metrics) |
  271. ## Contributing
  272. Contributions are welcome: bug fixes, integrations, agent prompts, workflows, or new agents. Join the community on [Discord](https://discord.gg/nVprk5uHGq).
  273. 1. Fork the repo and create a feature branch.
  274. 2. Make your changes and test them.
  275. 3. Open a pull request with a clear description.
  276. See the [contributing guide](https://vigilsoc.org/docs/contributing/) for the full process.
  277. ## License
  278. Apache 2.0. See [LICENSE](LICENSE).
  279. ## References
  280. - [Vigil](https://vigilsoc.org/): project homepage
  281. - [DeepTempo](https://deeptempo.ai): Vigil sponsor; LogLM connects via MCP as an optional detection layer
  282. - [Vigil-SOC/metrics](https://github.com/Vigil-SOC/metrics): the project's adoption figures, published daily so anyone can check them
  283. - [Model Context Protocol](https://modelcontextprotocol.io/): MCP specification
  284. - [SOCBench](https://socbench.org): open benchmark for AI in cybersecurity operations

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.