pentest-toolkit

What this skill does

# 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**:
```bash
uv run python scripts/discover_structure.py <TARGET_URL>
```

**Returns JSON**:
```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**:
```bash
uv run python scripts/enumerate_endpoints.py <TARGET_URL>
```

**Returns JSON**:
```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**:
```bash
uv run python scripts/scan_ports.py <TARGET_IP>
```

**Returns JSON**:
```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**:
```bash
uv run python scripts/analyze_responses.py <RESPONSES_FILE>
```

**Input**: JSON file with HTTP responses
**Returns JSON**:
```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**:
```bash
uv run python scripts/generate_context_tests.py <STRUCTURE_FILE> <PATTERNS_FILE>
```

**Returns JSON**:
```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**:
```bash
uv run python scripts/test_sql_injection.py <TARGET_URL>
```

**Returns JSON**:
```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**:
```bash
uv run python scripts/test_xss.py <TARGET_URL>
```

**Returns JSON**:
```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**:
```bash
uv run python scripts/comprehensive_test.py <TARGET_URL>
```

**Returns JSON**:
```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**:
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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

```python
# 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:

```bash
# 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
```json
{
  "success": false,
  "error_type": "NETWORK_ERROR|VALIDATION_ERROR|SECURITY_ERROR",
  "message": "string",
  "context": {}
}
```

## 🎯 Agent Integration Examples

### Claude Skill Integration
```bash
# Claude will automatically discover and use these scripts
skill: "pentest-toolkit"

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

##