lv24-vigil

module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: Apache-2.0

README

Vigil

Security audit for your code, on your own model.

Vigil is a local-first security auditor exposed as an MCP server and a CLI. It runs 100+ deterministic rules over a repository, then optionally uses the model you already pay for to triage findings, review risky code, propose fixes and write a threat model. There is no Vigil account, no telemetry and no Docker requirement for a normal scan.

npm release license go

Status: 0.1.0. The deterministic engine is usable today. LLM output is advisory, rule coverage is still growing, and Vigil is not a replacement for a pentest. Treat every finding as a lead to verify, not a verdict.

Why Vigil

  • Your model, your keys. OpenAI, Anthropic, Gemini, OpenRouter, Groq, DeepSeek, Mistral, xAI, Ollama, LM Studio, or any OpenAI-compatible endpoint. No proxy, no cloud account, no telemetry.
  • Deterministic first. The rules run before any model call. A provider outage cannot hide a hardcoded secret or a shell injection.
  • Fits the agent you already use. One 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. Scans never modify the tree. vigil fix --apply writes a validated unified diff and never commits; the baseline and report commands write only their own files. Secrets are masked in output.
  • 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.

How it works

 repository
     |
     v
 +-----------------+     +--------------------------+     +-------------------+
 | walker + ignore |---->| 100+ deterministic rules |---->| findings          |
 | size + binary   |     | secrets injection crypto |     | severity evidence |
 +-----------------+     | auth web config CI deps  |     +-------------------+
                         +--------------------------+              |
                                                                  v
                        +------------------------------------------------------+
                        | optional, on your model: triage, deep review,        |
                        | fix diff, STRIDE threat model                        |
                        +------------------------------------------------------+
                                                                  |
                                                                  v
                        +------------------------------------------------------+
                        | baseline -> report (md/json/sarif/html) -> history   |
                        |                                  -> MCP resources     |
                        +------------------------------------------------------+

The model never replaces deterministic evidence. A failed or missing model is a warning, not a failed scan. See docs/architecture.md.

Install

npm i -g lv24-vigil

The npm package selects a platform package (@lv24/vigil-<os>-<cpu>) at install time and runs no install scripts.

Other options:

# Go 1.27+
go install github.com/levapveeskela/lv24-vigil/cmd/vigil@latest

Standalone binaries and installers are published with GitHub releases. A distroless Dockerfile is included for container use. Details: docs/install.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                         # resolved provider, model and config sources
vigil rules                          # the rule catalog (source of truth)
vigil scan --format sarif --fail-on high
vigil review --base origin/main --format sarif --fail-on high
vigil fix VGL-XXXXXXXXXX             # print a proposed unified diff
vigil fix VGL-XXXXXXXXXX --apply     # write it to the working tree, never commit
vigil threat-model                   # STRIDE-style markdown, needs a model
vigil report --format html > report.html

vigil scan with no path scans the current directory. A finding ID comes from a previous scan or report. Full command reference: docs/cli.md.

Use it from your coding agent (MCP)

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

OpenCode - .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"]
    }
  }
}

Then ask your agent: "Scan this repository with Vigil and explain the top three findings." Setup details, tools, resources and prompts: 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.

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
Ollama ollama none qwen2.5-coder:14b
LM Studio lmstudio none local-model
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

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.

What it checks

Category Prefix Rules Looks for
Secrets VGL-SEC 24 cloud keys, tokens, private keys, connection strings, .env leaks
Injection VGL-INJ 36 SQL, shell, code eval, XSS, deserialization, SSTI, prototype pollution
Crypto VGL-CRY 12 weak hashes/ciphers, ECB, static IVs, bad randomness, TLS verify off, JWT none
Auth VGL-AUTH 9 unverified JWTs, cookie flags, CORS + credentials, CSRF, default passwords
Web VGL-WEB 12 SSRF, path traversal, open redirect, CORS, debug endpoints, host header
Config / IaC VGL-CFG 17 Docker, Compose, Kubernetes, Terraform, nginx, committed env files
CI VGL-CI 11 unpinned actions, pull_request_target, script injection, secrets in logs
Dependencies VGL-DEP 7 missing lockfiles, wildcard versions, git/HTTP installs, TLS bypass

Representative IDs: VGL-SEC-002 (critical, AWS secret key), VGL-SEC-011 (critical, private key), VGL-INJ-001 (high, JS code execution), 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).

Model-only findings use VGL-AI-001 and are marked as LLM-sourced. The CLI vigil rules is the authoritative list. More: docs/rules.md.

MCP tools

Tool What it does Writes?
vigil_scan Scan a repository or directory no
vigil_review Review only changed lines or a supplied diff no
vigil_explain Explain one finding in context no
vigil_fix Propose a unified diff; apply=true writes it apply=true only
vigil_threat_model Generate a STRIDE-style threat model no
vigil_status Provider, model, engine and store status no
vigil_rules List detection rules no
vigil_baseline Inspect or update the suppression baseline baseline file only
vigil_report Render a stored scan as md/json/sarif/html only when path is supplied
vigil_verify Re-check whether a finding is still present no
vigil_history List recent scans from the local store no

Resources: vigil://status, vigil://rules, vigil://scan/last, vigil://scan/<id>. Prompts: security_review, threat_model, fix_finding.

Every tool returns a useful text result even when no model is configured; the deterministic findings are never blocked by an LLM outage.

CI

vigil review --base origin/main --format sarif --fail-on high > vigil.sarif

Upload the result with github/codeql-action/upload-sarif and keep the workflow at fetch-depth: 0. The repository ships a composite action in action.yml; the example below uses the CLI directly so it also works on any runner.

- uses: actions/checkout@v4
  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@v3
  with: { sarif_file: vigil.sarif }

Fork pull requests do not receive repository secrets; without a key Vigil still runs the deterministic rules. Full guide: docs/ci.md.

Security model

  • Local-first. No Vigil cloud, no telemetry, no analytics, no account.
  • Read-only by default. A scan writes nothing. The write paths are vigil_fix with apply=true (or vigil fix --apply), the baseline command, an explicitly requested report file, and vigil init. A fix never commits and never stages.
  • 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.
  • Secrets are masked. Detected credentials are redacted in evidence, snippets and reports. Raw secret values are never printed by the rule engine.
  • 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, binary patches and .git edits are rejected, hunk counts must match, and git apply --check runs before any write.

Details and limits: docs/security-model.md.

How Vigil compares

Strix (usestrix/strix) Vigil Hosted scanner
What it is autonomous pentesting agent static + LLM auditor managed service
Runs where sandbox, Docker required your machine or CI vendor cloud
Actively exploits targets yes no varies
Fits a coding agent via MCP separate integration first-class usually not
Code leaves your machine to your model only to your model, if enabled yes
Best for validating exploitable issues fast, local, repeatable checks teams without local setup

Vigil and Strix are complementary: Vigil finds cheap, deterministic issues while you write code; Strix validates deeper issues in an authorized sandbox. See docs/comparison.md and the LV24 fork analysis in docs/lv24-security-analysis.md.

Roadmap

Not commitments, just direction:

  • broader language and framework coverage for the injection and auth packs;
  • better data-flow rules without turning Vigil into a full SAST engine;
  • smoother baseline and suppression workflows;
  • more MCP client recipes and editor integrations;
  • translated docs beyond the current English set.

Documentation

Document Contents
docs/install.md npm, Go, installers, binaries, container
docs/providers.md providers, keys, local models, config precedence
docs/mcp.md MCP clients, tools, resources, prompts
docs/cli.md commands, flags, exit codes, formats
docs/rules.md rule families, representative IDs, baseline
docs/ci.md GitHub Actions, SARIF, fork PRs, baselines
docs/security-model.md egress, masking, prompt safety, limits
docs/architecture.md packages, pipeline, design decisions
docs/troubleshooting.md common failures and fixes
docs/comparison.md Vigil vs Strix vs hosted scanners
docs/lv24-security-analysis.md Strix upstream sync and the LV24 fork

Russian overview: README.ru.md. Changes: CHANGELOG.md. Contributing: CONTRIBUTING.md. Security reports: SECURITY.md.

License

Apache-2.0. See LICENSE.

Directories

Path Synopsis
cmd
vigil command
Command vigil is the CLI and MCP server entry point.
Command vigil is the CLI and MCP server entry point.
internal
analysis
Package analysis implements the model-assisted half of Vigil: triage of deterministic findings, deep review of high-risk files, fix proposals, explanations and repository threat models.
Package analysis implements the model-assisted half of Vigil: triage of deterministic findings, deep review of high-risk files, fix proposals, explanations and repository threat models.
app
Package app wires configuration, the rule registry, the scanner, the LLM analyzer and the scan store into one object used by the CLI and the MCP server.
Package app wires configuration, the rule registry, the scanner, the LLM analyzer and the scan store into one object used by the CLI and the MCP server.
config
Package config resolves Vigil's configuration from defaults, a user config file, a project config file and environment variables, in that order.
Package config resolves Vigil's configuration from defaults, a user config file, a project config file and environment variables, in that order.
gitutil
Package gitutil provides the small, read-only git operations Vigil needs: finding the repository root, listing changed files, producing a unified diff and checking whether a proposed fix applies.
Package gitutil provides the small, read-only git operations Vigil needs: finding the repository root, listing changed files, producing a unified diff and checking whether a proposed fix applies.
llm
Package llm defines the provider-neutral model client used for triage, deep review and fix generation.
Package llm defines the provider-neutral model client used for triage, deep review and fix generation.
mcp
Package mcp implements the Model Context Protocol server transport and the JSON-RPC types Vigil exposes.
Package mcp implements the Model Context Protocol server transport and the JSON-RPC types Vigil exposes.
model
Package model holds the shared domain types for Vigil.
Package model holds the shared domain types for Vigil.
report
Package report renders scan results as Markdown, JSON, SARIF or HTML.
Package report renders scan results as Markdown, JSON, SARIF or HTML.
rules
Package rules contains the deterministic detection rules and the engine that runs them over files.
Package rules contains the deterministic detection rules and the engine that runs them over files.
scanner
Package scanner walks a repository, selects the files that should be inspected, runs the deterministic rules with a worker pool and applies baselines and unified-diff filtering.
Package scanner walks a repository, selects the files that should be inspected, runs the deterministic rules with a worker pool and applies baselines and unified-diff filtering.
store
Package store persists scan history on disk.
Package store persists scan history on disk.
tools
Package tools implements Vigil's MCP surface: the vigil_* tools, the vigil:// resources and the review prompts.
Package tools implements Vigil's MCP surface: the vigil_* tools, the vigil:// resources and the review prompts.
version
Package version holds build metadata injected by GoReleaser.
Package version holds build metadata injected by GoReleaser.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL