arcanaai-pta 1.0.0

ArcanaAI PTA - AI-Powered Penetration Testing Agent

🔒 Penetration Testing Claude Skill

Production-grade penetration testing automation powered by Claude AI

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

# 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

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

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:

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:

{
  "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

# 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)

{
  "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

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

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:

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) ✅

• SAST analysis with Claude
• GitHub Actions integration
• JSON/HTML reporting
• 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 for guidelines.

Development Setup

# 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 file for details.

Support

• Documentation: docs/
• Issues: GitHub Issues
• Security: [e-mail]
• Discord: Join our community

Acknowledgments

• Built on 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