A comprehensive pentesting automation server that integrates multiple security tools with AI assistants through the Model Context Protocol (MCP).
- 🔍 Web Reconnaissance - HTTP probing, crawling, URL discovery
- 🌐 Network Discovery - Port scanning, service enumeration, SMB tools
- 🛡️ Vulnerability Assessment - Web and API security testing, XSS, SQL injection, fuzzing
- 🔐 Password Cracking - Rate-limited credential spray (customizable)
- 🎯 Comprehensive Network Pentest - Automated reconnaissance and exploitation
- ☁️ Cloud Security - AWS, Kubernetes, Container, IaC, and multi-cloud security assessment
- ⚡ Async Jobs - Background scans for long-running categories (avoids MCP timeouts)
- 📊 Report Summarizer - Auto-generate findings summary from scan reports
- 🤖 MCP Integration - Direct integration with AI assistants (Claude, Cursor, etc.)
- pentakill CLI - Optional Go binary that calls the HTTP API so you can run tools and rely on server-side reports without MCP or any AI assistant
| Component | Requirement |
|---|---|
| OS | Ubuntu 20.04+ (installation script supports Ubuntu only) |
| Python | 3.10+ (3.12 recommended) |
| Go | 1.22+ (to build pentakill; 1.19+ still fine for installing Go-based security tools) |
| Disk Space | 20 GB minimum |
| Memory | 4 GB RAM (8 GB recommended) |
| Privileges | Root/sudo access |
Dependencies: Docker (optional), Git, curl/wget, build-essential
docker-compose up -d
docker-compose logs -f
Default: Uses Dockerfile.base (essential tools, \~500MB-1GB). Change to Dockerfile in docker-compose.yml for full tools (\~2GB-4GB).
Base image (essential tools):
docker build -f Dockerfile.base -t pentest-ai-killer:base .
docker run -d -p 8080:8080 -v $(pwd)/config.base.py:/app/config.py:ro pentest-ai-killer:base
Full image (all tools):
docker build -f Dockerfile -t pentest-ai-killer:full .
docker run -d -p 8080:8080 -v $(pwd)/config.py:/app/config.py:ro pentest-ai-killer:full
git clone git@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
Edit config.py to:
- Enable/disable tools: Set
"enabled": True/Falsefor each tool - Set per-tool timeouts:
"timeout": 600(seconds) on individual tools - Configure API authentication: Set
X_API_KEYto your desired API key
Environment variables:
| Variable | Default | Purpose |
|---|---|---|
PENTAKILL_API_KEY |
YOUR_API_KEY |
API authentication |
PENTAKILL_TOOL_TIMEOUT |
600 |
Default per-tool timeout (seconds) |
PENTAKILL_TIMEOUT |
3600 |
Max server process timeout |
PENTAKILL_INPUT_DIR |
input |
Path to input wordlists |
Security Note: The API server requires authentication via the X-API-KEY header. Make sure to:
- Change the default
X_API_KEYvalue inconfig.pybefore deploying - Keep your API key secret and secure
- The MCP client automatically uses the API key from
config.py
- gobuster DNS: fixed
-doflag bug (was parsing domain aso); now uses-d [TARGET] - dnsenum: uses
input/subdomains-common.txtinstead of invalid/dev/nullwordlist - sqlmap: non-interactive mode with
--answers=sitemap=N,--crawl=0 - ffuf: corrected command syntax with
-wwordlist flag - hydra: rate-limited spray using
input/users-common.txtandinput/passwords-spray-small.txt - masscan (web recon): limited to common ports instead of full 1-65535 scan
- Enabled:
enum4linux,smbmap,ffuf,dirsearchfor Windows/web testing
source venv/bin/activate
python3 pentest_ai_killer_server.py
Server runs on http://localhost:8080
Authentication Required: All API endpoints require the X-API-KEY header for authentication.
| Method | Endpoint | Description |
|---|---|---|
| GET | /health |
Server health check |
| GET | /tools |
List all tools |
| GET | /categories |
List all categories |
| POST | /tools/{tool_name} |
Execute specific tool ( "async": true for background) |
| POST | /web-reconnaissance |
Web security scanning ( "async": true supported) |
| POST | /network-discovery |
Network reconnaissance |
| POST | /vulnerability-assessment |
Web/API security testing |
| POST | /password-cracking |
Password testing |
| POST | /comprehensive-pentest |
Full pentest suite |
| POST | /jobs |
Start async category/tool job |
| GET | /jobs |
List recent jobs |
| GET | /jobs/{job_id} |
Poll async job status |
| GET/POST | /reports/summarize/{target} |
Generate findings summary |
| POST | /cloud-security-assessment |
AWS cloud security |
| POST | /kubernetes-security-assessment |
Kubernetes security |
| POST | /container-security-assessment |
Container security |
| POST | /iac-security-assessment |
IaC security analysis |
| POST | /multi-cloud-assessment |
Multi-cloud security |
# Execute specific tool (with authentication)
curl -X POST http://localhost:8080/tools/nmap \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-d '{"targets": "scanme.nmap.org"}'
# Run category scan synchronously
curl -X POST http://localhost:8080/web-reconnaissance \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-d '{"targets": "example.com"}'
# Run category scan asynchronously (recommended for MCP / long scans)
curl -X POST http://localhost:8080/web-reconnaissance \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-d '{"targets": "example.com", "async": true}'
# Returns: {"job_id": "...", "poll_url": "/jobs/..."}
# Poll job status
curl -H "X-API-KEY: YOUR_API_KEY" http://localhost:8080/jobs/<job_id>
# Generate report summary
curl -H "X-API-KEY: YOUR_API_KEY" http://localhost:8080/reports/summarize/example.com
The pentakill program is a small Go client for the same REST API as curl. Start the Flask server (or Docker Compose), then run scans from your terminal without MCP.
Build:
go build -o bin/pentakill ./cmd/pentakill
Cross-compile examples:
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
Environment:
| Variable | Purpose |
|---|---|
PENTAKILL_URL |
API base URL (default http://127.0.0.1:8080) |
PENTAKILL_API_KEY |
Same value as X_API_KEY in config.py |
Override with flags -url, -key, and -timeout (placed before the subcommand). Reports are written on the server under reports/; bind-mount ./reports:/app/reports in Docker if you want files on the host. stderr lists report_path when the API returns it.
Examples:
./bin/pentakill health
export PENTAKILL_API_KEY='YOUR_API_KEY'
./bin/pentakill tools
./bin/pentakill categories -json
./bin/pentakill run tool nmap -target scanme.nmap.org
./bin/pentakill run category web-reconnaissance -target example.com
Category names accept underscores or hyphens (for example comprehensive_network_pentest maps to /comprehensive-pentest). Run ./bin/pentakill --help for full usage (run tool, -custom-command, -params-json, exit codes).
Connect Pentest AI Killer to AI assistants (Claude Desktop, Cursor, LibreChat, VSCode) for seamless pentesting via chat.
- Start API server:
source venv/bin/activate
python3 pentest_ai_killer_server.py
- Install MCP dependencies:
pip install -r requirements_mcp.txt - Configure AI assistant:
- Copy config fromMCP_CONFIG_SAMPLE/to your AI assistant's config location
- Replace placeholders:[PATH_TO_PYTHON],[PATH_TO_PENTEST_AI_KILLER],[PENTEST_AI_KILLER_SERVER_IP:PORT]
- Claude Desktop:~/Library/Application Support/Claude/claude_desktop_config.json(macOS)
- Cursor:~/.cursor/mcp.json
- LibreChat: Add tolibrechat.yaml - Restart AI assistant
Ask your AI assistant natural language commands:
- "Use pentest-ai-killer mcp, perform a comprehensive pentest on testphp.vulnweb.com"
- "Use pentest-ai-killer mcp, run web reconnaissance on testphp.vulnweb.com"
- "Use pentest-ai-killer mcp and template 05, run a test on testphp.vulnweb.com"
- "Use pentest-ai-killer mcp, scan testphp.vulnweb.com for vulnerabilities using nuclei"
- "Use pentest-ai-killer mcp, get API information in input/api_postman_info.txt, then run api pentest on them"
Long category scans (web recon, vuln assessment) often exceed MCP client timeouts. Use async jobs:
mcp_start_async_job(job_type="category", name="web_reconnaissance", targets="example.com")
mcp_get_job_status(job_id="<returned-job-id>")
mcp_generate_report(target="example.com")
Or use the pentakill CLI with -timeout 2h for uninterrupted scans.
Category Tools: mcp_web_reconnaissance, mcp_network_discovery, mcp_vulnerability_assessment, mcp_password_cracking, mcp_comprehensive_network_pentest, mcp_cloud_security_assessment, mcp_kubernetes_security_assessment, mcp_container_security_assessment, mcp_iac_security_assessment, mcp_multi_cloud_assessment
Utility Tools: mcp_list_tools, mcp_list_categories, mcp_execute_tool
Async Jobs: mcp_start_async_job, mcp_get_job_status
Report Management: mcp_list_reports, mcp_get_reports_by_target, mcp_get_latest_reports, mcp_read_report, mcp_generate_report
Resource Management: mcp_list_input_resources, mcp_read_input_resource, mcp_list_output_resources, mcp_read_output_resource, mcp_write_output_resource
Templates: mcp_list_templates, mcp_read_template, mcp_execute_template
Templates: Pre-defined workflows in template/ folder (01_full_pentest.md, 02_reconnaissance.md, 03_test_with_info.md, 04_specific_tools.md, 05_fast_web_pentest.md). Use [TARGET] placeholder.
Reports: Automatically saved to reports/ as [target]_[tool_name]_[timestamp].txt (ANSI codes stripped for readability)
Custom Commands: Use custom_command parameter in mcp_execute_tool for full control over tool arguments.
- Verify API server:
curl -H "X-API-KEY: YOUR_API_KEY" http://127.0.0.1:8080/health - Ensure
X_API_KEYinconfig.pymatches between server and MCP client - MCP timeouts: Use
mcp_start_async_jobor pentakill CLI for long scans - Check Python path:
which python3 - Use absolute paths (no
~shortcuts) - Check sample configs in
MCP_CONFIG_SAMPLE/ - Restart AI assistant
Enable/disable tools in config.py by setting "enabled": True/False
Key Tools: nmap, httpx, nuclei, sqlmap, nikto, gobuster, wpscan, ffuf, dirsearch, enum4linux, smbmap, dalfox, wapiti, arjun, zap, autorecon, rustscan, dnsenum
Input wordlists (input/):
subdomains-common.txt— DNS brute-forceusers-common.txt/passwords-spray-small.txt— rate-limited credential spray
pentest-ai-killer/
├── go.mod # Go module (pentakill CLI)
├── cmd/pentakill/ # pentakill CLI entrypoint
├── internal/api/ # HTTP client for the Flask API
├── config.py # Tool configurations
├── pentest_ai_killer_server.py # Flask API server
├── pentest_ai_killer_mcp.py # MCP server
├── utils/ # text_utils, job_manager, report_summarizer
├── install_pentest_tools.sh # Tool installation
├── Dockerfile, Dockerfile.base # Docker builds
├── docker-compose.yml # Docker Compose config
├── MCP_CONFIG_SAMPLE/ # MCP config samples
├── template/ # Pentest templates
├── input/, output/, reports/ # Resources and reports
└── requirements.txt, requirements_mcp.txt
pip install -r requirements-dev.txt
pytest tests/ -v
95 tests cover tool execution, config fixes, async jobs, report summarization, API endpoints, and MCP client methods.
With coverage:
pytest tests/ --cov=. --cov-report=term-missing --cov-config=.coveragerc````
docker-compose up -d --build
bash scripts/test_integration.sh http://127.0.0.1:8080 YOUR_API_KEY scanme.nmap.org
```
Verifies: health check, async httpx job, job polling, report summarization, gobuster-d` flag fix.
⚠️ WARNING: For authorized security testing only. Unauthorized use is illegal. Users are responsible for compliance.
Fork → Create feature branch → Make changes → Submit PR
Educational and authorized security testing purposes only.
Tools not found: export PATH=$PATH:$HOME/go/bin
Permission denied: sudo chmod +x install_pentest_tools.sh
Docker issues: docker system prune -a && docker build --no-cache -t pentest-ai-killer .
gobuster finds no subdomains: Ensure -d flag is used (fixed in latest config)
dnsenum fails on wordlist: Use input/subdomains-common.txt (bundled)
- Install tool (ensure it's in PATH or use absolute path)
- Add to
config.py: "category_name": [ {"tool": "TOOL_NAME", "command": "COMMAND", "params": "DEFAULT_PARAMS", "description": "...", "enabled": True, "timeout": 600} ] - Test:
curl -X POST http://localhost:8080/tools/TOOL_NAME -H "Content-Type: application/json" -d '{"targets": "test.com"}'
Categories: web_reconnaissance, network_discovery, vulnerability_assessment, password_cracking, comprehensive_network_pentest, stress_testing
Endpoints: /health, /tools, /categories, /processes, /jobs, /jobs/{id}, /reports/summarize/{target}, /tools/{tool_name}, /web-reconnaissance, /network-discovery, /vulnerability-assessment, /password-cracking, /comprehensive-pentest, /cloud-security-assessment, /kubernetes-security-assessment, /container-security-assessment, /iac-security-assessment, /multi-cloud-assessment
Sync request: POST /endpoint with {"targets": "example.com"}
Async request: POST /endpoint with {"targets": "example.com", "async": true} → poll GET /jobs/{job_id}
Response: {"success": true, "tools_executed": [...], "results": {...}}
- Target-aware scan profiles (auto-select tools by detected OS/services)
- Burp Suite, Nessus integration
- Automated tool updates
- Custom tools framework
Open an issue on the project repository.
Made with ❤️ for the security community