name: pentest-toolkit

prettier-ignore

description: AI-Powered Security Testing Toolkit - Professional penetration testing scripts for discovering vulnerabilities, analyzing application structure, and generating context-aware security tests. All scripts return structured JSON for agent consumption.
allowed-tools:
- Read
- Grep
- Glob
- Bash(uv:*)

AI-Powered Security Testing Toolkit

A comprehensive penetration testing skill designed specifically for AI agents. This toolkit provides specialized scripts that perform intelligent security assessments and return structured JSON output for agent consumption. All scripts are designed for automated execution without human interaction.

🚀 AI Agent Scripts

All scripts are located in the scripts/ directory and return structured JSON output.

Discovery Scripts

discover_structure.py

Purpose: Blindly discovers API structure, data models, and business logic without source code access.

Usage:

uv run python scripts/discover_structure.py <TARGET_URL>

Returns JSON:

{
  "base_url": "string",
  "discovered_endpoints": [...],
  "data_models": {...},
  "business_entities": [...],
  "authentication_patterns": {...},
  "technologies": [...],
  "vulnerability_indicators": [...]
}

Key Features:
- Automatic endpoint enumeration
- Data model inference from responses
- Business entity identification
- Authentication pattern mapping
- Technology stack detection

enumerate_endpoints.py

Purpose: Fast endpoint enumeration for quick attack surface mapping.

Usage:

uv run python scripts/enumerate_endpoints.py <TARGET_URL>

Returns JSON:

{
  "endpoints": [
    {
      "url": "string",
      "method": "string",
      "status_code": "number",
      "content_type": "string",
      "parameters": [...]
    }
  ],
  "total_found": "number"
}

scan_ports.py

Purpose: Network port scanning for service discovery.

Usage:

uv run python scripts/scan_ports.py <TARGET_IP>

Returns JSON:

{
  "target": "string",
  "open_ports": [
    {
      "port": "number",
      "service": "string",
      "version": "string"
    }
  ],
  "scan_time": "string"
}

Analysis Scripts

analyze_responses.py

Purpose: Extracts security-relevant patterns and relationships from HTTP responses.

Usage:

uv run python scripts/analyze_responses.py <RESPONSES_FILE>

Input: JSON file with HTTP responses
Returns JSON:

{
  "patterns": {
    "data_relationships": [...],
    "business_logic_flaws": [...],
    "authentication_bypasses": [...]
  },
  "recommendations": [...]
}

Key Features:
- Pattern recognition in response structures
- Data relationship mapping
- Business logic vulnerability identification
- Security control gaps detection

Test Generation Scripts

generate_context_tests.py

Purpose: Creates targeted security tests based on discovered application structure and patterns.

Usage:

uv run python scripts/generate_context_tests.py <STRUCTURE_FILE> <PATTERNS_FILE>

Returns JSON:

{
  "test_scenarios": [
    {
      "id": "string",
      "name": "string",
      "category": "string",
      "risk_level": "HIGH|MEDIUM|LOW",
      "target_endpoints": ["string"],
      "test_cases": [...]
    }
  ]
}

Key Features:
- Context-aware test generation
- Business logic focused testing
- Application-specific payloads
- Risk-based test prioritization

Vulnerability Testing Scripts

test_sql_injection.py

Purpose: Comprehensive SQL injection testing with multiple techniques.

Usage:

uv run python scripts/test_sql_injection.py <TARGET_URL>

Returns JSON:

{
  "vulnerabilities": [
    {
      "type": "SQL_INJECTION",
      "location": "string",
      "payload": "string",
      "evidence": "string",
      "severity": "CRITICAL|HIGH|MEDIUM|LOW"
    }
  ],
  "tested_endpoints": ["string"]
}

Techniques:
- Union-based injection
- Boolean-based blind injection
- Time-based blind injection
- Error-based injection

test_xss.py

Purpose: Cross-site scripting vulnerability detection.

Usage:

uv run python scripts/test_xss.py <TARGET_URL>

Returns JSON:

{
  "xss_vulnerabilities": [
    {
      "type": "REFLECTED|STORED|DOM",
      "location": "string",
      "payload": "string",
      "context": "string",
      "severity": "HIGH|MEDIUM|LOW"
    }
  ]
}

comprehensive_test.py

Purpose: Runs all vulnerability tests in a coordinated manner.

Usage:

uv run python scripts/comprehensive_test.py <TARGET_URL>

Returns JSON:

{
  "assessment_summary": {
    "target": "string",
    "start_time": "string",
    "end_time": "string",
    "total_vulnerabilities": "number"
  },
  "vulnerabilities_by_category": {...}
}

Report Generation Scripts

generate_report.py

Purpose: Generates security reports from test results.

Usage:

uv run python scripts/generate_report.py <RESULTS_FILE>

Outputs:
- security_report.md - Human-readable report
- security_report.json - Machine-readable findings

🎯 AI Agent Workflows

Standard Security Assessment

# Step 1: Discover application structure
uv run python scripts/discover_structure.py https://target.com > structure.json

# Step 2: Analyze responses for patterns
uv run python scripts/analyze_responses.py structure.json > patterns.json

# Step 3: Generate targeted tests
uv run python scripts/generate_context_tests.py structure.json patterns.json > tests.json

# Step 4: Execute vulnerability tests
uv run python scripts/comprehensive_test.py https://target.com > vuln_results.json

# Step 5: Generate final report
uv run python scripts/generate_report.py vuln_results.json

API Security Testing

# Focus on API endpoints
uv run python scripts/discover_structure.py https://api.target.com > api_structure.json

# Test for API-specific vulnerabilities
uv run python scripts/test_sql_injection.py https://api.target.com/users
uv run python scripts/test_xss.py https://api.target.com/search

# Analyze API responses
uv run python scripts/analyze_responses.py api_responses.json

Business Logic Testing

# Discover business entities and relationships
uv run python scripts/discover_structure.py https://app.target.com > app_structure.json

# Generate business logic tests
uv run python scripts/generate_context_tests.py app_structure.json patterns.json > business_tests.json

# Execute with focus on authorization and workflow abuse

📚 Knowledge Base

Pattern Libraries

Located in patterns/ directory:

business_logic.json

Contains vulnerability patterns for:
- Authorization bypasses
- State manipulation
- Workflow circumvention
- Race conditions
- Resource abuse

data_relationships.json

Contains patterns for:
- Insecure direct object references
- Foreign key manipulation
- Junction table abuse
- Hierarchical relationship attacks

Using Patterns with Agents

# Load business logic patterns
with open('patterns/business_logic.json', 'r') as f:
    business_patterns = json.load(f)

# Generate tests based on discovered structure + patterns
# This creates context-aware tests for the specific application

🔧 Script Execution Requirements

Critical: UV Usage

All scripts MUST use uv run python for proper dependency management:

# Correct
uv run python scripts/discover_structure.py https://target.com

# Incorrect - will fail
python scripts/discover_structure.py https://target.com

Input/Output Format

All scripts follow these conventions:
- Input: Command-line arguments or JSON files
- Output: Structured JSON to stdout
- No prompts: All scripts run non-interactively
- Error handling: Structured error messages in JSON

Error Format

{
  "success": false,
  "error_type": "NETWORK_ERROR|VALIDATION_ERROR|SECURITY_ERROR",
  "message": "string",
  "context": {}
}

🎯 Agent Integration Examples

Claude Skill Integration

# Claude will automatically discover and use these scripts
skill: "pentest-toolkit"

# Claude can execute:
uv run python scripts/discover_structure.py {{TARGET_URL}}

Custom Agent Workflow

def security_assessment(target):
    # Discover structure
    structure = execute_script("discover_structure.py", target)

    # Analyze patterns
    patterns = execute_script("analyze_responses.py", "structure.json")

    # Generate tests
    tests = execute_script("generate_context_tests.py", "structure.json", "patterns.json")

    # Execute tests
    results = execute_script("comprehensive_test.py", target)

    # Generate report
    report = execute_script("generate_report.py", "results.json")

    return {
        "structure": structure,
        "vulnerabilities": results,
        "report": report
    }

Batch Testing Multiple Targets

def batch_assessment(targets):
    results = {}

    for target in targets:
        # Run full assessment
        assessment = security_assessment(target)
        results[target] = assessment

        # Learn from patterns for faster testing
        update_knowledge_base(assessment)

    return results

⚡ Performance Considerations

Caching

• Structure discovery results can be cached
• Pattern analysis is reusable across similar applications
• Test generation is fast once patterns are understood

Parallel Execution

• Multiple endpoints can be tested in parallel
• Different vulnerability types can be tested simultaneously
• Batch processing supported for multiple targets

Rate Limiting

• Use conservative request rates when testing targets
• Respect published rate limit headers and robots.txt as appropriate
• Avoid denial-of-service conditions

🛡️ Security & Compliance

Authorization Testing Only

• Only test systems you own or have explicit authorization to assess
• Focus on discovery and validation, avoiding destructive payloads

Output Handling

• Results may contain response data; handle and store securely
• Avoid logging credentials or secrets; redact where necessary

Legal Compliance

• Designed for authorized security testing only
• Includes responsible usage validation
• Supports compliance reporting

📊 Success Metrics

When scripts run successfully, agents should expect:
- Structured JSON output with consistent schemas
- Actionable findings with risk levels and remediation
- Performance metrics for optimization
- Error details for troubleshooting

🔗 Related Files

• reference.md - Detailed API documentation
• examples.md - Practical usage examples
• templates/ - Reusable test templates and workflows