Metadata-Version: 2.4
Name: zimkk-vigil
Version: 0.1.0
Summary: AI-powered red teaming harness
Author: Hassan Nazir
License-Expression: MIT
Project-URL: Homepage, https://github.com/zimkk/vigil
Project-URL: Repository, https://github.com/zimkk/vigil
Project-URL: Issues, https://github.com/zimkk/vigil/issues
Project-URL: Releases, https://github.com/zimkk/vigil/releases
Keywords: security,red-team,pentest,cli,automation,ai
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.40.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: dnspython>=2.6.0
Requires-Dist: python-whois>=0.9.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: pypdf>=4.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: textual>=0.80.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="vigil-brand/svg/vigil-lockup-stacked.svg" alt="Vigil" height="120" />
</p>

<p align="center">
  <strong>Open-source AI-assisted red-team orchestration framework</strong>
</p>

<p align="center">
  <a href="https://github.com/zimkk/vigil/releases"><img src="https://img.shields.io/github/v/release/zimkk/vigil?color=C24A22&label=version" alt="version"></a>
  <a href="https://pypi.org/project/zimkk-vigil/"><img src="https://img.shields.io/pypi/pyversions/zimkk-vigil?color=1C1C1A" alt="python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/zimkk/vigil?color=C24A22" alt="license"></a>
</p>

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](./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+.

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

Or install from Python tooling:

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

For development:

```bash
pip install -e .[dev]
```

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

```bash
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](./redteam/cli.py): CLI surface and entrypoint routing
- [redteam/tui/app.py](./redteam/tui/app.py): interactive TUI
- [redteam/core/controller.py](./redteam/core/controller.py): engagement controller, scheduler, snapshots
- [redteam/core/phase_execution.py](./redteam/core/phase_execution.py): normalized phase execution contract
- [redteam/core/context_store.py](./redteam/core/context_store.py): low-level SQLite access
- [redteam/core/repositories.py](./redteam/core/repositories.py): higher-level repository layer
- [redteam/core/runtime_schema.py](./redteam/core/runtime_schema.py): runtime schema versioning and normalization
- [redteam/modules/reporting/orchestrator.py](./redteam/modules/reporting/orchestrator.py): deterministic report assembly

For fuller detail, see [current_architecture.md](./current_architecture.md).

## Usage

Passive recon:

```bash
vigil enumerate example.com
```

Controller-driven run:

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

Single phase through controller:

```bash
vigil engage-phase 127.0.0.1 --phase reporting
```

Export engagement status:

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

Generate final report:

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

List registered tools for a phase:

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

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

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

```bash
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](./LICENSE).

<p align="center">
  <img src="vigil-brand/svg/vigil-mark.svg" alt="" height="32" />
</p>
