pentest-ai-killer-automation

---
name: pentest-ai-killer-automation
description: Comprehensive pentesting automation server integrating 69+ security tools with AI assistants through MCP and REST API
triggers:
  - run a pentest on this target
  - scan this web application for vulnerabilities
  - perform network reconnaissance on this domain
  - automate security testing with pentest-ai-killer
  - set up comprehensive penetration testing workflow
  - execute nuclei/sqlmap/nmap scan through pentakill
  - integrate pentest tools with AI assistant
  - run cloud security assessment on AWS
---

# Pentest AI Killer Automation

> Skill by [ara.so](https://ara.so) — Security Skills collection.

Pentest AI Killer (Pentakill) is a comprehensive pentesting automation server that integrates 69+ security tools (nmap, nuclei, sqlmap, httpx, gobuster, etc.) with AI assistants through the Model Context Protocol (MCP). It provides a unified REST API and optional CLI for executing reconnaissance, vulnerability assessment, network discovery, password cracking, and cloud security testing.

## Installation

### Docker Compose (Recommended)

```bash
git clone https://github.com/vietjovi/pentest-ai-killer.git
cd pentest-ai-killer
docker-compose up -d
```

Default uses `Dockerfile.base` (~500MB-1GB, essential tools). For full toolset (~2GB-4GB), edit `docker-compose.yml`:

```yaml
services:
  pentest-ai-killer:
    build:
      dockerfile: Dockerfile  # Change from Dockerfile.base
```

### Manual Installation (Ubuntu 20.04+)

```bash
git clone https://github.com/vietjovi/pentest-ai-killer.git
cd pentest-ai-killer
sudo bash install_pentest_tools.sh
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### Build pentakill CLI (Optional)

```bash
go build -o bin/pentakill ./cmd/pentakill

# Cross-compile
GOOS=linux GOARCH=amd64 go build -o bin/pentakill-linux-amd64 ./cmd/pentakill
GOOS=darwin GOARCH=arm64 go build -o bin/pentakill-darwin-arm64 ./cmd/pentakill
```

## Configuration

### API Authentication

Edit `config.py` before first run:

```python
# REQUIRED: Change default API key for security
X_API_KEY = "your-secure-api-key-here"

# Enable/disable tools
PENTEST_TOOLS = {
    "web_reconnaissance": [
        {"tool": "httpx", "enabled": True},
        {"tool": "nuclei", "enabled": True},
        # ...
    ],
    "vulnerability_assessment": [
        {"tool": "sqlmap", "enabled": True},
        {"tool": "nikto", "enabled": True},
        # ...
    ]
}
```

### Environment Variables

```bash
# For pentakill CLI
export PENTAKILL_URL="http://127.0.0.1:8080"
export PENTAKILL_API_KEY="your-secure-api-key-here"

# For Docker
docker run -d -p 8080:8080 \
  -v $(pwd)/config.py:/app/config.py:ro \
  -v $(pwd)/reports:/app/reports \
  pentest-ai-killer:base
```

## Starting the Server

```bash
source venv/bin/activate
python3 pentest_ai_killer_server.py
```

Server runs on `http://localhost:8080`

## REST API Usage

All endpoints require `X-API-KEY` header.

### Execute Specific Tool

```bash
curl -X POST http://localhost:8080/tools/nmap \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: ${PENTAKILL_API_KEY}" \
  -d '{
    "targets": "scanme.nmap.org"
  }'
```

### Category Scans

```bash
# Web reconnaissance
curl -X POST http://localhost:8080/web-reconnaissance \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: ${PENTAKILL_API_KEY}" \
  -d '{
    "targets": "testphp.vulnweb.com"
  }'

# Comprehensive pentest
curl -X POST http://localhost:8080/comprehensive-pentest \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: ${PENTAKILL_API_KEY}" \
  -d '{
    "targets": "example.com"
  }'

# Cloud security assessment
curl -X POST http://localhost:8080/cloud-security-assessment \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: ${PENTAKILL_API_KEY}" \
  -d '{
    "targets": "my-aws-account",
    "aws_profile": "default"
  }'
```

### Custom Tool Commands

```python
import requests

response = requests.post(
    "http://localhost:8080/tools/nuclei",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": os.environ["PENTAKILL_API_KEY"]
    },
    json={
        "targets": "testphp.vulnweb.com",
        "custom_command": "nuclei -u testphp.vulnweb.com -t cves/ -severity critical,high"
    }
)
print(response.json())
```

### List Available Tools

```bash
curl -H "X-API-KEY: ${PENTAKILL_API_KEY}" http://localhost:8080/tools
curl -H "X-API-KEY: ${PENTAKILL_API_KEY}" http://localhost:8080/categories
```

## pentakill CLI Usage

The `pentakill` Go binary provides a CLI interface to the REST API without requiring MCP integration.

### Basic Commands

```bash
# Health check
./bin/pentakill health

# List tools and categories
./bin/pentakill tools
./bin/pentakill categories -json

# Execute specific tool
./bin/pentakill run tool nmap -target scanme.nmap.org

# Execute category scan
./bin/pentakill run category web-reconnaissance -target example.com

# Custom command
./bin/pentakill run tool nuclei \
  -target testphp.vulnweb.com \
  -custom-command "nuclei -u testphp.vulnweb.com -t cves/ -severity critical"
```

### Advanced Usage

```bash
# Override API settings
./bin/pentakill -url http://192.168.1.100:8080 \
  -key "custom-key" \
  -timeout 600 \
  run category comprehensive-pentest -target example.com

# Pass JSON parameters
./bin/pentakill run tool sqlmap \
  -params-json '{"targets":"testphp.vulnweb.com/listproducts.php?cat=1","sqlmap_options":"--batch --dbs"}'
```

Category names accept underscores or hyphens: `comprehensive_network_pentest` maps to `/comprehensive-pentest`.

## MCP Integration

Connect Pentest AI Killer to AI assistants (Claude Desktop, Cursor, LibreChat).

### Setup

1. **Install MCP dependencies:**

```bash
source venv/bin/activate
pip install -r requirements_mcp.txt
```

2. **Configure AI assistant:**

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "pentest-ai-killer": {
      "command": "/usr/bin/python3",
      "args": ["/path/to/pentest-ai-killer/pentest_ai_killer_mcp.py"],
      "env": {
        "PENTEST_API_URL": "http://127.0.0.1:8080"
      }
    }
  }
}
```

**Cursor** (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "pentest-ai-killer": {
      "command": "/usr/bin/python3",
      "args": ["/path/to/pentest-ai-killer/pentest_ai_killer_mcp.py"],
      "env": {
        "PENTEST_API_URL": "http://127.0.0.1:8080"
      }
    }
  }
}
```

3. **Restart AI assistant**

### MCP Natural Language Usage

Ask your AI assistant:

- "Use pentest-ai-killer mcp, perform a comprehensive pentest on testphp.vulnweb.com"
- "Use pentest-ai-killer mcp, run web reconnaissance on example.com"
- "Use pentest-ai-killer mcp and template 05, run a fast web pentest on testphp.vulnweb.com"
- "Use pentest-ai-killer mcp, scan example.com for vulnerabilities using nuclei"
- "Use pentest-ai-killer mcp, get API information in input/api_postman_info.txt, then run api pentest"

### MCP Python API

```python
# In your MCP-enabled application
from pentest_ai_killer_mcp import PentestAIKillerMCP

# Initialize
mcp = PentestAIKillerMCP(api_url="http://127.0.0.1:8080")

# Execute tool
result = await mcp.mcp_execute_tool(
    tool_name="nuclei",
    targets="testphp.vulnweb.com",
    custom_command="nuclei -u testphp.vulnweb.com -t cves/"
)

# Run category scan
result = await mcp.mcp_vulnerability_assessment(
    targets="example.com"
)

# Use template
result = await mcp.mcp_execute_template(
    template_id="05_fast_web_pentest",
    target="testphp.vulnweb.com"
)

# Read reports
reports = await mcp.mcp_get_latest_reports(limit=10)
report_content = await mcp.mcp_read_report(
    report_path="reports/testphp.vulnweb.com_nuclei_20250124_143022.txt"
)
```

## Key API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Server health check |
| `/tools` | GET | List all available tools |
| `/categories` | GET | List all tool categories |
| `/tools/{tool_name}` | POST | Execute specific tool |
| `/web-reconnaissance` | POST | Web security scanning (httpx, nuclei, etc.) |
| `/network-discovery` | POST | Network reconnaissance (nmap, rustscan) |
| `/vulnerability-assessment` | POST | Vulnerability testing (sqlmap, nikto, wpscan) |
| `/password-cracking` | POST | Password brute-forcing |
| `/comprehensive-pentest` | POST | Full pentest suite (autorecon, legion) |
| `/cloud-security-assessment` | POST | AWS security (prowler, cloudsploit) |
| `/kubernetes-security-assessment` | POST | Kubernetes security (kube-hunter) |
| `/container-security-assessment` | POST | Container security (trivy, clair) |
| `/iac-security-assessment` | POST | IaC security (checkov, tfsec) |
| `/multi-cloud-assessment` | POST | Multi-cloud security |

## Common Patterns

### Sequential Tool Execution

```python
import requests
import os

API_URL = "http://localhost:8080"
API_KEY = os.environ["PENTAKILL_API_KEY"]
headers = {
    "Content-Type": "application/json",
    "X-API-KEY": API_KEY
}

target = "testphp.vulnweb.com"

# Step 1: HTTP probing
httpx_resp = requests.post(
    f"{API_URL}/tools/httpx",
    headers=headers,
    json={"targets": target}
)

# Step 2: Subdomain enumeration
subfinder_resp = requests.post(
    f"{API_URL}/tools/subfinder",
    headers=headers,
    json={"targets": target}
)

# Step 3: Vulnerability scanning
nuclei_resp = requests.post(
    f"{API_URL}/tools/nuclei",
    headers=headers,
    json={
        "targets": target,
        "custom_command": f"nuclei -u {target} -t cves/ -severity critical,high"
    }
)

# Step 4: SQL injection testing
sqlmap_resp = requests.post(
    f"{API_URL}/tools/sqlmap",
    headers=headers,
    json={
        "targets": f"{target}/listproducts.php?cat=1",
        "sqlmap_options": "--batch --dbs --risk=3 --level=5"
    }
)
```

### Parallel Execution with Process Management

```python
import requests
import time

# Start multiple tools asynchronously
processes = []

tools = ["httpx", "subfinder", "nuclei"]
for tool in tools:
    resp = requests.post(
        f"{API_URL}/tools/{tool}",
        headers=headers,
        json={"targets": target}
    )
    if resp.json().get("success"):
        processes.append(tool)

# Monitor progress
time.sleep(5)
status_resp = requests.get(f"{API_URL}/processes", headers=headers)
print(status_resp.json())
```

### Template-Based Workflows

```python
# Use predefined templates from template/ directory
templates = {
    "01_full_pentest": "Comprehensive pentest workflow",
    "02_reconnaissance": "Recon-only workflow",
    "05_fast_web_pentest": "Quick web application scan"
}

# Execute template (via MCP or direct API)
result = await mcp.mcp_execute_template(
    template_id="05_fast_web_pentest",
    target="testphp.vulnweb.com"
)
```

### Reading and Managing Reports

```python
# List all reports
reports_resp = requests.get(
    f"{API_URL}/mcp/reports",
    headers=headers
)
reports = reports_resp.json()

# Get reports for specific target
target_reports = [r for r in reports if "testphp.vulnweb.com" in r]

# Read latest report
if target_reports:
    latest = sorted(target_reports)[-1]
    with open(f"reports/{latest}", "r") as f:
        report_content = f.read()
        print(report_content)
```

## Adding Custom Tools

1. **Install the tool** (ensure it's in PATH):

```bash
sudo apt install custom-tool
# or
go install github.com/author/custom-tool@latest
export PATH=$PATH:$HOME/go/bin
```

2. **Add to `config.py`**:

```python
PENTEST_TOOLS = {
    "vulnerability_assessment": [
        {
            "tool": "custom-tool",
            "command": "custom-tool",
            "params": "-v --threads 10 [TARGET]",
            "description": "Custom vulnerability scanner",
            "enabled": True
        }
    ]
}
```

3. **Test the tool**:

```bash
curl -X POST http://localhost:8080/tools/custom-tool \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: ${PENTAKILL_API_KEY}" \
  -d '{"targets": "example.com"}'
```

## Key Tools by Category

### Web Reconnaissance (10 enabled)
- `httpx`: HTTP probing and URL discovery
- `nuclei`: Template-based vulnerability scanning
- `subfinder`: Subdomain enumeration
- `gospider`: Web crawling
- `katana`: Web crawling and spidering
- `hakrawler`: URL discovery
- `gau`: URL fetching from archives
- `waybackurls`: Wayback Machine URL extraction
- `paramspider`: Parameter discovery
- `arjun`: HTTP parameter discovery

### Vulnerability Assessment (12 enabled)
- `sqlmap`: SQL injection detection and exploitation
- `nikto`: Web server vulnerability scanning
- `wpscan`: WordPress security scanner
- `dalfox`: XSS scanning
- `wapiti`: Web application vulnerability scanner
- `gobuster`: Directory/file brute-forcing
- `ffuf`: Web fuzzing
- `xsstrike`: Advanced XSS detection
- `commix`: Command injection exploitation
- `noSQLMap`: NoSQL injection testing
- `wafw00f`: WAF detection
- `zap`: OWASP ZAP security testing

### Network Discovery (2 enabled)
- `nmap`: Network port scanning
- `rustscan`: Fast port scanner

### Comprehensive Pentest (2 enabled)
- `autorecon`: Automated reconnaissance
- `legion`: Automated penetration testing framework

## Troubleshooting

### API Server Not Starting

```bash
# Check if port 8080 is in use
sudo lsof -i :8080

# Use different port
export FLASK_RUN_PORT=9090
python3 pentest_ai_killer_server.py
```

### Tools Not Found

```bash
# Add Go tools to PATH
export PATH=$PATH:$HOME/go/bin

# Verify tool installation
which nuclei httpx subfinder

# Reinstall tools
sudo bash install_pentest_tools.sh
```

### Docker Permission Issues

```bash
# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Fix volume permissions
sudo chown -R $(id -u):$(id -g) reports/
```

### MCP Connection Failures

```bash
# Verify server is running
curl -H "X-API-KEY: ${PENTAKILL_API_KEY}" http://127.0.0.1:8080/health

# Check Python path
which python3

# Test MCP directly
python3 pentest_ai_killer_mcp.py
```

### Authentication Errors

```bash
# Verify API key matches in both config.py and environment
grep X_API_KEY config.py
echo $PENTAKILL_API_KEY

# Update API key in config.py
sed -i 's/X_API_KEY = .*/X_API_KEY = "new-key"/' config.py
```

### Report Access Issues

```bash
# Ensure reports directory exists and is writable
mkdir -p reports
chmod 755 reports

# Docker: bind-mount reports directory
docker run -v $(pwd)/reports:/app/reports pentest-ai-killer:base
```

### Tool Execution Timeouts

```python
# Increase timeout in pentakill CLI
./bin/pentakill -timeout 1200 run tool nmap -target example.com

# Or in Python API call
response = requests.post(
    f"{API_URL}/tools/nmap",
    headers=headers,
    json={"targets": "example.com"},
    timeout=1200  # 20 minutes
)
```

## Security Considerations

⚠️ **WARNING**: This tool is for **authorized security testing only**. Unauthorized use is illegal.

- **Change default API key** in `config.py` before deployment
- **Use HTTPS** in production (reverse proxy with nginx/traefik)
- **Restrict network access** (firewall rules, VPN)
- **Store API keys securely** (environment variables, secrets management)
- **Review tool configurations** before enabling dangerous features
- **Monitor execution logs** for suspicious activity
- **Scope targets carefully** to avoid unintended scanning

## Resources

- **GitHub**: https://github.com/vietjovi/pentest-ai-killer
- **MCP Config Samples**: `MCP_CONFIG_SAMPLE/` directory
- **Templates**: `template/` directory for workflow examples
- **Input/Output**: `input/` and `output/` directories for resources