pentestai-cli 1.1.0
PentestAI - AI-assisted pentest CLI workflow (recon -> analysis -> scan -> validate -> report)
License: MIT
Requires Python: >=3.12

# PentestAI

**PentestAI** is a **CLI-first, AI-assisted penetration testing framework** for Linux.

It combines **real-world pentest tools** with **multiple LLM providers** to assist with
analysis, triage, validation, and reporting — **without replacing the pentester**.

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

## What PentestAI Is (and Is Not)

### PentestAI IS

- A CLI tool for **authorized penetration testing**
- AI-assisted **analysis, validation, triage, 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

## Requirements

- Linux (Parrot / Kali / Ubuntu recommended)
- Python **3.12+**
- The following tools available in `$PATH`:
  - `subfinder`
  - `httpx`
  - `nmap`
  - `nuclei`

## Installation (Recommended)

```bash
pip install pentestai-cli
```
Verify installation:

```bash
pentestai --help
```

## API Keys Configuration (REQUIRED)

PentestAI uses **environment variables** for AI providers.

You must export **at least one API key** before running.

### OpenAI (default)

```bash
export OPENAI_API_KEY="sk-..."
```

(Optional – persist across sessions)

```bash
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.bashrc
source ~/.bashrc
```

### Optional Providers

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="AIza..."
export DEEPSEEK_API_KEY="sk-..."
```

PentestAI will automatically route AI requests based on availability.

## Workspace Behavior (Automatic)

PentestAI **automatically creates a workspace directory** per target.

Default location:

```text
/home/<user>/workspaces/
```

Example:

```text
/home/user/workspaces/example.com/
├── recon/
├── scan/
├── validate/
└── reports/
```

You do **not** need to create this manually.

## Quick Start

PentestAI can be run **from any directory**.

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

## Required External Tools

Ensure the following tools are installed:

```bash
which subfinder httpx nmap nuclei
```

## Design Philosophy

* CLI-first
* Human-in-the-loop
* Safe-by-default
* AI assists analysis — **never auto-exploits**
* Works anywhere on the filesystem

## Legal & Ethical Use

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

## Notes for Advanced Users

* No `config.yaml` required for default usage
* Workspace paths are auto-resolved per user
* AI provider routing is handled internally
* Future versions may expose optional configuration overrides

## Contributing

Contributions are welcome.

You can contribute by:

* Adding tool integrations
* Improving AI prompts
* Improving reports
* 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 and cleaner reports
* Open-source contributors interested in **AI + security**

If PentestAI helps you, consider starring the project.