PTHelper Cheat Sheet

📋 Copy All Commands 📄 Generate PDF

Overview

PTHelper is an open-source modular assistant designed for orchestrating penetration testing steps using AI and automation frameworks. It combines artificial intelligence with traditional pentesting methodologies to streamline reconnaissance, vulnerability assessment, and exploitation phases while maintaining human oversight and control.

⚠️ Note: Open-source tool. Use only on systems you own or have explicit permission to test.

Installation

Prerequisites

# Required dependencies
python3 --version  # Python 3.8+
pip3 --version
git --version

# System requirements
sudo apt update
sudo apt install -y python3-pip python3-venv git curl wget

# Optional but recommended
sudo apt install -y nmap masscan gobuster dirb nikto sqlmap

Installation Methods

# Method 1: Git clone and install
git clone https://github.com/pthelper/pthelper.git
cd pthelper
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python setup.py install

# Method 2: Direct pip install (if available)
pip install pthelper

# Method 3: Docker installation
docker pull pthelper/pthelper:latest
docker run -it --rm pthelper/pthelper:latest

# Verify installation
pthelper --version
pthelper --help

Configuration Setup

# Create configuration directory
mkdir -p ~/.pthelper/config
mkdir -p ~/.pthelper/modules
mkdir -p ~/.pthelper/reports

# Initialize configuration
pthelper init

# Configure API keys (if using AI features)
pthelper config set openai_api_key "your-openai-key"
pthelper config set anthropic_api_key "your-anthropic-key"

# Set default options
pthelper config set default_threads 10
pthelper config set output_format json
pthelper config set verbose true

Core Commands

Basic Usage

# Display help and available modules
pthelper --help
pthelper modules list
pthelper modules info <module_name>

# Run basic reconnaissance
pthelper recon --target example.com
pthelper recon --target 192.168.1.0/24 --passive

# Quick vulnerability scan
pthelper scan --target example.com --quick
pthelper scan --target 192.168.1.100 --full

# Generate automated report
pthelper report --target example.com --format pdf
pthelper report --scan-id 12345 --format html

Target Management

# Add targets to workspace
pthelper target add --host example.com
pthelper target add --network 192.168.1.0/24
pthelper target add --url https://example.com/app

# List and manage targets
pthelper target list
pthelper target info example.com
pthelper target remove example.com

# Import targets from file
pthelper target import --file targets.txt
pthelper target import --nmap nmap_scan.xml

# Export target information
pthelper target export --format json
pthelper target export --target example.com --format csv

Workspace Management

# Create and manage workspaces
pthelper workspace create --name "client_pentest"
pthelper workspace list
pthelper workspace switch client_pentest
pthelper workspace delete old_project

# Workspace information
pthelper workspace info
pthelper workspace stats
pthelper workspace backup --file backup.tar.gz

# Share workspace data
pthelper workspace export --format json
pthelper workspace import --file workspace.json

AI-Powered Features

Automated Reconnaissance

# AI-guided reconnaissance
pthelper ai recon --target example.com --depth deep
pthelper ai recon --target example.com --focus web
pthelper ai recon --target 192.168.1.0/24 --focus network

# Passive information gathering
pthelper ai osint --target example.com
pthelper ai osint --domain example.com --social
pthelper ai osint --company "Example Corp" --employees

# Subdomain enumeration with AI
pthelper ai subdomains --domain example.com
pthelper ai subdomains --domain example.com --wordlist custom.txt
pthelper ai subdomains --domain example.com --recursive

Intelligent Vulnerability Assessment

# AI-powered vulnerability scanning
pthelper ai scan --target example.com --smart
pthelper ai scan --target example.com --web-focus
pthelper ai scan --target 192.168.1.100 --service-focus

# Vulnerability prioritization
pthelper ai prioritize --scan-id 12345
pthelper ai prioritize --target example.com --business-impact high
pthelper ai prioritize --cvss-min 7.0

# Exploit suggestion
pthelper ai exploit --vulnerability CVE-2023-1234
pthelper ai exploit --service "Apache 2.4.41"
pthelper ai exploit --target example.com --auto-suggest

AI-Assisted Analysis

# Analyze scan results with AI
pthelper ai analyze --scan-id 12345
pthelper ai analyze --target example.com --comprehensive
pthelper ai analyze --file nmap_results.xml

# Generate attack paths
pthelper ai attack-path --target example.com
pthelper ai attack-path --from external --to domain-admin
pthelper ai attack-path --target 192.168.1.0/24 --lateral

# Risk assessment
pthelper ai risk --target example.com
pthelper ai risk --scan-id 12345 --business-context
pthelper ai risk --vulnerability-list vulns.json

Module System

Core Modules

# Reconnaissance modules
pthelper module run nmap_scan --target example.com
pthelper module run subdomain_enum --domain example.com
pthelper module run port_scan --target 192.168.1.100

# Web application modules
pthelper module run web_crawl --url https://example.com
pthelper module run dir_brute --url https://example.com
pthelper module run sql_injection --url https://example.com/login

# Network modules
pthelper module run network_discovery --network 192.168.1.0/24
pthelper module run service_enum --target 192.168.1.100
pthelper module run smb_enum --target 192.168.1.100

Custom Module Development

# Example custom module: custom_scanner.py
from pthelper.core.module import BaseModule
from pthelper.core.logger import get_logger

class CustomScanner(BaseModule):
    def __init__(self):
        super().__init__()
        self.name = "custom_scanner"
        self.description = "Custom vulnerability scanner"
        self.logger = get_logger(__name__)

    def configure(self, config):
        self.target = config.get('target')
        self.port = config.get('port', 80)
        self.timeout = config.get('timeout', 10)

    def run(self):
        self.logger.info(f"Scanning {self.target}:{self.port}")

        # Custom scanning logic here
        results = self.perform_scan()

        return {
            'status': 'completed',
            'vulnerabilities': results,
            'target': self.target
        }

    def perform_scan(self):
        # Implement custom scanning logic
        return []

# Register module
pthelper.register_module(CustomScanner)

Module Configuration

# modules/config.yaml
modules:
  nmap_scan:
    enabled: true
    default_options: "-sS -sV -O"
    timeout: 300

  subdomain_enum:
    enabled: true
    wordlists:
      - /usr/share/wordlists/subdomains.txt
      - /opt/pthelper/wordlists/custom.txt

  web_crawl:
    enabled: true
    max_depth: 3
    follow_redirects: true
    user_agent: "PTHelper/1.0"

  sql_injection:
    enabled: true
    payloads_file: /opt/pthelper/payloads/sqli.txt
    blind_timeout: 5

Automation Workflows

Workflow Definition

# workflows/web_pentest.yaml
name: "Web Application Penetration Test"
description: "Comprehensive web application security assessment"

stages:
  - name: "reconnaissance"
    modules:
      - name: "subdomain_enum"
        config:
          domain: "{{ target.domain }}"
          wordlist: "comprehensive"

      - name: "port_scan"
        config:
          target: "{{ target.ip }}"
          ports: "1-65535"

  - name: "vulnerability_assessment"
    depends_on: ["reconnaissance"]
    modules:
      - name: "web_crawl"
        config:
          url: "{{ target.url }}"
          max_depth: 5

      - name: "dir_brute"
        config:
          url: "{{ target.url }}"
          wordlist: "common"

  - name: "exploitation"
    depends_on: ["vulnerability_assessment"]
    condition: "vulnerabilities_found > 0"
    modules:
      - name: "sql_injection"
        config:
          target: "{{ target.url }}"
          auto_exploit: false

Workflow Execution

# Run predefined workflows
pthelper workflow run web_pentest --target example.com
pthelper workflow run network_pentest --target 192.168.1.0/24
pthelper workflow run api_security --target https://api.example.com

# Custom workflow execution
pthelper workflow run --file custom_workflow.yaml --target example.com
pthelper workflow run --template basic_scan --target 192.168.1.100

# Workflow management
pthelper workflow list
pthelper workflow status web_pentest_001
pthelper workflow stop web_pentest_001
pthelper workflow resume web_pentest_001

Conditional Logic

# Advanced workflow with conditions
name: "Adaptive Network Scan"

variables:
  scan_intensity: "{{ env.SCAN_INTENSITY | default('medium') }}"
  target_network: "{{ target.network }}"

stages:
  - name: "discovery"
    modules:
      - name: "network_discovery"
        config:
          network: "{{ target_network }}"

  - name: "port_scan_light"
    condition: "scan_intensity == 'light'"
    modules:
      - name: "port_scan"
        config:
          ports: "22,80,443,3389"

  - name: "port_scan_full"
    condition: "scan_intensity == 'full'"
    modules:
      - name: "port_scan"
        config:
          ports: "1-65535"
          timing: "aggressive"

Reporting and Output

Report Generation

# Generate comprehensive reports
pthelper report generate --target example.com --format pdf
pthelper report generate --scan-id 12345 --format html
pthelper report generate --workspace client_pentest --format docx

# Custom report templates
pthelper report generate --template executive --target example.com
pthelper report generate --template technical --scan-id 12345
pthelper report generate --template compliance --format pdf

# Report customization
pthelper report generate --target example.com \
  --include-screenshots \
  --include-raw-output \
  --severity-filter high,critical

Output Formats

# JSON output for automation
pthelper scan --target example.com --output json > results.json
pthelper ai analyze --scan-id 12345 --output json

# XML output for tool integration
pthelper scan --target example.com --output xml > results.xml

# CSV output for spreadsheet analysis
pthelper vulnerabilities list --output csv > vulns.csv
pthelper targets list --output csv > targets.csv

# Custom output formatting
pthelper scan --target example.com --output custom \
  --template "{{ target }}: {{ vulnerability.name }} ({{ severity }})"

Integration with External Tools

# Export to other security tools
pthelper export --format nessus --scan-id 12345
pthelper export --format burp --target example.com
pthelper export --format metasploit --vulnerabilities high,critical

# Import from external tools
pthelper import --format nmap --file scan_results.xml
pthelper import --format nessus --file vulnerability_scan.nessus
pthelper import --format burp --file burp_results.xml

Advanced Configuration

AI Model Configuration

# config/ai_models.yaml
ai_models:
  primary:
    provider: "openai"
    model: "gpt-4"
    api_key: "${OPENAI_API_KEY}"
    max_tokens: 4000
    temperature: 0.3

  secondary:
    provider: "anthropic"
    model: "claude-3-sonnet"
    api_key: "${ANTHROPIC_API_KEY}"
    max_tokens: 4000

  local:
    provider: "ollama"
    model: "llama2"
    endpoint: "http://localhost:11434"

reasoning:
  vulnerability_analysis:
    model: "primary"
    prompt_template: "analyze_vulnerability.txt"

  exploit_suggestion:
    model: "primary"
    prompt_template: "suggest_exploit.txt"

  risk_assessment:
    model: "secondary"
    prompt_template: "assess_risk.txt"

Plugin System

# plugins/custom_plugin.py
from pthelper.core.plugin import BasePlugin

class CustomIntegration(BasePlugin):
    def __init__(self):
        super().__init__()
        self.name = "custom_integration"
        self.version = "1.0.0"

    def on_scan_complete(self, scan_results):
        # Custom processing after scan completion
        self.send_to_siem(scan_results)
        self.update_asset_inventory(scan_results)

    def on_vulnerability_found(self, vulnerability):
        # Custom actions when vulnerability is discovered
        if vulnerability.severity == "critical":
            self.send_alert(vulnerability)

    def send_to_siem(self, results):
        # Integration with SIEM system
        pass

    def send_alert(self, vulnerability):
        # Send immediate alert for critical vulnerabilities
        pass

Database Configuration

# config/database.yaml
database:
  type: "postgresql"
  host: "localhost"
  port: 5432
  name: "pthelper"
  username: "pthelper_user"
  password: "${DB_PASSWORD}"

  # Connection pool settings
  pool_size: 10
  max_overflow: 20
  pool_timeout: 30

  # Backup settings
  backup:
    enabled: true
    schedule: "0 2 * * *"  # Daily at 2 AM
    retention_days: 30
    location: "/opt/pthelper/backups"

Security and Best Practices

Secure Configuration

# Set up secure file permissions
chmod 600 ~/.pthelper/config/api_keys.conf
chmod 700 ~/.pthelper/

# Use environment variables for sensitive data
export PTHELPER_API_KEY="your-api-key"
export PTHELPER_DB_PASSWORD="secure-password"

# Enable audit logging
pthelper config set audit_logging true
pthelper config set audit_log_file /var/log/pthelper/audit.log

# Configure rate limiting
pthelper config set rate_limit_enabled true
pthelper config set max_requests_per_minute 60

Ethical Usage Guidelines

# Always verify authorization before testing
pthelper auth verify --target example.com
pthelper auth add-authorized --target example.com --scope full

# Use safe scanning options
pthelper scan --target example.com --safe-mode
pthelper scan --target example.com --no-exploit --no-dos

# Respect rate limits and avoid disruption
pthelper config set scan_delay 1000  # 1 second between requests
pthelper config set max_concurrent_scans 5

Legal Compliance

# config/compliance.yaml
compliance:
  authorization_required: true
  log_all_activities: true

  restrictions:
    - no_dos_attacks: true
    - no_data_exfiltration: true
    - respect_robots_txt: true
    - max_scan_duration: 3600  # 1 hour

  documentation:
    require_scope_of_work: true
    require_signed_agreement: true
    auto_generate_evidence: true

Troubleshooting

Common Issues

# Debug mode for troubleshooting
pthelper --debug scan --target example.com
pthelper --verbose ai analyze --scan-id 12345

# Check system requirements
pthelper system check
pthelper system requirements

# Verify module dependencies
pthelper modules check-deps
pthelper modules install-deps

# Clear cache and reset
pthelper cache clear
pthelper config reset
pthelper database reset --confirm

Performance Optimization

# Optimize for large networks
pthelper config set max_threads 50
pthelper config set chunk_size 1000
pthelper config set memory_limit 8GB

# Database optimization
pthelper database optimize
pthelper database vacuum
pthelper database reindex

# Monitor resource usage
pthelper system monitor
pthelper system stats --real-time

Log Analysis

# View logs
pthelper logs view --level error
pthelper logs view --module nmap_scan
pthelper logs view --target example.com

# Export logs for analysis
pthelper logs export --format json --date-range "2024-01-01,2024-01-31"
pthelper logs export --level critical --format csv

# Log rotation and cleanup
pthelper logs rotate
pthelper logs cleanup --older-than 30d

Integration Examples

CI/CD Pipeline Integration

# .github/workflows/security-scan.yml
name: Security Scan
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3

    - name: Setup PTHelper
      run: |
        pip install pthelper
        pthelper config set api_key ${{ secrets.PTHELPER_API_KEY }}

    - name: Run Security Scan
      run: |
        pthelper scan --target ${{ env.TARGET_URL }} --format json > results.json
        pthelper ai analyze --file results.json --output report.html

    - name: Upload Results
      uses: actions/upload-artifact@v3
      with:
        name: security-scan-results
        path: |
          results.json
          report.html

SIEM Integration

# integrations/splunk_integration.py
import requests
import json
from pthelper.core.integration import BaseIntegration

class SplunkIntegration(BaseIntegration):
    def __init__(self, splunk_url, auth_token):
        self.splunk_url = splunk_url
        self.auth_token = auth_token

    def send_vulnerability(self, vulnerability):
        event = {
            "time": vulnerability.discovered_at,
            "source": "pthelper",
            "sourcetype": "vulnerability",
            "event": {
                "target": vulnerability.target,
                "severity": vulnerability.severity,
                "cve": vulnerability.cve,
                "description": vulnerability.description
            }
        }

        headers = {
            "Authorization": f"Splunk {self.auth_token}",
            "Content-Type": "application/json"
        }

        response = requests.post(
            f"{self.splunk_url}/services/collector/event",
            headers=headers,
            data=json.dumps(event)
        )

        return response.status_code == 200

Slack Notifications

# integrations/slack_notifications.py
import requests
import json

class SlackNotifier:
    def __init__(self, webhook_url):
        self.webhook_url = webhook_url

    def send_critical_alert(self, vulnerability):
        message = {
            "text": f"🚨 Critical Vulnerability Detected",
            "attachments": [
                {
                    "color": "danger",
                    "fields": [
                        {
                            "title": "Target",
                            "value": vulnerability.target,
                            "short": True
                        },
                        {
                            "title": "Severity",
                            "value": vulnerability.severity,
                            "short": True
                        },
                        {
                            "title": "CVE",
                            "value": vulnerability.cve or "N/A",
                            "short": True
                        },
                        {
                            "title": "Description",
                            "value": vulnerability.description,
                            "short": False
                        }
                    ]
                }
            ]
        }

        requests.post(self.webhook_url, json=message)

Best Practices

Reconnaissance Best Practices

# Start with passive reconnaissance
pthelper ai osint --target example.com --passive-only
pthelper ai subdomains --domain example.com --passive

# Gradually increase scan intensity
pthelper scan --target example.com --intensity low
pthelper scan --target example.com --intensity medium
pthelper scan --target example.com --intensity high

# Use multiple data sources
pthelper ai recon --target example.com --sources all
pthelper ai recon --target example.com --cross-reference

Vulnerability Assessment Best Practices

# Prioritize based on business impact
pthelper ai prioritize --scan-id 12345 --business-context
pthelper ai risk --target example.com --asset-criticality high

# Validate findings before reporting
pthelper validate --vulnerability-id 67890
pthelper validate --scan-id 12345 --auto-verify

# Document evidence thoroughly
pthelper evidence capture --vulnerability-id 67890
pthelper evidence export --format zip --scan-id 12345

Reporting Best Practices

# Generate executive summaries
pthelper report generate --template executive --target example.com
pthelper ai summarize --scan-id 12345 --audience executive

# Include remediation guidance
pthelper report generate --include-remediation --scan-id 12345
pthelper ai remediate --vulnerability-list vulns.json

# Provide timeline and metrics
pthelper report generate --include-timeline --include-metrics
pthelper metrics export --scan-id 12345 --format dashboard

Resources

Documentation

• PTHelper Documentation
• API Reference
• Module Development Guide

Community

• PTHelper GitHub
• Community Forum
• Discord Server

Training

• PTHelper Academy
• Video Tutorials
• Certification Program