# 🔒 Penetration Testing Claude Skill

**Production-grade penetration testing automation powered by Claude AI**

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/yourusername/pentesting-skill)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

## Overview

The Penetration Testing Claude Skill is a comprehensive security assessment tool that combines **Static Application Security Testing (SAST)**, **dynamic attack simulation**, and **enterprise-grade reporting** to automate penetration testing workflows.

Built on Claude's advanced semantic code understanding, this Skill goes beyond simple pattern matching to identify complex vulnerabilities across code, infrastructure, and application layers.

### Key Features

- 🔍 **Semantic SAST Analysis** - Deep code understanding using Claude's AI
- 🎯 **OWASP Top 10 Coverage** - Comprehensive vulnerability detection
- 🚀 **CI/CD Integration** - Seamless GitHub Actions workflows
- 📊 **Enterprise Reporting** - Professional HTML/PDF/JSON reports
- 🔗 **Attack Chain Detection** - Identify multi-step exploitation paths
- ✅ **False Positive Filtering** - Context-aware noise reduction
- 🛡️ **Dynamic Testing** (Phase 2) - Active vulnerability confirmation

## Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/pentesting-skill.git
cd pentesting-skill

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
export ANTHROPIC_API_KEY="your-api-key"
```

### Basic Usage

#### 1. Run SAST Analysis

```python
from handlers.sast_analyzer import SASTAnalyzer

analyzer = SASTAnalyzer()
findings = analyzer.analyze_codebase(
    repo_path="./my-project",
    scope="full_codebase"
)

# Export results
analyzer.export_findings(findings, "findings.json", format="json")
```

#### 2. Generate Security Report

```python
from handlers.report_generator import ReportGenerator

report_gen = ReportGenerator(organization_context={
    "name": "Your Company",
    "application": "My Application"
})

report_path = report_gen.generate_report(
    findings=findings,
    format="html"
)

print(f"Report generated: {report_path}")
```

#### 3. GitHub Actions Integration

Add to `.github/workflows/security.yml`:

```yaml
name: Security Scan

on:
  pull_request:
    branches: [main]

jobs:
  pentest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Run Security Assessment
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          python -m handlers.sast_analyzer \
            --scope changed_files \
            --output findings.json
```

## Architecture

```
pentesting-skill/
├── SKILL.md                      # Skill manifest
├── instructions/                 # Analysis instructions for Claude
│   ├── security-review.md        # SAST guidelines
│   ├── dynamic-testing.md        # Active testing protocols
│   ├── attack-vectors.md         # Attack taxonomy
│   ├── reporting.md              # Report generation
│   └── orchestration.md          # Workflow coordination
├── handlers/                     # Core Python modules
│   ├── sast_analyzer.py          # Static analysis engine
│   ├── report_generator.py       # Report generation
│   ├── finding_aggregator.py    # Finding deduplication
│   ├── payload_generator.py     # Attack payload creation
│   └── dynamic_executor.py      # Dynamic testing (Phase 2)
├── resources/                    # Configuration & templates
│   ├── attack_vectors.json       # Vulnerability taxonomy
│   ├── severity_matrix.json      # CVSS scoring matrix
│   ├── false_positive_filters.txt
│   └── report_templates/
├── tests/                        # Test suite
└── .github/workflows/            # CI/CD workflows
```

## Vulnerability Coverage

### OWASP Top 10 2021

✅ **A01:2021 - Broken Access Control**
- IDOR (Insecure Direct Object References)
- Path Traversal
- Missing Authorization

✅ **A02:2021 - Cryptographic Failures**
- Weak Algorithms (MD5, SHA1, DES)
- Hardcoded Secrets
- Insufficient Key Length

✅ **A03:2021 - Injection**
- SQL Injection
- NoSQL Injection
- Command Injection
- LDAP/XPath Injection

✅ **A04:2021 - Insecure Design**
- Business Logic Flaws
- Race Conditions

✅ **A05:2021 - Security Misconfiguration**
- Debug Mode Enabled
- Default Credentials
- CORS Misconfiguration
- Missing Security Headers

✅ **A06:2021 - Vulnerable Components**
- Outdated Dependencies
- Known CVEs

✅ **A07:2021 - Authentication Failures**
- Weak Password Hashing
- Predictable Session Tokens
- Missing Rate Limiting

✅ **A08:2021 - Integrity Failures**
- Insecure Deserialization
- CI/CD Pipeline Vulnerabilities

✅ **A09:2021 - Logging Failures**
- Insufficient Logging
- Sensitive Data in Logs

✅ **A10:2021 - SSRF**
- Server-Side Request Forgery
- Cloud Metadata Access

### Additional Coverage

- Cross-Site Scripting (XSS) - Reflected, Stored, DOM-based
- XML External Entities (XXE)
- CSRF (Cross-Site Request Forgery)
- Open Redirect
- Clickjacking
- Information Disclosure

## Configuration

### Custom Security Policies

Create `.security/pen-test-policies.json`:

```json
{
  "severity_threshold": "medium",
  "scan_scope": "changed_files",
  "false_positive_filters": true,
  "custom_rules": [
    {
      "id": "CUSTOM-001",
      "pattern": "hardcoded_api_key",
      "severity": "critical",
      "message": "API keys must be in environment variables"
    }
  ],
  "excluded_paths": [
    "tests/",
    "vendor/",
    "node_modules/"
  ],
  "compliance_frameworks": ["OWASP", "PCI-DSS", "NIST"]
}
```

### Environment Variables

```bash
# Required
ANTHROPIC_API_KEY=your-claude-api-key

# Optional
PENTEST_ENVIRONMENT=staging          # Target environment
PENTEST_MAX_RPS=2                   # Rate limit for dynamic testing
PENTEST_TIMEOUT=30                  # Timeout in seconds
PENTEST_HALT_ON_ERROR=true          # Stop on service disruption
```

## Report Formats

### JSON (Machine-readable)

```json
{
  "report_metadata": {
    "report_id": "PENTEST-2025-001",
    "date": "2025-10-31T14:30:00Z",
    "scope": "Customer Portal v2.3.1"
  },
  "findings": [
    {
      "id": "FIND-001",
      "severity": "CRITICAL",
      "category": "SQL Injection",
      "cvss_score": 9.8,
      "file": "api/auth.py",
      "line": 42,
      "description": "...",
      "remediation": "..."
    }
  ]
}
```

### HTML (Professional Report)

- Executive summary
- Severity distribution charts
- Detailed findings with code snippets
- Remediation guidance
- Compliance mapping

### PDF (Executive Distribution)

- Print-ready format
- One-page executive summary
- Technical appendices

## Testing

```bash
# Run unit tests
python -m pytest tests/

# Test SAST analyzer
python -m pytest tests/test_sast.py -v

# Test finding aggregator
python -m pytest tests/test_finding_aggregator.py -v

# Test with vulnerable code fixtures
python -m pytest tests/ --fixtures
```

## CI/CD Integration

### Pull Request Scanning

Automatically scans changed files on every PR:

```yaml
on:
  pull_request:
    branches: [main]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run SAST
        run: python -m handlers.sast_analyzer --scope changed_files
```

### Scheduled Full Scans

Weekly comprehensive security assessment:

```yaml
on:
  schedule:
    - cron: '0 2 * * 1'  # Every Monday at 2 AM

jobs:
  full-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Comprehensive Security Scan
        run: python -m handlers.sast_analyzer --scope full_codebase
```

## Roadmap

### Phase 1: MVP (Weeks 1-4) ✅
- [x] SAST analysis with Claude
- [x] GitHub Actions integration
- [x] JSON/HTML reporting
- [x] False positive filtering

### Phase 2: Advanced Analysis (Weeks 5-8)
- [ ] Infrastructure-as-Code scanning (Terraform, K8s)
- [ ] Dependency vulnerability analysis
- [ ] API security assessment
- [ ] Business logic flaw detection

### Phase 3: Dynamic Testing (Weeks 9-14)
- [ ] Payload generation engine
- [ ] Sandboxed attack execution
- [ ] Multi-step attack chains
- [ ] Vulnerability confirmation

### Phase 4: Enterprise Features (Weeks 15-20)
- [ ] PDF report generation
- [ ] CVSS v3.1 scoring
- [ ] Jira/GitHub issue integration
- [ ] Compliance mapping (PCI-DSS, HIPAA, SOC2)
- [ ] Multi-assessment trending

## Security & Safety

⚠️ **Important Safety Guidelines**:

1. **Never run dynamic testing against production environments**
2. **Always validate target environment before active testing**
3. **Use rate limiting to prevent service disruption**
4. **Maintain audit logs of all testing activities**
5. **Obtain proper authorization before conducting penetration tests**

### Dynamic Testing Safety Controls

- **Environment Validation**: Blocks testing on production domains
- **Circuit Breaker**: Halts testing after repeated failures
- **Rate Limiting**: Maximum 2 requests/second (configurable)
- **Audit Logging**: Comprehensive testing activity logs

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python -m pytest tests/ -v

# Run linter
pylint handlers/

# Format code
black handlers/ tests/
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- **Documentation**: [docs/](./docs/)
- **Issues**: [GitHub Issues](https://github.com/yourusername/pentesting-skill/issues)
- **Security**: security@example.com
- **Discord**: [Join our community](https://discord.gg/example)

## Acknowledgments

- Built on [Claude](https://www.anthropic.com/claude) by Anthropic
- Inspired by the open-source security community
- OWASP for vulnerability classifications
- CWE/SANS for security standards

---

**⚠️ Disclaimer**: This tool is for authorized security testing only. Ensure you have proper authorization before conducting penetration tests. The authors are not responsible for misuse of this tool.

---

Made with ❤️ by the Security Engineering Team

