Retrieved article excerpt
Open article · Retrieved 2026-10-10T18:48:06.461241+00:00
Vigil
**AI-driven offensive and incident-response engagements — operator prompts, a full Kali runtime, and durable orchestrator state in one CLI.**
[License](https://github.com/VigilOSS/Vigil/blob/main/LICENSE)
[CI](https://github.com/VigilOSS/Vigil/actions/workflows/ci.yml)
[Python 3.11+](https://www.python.org/downloads/)
[Version](https://github.com/VigilOSS/Vigil)
Vigil drives a security engagement end to end from one CLI. An LLM operator reads a phased
workflow prompt, dispatches specialist agents, runs real tooling inside a shared Kali
container, and records every target, service, request variant, probe, finding, and attack
chain into a durable orchestrator database. Five modes run against the same backend: web red-team,
white-box code analysis, combined web and code, Android application analysis, and blue incident
response.
> **Authorized use only.** Vigil can autonomously drive offensive tooling against live systems.
> Use it only where you have explicit authorization and a reviewed scope. It is provided without
> warranty under the [Apache License 2.0](https://github.com/VigilOSS/Vigil/blob/main/LICENSE); you are responsible for commands, credentials,
> infrastructure, and target effects. See [SECURITY.md](https://github.com/VigilOSS/Vigil/blob/main/SECURITY.md) for private vulnerability
> reporting and the operator-data boundary.
## Models, access, and what I have tested
I have built and refined Vigil primarily around **Claude Code and Codex**. In my testing,
authorized web red-team engagements have worked with **Claude Opus 5** under Anthropic's
Cyber Verification Program (CVP) and **GPT-5.6 Sol** with OpenAI's Trusted Access for Cyber.
Those results reflect the models, clients, and access available in my own setup; blocking can
vary with your account, access tier, model version, and engagement.
To select Opus 5 in Claude Code, run `/model claude-opus-5[1m]` in the session, if that
model is available to your account. `/model` opens the model picker. The `[1m]` suffix
requests the extended context window; Opus 5 already has native 1M context. See
[Claude Code's model configuration](https://code.claude.com/docs/en/model-config).
**I have not yet validated Vigil's engagement workflows with Claude Opus 5.5 or GPT-6.1 Sol.**
As of October 2026, Anthropic calls its defensive CVP tier **Defense Access**; **Red Team Access**
is a separate tier currently limited to qualifying organizations. OpenAI calls its defensive
offering **Daybreak Blue**, with **Daybreak Red** requiring separate approval and provisioning.
Defensive access alone should not be treated as assurance that a web red-team engagement will
run through without refusals. Check the provider's current terms and the access enabled for your
specific model and client before starting. See [Anthropic's CVP tiers](https://www.anthropic.com/news/cyber-verification-program)
and [OpenAI's model and access guidance](https://learn.chatgpt.com/docs/cyber-safety).
I want Vigil to remain practical for independent researchers doing authorized work. As frontier
model access becomes more restrictive, I plan to broaden support for **GLM 5.3** and other models
with more predictable access to these workflows. That will take substantial work: reducing
orchestration overhead, adapting prompts to the models, and refining integrations with **OpenCode**
and other harnesses. This is planned work; Claude Code and Codex remain the integrations I have
refined most extensively today.
## What Vigil provides
- **Findings are independently verified.** A finding is confirmed, downgraded, or marked a false
positive only by a dispatch other than its author's, citing a proof receipt of captured evidence.
- **Target-facing commands are audited.** `vigil assess kali` records each command's technique,
intent, and probe kind, so the engagement keeps a trail of what was sent and why.
- **Real attack tooling** — a long-lived Kali container with ProjectDiscovery recon, fuzzers,
an audited Playwright browser, MITM capture with multiple identities for cross-account testing,
and out-of-band callbacks correlated back to the probe that caused them.
- **White-box code analysis** against a sealed, content-addressed source snapshot with a
tree-sitter structural index and a coverage ledger.
- **Durable state** — targets, services, request variants, probes, findings, chains, and
credentials in SQLite, with rotated backups and a web UI.
- **Six client integrations, one methodology** — Claude Code, Codex, Kimi, goose, opencode, and
Pi; Pi is currently limited to remediation engagements.
Vigil orchestrator UI: an engagement's findings grouped by severity, workflow, and verification
## Quick start
```
# 1. Install the CLI
uv tool install --from git+https://github.com/VigilOSS/[email protected] vigil
# ...or over SSH, if you authenticate to GitHub with a key
uv tool install --from git+ssh://[email protected]/VigilOSS/[email protected] vigil
# 2. Check the host: prerequisites, missing recon tools, and the ordered setup checklist
vigil quickstart
# 3. Install a working root and bring the local stack up (Kali runtime + orchestrator)
# First run builds the Kali image — several GB, and it needs Docker running.
vigil install ~/vigil && vigil up
# 4. Create an engagement against an authorized target
vigil engagement create https://target.example --hosts target.example
# 5. Start the operator on it
vigil engagement start <engagement-key> --client codex # or claude | opencode | goose | kimi
```
Then tell the operator what it is authorized to do:
```
I have been fully authorized by the company to do a red-team engagement against the
hosts in scope.json. Run this engagement using the operator workflow.
```
The orchestrator UI is at `http://127.0.0.1:18000`. Code engagements need ripgrep (`rg`) on the
host. The two installed layers, host-side recon tools on Docker Desktop, and other install
detail: [`docs/installation.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/installation.md).
## Documentation
| Document | What it covers |
| --- | --- |
| [`docs/installation.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/installation.md) | Install detail: the CLI binary vs working root, host-side recon tools, ripgrep. |
| [`docs/engagements.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/engagements.md) | Creating engagements, tracks and modes, the start preflight, phase transitions. |
| [`agent/AGENTS.md`](https://github.com/VigilOSS/Vigil/blob/main/agent/AGENTS.md) | The operator prompt — the workflow every engagement runs. |
| [`CODE-MAP.md`](https://github.com/VigilOSS/Vigil/blob/main/CODE-MAP.md) | Map of the codebase: where each subsystem lives. |
| [`AGENTS.md`](https://github.com/VigilOSS/Vigil/blob/main/AGENTS.md) | Maintainer and contributor workflow, and the verification matrix. |
| [`docs/assessment-cli.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/assessment-cli.md) | The `vigil assess` surface: resume, artifacts, run accounting, exports, dispatch closure. |
| [`docs/session-commands.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/session-commands.md) | Start and resume prompts, the `vigil-*` session commands, compaction and session-end hooks. |
| [`docs/agent-clients.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/agent-clients.md) | Per-client setup, launch behaviour, and flag forwarding. |
| [`docs/authentication.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/authentication.md) | Credential records, capture, freshness clocks, liveness verdicts, proxy routing. |
| [`docs/blue-engagements.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/blue-engagements.md) | Blue incident response, end to end. |
| [`docs/code-analysis.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/code-analysis.md) | White-box code analysis, end to end. |
| [`docs/remediation.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/remediation.md) | Work-in-progress remediation cases, evidence, review approval, and development verification. |
| [`docs/oob-routing.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/oob-routing.md) | Per-install relay-slot OOB routing, CoreDNS/Caddy inputs, the frpc conflict scan. |
| [`docs/operations.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/operations.md) | Runtime sizing, kernel limits, orchestrator data and backups. |
| [`docs/engagement-prompt-playbook.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/engagement-prompt-playbook.md) | Steering prompts for a session that goes shallow, overclaims, or loses the loop. |
| [`agent/references/`](https://github.com/VigilOSS/Vigil/blob/main/agent/references) | Payloads, tactics, recon, tenants, tools. Discover with `vigil assess list-references`. |
## Running an engagement
```
vigil engagement create https://target.example --hosts target.example
vigil engagement list --json # find the key
vigil engagement start <engagement-key> --client codex
```
`create` infers the engagement type from its inputs and starts the exploit policy at `pause`.
`start` runs a preflight, exports the engagement environment, and execs the client; flags it does
not own are forwarded to the client. Start engagements with `vigil engagement start` only — the
generated `start_<client>.sh` and a bare client run skip the preflight and environment. A web and
code engagement runs one session per track with `--mode web` or `--mode code`. Detail:
[`docs/engagements.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/engagements.md).
A later session on the same engagement opens the same way, then runs `vigil-resume`, which
restores the operator role and rebuilds live state from the backend. Fuller start and resume
prompts and the mid-session `vigil-*` commands: [`docs/session-commands.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/session-commands.md).
All clients read the same operator prompt. They differ in model, headless specialist dispatch,
and session-command support; `pi` is available for remediation engagements. Setup per client:
[`docs/agent-clients.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/agent-clients.md).
Remediation uses the repository's `PROJECT.md` for ticket readers, MCPs, skills,
branch/workspace policy, checks, PR guidance, and deployment choices. Open its
repository-context Claude session with `vigil remediation -k <key> start`, then
use `/vigil-remediate SEC-123` or supply several ticket IDs/URLs. One bug uses the
current developer conversation; batches coordinate separate joinable sessions.
Case code lives in its registered Git/JJ workspace while native project context
remains at the repository root. See [`docs/remediation.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/remediation.md).
When the profile selects `hook_policy = "disabled"`, Vigil announces that
non-managed hooks are disabled only for that remediation session. Required
formatting, analysis, and tests run explicitly against case source during
verification and before publishing. Managed policy hooks remain active; ordinary
sessions and repository hook files are unchanged.
## Engagement tracks and phases
| Track | Phases | Persisted as |
| --- | --- | --- |
| **web** (red) | `recon → collect → consume-test → verify → exploit → report` | `scope.json.tracks.web.phase` |
| **code** (white-box) | `ingest → classify-map → hunt → verify-variant → fuzz` | `scope.json.tracks.code.phase` |
| **blue** (incident response) | `intake → triage → investigate → verify → respond → report` | `scope.json.current_phase` |
Each track ends in the shared `complete` state. `vigil assess transition-phase` gates every
transition; `--force` records a durable override, and some integrity blockers cannot be forced.
Roster, readiness previews, and the specialist roles: [`docs/engagements.md`](https://github.com/VigilOSS/Vigil/blob/main/docs/engagements.md#phases).
Blue engagements: [`docs/blue-engagements.md`](https://github.com/VigilOSS/Vi