ai-pentest-agent

AI Pentest Agent 🛡️🤖

The first open-source autonomous AI penetration testing agent skill.

Takes target → plans attack path → executes multi-phase pentest → generates CVSS-scored report. Pure Python stdlib, zero extra dependencies.

Problem

Existing pentest skills are manual tool catalogs — they list tools but don't plan or execute. Existing autonomous frameworks (PentaGI ⭐21K, HexStrike ⭐10.5K) are monolithic Go/Rust programs. There's nothing that tells an AI agent how to think about pentesting while orchestrating existing tools.

Solution

AI Pentest Agent is an agent-native skill that:

1. Plans an adaptive attack path based on target type and discovered services
2. Executes 5 phases: recon → scan → exploit → post-exploit → report
3. Scores every finding with CVSS 3.1 (pure Python, zero deps)
4. Gathers evidence — every command output saved as structured JSON
5. Reports in markdown (human) + JSON (machine) formats

Quick Start

# Clone and run tests
git clone https://github.com/Erfix404/ai-pentest-agent
cd ai-pentest-agent
python3 tests/run_tests.py

# Full autonomous pentest
python3 scripts/ai-pentest.py --target example.com --full --output ./results

# Attack plan (dry-run)
python3 scripts/ai-pentest.py --target example.com --plan-only

# Single phase
python3 scripts/ai-pentest.py --target https://api.example.com --phase recon

Architecture

┌─────────────────────────────────────┐
│  PHASE 1: RECONNAISSANCE            │
│  subfinder → httpx → katana → gau   │
│  → waybackurls → naabu → dnsx       │
│  Output: targets.txt, surface.json  │
├─────────────────────────────────────┤
│  PHASE 2: SCANNING                  │
│  nuclei → nmap → tlsx → uncover     │
│  → gf secrets → searchsploit        │
│  Output: vulns.json, findings.json  │
├─────────────────────────────────────┤
│  PHASE 3: EXPLOITATION              │
│  ffuf → sqlmap → xsstrike → hydra   │
│  → pwntools → custom exploits       │
│  Output: evidence/*, exploits.log   │
├─────────────────────────────────────┤
│  PHASE 4: POST-EXPLOITATION         │
│  pivoting → persistence → data      │
│  exfiltration (proof only)          │
│  Output: postex.json                │
├─────────────────────────────────────┤
│  PHASE 5: REPORTING                 │
│  CVSS scoring → finding grouping →  │
│  markdown report → JSON evidence    │
│  Output: report.md, report.json     │
└─────────────────────────────────────┘

Features

🧠 Autonomous Attack Path Planning

Builds adaptive attack plans based on target characteristics:

• Target type auto-detection: web / API / network / cloud
• Technology-aware: WordPress → wpscan, Laravel → .env leak, Apache → version exploit
• Adaptive decision tree: plan changes based on what each phase discovers

📊 CVSS 3.1 Scoring Engine

Pure Python, zero dependencies. Validates all metric combinations:

from cvss31 import cvss31_score, cvss31_vector_to_score

score, vector = cvss31_score("N", "L", "N", "N", "U", "H", "H", "H")
# → 9.8, "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"

🔧 Tool Auto-Detection

Auto-detects available tools with graceful fallbacks:

📋 Evidence-First Methodology

Every command output is saved as structured JSON evidence. Reproducible — full command + output captured.

Installation

As an Agent Skill (Hermes / Claude Code / Codex)

Copy SKILL.md to your skills directory:

mkdir -p ~/skills/security/ai-pentest-agent
cp SKILL.md ~/skills/security/ai-pentest-agent/
cp -r scripts/ ~/skills/security/ai-pentest-agent/
cp -r references/ ~/skills/security/ai-pentest-agent/

Standalone Python

git clone https://github.com/Erfix404/ai-pentest-agent
cd ai-pentest-agent
python3 scripts/ai-pentest.py --help

No pip install needed. Pure Python stdlib.

Usage Examples

Full Autonomous Pentest

python3 scripts/ai-pentest.py --target example.com --full --output ./results

Web Application Focus

python3 scripts/ai-pentest.py --target https://app.example.com \
  --type web --output ./web-results

API Security Assessment

python3 scripts/ai-pentest.py --target https://api.example.com \
  --type api --output ./api-results

Network Pentest

python3 scripts/ai-pentest.py --target 10.0.0.0/24 \
  --type network --output ./net-results

Validate a Specific Finding

python3 scripts/ai-pentest.py --validate \
  --finding "SQL injection at /api/users?id=1"

Project Structure

ai-pentest-agent/
├── SKILL.md              # Agent skill definition
├── SKILL.yaml            # Skill metadata for marketplaces
├── README.md             # This file
├── LICENSE               # MIT
├── scripts/
│   ├── ai-pentest.py     # Main autonomous engine (950+ lines)
│   └── cvss31.py         # Pure Python CVSS 3.1 calculator
├── tests/
│   ├── run_tests.py      # Test runner (system pytest not needed)
│   ├── test_cvss31.py    # 8 tests — CVSS scoring + validation
│   ├── test_planner.py   # 10 tests — attack path planning
│   └── test_evidence.py  # 6 tests — evidence capture
├── references/
│   └── attack-paths.md   # Reference attack trees
└── .github/workflows/
    └── ci.yml            # CI pipeline

Tests

# Run all tests (no pytest needed)
python3 tests/run_tests.py

# Or with pytest
python3 -m pytest tests/ -v

Safety & Ethics

• Authorization required. Every pipeline asks for target ownership confirmation
• Destructive OFF by default. No password spraying, DoS, or data-write exploits without --aggressive
• Scope enforcement. Tools limited to declared scope
• Rate limiting. Default 50 req/s
• Evidence only. No actual data exfiltration

Research Foundation

License

MIT — free to use, modify, distribute. Attribution appreciated.

🏆 Ecosystem Gap Filled

skills.sh: 0 skills, 0 installs for "ai-pentesting" keyword
GitHub demand: ⭐21K+ repos exist but no agent skill standard
Hermes coverage: 0 skills before this one