pentestai-cli 0.1.0

PentestAI - AI-assisted pentest CLI workflow (recon -> analysis -> scan -> validate -> report)

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

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

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

(Optional – persist across sessions)

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:

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

3. config.yaml (public)

Minimal example:

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

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

Reconnaissance

pentestai recon run --target example.com

AI Attack Surface Analysis

pentestai surface analyze --target example.com

Vulnerability Scanning

pentestai scan run --target example.com

Validation & Triage (AI-assisted)

pentestai validate run --target example.com

Report Generation

pentestai report build --target example.com

Reports are written to:

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.