Skip to main content
Glama
README.md
![Vigil — security audit on your own model](.github/assets/banner.svg)

# Vigil

[![npm](https://img.shields.io/npm/v/lv24-vigil?label=npm&color=cb3837&logo=npm)](https://www.npmjs.com/package/lv24-vigil)
[![downloads](https://img.shields.io/npm/dm/lv24-vigil?color=cb3837)](https://www.npmjs.com/package/lv24-vigil)
[![GitHub Marketplace](https://img.shields.io/badge/GitHub_Marketplace-Vigil-6C5CE7?logo=github)](https://github.com/marketplace/actions/vigil-security-scan)
[![release](https://img.shields.io/github/v/release/LevapVeeskela/lv24-vigil?color=0b6b5f&logo=github)](https://github.com/LevapVeeskela/lv24-vigil/releases)
[![license](https://img.shields.io/badge/license-Apache--2.0-2ea44f)](LICENSE)
[![Go](https://img.shields.io/badge/Go-1.27-00ADD8?logo=go&logoColor=white)](go.mod)
[![MCP](https://img.shields.io/badge/MCP-stdio-6C5CE7)](docs/mcp.md)
[![OpenCode Go](https://img.shields.io/badge/OpenCode_Go-supported-6C5CE7)](docs/providers.md)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/LevapVeeskela/lv24-vigil/badge)](https://securityscorecards.dev/viewer/?uri=github.com/LevapVeeskela/lv24-vigil)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://pre-commit.com)
[![Go Reference](https://pkg.go.dev/badge/github.com/levapveeskela/lv24-vigil.svg)](https://pkg.go.dev/github.com/levapveeskela/lv24-vigil)

**Docs:** English · [Русский](README.ru.md) · [Documentation](docs/) · [llms.txt](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.

| 🚀 Start | 🧠 Use | 🛠 Operate |
| --- | --- | --- |
| [Install](#install) · [See it work](#see-it-work) · [Quickstart](#60-second-quickstart) | [MCP setup](#mcp-setup) · [For AI agents](#for-ai-agents) · [Providers](#providers) · [Rules](#rules) | [CI & SARIF](#ci-sarif-and-precheck) · [Safety](#safety) · [Docs](#documentation) |

> **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:

```text
$ 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:

```bash
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 and self-contained HTML |
| 🧾 | **Baseline** | Suppresses accepted findings so only new issues fail a gate |
| 🧰 | **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 |
| 🚦 | **CI gate** | `--fail-on`, exit code `2`, SARIF upload and `vigil precheck` |

## Install

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

```bash
npm i -g lv24-vigil@latest
vigil version
```

Or run it without a global install:

```bash
npx -y lv24-vigil scan --no-llm
npx -y lv24-vigil mcp
```

### Package choice

| 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. 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:

```bash
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:

```bash
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](https://github.com/LevapVeeskela/lv24-vigil/releases). Options
and manual verification: [docs/install.md](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](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](docs/mcp-registry.md). Other MCP catalogues and the status
of each submission: [docs/mcp-directories.md](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:

```bash
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:

```bash
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](docs/install.md#container) and [docs/container.md](docs/container.md).

### Verify

```bash
vigil version   # build metadata
vigil status    # resolved provider, model, rules, store and last scan
vigil rules     # the authoritative rule catalog
```

## 60-second quickstart

```bash
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:

```bash
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](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`):

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

**Claude Code**:

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

**Codex** — `~/.codex/config.toml`:

```toml
[mcp_servers.vigil]
command = "npx"
args = ["-y", "lv24-vigil", "mcp"]
```

**Cursor** — `~/.cursor/mcp.json`:

```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 | 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:

```text
Scan this repository with Vigil and explain the top three findings.
```

Client recipes and protocol details: [docs/mcp.md](docs/mcp.md) ·
[Cursor](examples/cursor.md) · [Claude Code](examples/claude-code.md) ·
[Codex](examples/codex.md).

## For AI agents

If you are an agent, these are the stable contracts. Prefer them over scraping
prose.

```json
{
  "package": "lv24-vigil",
  "install": "npm i -g lv24-vigil",
  "binary": "vigil",
  "mcp": { "command": "npx", "args": ["-y", "lv24-vigil", "mcp"] },
  "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",
  "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"
  ],
  "exit_codes": { "0": "clean", "1": "error", "2": "findings at or above --fail-on" },
  "docs_index": "llms.txt"
}
```

Rules that matter when you drive it:

1. **Install `lv24-vigil` only.** Never install `@lv24/vigil-<os>-<cpu>`
   directly; it is an optional dependency selected by the launcher.
2. **No model? Use `--no-llm`.** All 263 deterministic rules still run and
   produce findings. A missing model is a warning, not a failed scan.
3. **Do not parse the human summary.** Use `--format json`, `vigil status
   --json`, or an MCP tool. stdout carries the report; logs go to stderr.
4. **Fixes need confirmation.** Call `vigil_fix` with `apply=false` first, show
   the diff, and only then apply. Vigil never commits or stages.
5. **Respect the boundary.** Scan only the requested path. Do not upload code
   anywhere except the model endpoint the user configured.
6. **No telemetry.** There is no Vigil cloud, account, analytics or update
   check. `vigil precheck` is the only explicit upload and needs a staff JWT.

Full agent index: [`llms.txt`](llms.txt) · onboarding:
[`AGENTS.md`](AGENTS.md) · client recipes: [docs/mcp.md](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:

```bash
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:

```yaml
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](docs/providers.md) · keyless example:
[examples/config.command.yaml](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:

```bash
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](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:

```yaml
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](docs/rules.md#inline-suppressions).

Severity, confidence, baseline and masking details:
[docs/rules.md](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.
- **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](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`](examples/github-workflow.yml) |
| Block merge requests and `main` on GitLab | GitLab CI | copy [`examples/gitlab-ci.yml`](examples/gitlab-ci.yml) |
| Record evidence in the LV24 control plane | Optional pre-check | set `VIGIL_SECURITY_API_TOKEN` |

### Local hook (fastest, offline)

```bash
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](https://pre-commit.com) 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](docs/pre-commit.md).

### GitHub Actions (PR, `main`, manual)

The same action is listed on the [GitHub Marketplace](https://github.com/marketplace/actions/vigil-security-scan). Use `uses: LevapVeeskela/lv24-vigil@v0.9.3`; add `version: 0.9.3` when the CLI must match the action tag.

Copy [`examples/github-workflow.yml`](examples/github-workflow.yml) to
`.github/workflows/vigil.yml`:

```yaml
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`](examples/gitlab-ci.yml) to `.gitlab-ci.yml`:

```yaml
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](docs/ci.md).

## CI, SARIF and precheck

```bash
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:

```yaml
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:

```bash
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](docs/ci.md) · example:
[examples/github-workflow.yml](examples/github-workflow.yml).

## Documentation

| Document | Contents |
| --- | --- |
| [docs/install.md](docs/install.md) | npm, Go, installers, deb/rpm/apk, binaries, container |
| [docs/cli.md](docs/cli.md) | Commands, flags, exit codes, formats |
| [docs/mcp.md](docs/mcp.md) | MCP clients, tools, resources, prompts |
| [docs/providers.md](docs/providers.md) | Providers, keys, local models, config precedence |
| [docs/rules.md](docs/rules.md) | Rule families, representative IDs, baseline |
| [docs/security-model.md](docs/security-model.md) | Egress, masking, prompt safety, limits |
| [docs/ci.md](docs/ci.md) | GitHub Actions, SARIF, fork PRs, prechecks |
| [docs/architecture.md](docs/architecture.md) | Packages, pipeline, design decisions |
| [docs/troubleshooting.md](docs/troubleshooting.md) | Common failures and fixes |
| [docs/comparison.md](docs/comparison.md) | Vigil vs Strix vs hosted scanners |
| [docs/release.md](docs/release.md) | Release pipeline, npm Trusted Publishing, re-runs |
| [docs/pypi.md](docs/pypi.md) | Python launcher and PyPI publishing |
| [docs/history.md](docs/history.md) | The `dist-0.1.4` incident and repository history |
| [docs/lv24-security-analysis.md](docs/lv24-security-analysis.md) | Strix upstream sync and the LV24 fork |
| [llms.txt](llms.txt) | Plain-text index for AI agents |
| [AGENTS.md](AGENTS.md) | Short onboarding for coding agents |

Russian overview: [README.ru.md](README.ru.md) · changes:
[CHANGELOG.md](CHANGELOG.md) · contributing: [CONTRIBUTING.md](CONTRIBUTING.md) ·
security reports: [SECURITY.md](SECURITY.md).

## License

Apache-2.0. See [LICENSE](LICENSE).