
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.10.3. If you are on 0.10.1 or older, upgrade: 0.10.2 was a
security patch release with the fixes from an adversarial review and a
patched Go toolchain, and 0.10.3 is the same code with refreshed package
pages (changelog). 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
|
Feature |
What it does |
| 🔍 |
263 deterministic rules |
Secrets, injection, crypto, auth, web, config/IaC, CI, dependencies, MCP configuration and anti-RE hardening — no model required |
| 🧠 |
LLM triage |
Ranks and filters findings with your model; deterministic severity stays visible |
| 🧪 |
Deep review |
Reads bounded windows of high-risk files and adds VGL-AI-001 findings |
| 🛠 |
Fix diffs |
Produces a validated unified diff; --apply writes the working tree only |
| 🗺 |
Threat model |
Generates a STRIDE-style Markdown threat model |
| 🔌 |
MCP server |
14 tools, 4 resources and 5 prompts over stdio |
| 📊 |
Reports |
Markdown, JSON, SARIF 2.1.0, JUnit (report-only) and self-contained HTML |
| 🧾 |
Baseline |
Suppresses accepted findings so only new issues fail a gate; entries can carry a ticket, path scope and expiry date |
| 🧰 |
Command provider |
Reuses an already-authenticated local CLI without storing an API key |
| 🛡 |
Dependency advisories |
Reads lockfiles and queries api.osv.dev for known public advisories (opt-in network); vigil_dependencies |
| 🧩 |
MCP config audit |
VGL-MCP rules for unpinned server packages, literal secrets, cleartext endpoints, disabled TLS and dangerous mounts; CLI and vigil_mcp_audit |
| 📦 |
SBOM |
CycloneDX 1.6 or SPDX 2.3 JSON from the manifests and lockfiles Vigil already reads; offline |
| 🔒 |
Anti-RE hardening |
Flags missing release controls and the artifact surfaces a reverse-engineering toolkit (REA) reads: symbols/DWARF, Electron fuses, JS minify, WebView, Hermes, iOS testability, plus debug signing, debuggable builds, backup/cleartext, inspector flags and source maps; --platform narrows the review |
| 🚦 |
CI gate |
--fail-on, exit code 2, SARIF upload and vigil precheck |
How it works
your repository
| walk the tree: ignore lists, 2 MiB file cap, binary sniffing;
| symlinks and hardlinked files are skipped
v
263 deterministic rules ----> findings: rule, severity, CWE, OWASP,
| masked evidence, stable ID and fingerprint
|
| inline vigil:ignore and the baseline move accepted findings
| to "suppressed"; nothing is deleted
v
optional, on your model ----> triage, deep review, fix diff, threat model
|
v
Markdown . JSON . SARIF . JUnit . HTML exit code 0 / 1 / 2
the same engine behind the CLI and the 14 MCP tools
- Step one never needs a network. The rules read files and nothing else:
no code is executed, nothing is uploaded, and a missing model changes nothing.
- The model is an add-on, not the detector. When you configure one, Vigil
sends bounded context to the endpoint you chose and validates what comes
back before it becomes a finding or a diff.
- Output is stable. The same tree produces the same findings and the same
IDs, so a baseline, a CI gate and an agent can all rely on them.
Design and limits: docs/architecture.md.
Install
The only package you install is lv24-vigil. Pick the channel that fits
your machine; every one of them ends at the same vigil command.
| You are on |
Fastest path |
Also available |
| Windows |
npm i -g lv24-vigil or scoop install lv24/vigil |
.exe from Releases, PowerShell installer, Python launcher, container |
| macOS |
npm i -g lv24-vigil or brew install LevapVeeskela/tap/vigil |
release binary (Intel and Apple silicon), shell installer, go install |
| Linux |
npm i -g lv24-vigil or brew install LevapVeeskela/tap/vigil |
.deb / .rpm / .apk, release binary, shell installer, go install, container |
| CI |
uses: LevapVeeskela/lv24-vigil@v0.10.3 or the GitLab template |
npx -y lv24-vigil, container image |
| An MCP client |
npx -y lv24-vigil mcp |
vigil mcp after any install below |
| Python tooling only |
pipx install lv24-vigil or uvx lv24-vigil |
needs Node.js 18+; see Python |
Binaries exist for Windows, macOS and Linux on x64 and arm64. What is live
on each channel today: docs/distribution.md.
npm (recommended)
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 |
Install directly? |
What it is |
lv24-vigil |
✅ Yes |
Launcher, CLI and MCP server entry point; picks the right binary |
@lv24/vigil-<os>-<cpu> |
❌ No |
Platform binary (win32, darwin, linux × x64, arm64) pulled in as an optionalDependency |
lv24-vigil on PyPI |
Optional |
Thin Python launcher that delegates to npm; needs Node.js 18+ |
The npm distribution is seven packages: one lv24-vigil launcher plus six
platform packages. It runs no install scripts and downloads nothing at install
time. 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.
Requirements: Node.js 18+ for npm, Go 1.27+ for go install; release binaries
and installers need no runtime.
Do not pin 0.5.0
The v0.5.0 tag and 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.10.3 or
newer, or @latest.
Python
A thin launcher on PyPI runs the same CLI through npx. It needs Node.js 18+
and Python 3.9+, and bundles no binary of its own.
pipx install lv24-vigil # or: pip install lv24-vigil
uvx lv24-vigil scan --no-llm # run once without installing
Version pinning (VIGIL_NPM_VERSION) and exit codes:
docs/pypi.md.
Homebrew and Scoop
brew install LevapVeeskela/tap/vigil # macOS and Linux; builds from source
scoop bucket add lv24 https://github.com/LevapVeeskela/scoop-bucket
scoop install lv24/vigil # Windows, x64 and arm64
Linux packages
Every release ships .deb, .rpm and .apk for amd64 and arm64. Download
the file from the
releases page and
install it by path:
sudo apt install ./vigil-0.10.3-linux-amd64.deb # Debian, Ubuntu
sudo dnf install --nogpgcheck ./vigil-0.10.3-linux-amd64.rpm # Fedora, RHEL, openSUSE
sudo apk add --allow-untrusted ./vigil-0.10.3-linux-amd64.apk # Alpine
The packages carry no distribution key, which is why dnf and apk need the
extra flag; integrity comes from the signed checksums.txt
(Verify a download).
Arch Linux: the vigil-security-bin PKGBUILD in
packaging/aur is refreshed from the published release
assets, but AUR registration is temporarily paused, so the package is not
published yet. Status, manual build and verification:
docs/aur.md.
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.
Binaries and 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.
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.10.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.
Registries and catalogues
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.
WinGet: the manifest is in review; use Scoop or the release binaries until it
is merged.
Update and uninstall
| Channel |
Update |
Remove |
| npm |
npm i -g lv24-vigil@latest |
npm uninstall -g lv24-vigil |
| pipx / pip |
pipx upgrade lv24-vigil · pip install -U lv24-vigil |
pipx uninstall lv24-vigil · pip uninstall lv24-vigil |
| Homebrew |
brew upgrade vigil |
brew uninstall vigil |
| Scoop |
scoop update vigil |
scoop uninstall vigil |
| deb / rpm / apk |
install the new package file |
sudo apt remove vigil · sudo dnf remove vigil · sudo apk del vigil |
| Go |
go install github.com/levapveeskela/lv24-vigil/cmd/vigil@latest |
delete vigil from $(go env GOPATH)/bin |
| Installer |
run it again |
install.sh --uninstall · install.ps1 -Uninstall |
| Container |
docker pull ghcr.io/levapveeskela/lv24-vigil:<version> |
docker rmi ghcr.io/levapveeskela/lv24-vigil:<version> |
Vigil installs no daemon, service or scheduled task. Scan history lives in the
repository under .vigil/scans or in the user cache directory; delete it if
you want a clean slate.
Verify the install
vigil version # build metadata
vigil status # resolved provider, model, rules, store and last scan
vigil rules # the authoritative rule catalog
Verify a download
Every release is covered four ways: a keyless cosign signature over
checksums.txt, a GitHub build-provenance attestation for each asset, a
CycloneDX SBOM, and npm provenance for the packages.
gh release download v0.10.3 --pattern checksums.txt --pattern checksums.txt.sigstore.json
cosign verify-blob \
--bundle checksums.txt.sigstore.json \
--certificate-identity "https://github.com/LevapVeeskela/lv24-vigil/.github/workflows/release.yml@refs/tags/v0.10.3" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
checksums.txt # prints: Verified OK
sha256sum -c checksums.txt --ignore-missing # the files you downloaded
gh attestation verify vigil_0.10.3_linux_amd64 --repo LevapVeeskela/lv24-vigil
Container digests, npm provenance and the full flow:
docs/release.md.
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 config validate --json # check the effective configuration
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 junit > junit.xml # JUnit for a CI test report
vigil report --format html > report.html # render the last stored scan
vigil hardening . --platform android # anti-RE gaps for one surface
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.
Configuration
Vigil needs no configuration. When you want one, vigil init writes a
commented .vigil.yaml that is safe to commit:
scan:
mode: standard # quick | standard | deep (deep adds the LLM deep review)
min_severity: low
max_findings: 200
exclude: ["node_modules/**", "dist/**", "*.min.js"]
disable_rules: [] # for example [VGL-DEP-001]
# baseline: .vigil-baseline.json
output:
format: md # md | json | sarif | html
Values resolve in this order, later wins: built-in defaults → user config →
project .vigil.yaml → environment variables → command-line flags. The user
config is ~/.config/vigil/config.yaml on Linux,
~/Library/Application Support/vigil/config.yaml on macOS and
%AppData%\vigil\config.yaml on Windows.
- Keys never live in a project file.
api_key, base_url, the command
provider and scan.osv_base_url are accepted only from the user config or
the environment. A project file that sets one of them is rejected.
- A project file is repository content. It can narrow a scan (
exclude,
disable_rules, min_severity), so review a change to it the way you review
code.
- See what is in effect.
vigil config validate checks both files, and
vigil config show --json prints every resolved value with its source and
with secrets redacted.
Reference: docs/providers.md ·
docs/cli.md · trust boundary:
docs/security-model.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:
| Tool |
What it does |
Needs |
vigil_scan |
Deterministic scan with optional LLM triage; optional OSV |
model optional; OSV optional |
vigil_review |
Reviews changed lines or a supplied diff |
model optional; OSV optional |
vigil_explain |
Explains one finding and a fix direction |
model |
vigil_fix |
Proposes a minimal diff; apply=true writes it |
model |
vigil_threat_model |
STRIDE-style threat model |
model |
vigil_status |
Provider, model, engine, store, baseline, last scan |
none |
vigil_rules |
Rule catalog with IDs, severities and categories |
none |
vigil_hardening |
VGL-ARE release-hardening gaps, grouped by platform; platform narrows one surface |
offline |
vigil_mcp_audit |
VGL-MCP configuration gaps in MCP server configs |
offline |
vigil_dependencies |
Declared packages checked against OSV |
network to OSV |
vigil_baseline |
List, add, remove or clear accepted findings |
baseline file |
vigil_report |
Renders a stored scan as md/json/sarif/html |
local store |
vigil_verify |
Re-checks whether a finding is still present |
none |
vigil_history |
Lists recent scans from the local store |
local store |
The same server exposes resources vigil://status, vigil://rules,
vigil://scan/last, vigil://scan/<id> and prompts security_review,
threat_model, fix_finding, anti_re_hardening, dependency_audit.
Only vigil_fix with apply=true changes source files.
Then ask your agent:
Scan this repository with Vigil and explain the top three findings.
Client recipes and protocol details: docs/mcp.md ·
Cursor · Claude Code ·
Codex.
For AI agents
If you are an agent, these are the stable contracts. Prefer them over scraping
prose.
{
"package": "lv24-vigil",
"install": "npm i -g lv24-vigil",
"binary": "vigil",
"mcp": { "command": "npx", "args": ["-y", "lv24-vigil", "mcp"] },
"mcp_registry_name": "io.github.LevapVeeskela/vigil",
"deterministic_only": "vigil scan --no-llm",
"json_report": "vigil scan --format json",
"sarif": "vigil scan --format sarif --fail-on high",
"status_json": "vigil status --json",
"config_check": "vigil config validate --json",
"fix_dry_run": "vigil fix <finding-id>",
"fix_apply": "vigil fix <finding-id> --apply",
"mcp_tools": [
"vigil_scan", "vigil_review", "vigil_explain", "vigil_fix",
"vigil_threat_model", "vigil_status", "vigil_rules", "vigil_hardening",
"vigil_mcp_audit", "vigil_dependencies", "vigil_baseline", "vigil_report",
"vigil_verify", "vigil_history"
],
"writes_source_files": ["vigil fix --apply", "vigil_fix apply=true"],
"network": {
"none": ["vigil scan --no-llm", "vigil hardening", "vigil mcp-audit", "vigil sbom"],
"osv": ["vigil dependencies", "vigil_dependencies", "scan.osv: true"],
"model": ["scan and review with a model", "vigil fix", "vigil threat-model", "vigil_explain"]
},
"exit_codes": { "0": "clean", "1": "error", "2": "findings at or above --fail-on" },
"docs_index": "llms.txt"
}
| You need to |
MCP tool |
CLI |
| Scan a repository |
vigil_scan |
vigil scan <path> --no-llm --format json |
| Look only at changed lines |
vigil_review |
vigil review --base origin/main --format json |
| Understand one finding |
vigil_explain |
— |
| Get a fix as a diff |
vigil_fix with apply=false |
vigil fix <finding-id> |
| Confirm a fix worked |
vigil_verify |
scan again |
| Check dependencies for known advisories |
vigil_dependencies |
vigil dependencies . --format json |
| Audit MCP server configs |
vigil_mcp_audit |
vigil mcp-audit . --format json |
| Review release hardening |
vigil_hardening |
vigil hardening . --format json |
| List rules or check the setup |
vigil_rules, vigil_status |
vigil rules --json, vigil status --json |
| Accept a finding |
vigil_baseline |
vigil baseline add <finding-id> --reason TEXT |
| Render or list stored scans |
vigil_report, vigil_history |
vigil report --format json |
| Tool |
Arguments |
Writes |
Network |
vigil_scan |
path, mode, minSeverity, maxFindings, include, exclude, onlyRules, disableRules, changedOnly, baseRef, diff, useLlm, deepReview, threatModel, noBaseline |
scan history |
model when useLlm; OSV when scan.osv is on |
vigil_review |
path, baseRef, changedOnly, diff, useLlm |
scan history |
model when useLlm |
vigil_hardening |
path, platform, minSeverity, maxFindings, noBaseline |
scan history |
none |
vigil_mcp_audit |
path, includeUser, minSeverity, maxFindings |
nothing |
none |
vigil_dependencies |
path, includeDev, maxPackages, osvBaseUrl |
nothing |
OSV |
vigil_explain |
findingId, scanId |
nothing |
model |
vigil_fix |
findingId, scanId, apply |
source files when apply=true |
model |
vigil_threat_model |
path |
nothing |
model |
vigil_verify |
findingId, scanId, paths |
nothing |
none |
vigil_baseline |
action, findingId, scanId, reason |
the baseline file |
none |
vigil_report |
format, path, scanId |
a report file when path is set |
none |
vigil_rules |
category, language, severity, query |
nothing |
none |
vigil_status, vigil_history |
— , limit |
nothing |
none |
What a finding looks like
vigil scan --format json returns schemaVersion, id, root, mode,
findings, suppressed, stats, errors, engine and version. One
finding:
{
"id": "VGL-A421AAF486",
"ruleId": "VGL-INJ-014",
"title": "SQL query built with Python string formatting",
"severity": "high",
"confidence": "high",
"category": "injection",
"cwe": ["CWE-89"],
"owasp": ["A03:2021 - Injection"],
"location": { "path": "app.py", "startLine": 6, "endLine": 6, "snippet": "..." },
"evidence": "return conn.execute(\"SELECT * FROM users WHERE name = '%s'\" % name).fetchone()",
"remediation": "Use parameterized queries or an ORM that binds parameters.",
"fingerprint": "fp_89db402212f46ea0",
"source": "rule"
}
severity is info, low, medium, high or critical; source is rule,
llm or hybrid. Pass id to vigil fix, vigil_explain and
vigil_verify. The fingerprint survives a line move, the id does not.
Rules that matter when you drive it
- Install
lv24-vigil only. Never install @lv24/vigil-<os>-<cpu>
directly; it is an optional dependency selected by the launcher.
- No model? Use
--no-llm. All 263 deterministic rules still run and
produce findings. A missing model is a warning, not a failed scan.
- Do not parse the human summary. Use
--format json, vigil status --json, or an MCP tool. stdout carries the report; logs go to stderr.
- Fixes need confirmation. Call
vigil_fix with apply=false first, show
the diff, and only then apply. Vigil never commits or stages.
- Respect the boundary. Scan only the requested path. Do not upload code
anywhere except the model endpoint the user configured.
- No telemetry. There is no Vigil cloud, account, analytics or update
check.
vigil precheck is the only explicit upload and needs a staff JWT.
- Read the whole result. Exit code
2 is a policy failure, not a crash.
Accepted findings are in suppressed, warnings are in errors, and a
non-zero stats.findingsTruncated means the list was capped.
Full agent index: llms.txt · onboarding:
AGENTS.md · client recipes: docs/mcp.md.
Providers
Set VIGIL_PROVIDER and the provider key, or let Vigil infer the provider from
a well-known key. Explicit VIGIL_* variables win over provider conventions.
A deterministic scan needs none of this.
| Provider |
VIGIL_PROVIDER |
Key variable |
Default model |
| OpenAI |
openai |
OPENAI_API_KEY |
gpt-4.1-mini |
| Anthropic |
anthropic |
ANTHROPIC_API_KEY |
claude-sonnet-4-5 |
| Google Gemini |
gemini |
GEMINI_API_KEY or GOOGLE_API_KEY |
gemini-2.5-flash |
| OpenRouter |
openrouter |
OPENROUTER_API_KEY |
anthropic/claude-sonnet-4.5 |
| Groq |
groq |
GROQ_API_KEY |
llama-3.3-70b-versatile |
| DeepSeek |
deepseek |
DEEPSEEK_API_KEY |
deepseek-chat |
| Mistral |
mistral |
MISTRAL_API_KEY |
mistral-large-latest |
| xAI |
xai |
XAI_API_KEY |
grok-4-fast |
| OpenCode Go |
opencode-go (alias opencode) |
OPENCODE_API_KEY or OPENCODE_GO_API_KEY |
deepseek-v4.1-flash |
| Ollama |
ollama |
none |
qwen2.5-coder:14b |
| LM Studio |
lmstudio |
none |
local-model |
| Local CLI |
command |
none |
free-form label |
| OpenAI-compatible |
custom |
VIGIL_API_KEY |
set VIGIL_MODEL |
Local models:
VIGIL_PROVIDER=ollama VIGIL_MODEL=qwen2.5-coder:14b vigil scan
VIGIL_PROVIDER=lmstudio VIGIL_MODEL=local-model vigil scan
The command provider reuses an already-authenticated local CLI — for example
opencode run — without storing an API key. Configure it in the user config:
provider: command
model: opencode-go/deepseek-v4.1-flash
command: ["opencode", "run", "--format", "json", "--model", "opencode-go/deepseek-v4.1-flash", "--agent", "plan", "{prompt}"]
command_output: opencode-json
The CLI runs with your privileges; use a no-tools agent such as --agent plan.
A project .vigil.yaml cannot set command or command_env on purpose.
OLLAMA_HOST points at a non-default Ollama. VIGIL_BASE_URL overrides the
endpoint for any provider; custom requires it. Full reference:
docs/providers.md · keyless example:
examples/config.command.yaml.
Rules
263 deterministic rules in ten families. They are pure: they read a file,
never write, never execute scanned code and never make a network call. The CLI is
the authoritative catalog:
vigil rules
| Family |
Prefix |
Rules |
Looks for |
| Secrets |
VGL-SEC |
37 |
Cloud keys, tokens, private keys, connection strings, .env leaks |
| Injection |
VGL-INJ |
54 |
SQL, shell, eval, XSS, deserialization, SSTI, prototype pollution |
| Crypto |
VGL-CRY |
16 |
Weak hashes/ciphers, ECB, static IVs, bad randomness, disabled TLS |
| Auth |
VGL-AUTH |
19 |
JWT verification, cookie flags, CORS with credentials, CSRF, defaults |
| Web |
VGL-WEB |
22 |
SSRF, path traversal, open redirect, headers, debug surfaces |
| Config / IaC |
VGL-CFG |
42 |
Docker, Compose, Kubernetes, Terraform, nginx, committed env files |
| CI |
VGL-CI |
20 |
Unpinned actions, pull_request_target, script injection, secret logs |
| Dependencies |
VGL-DEP |
15 |
Lockfiles, wildcard ranges, git/HTTP installs, TLS bypass |
| Anti-RE |
VGL-ARE |
28 |
Missing mobile/desktop hardening: release obfuscation, debug signing, debuggable builds, backup/cleartext, plist exceptions, inspector flags, source maps, plus Rust symbols/DWARF, .NET, iOS testability and symbols, Electron fuses/ASAR, JS minify, WebView and Hermes. Mapping: docs/anti-re-hardening.md |
| MCP |
VGL-MCP |
10 |
MCP server configuration: unpinned packages, literal secrets in env/headers/args, cleartext endpoints, disabled TLS, dangerous mounts, auto-approval and prompt-injection surfaces |
Representative IDs: VGL-SEC-002 (critical, AWS secret key), VGL-INJ-019
(critical, Java deserialization), VGL-CRY-011 (critical, JWT none),
VGL-AUTH-002 (critical, JWT verification disabled), VGL-WEB-001 (high,
SSRF), VGL-CFG-009 (high, Docker socket), VGL-CI-002 (critical,
pull_request_target checkout), VGL-DEP-006 (high, npm TLS off),
VGL-ARE-003 (high, debuggable Android manifest), VGL-ARE-010 (high, iOS
get-task-allow), VGL-MCP-002 (critical, literal secret in an MCP server
definition).
Model-only findings use VGL-AI-001 and are marked as LLM-sourced. OSV findings
use VGL-OSV-<advisory> and appear only when scan.osv is enabled. Disable a
rule when it does not fit the project, not to make a report green:
scan:
disable_rules: [VGL-DEP-001]
For one-off cases, suppress a finding with a comment directive:
// vigil:ignore VGL-SEC-001 reason="test fixture". Rule lists, *,
reason=, until=YYYY-MM-DD, precedence and diff/review behavior:
docs/rules.md#inline-suppressions.
Accepted findings go in the baseline. vigil baseline add accepts --ticket,
--expires YYYY-MM-DD and --path, list shows that metadata and prune
removes expired entries, which stop suppressing immediately:
docs/rules.md#baseline-and-suppression.
Severity, confidence, baseline and masking details:
docs/rules.md.
Safety
- Read-only by default. A scan writes no source files; it writes only its
scan history under
.vigil/scans (or the user cache). The other write paths
are vigil fix --apply / vigil_fix apply=true, the baseline command, an
explicitly requested report file, vigil init and vigil hook install
(.git/hooks/<mode> plus a .pre-vigil.bak backup with --force). A fix
never commits and never stages.
- Secrets are masked. Detected credentials are redacted in evidence,
snippets and reports. Raw secret values are never printed by the rule engine.
- Your code goes only where you point it. Deterministic scans make no
network calls. LLM features send the minimum context needed to the endpoint
you configured. Use a local model if code must not leave the machine.
- Scanned code is untrusted. Prompts delimit code as data, strip control
characters and instruct the model to ignore instructions inside it. Model
output is validated before it becomes a finding or a diff.
- Fixes are checked before they land. Paths must stay inside the repository
(including through symlinks, junctions and hardlinks); binary and symlink
patches and
.git edits are rejected; hunk counts must match;
git apply --check runs before any write.
- The project file is repository content. A committed
.vigil.yaml cannot
set a key, an endpoint or a command, and its output.path cannot replace a
file that is not a Vigil report. It can still narrow a scan, so review
changes to it like code.
- No telemetry. No Vigil cloud, account, analytics, crash reporter or update
check. The only optional upload is
vigil precheck, which needs an explicit
staff JWT.
Details and limits: docs/security-model.md.
Before commit / before deploy
One deterministic gate everywhere: vigil scan --no-llm --fail-on high. No
model, no key, no network.
| You want |
Path |
Setup |
| Catch issues before a commit or push |
Local git hook |
vigil hook install |
Block pull requests and main on GitHub |
GitHub Actions |
copy examples/github-workflow.yml |
Block merge requests and main on GitLab |
GitLab CI |
copy examples/gitlab-ci.yml |
| Record evidence in the LV24 control plane |
Optional pre-check |
set VIGIL_SECURITY_API_TOKEN |
Local hook (fastest, offline)
vigil hook install # pre-commit, fail on high
vigil hook install --mode pre-push # before push instead
vigil hook status
vigil hook uninstall
The hook runs git diff --cached --unified=0 --no-color | vigil scan --diff - --no-llm --fail-on high --quiet
for a commit. A pre-push hook diffs against @{upstream} and falls back to
HEAD~1 (then HEAD on a single-commit branch). It is marked
# managed by lv24-vigil, honours VIGIL_BIN (default vigil) and never
replaces a foreign hook without --force, which saves it as
<hook>.pre-vigil.bak. Uninstall removes only marked hooks and restores that
backup.
Using the pre-commit framework instead? The repository
ships a vigil-scan hook id that runs the same deterministic gate; setup,
skipping, autoupdate and the comparison with vigil hook install:
docs/pre-commit.md.
GitHub Actions (PR, main, manual)
The same action is listed on the GitHub Marketplace. Use uses: LevapVeeskela/lv24-vigil@v0.10.3; add version: 0.10.3 when the CLI must match the action tag.
Copy examples/github-workflow.yml to
.github/workflows/vigil.yml:
name: vigil
on:
workflow_dispatch:
inputs:
fail-on:
default: high
type: choice
options: [low, medium, high, critical]
pull_request:
push:
branches: [main]
permissions:
contents: read
security-events: write
jobs:
scan:
runs-on: ubuntu-latest
env:
FAIL_ON: ${{ inputs['fail-on'] || 'high' }}
VIGIL_SECURITY_API_TOKEN: ${{ secrets.VIGIL_SECURITY_API_TOKEN }}
VIGIL_SECURITY_API: ${{ vars.VIGIL_SECURITY_API }}
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with: { node-version: 22 }
- run: npm i -g lv24-vigil@latest
- run: vigil scan . --no-llm --format sarif --output vigil.sarif --fail-on "$FAIL_ON"
- if: always() && hashFiles('vigil.sarif') != ''
uses: github/codeql-action/upload-sarif@v4
with: { sarif_file: vigil.sarif }
- if: always() && env.VIGIL_SECURITY_API_TOKEN != '' && hashFiles('vigil.sarif') != ''
run: vigil precheck --sarif vigil.sarif --api "${VIGIL_SECURITY_API:-https://lv24.by/api}" --target "$GITHUB_REPOSITORY" --commit "$GITHUB_SHA"
The SARIF upload uses if: always() because --fail-on exits 2 after writing
the report. The pre-check is optional: without the secret the step is skipped.
VIGIL_SECURITY_API_TOKEN is a staff JWT with ops:security-scans, not an
API key; set the optional VIGIL_SECURITY_API repository variable only if your
control plane is not https://lv24.by/api.
GitLab CI (MR, main, manual)
Copy examples/gitlab-ci.yml to .gitlab-ci.yml:
vigil:
image: node:22
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
- if: '$CI_PIPELINE_SOURCE == "web"'
when: manual
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
variables:
GIT_DEPTH: "0"
script:
- npm i -g lv24-vigil@latest
- vigil scan . --no-llm --format sarif --output vigil.sarif --fail-on high
artifacts:
when: always
paths: [vigil.sarif]
reports:
sarif: vigil.sarif
The optional pre-check runs when the VIGIL_SECURITY_API_TOKEN CI/CD variable
is set. reports: sarif is native SARIF ingestion (GitLab 19.2+ Ultimate); on
older instances keep the plain paths artifact and remove the reports block.
GitLab's reports: sast expects its own gl-sast-report.json schema, not
SARIF.
Full instructions, secrets, exit codes and SARIF details:
docs/ci.md.
CI, SARIF and precheck
vigil review --base origin/main --format sarif --fail-on high > vigil.sarif
Upload the result with github/codeql-action/upload-sarif and keep
fetch-depth: 0. The repository ships a composite action in action.yml; this
example uses the CLI directly so it also works on any runner:
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v7
with: { fetch-depth: 0 }
- run: npx -y lv24-vigil review --base origin/${{ github.base_ref }} --format sarif --fail-on high > vigil.sarif
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
- if: always()
uses: github/codeql-action/upload-sarif@v4
with: { sarif_file: vigil.sarif }
Fork pull requests do not receive repository secrets; without a key Vigil still
runs every deterministic rule and produces SARIF. --fail-on high exits 2,
so the upload step must use if: always().
With the LV24 security control plane, record the same SARIF as evidence before a
full assessment:
vigil precheck --sarif vigil.sarif --api "$SECURITY_API" --token "$STAFF_JWT" \
--target "$GITHUB_REPOSITORY" --commit "$GITHUB_SHA"
STAFF_JWT is a staff JWT with ops:security-scans, not an API key. A precheck
does not start a scan. Full guide: docs/ci.md · example:
examples/github-workflow.yml.
Troubleshooting
| You see |
What it means |
What to do |
platform package ... is not installed |
npm skipped optional dependencies |
Reinstall without --no-optional / --omit=optional |
"LLM disabled" or no LLM provider configured |
No usable model; the deterministic scan still ran |
Set a provider key, or pass --no-llm to make it explicit |
provider "..." requires an API key |
A config names a provider you have no key for |
Export that provider's key, or change provider |
Exit code 2 |
Findings at or above --fail-on; not a crash |
Fix, baseline or suppress the finding; do not retry |
findings truncated in warnings |
The list hit max_findings; the most severe are kept |
Raise --max-findings |
| A finding is a false positive |
The rule matched safe code |
// vigil:ignore RULE-ID reason="..." on that line, or vigil baseline add <finding-id> --reason TEXT |
| No tools in the MCP client |
The server did not start or the config shape is wrong |
Run vigil mcp by hand; command and args must be arrays; restart the client |
| The agent scans the wrong directory |
The server uses its working directory as the root |
Start the client in the repository or pass vigil mcp --root DIR |
More cases, with the exact messages: docs/troubleshooting.md.
Documentation
| Document |
Contents |
| docs/install.md |
npm, Go, installers, deb/rpm/apk, Scoop, Homebrew, AUR, container |
| docs/distribution.md |
Per-channel status: GitHub, npm, PyPI, GHCR, Go, Scoop, Homebrew, WinGet, AUR, MCP Registry |
| docs/cli.md |
Commands, flags, exit codes, formats |
| docs/mcp.md |
MCP clients, tools, resources, prompts |
| docs/providers.md |
Providers, keys, local models, config precedence |
| docs/rules.md |
Rule families, representative IDs, baseline |
| docs/security-model.md |
Egress, masking, prompt safety, limits |
| docs/ci.md |
GitHub Actions, SARIF, fork PRs, prechecks |
| docs/architecture.md |
Packages, pipeline, design decisions |
| docs/troubleshooting.md |
Common failures and fixes |
| docs/comparison.md |
Vigil vs Strix vs hosted scanners |
| docs/release.md |
Release pipeline, npm Trusted Publishing, re-runs |
| docs/pypi.md |
Python launcher and PyPI publishing |
| docs/mcp-registry.md |
Official MCP Registry entry, publish and verify |
| docs/mcp-directories.md |
MCP directory metadata and submission status |
| docs/aur.md |
Arch AUR package, build and publication |
| docs/pre-commit.md |
pre-commit framework hooks |
| docs/container.md |
GHCR image, provenance and SBOM |
| docs/scorecard.md |
OpenSSF Scorecard workflow and badge |
| docs/anti-re-hardening.md |
ARE rule mapping to REA capabilities |
| docs/cii-best-practices.md |
CII Best Practices checklist |
| docs/history.md |
The dist-0.1.4 incident and repository history |
| docs/lv24-security-analysis.md |
Strix upstream sync and the LV24 fork |
| llms.txt |
Plain-text index for AI agents |
| AGENTS.md |
Short onboarding for coding agents |
Russian overview: README.ru.md · changes:
CHANGELOG.md · contributing: CONTRIBUTING.md ·
security reports: SECURITY.md.
License
Apache-2.0. See LICENSE.