Vigil

Vigil

Docs: English · Русский · Documentation · llms.txt

Your code. Your model. Your findings. Vigil runs 263 deterministic

security rules over a repository, then — only if you ask — sends the minimum

context to the model you already pay for to triage findings, review risky

code, propose fixes and write a threat model. One static Go binary, one MCP

server, no account, no telemetry, no Docker for a normal scan.

Status: 0.9.x. The deterministic engine, CLI and MCP server are usable

today. LLM output is advisory, rule coverage keeps growing, and Vigil is not a

replacement for a pentest. Treat every finding as a lead to verify, not a

verdict.

See it work

A nine-line Python file with a string-built SQL query and MD5 password hashing:

$ vigil scan . --no-llm

vigil scan · . mode standard model deterministic rules only files 1 scanned, 0 skipped duration 2ms findings 2 high report stdout

HIGH app.py:6 VGL-INJ-014 — SQL query built with Python string formatting HIGH app.py:9 VGL-CRY-001 — Weak hash algorithm used for passwords or signatures

No key, no network, no Docker. Add a model and the same findings get triage, context and a proposed diff:

export OPENAI_API_KEY=sk-...

vigil scan . vigil fix VGL-XXXXXXXXXX # print a unified diff vigil fix VGL-XXXXXXXXXX --apply # write it to the working tree, never commit

Why Vigil

• Your model, your keys. OpenAI, Anthropic, Gemini, OpenRouter, Groq, DeepSeek, Mistral, xAI, OpenCode Go, Ollama, LM Studio, a local CLI or any OpenAI-compatible endpoint. No proxy, no Vigil account, no telemetry.
• Deterministic first. All 263 rules run before any model call. A provider outage cannot hide a hardcoded secret, a shell injection or a disabled JWT check.
• Fits the agent you already use. One stdio MCP server for OpenCode, Claude Code, Codex and Cursor. The agent can scan, explain, fix and re-check without leaving the conversation.
• Read-only by default. A scan never modifies source files; it writes only its own history under .vigil/scans or the user cache. vigil fix --apply writes a validated unified diff and never commits. Secrets are masked.
• Small and portable. One static Go binary, standard library plus gopkg.in/yaml.v3, no CGO, no Docker for the default scan.
• CI-native. Markdown, JSON, SARIF and HTML. --fail-on high exits 2, so a pull request can block on a real finding.

What you get

Install

The only package you install is `lv24-vigil`. It selects the binary for your platform at install time and runs no install scripts.

npm i -g lv24-vigil@latest

vigil version

Or run it without a global install:

npx -y lv24-vigil scan --no-llm

npx -y lv24-vigil mcp

Package choice

The npm distribution is seven packages: one lv24-vigil launcher plus six platform packages. Keep optional dependencies enabled — --no-optional and --omit=optional skip the platform package, and vigil then exits with platform package ... is not installed. Releases use npm Trusted Publishing (OIDC) with a provenance attestation.

Do not pin 0.5.0: the tag and the npm package are immutable and still installable, but the CI examples on that tag are stale (inputs.fail-on, an unguarded GitLab pre-check). The binaries are fine; the templates are not. Use 0.9.3 or newer, or @latest.

Requirements: Node.js 18+ for npm, Go 1.27+ for go install; release binaries and installers need no runtime.

Go

Go 1.27 or newer:

go install github.com/levapveeskela/lv24-vigil/cmd/vigil@latest

Make sure $(go env GOPATH)/bin is on PATH.

Standalone installers

The installers resolve a release, verify the SHA-256 checksum, install atomically and keep the previous binary:

git clone https://github.com/LevapVeeskela/lv24-vigil

cd lv24-vigil bash installers/unix/install.sh # macOS / Linux .\installers\windows\install.ps1 # Windows PowerShell 5.1+

Each release also publishes six raw binaries and checksums.txt on the releases page. Options and manual verification: docs/install.md.

Other channels

Arch Linux: the AUR package builds from the published release (yay -S vigil-bin), with the PKGBUILD and verification steps in docs/aur.md.

MCP: Vigil is listed in the official MCP Registry as io.github.LevapVeeskela/vigil; the npm package carries mcpName and the repository ships server.json, so registry-aware clients can install it as npx -y lv24-vigil mcp. Registry layout, publishing and verification: docs/mcp-registry.md. Other MCP catalogues and the status of each submission: docs/mcp-directories.md.

Container

A prebuilt multi-arch image (linux/amd64 and linux/arm64, distroless and running as nonroot) is published to GitHub Container Registry for every release:

docker run --rm -v "$PWD:/workspace" ghcr.io/levapveeskela/lv24-vigil:0.9.3 scan --no-llm --path /workspace

The local Dockerfile builds the same image if you prefer:

docker build -t lv24-vigil .

docker run --rm -v "$PWD:/workspace" -w /workspace lv24-vigil scan --no-llm

Tags, digest pinning, provenance/SBOM attestations and limitations: docs/install.md and docs/container.md.

Verify

vigil version   # build metadata

vigil status # resolved provider, model, rules, store and last scan vigil rules # the authoritative rule catalog

60-second quickstart

cd your-repo

Deterministic rules only: no key, no network.

vigil scan --no-llm

Add LLM triage with a hosted model.

export OPENAI_API_KEY=sk-... vigil scan

Or keep everything local.

VIGIL_PROVIDER=ollama VIGIL_MODEL=qwen2.5-coder:14b vigil scan

Useful next commands:

vigil status --json                              # machine-readable environment check

vigil scan --format sarif --fail-on high # CI gate, SARIF on stdout vigil review --base origin/main --format sarif # review only changed lines vigil fix VGL-XXXXXXXXXX # proposed diff vigil fix VGL-XXXXXXXXXX --apply # write it, never commit vigil threat-model # STRIDE-style Markdown, needs a model vigil report --format html > report.html # render the last stored scan vigil mcp-audit . --fail-on high # MCP config posture (VGL-MCP) vigil sbom . --output sbom.cdx.json # CycloneDX 1.6 bill of materials

vigil scan with no path scans the current directory. A finding ID comes from a previous scan or report. Exit codes: 0 clean, 1 error, 2 findings at or above --fail-on. Full reference: docs/cli.md.

MCP setup

Start the server with vigil mcp (stdio, JSON-RPC). Register it once:

OpenCode — opencode.json in the project root (or ~/.config/opencode/opencode.json):

{

"mcp": { "vigil": { "type": "local", "command": ["npx", "-y", "lv24-vigil", "mcp"], "enabled": true } } }

Claude Code:

claude mcp add vigil -- npx -y lv24-vigil mcp

Codex — ~/.codex/config.toml:

[mcp_servers.vigil]

command = "npx" args = ["-y", "lv24-vigil", "mcp"]

Cursor — ~/.cursor/mcp.json:

{

"mcpServers": { "vigil": { "command": "npx", "args": ["-y", "lv24-vigil", "mcp"] } } }

If Vigil is installed globally, use ["vigil", "mcp"] instead of npx. Start the client from the repository you want to scan; vigil mcp --root DIR sets a different project root.

The server exposes 14 tools:

| vigil_review | Reviews changed lines o