pentest-toolkit

# AI-Powered Security Testing Toolkit

A comprehensive penetration testing toolkit that provides professional security testing capabilities for both human security professionals and AI agents. This toolkit combines traditional vulnerability testing with intelligent, context-aware security assessment capabilities.

**License**: MIT License - Free for commercial and personal use

## Quick Start for Human Users

### Prerequisites
- Python 3.8 or higher
- Target URL (must have written permission to test)

### Basic Usage

```bash
# Make the toolkit executable
chmod +x pentest-toolkit

# Run a quick security scan
./pentest-toolkit --target https://example.com --mode quick

# Run comprehensive penetration test
./pentest-toolkit --target https://example.com --mode comprehensive

# API-focused testing
./pentest-toolkit --target https://api.example.com --mode api
```

### For Claude AI Agents

The toolkit is designed as a Claude Skill that AI agents can use autonomously:

```bash
# Claude will automatically discover and use this skill
skill: "pentest-toolkit"
```

For detailed AI agent capabilities and workflows, see [SKILL.md](SKILL.md).

## Installation

### Requirements
- Python 3.8 or higher
- Optional: Astral uv (auto-installed if needed)

### Setup Methods

**1. Self-Contained (No uv)**
```bash
# Clone and run directly
git clone https://github.com/your-username/pentest-toolkit
cd pentest-toolkit
chmod +x pentest-toolkit
./pentest-toolkit --target https://example.com --mode quick
```

**2. With uv (Recommended)**
```bash
# Clone and setup with uv
git clone https://github.com/your-username/pentest-toolkit
cd pentest-toolkit
chmod +x pentest-toolkit
# Run directly - uv will be installed automatically if needed
./pentest-toolkit --target https://example.com --mode quick
```

### uv Benefits
- **Isolated Environment**: Each test runs in isolated virtual environment
- **Fast Execution**: uv's optimized Python package management
- **Auto-Installation**: Automatically installs if not present
- **Fallback Support**: Gracefully uses system Python if uv unavailable

## Testing Modes

### Quick Mode (Recommended for Start)
- **Purpose**: Fast identification of critical vulnerabilities
- **Duration**: 5-10 minutes
- **Tests**: Basic injection, common misconfigurations, exposed panels

### Comprehensive Mode
- **Purpose**: Full security assessment
- **Duration**: 30-60 minutes
- **Tests**: All vulnerability categories, business logic analysis

### API Mode
- **Purpose**: API-specific security testing
- **Duration**: 15-30 minutes
- **Tests**: Authentication, authorization, API-specific attacks

## Sample Outputs

### Quick Scan Results
```
[+] Target: https://example.com
[+] Scan started: 2024-01-15 10:00:00

=== Discovery Phase ===
[+] Endpoints found: 12
[+] Technology: Node.js / Express 4.18

=== Vulnerability Testing ===
[+] Testing login form for SQL injection...
[+] Testing search parameter for XSS...

=== Summary ===
Critical: 0
High: 1
Medium: 2
Low: 5
```

### Generated Files
- `discovered_endpoints.json` - All discovered URLs
- `security_report.md` - Human-readable report
- `security_report.json` - Machine-readable findings

## Next Steps

### For Detailed Documentation
- **[SKILL.md](SKILL.md)** - Complete AI agent capabilities and workflows
- **[reference.md](reference.md)** - Technical API documentation
- **[examples.md](examples.md)** - Practical usage examples and scenarios

### For Advanced Usage
- Individual script execution for custom testing
- Integration with CI/CD pipelines
- Custom pattern creation for business logic testing

### Responsible Usage
⚠️ **CRITICAL**: Only test systems you own or have explicit written permission to test.

1. **Always get authorization** before testing
2. **Use staging environments** for initial testing
3. **Follow responsible disclosure** for found vulnerabilities
4. **Respect rate limits** and avoid denial-of-service

## Troubleshooting

### Common Issues

**Permission Denied**
```bash
chmod +x pentest-toolkit
```

**Network Timeout**
```bash
# Test local server instead
./pentest-toolkit --target http://localhost:3000 --mode quick
```

**SSL Certificate Errors**
```bash
# Use HTTP for local testing
./pentest-toolkit --target http://localhost:3000 --mode quick
```

## Support

For detailed technical documentation:
- **[SKILL.md](SKILL.md)** - Complete feature reference
- **[reference.md](reference.md)** - API documentation
- **[examples.md](examples.md)** - Usage examples

For issues or questions, check the script outputs for detailed error messages.

---

**Remember**: Security tools should only be used for legitimate, authorized testing purposes.