Zen-AI-Pentest

AI-powered penetration testing framework that orchestrates 20+ security tools via LLMs for automated reconnaissance, vulnerability scanning, exploitation, and reporting.

Installation

Using pip (from repository)

# Clone the repository
git clone https://github.com/SHAdd0WTAka/zen-ai-pentest.git
cd zen-ai-pentest

# Install dependencies
pip install -r requirements.txt

# Copy and configure environment
cp .env.example .env

# Edit .env with your API keys and settings
nano .env

Using Docker (recommended)

# One-command deployment with all security tools pre-installed
docker-compose up -d

# Verify containers are running
docker-compose ps

# View logs
docker-compose logs -f

Setup CLI Aliases

# Load all k-* command aliases
source tools/setup_aliases.sh

# Verify installation
k-recon --help
k-exploit --help

Basic Commands

Command	Description
k-recon "Target: example.com"	Run AI-guided reconnaissance on a target
k-exploit "Target: 192.168.1.1"	Launch exploitation agent against target
k-report	Generate penetration test report
k-audit	Run security audit operations
source tools/setup_aliases.sh	Load all CLI tool aliases
docker-compose up -d	Start framework with Docker
docker-compose logs -f	Follow container logs
docker-compose down	Stop all containers

Agent Personas

Agent	Purpose
k-recon	Reconnaissance — information gathering, subdomain enumeration, port scanning
k-exploit	Exploitation — vulnerability validation, payload delivery
k-report	Reporting — compile findings into structured penetration test reports
k-audit	Auditing — compliance checks, configuration review
k-social	Social engineering — phishing simulation, pretexting assessment
k-network	Network analysis — traffic inspection, protocol analysis
k-mobile	Mobile security — Android/iOS application testing
k-redteam	Red team operations — adversary simulation, lateral movement
k-ics	ICS/SCADA — industrial control system security assessment
k-cloud	Cloud security — AWS, Azure, GCP misconfiguration scanning
k-crypto	Cryptographic analysis — cipher suite evaluation, certificate checks

Reconnaissance Operations

Command	Description
k-recon "Target: example.com"	Full reconnaissance scan
k-recon "Subdomain enumeration: example.com"	Enumerate subdomains
k-recon "Port scan: 192.168.1.0/24"	Scan network range for open ports
k-recon "DNS enumeration: example.com"	DNS record discovery
k-recon "Technology fingerprint: example.com"	Identify web technologies
k-recon "OSINT gather: target_org"	Open-source intelligence gathering
k-recon "SSL analysis: example.com"	Analyze SSL/TLS configuration

Vulnerability Scanning

Command	Description
k-exploit "Vuln scan: example.com"	Automated vulnerability scanning
k-exploit "Web app test: https://example.com"	Web application security testing
k-exploit "SQL injection: https://example.com/login"	Test for SQL injection
k-exploit "XSS scan: https://example.com"	Cross-site scripting detection
k-exploit "API test: https://api.example.com"	API security assessment
k-exploit "Auth bypass: https://example.com/admin"	Authentication bypass testing

Integrated Security Tools

Tool	Category	Used By
Nmap	Network scanning	k-recon, k-network
SQLMap	SQL injection	k-exploit
Metasploit	Exploitation framework	k-exploit, k-redteam
Burp Suite	Web app testing	k-exploit
Gobuster	Directory brute-forcing	k-recon
Nuclei	Template-based scanning	k-exploit
BloodHound	Active Directory	k-redteam
Nikto	Web server scanning	k-recon
Hydra	Password cracking	k-exploit
John the Ripper	Hash cracking	k-exploit
Amass	Subdomain enumeration	k-recon
Subfinder	Subdomain discovery	k-recon
ffuf	Web fuzzer	k-exploit
Responder	Network poisoning	k-network
Impacket	Network protocols	k-network, k-redteam

Report Generation

Command	Description
k-report	Generate full penetration test report
k-report --format json	Export findings as JSON
k-report --format junit	Export as JUnit XML (CI/CD integration)
k-report --format sarif	Export as SARIF (GitHub/GitLab integration)
k-report --compliance pci	Generate PCI-DSS compliance report
k-report --compliance hipaa	Generate HIPAA compliance report
k-report --compliance gdpr	Generate GDPR compliance report

CI/CD Integration

GitHub Actions

# .github/workflows/pentest.yml
name: Security Scan
on: [push]
jobs:
  pentest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: SHAdd0WTAka/zen-ai-pentest@v2
        with:
          target: ${{ secrets.SCAN_TARGET }}
          mode: recon
          output: sarif

GitLab CI

# .gitlab-ci.yml
security_scan:
  image: shadd0wtaka/zen-ai-pentest:latest
  script:
    - k-recon "Target: $SCAN_TARGET"
    - k-report --format junit
  artifacts:
    reports:
      junit: report.xml

Environment Configuration

Variable	Description	Example
OPENAI_API_KEY	OpenAI API key for LLM reasoning	sk-...
ANTHROPIC_API_KEY	Anthropic API key (alternative LLM)	sk-ant-...
SCAN_TARGET	Default target for scans	example.com
REPORT_FORMAT	Default report format	json, sarif, junit
MAX_THREADS	Maximum concurrent scan threads	10
TIMEOUT	Scan timeout in seconds	3600
PROXY	Proxy for scan traffic	http://127.0.0.1:8080

Operating Modes

Mode	Description
Interactive	Continuous engagement with AI-guided decisions
One-shot	Single execution with predefined parameters
Pipeline	CI/CD integration with exit codes and status reporting
Autonomous	Full AI-driven scan with minimal human interaction

Best Practices

• Always obtain proper authorization before scanning any target
• Start with reconnaissance before exploitation
• Use the --proxy flag to route traffic through Burp Suite for manual review
• Review AI decisions in interactive mode before allowing autonomous exploitation
• Generate compliance reports for regulatory requirements
• Use Docker deployment for consistent tool versions across team members
• Configure rate limiting to avoid overwhelming target systems
• Store scan results in version control for audit trails