# Pentest Toolkit

> 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.

- Skill: `majiayu000/pentest-toolkit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/pentest-toolkit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/pentest-toolkit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/pentest-toolkit

---


# 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}}
```

### Custom Agent Workflow
```python
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
```python
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