Metadata-Version: 2.4
Name: pentestai-cli
Version: 0.1.0
Summary: PentestAI - AI-assisted pentest CLI workflow (recon -> analysis -> scan -> validate -> report)
Author: Dinhvaren
License: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Requires-Dist: pydantic==2.10.6
Requires-Dist: pyyaml==6.0.2
Requires-Dist: python-dotenv==1.0.1
Requires-Dist: httpx==0.27.2
Requires-Dist: click==8.1.7
Dynamic: license-file

# PentestAI

**PentestAI** is a **CLI-first, AI-assisted penetration testing framework** for Linux.
It combines **real pentest tools** with **multiple LLM providers** to support analysis, validation, and reporting — **without replacing the pentester**.

PentestAI is designed to be used **from anywhere on your system**, not tied to the project directory.

## What PentestAI Is (and Is Not)

**PentestAI IS**

* A CLI tool for **authorized penetration testing**
* AI-assisted **analysis, triage, validation, and reporting**
* Built on real tools: `subfinder`, `httpx`, `nmap`, `nuclei`
* Safe-by-default, scope-aware

**PentestAI IS NOT**

* An auto-exploitation framework
* A payload generator
* A replacement for human decision-making

> **Human-in-the-loop by design.**

## Requirements

* Linux (Parrot / Kali / Ubuntu recommended)
* Python **3.12+**
* Pentest tools in `$PATH`:

  * `subfinder`
  * `httpx`
  * `nmap`
  * `nuclei`

## Installation

```bash
git clone https://github.com/dinhvaren/PentestAI.git
cd PentestAI

python -m venv .venv
source .venv/bin/activate

pip install -e .
```

After installation, the command `pentestai` is available **globally inside the virtual environment**.


## Configuration (IMPORTANT)

PentestAI is designed to be run **outside the project directory**.

### 1. Set config path via environment variable

```bash
export PENTESTAI_CONFIG=/absolute/path/to/PentestAI/config.yaml
```

(Optional – persist across sessions)

```bash
echo 'export PENTESTAI_CONFIG=/absolute/path/to/PentestAI/config.yaml' >> ~/.zshrc
source ~/.zshrc
```

> This allows you to run `pentestai` from **any directory** (e.g. `~/`, `/tmp`, `/home/user/targets`).

### 2. `.env` (API keys – private)

Create `.env` **next to `config.yaml`**:

```env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
DEEPSEEK_API_KEY=sk-...
```

### 3. `config.yaml` (public)

Minimal example:

```yaml
workspace_root: "workspaces"
safe_mode_default: true

ai:
  default_provider: openai
  fallback_providers: [anthropic, gemini, deepseek]

  routing:
    surface: [openai, anthropic, gemini, deepseek]
    triage:  [anthropic, openai, gemini, deepseek]
    report:  [openai, anthropic, gemini, deepseek]

  providers:
    openai:
      api_key_env: OPENAI_API_KEY
      model: gpt-4.1-mini
      base_url: https://api.openai.com/v1
```

## Usage (Quick Start)

You can now run PentestAI **from any directory**.

### Initialize a target workspace

```bash
pentestai init --target example.com --scope "*.example.com"
```

### Reconnaissance

```bash
pentestai recon run --target example.com
```

### AI Attack Surface Analysis

```bash
pentestai surface analyze --target example.com
```

### Vulnerability Scanning

```bash
pentestai scan run --target example.com
```

### Validation & Triage (AI-assisted)

```bash
pentestai validate run --target example.com
```

### Report Generation

```bash
pentestai report build --target example.com
```

Reports are written to:

```text
workspaces/example.com/reports/report.md
```

## Commands & Advanced Usage

For **full command list, flags, and examples**, see:

* `docs/command.md`
* `docs/usage.md`

These documents cover:

* All CLI flags
* Safe / unsafe mode
* AI provider routing
* Dry-run usage
* Advanced scanning options

## Legal & Ethical Use

PentestAI **must only be used on systems you own or have explicit authorization to test**.

By using this tool, you agree that:

* You are responsible for authorization and scope
* You will not use this tool illegally
* You understand AI does not perform exploitation

## Contributing

Contributions are welcome.

See:

* `docs/contributing.md`
* `docs/security.md`

You can contribute by:

* Adding tool plugins
* Adding AI providers
* Improving prompts
* Improving documentation

## License

MIT License
See `LICENSE`.

## Why PentestAI?

PentestAI is built for:

* Students learning real pentest workflows
* Security interns & junior pentesters
* Professionals who want faster analysis & cleaner reports
* Open-source contributors interested in **AI + security**

If PentestAI helps you, consider starring the project.
