Open-source AI-assisted red-team orchestration framework

Vigil is an MIT-licensed Python project for orchestrating authorized red-team workflows from a CLI or Textual TUI. It combines phase-specific tool registries, multi-step orchestration, SQLite-backed runtime state, and deterministic reporting.

License

This project is open source under the MIT License.

Features

• 18 canonical engagement phases from passive recon through reporting
• CLI entrypoint: vigil
• Textual TUI for interactive operation
• controller-driven engagement flow with queueing, snapshots, and resume support
• SQLite runtime state with schema normalization and legacy phase alias cleanup
• deterministic final reporting from persisted evidence
• direct phase commands and controller-driven engage-* commands
• support for Anthropic and OpenAI-compatible backends

Install

Requires Python 3.11+.

curl -sSfL https://raw.githubusercontent.com/zimkk/vigil/main/install.sh | bash

Or install from Python tooling:

pipx install zimkk-vigil
# or
pip install zimkk-vigil

For development:

pip install -e .[dev]

Until first PyPI release is published, Git install also works:

pipx install git+https://github.com/zimkk/vigil.git

Canonical phase model

Published package name is zimkk-vigil. Installed command remains vigil.

Vigil currently uses these 18 canonical phases:

1. passive_recon
2. active_recon
3. vulnerability_assessment
4. validation
5. exploitation
6. post_exploitation
7. privilege_escalation
8. credential_access
9. discovery
10. lateral_movement
11. persistence
12. defense_evasion
13. c2
14. collection
15. exfiltration
16. impact
17. cleanup
18. reporting

Legacy aliases such as enumeration and vuln_assessment are normalized to canonical names in runtime maintenance and reporting flows.

Main commands

Direct phase commands

Command	Canonical phase
vigil enumerate	passive_recon
vigil active	active_recon
vigil assess	vulnerability_assessment
vigil validate	validation
vigil exploit	exploitation
vigil post-exploit	post_exploitation
vigil privesc	privilege_escalation
vigil cred-access	credential_access
vigil discover	discovery
vigil lateral	lateral_movement
vigil persist	persistence
vigil evade	defense_evasion
vigil c2	c2
vigil collect	collection
vigil exfil	exfiltration
vigil impact	impact
vigil cleanup	cleanup
vigil report	reporting

Controller and maintenance commands

• vigil engage-run
• vigil engage-phase
• vigil engage-status
• vigil engage-report
• vigil db-maintain
• vigil tools

Architecture summary

Current core architecture:

• redteam/cli.py: CLI surface and entrypoint routing
• redteam/tui/app.py: interactive TUI
• redteam/core/controller.py: engagement controller, scheduler, snapshots
• redteam/core/phase_execution.py: normalized phase execution contract
• redteam/core/context_store.py: low-level SQLite access
• redteam/core/repositories.py: higher-level repository layer
• redteam/core/runtime_schema.py: runtime schema versioning and normalization
• redteam/modules/reporting/orchestrator.py: deterministic report assembly

For fuller detail, see current_architecture.md.

Usage

Passive recon:

vigil enumerate example.com

Controller-driven run:

vigil engage-run 127.0.0.1 --authorize --notes "Authorized lab target only"

Single phase through controller:

vigil engage-phase 127.0.0.1 --phase reporting

Export engagement status:

vigil engage-status 127.0.0.1 --json-output snapshot.json

Generate final report:

vigil report 127.0.0.1 --authorize --output report.md --json-output report.json

List registered tools for a phase:

vigil tools enumerate

LLM backend

Vigil works with Anthropic by default and also supports OpenAI-compatible endpoints such as Ollama, vLLM, LM Studio, and OpenRouter.

Example .env:

# Anthropic
VIGIL_BACKEND=anthropic
VIGIL_API_KEY=sk-ant-...
VIGIL_MODEL=claude-sonnet-4-6

# OpenAI-compatible
VIGIL_BACKEND=openai_compat
VIGIL_BASE_URL=http://localhost:11434/v1
VIGIL_API_KEY=ollama
VIGIL_MODEL=qwen2.5:7b

External tools

Vigil integrates with real security binaries. Install supported dependencies:

curl -sSfL https://raw.githubusercontent.com/zimkk/vigil/main/install-tools.sh | bash

Support spans multiple tool families including recon, scanning, validation, and reporting helpers. Tool registration still relies on module import side effects, so keeping imports intact is part of runtime correctness.

Testing

Current test layout:

• tests/conftest.py
• tests/contracts/
• tests/integration/
• tests/e2e/

Recent verified local state on August 11, 2026:

• 32 passed

Release and PyPI publishing

Repository now includes GitHub Actions workflows for CI and PyPI publishing:

• .github/workflows/ci.yml
• .github/workflows/publish-pypi.yml

PyPI publishing path is configured for Trusted Publishing with distribution name zimkk-vigil.

One-time setup still required on GitHub and PyPI:

1. In GitHub repository settings, create environment pypi.
2. In PyPI, create or prepare project zimkk-vigil.
3. In PyPI project settings, add Trusted Publisher:
   • owner: zimkk
   • repository: vigil
   • workflow: publish-pypi.yml
   • environment: pypi
4. Publish a GitHub Release to trigger upload.

After first publish, public install should be:

pipx install zimkk-vigil

Legal and safety

Use Vigil only against systems you own or are explicitly authorized to test. Many commands invoke real reconnaissance and offensive-security tooling. Operator is responsible for scope control, authorization, and safe usage.

Software is provided under MIT License, without warranty. See LICENSE.