shieldscan 1.0.21
Professional Web Security Assessment Tool
License: MIT
Requires Python: >=3.9
Keywords: security, pentesting, web-security, owasp

# 🛡️ ShieldScan - Professional Web Security Assessment Tool

[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

**ShieldScan** is a professional, ethical web security assessment tool designed for authorized penetration testing. It provides comprehensive OWASP Top 10 vulnerability detection with a focus on safety, legal compliance, and responsible disclosure.

## ⚠️ Legal Notice

**USE THIS TOOL RESPONSIBLY AND LEGALLY**

- ✅ Only use on systems you **own** or have **explicit written authorization** to test
- ✅ Obtain proper consent before running in **active mode**
- ✅ Respect rate limits and avoid causing service disruption
- ❌ Unauthorized access to computer systems is **illegal** under applicable laws
- ❌ The authors assume **no liability** for misuse of this tool

## 🚀 Features

### Safe-by-Default Design
- **Passive Mode (Default)**: Non-intrusive reconnaissance and header analysis
- **Active Mode**: Requires explicit consent file for intrusive testing
- **Rate Limiting**: Configurable request throttling (default: 1 req/sec)
- **Dry Run**: Preview checks without sending requests

### Comprehensive Security Checks
✅ **HTTP Security Headers**: CSP, HSTS, X-Frame-Options, etc.  
✅ **Cookie Security**: Secure, HttpOnly, SameSite attributes  
✅ **XSS Detection**: Reflected XSS using benign markers  
✅ **SQL Injection**: Error-based detection (non-destructive)  
✅ **CORS Misconfiguration**: Wildcard and origin reflection  
✅ **Directory Listing**: Common directory exposure  
✅ **Open Redirect**: Parameter-based redirect testing  
✅ **Clickjacking**: Frame protection analysis  

### Professional Reporting
- **JSON**: Structured data for automation
- **Markdown**: Stakeholder-friendly reports
- **HTML**: Styled web reports with severity visualization
- **Console**: Real-time terminal output

### Reconnaissance
- 🔍 robots.txt and sitemap.xml parsing
- 🔗 Intelligent link discovery and crawling
- 📝 Form and input parameter extraction
- 🔧 Technology fingerprinting

## 📦 Installation

### From Source

```bash
# Clone the repository
git clone https://github.com/yourusername/shieldscan.git
cd shieldscan

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .
```

### Using pip (once published)

```bash
pip install shieldscan
```

## 🎯 Quick Start

### 1. Basic Passive Scan (Safe)

```bash
shieldscan scan --target https://example.com --output report.json
```

This performs non-intrusive checks:
- Security header analysis
- Cookie configuration
- CORS policy review
- Basic reconnaissance

### 2. Active Scan with Consent

First, create a consent file (see `examples/consent_template.txt`):

```bash
# Edit consent file with authorization details
cp examples/consent_template.txt my_consent.txt
nano my_consent.txt
```

Then run active scan:

```bash
shieldscan scan \
  --target https://authorized-site.com \
  --mode active \
  --consent-file my_consent.txt \
  --output report.md \
  --format markdown
```

### 3. Scan Multiple Targets

```bash
# Create file with URLs (one per line)
cat > targets.txt << EOF
https://example.com
https://test.example.com
EOF

shieldscan scan --target-file targets.txt --format all --output results
```

### 4. Dry Run (Preview)

```bash
shieldscan scan --target https://example.com --dry-run
```

## 🔧 Usage

### Command-Line Options

```
shieldscan scan [OPTIONS]

Target Options:
  --target URL              Single target URL
  --target-file FILE        File with URLs (one per line)

Scan Options:
  --mode MODE               Scanning mode: passive (default) or active
  --consent-file FILE       Consent file (required for active mode)
  --throttle FLOAT          Requests per second (default: 1.0)
  --max-depth INT           Maximum crawl depth (default: 2)

Output Options:
  --output FILE             Output file path
  --format FORMAT           Output format: json, markdown, html, all

Other Options:
  --dry-run                 Show planned checks without executing
  --no-logo                 Suppress logo display
  -v, --verbosity LEVEL     Logging verbosity: 0 (warn), 1 (info), 2 (debug)
```

### Examples

**Comprehensive scan with all report formats:**
```bash
shieldscan scan \
  --target https://example.com \
  --format all \
  --output comprehensive_report \
  --throttle 2.0 \
  --max-depth 3
```

**Quiet passive scan:**
```bash
shieldscan scan --target https://example.com --verbosity 0 --no-logo
```

**Active scan with custom rate limit:**
```bash
shieldscan scan \
  --target https://authorized.com \
  --mode active \
  --consent-file consent.txt \
  --throttle 0.5 \
  --output detailed_scan.html \
  --format html
```

## 📋 Consent File Format

Active mode requires a consent file with the following information:

```
TARGET: https://example.com
SIGNATURE: John Doe
DATE: 2025-10-29
```

See `examples/consent_template.txt` for a complete template.

## 🏗️ Architecture

ShieldScan follows a modular design:

```
┌─────────────┐
│   CLI       │  ← Entry point, argument parsing
└──────┬──────┘
       │
┌──────▼──────┐
│  Scanner    │  ← Orchestrates scan workflow
└──────┬──────┘
       │
       ├──────────────┬─────────────┬──────────────┐
       │              │             │              │
┌──────▼──────┐ ┌────▼─────┐ ┌────▼─────┐  ┌─────▼──────┐
│ HTTP Client │ │ Gatherer │ │ VulnCheck│  │  Reporter  │
│ (Rate Ltd.) │ │ (Recon)  │ │ (Detect) │  │ (Output)   │
└─────────────┘ └──────────┘ └──────────┘  └────────────┘
```

### Modules

- **cli.py**: Command-line interface with argparse
- **scanner.py**: Core orchestration engine
- **http_client.py**: HTTP wrapper with rate limiting and retries
- **gather.py**: Reconnaissance (robots.txt, sitemap, crawling)
- **vuln_checks.py**: Vulnerability detection checks
- **reporter.py**: Multi-format report generation
- **utils.py**: Common utilities and helpers
- **logo.py**: ASCII branding

## 🧪 Testing

Run the test suite:

```bash
# Run all tests
pytest

# With coverage
pytest --cov=web_pentest_cli --cov-report=html

# Run specific test file
pytest tests/test_utils.py -v
```

## 🔌 Adding Custom Checks

ShieldScan supports plugin-style vulnerability checks:

```python
from web_pentest_cli.vuln_checks import VulnerabilityCheck, VulnerabilityResult

class CustomCheck(VulnerabilityCheck):
    @property
    def check_id(self) -> str:
        return "CUSTOM-001"

    @property
    def check_name(self) -> str:
        return "My Custom Check"

    def check(self, target_url: str, context: dict) -> List[VulnerabilityResult]:
        # Implement your check logic
        results = []
        response = self.client.get(target_url)

        if response and "vulnerable_pattern" in response.text:
            results.append(VulnerabilityResult(
                vuln_id=self.check_id,
                name="Custom Vulnerability",
                severity="medium",
                confidence="high",
                description="Description of the issue",
                evidence="Evidence from response",
                remediation="How to fix it"
            ))

        return results
```

## 📊 Sample Output

### Console Summary
```
================================================================================
  SCAN SUMMARY
================================================================================
Target:     https://example.com
Scan ID:    scan_1730193600
Duration:   12.45 seconds
Requests:   23

Total Vulnerabilities: 5

Severity Breakdown:
  HIGH: 2
  MEDIUM: 2
  LOW: 1
================================================================================
```

### JSON Report Structure
```json
{
  "scan_id": "scan_1730193600",
  "target_url": "https://example.com",
  "mode": "passive",
  "vulnerabilities": [
    {
      "vuln_id": "SEC-HEADERS-001-csp",
      "name": "Missing Content-Security-Policy Header",
      "severity": "medium",
      "confidence": "high",
      "description": "CSP header is missing",
      "evidence": "Header 'content-security-policy' not found",
      "remediation": "Implement CSP to prevent XSS",
      "references": ["https://owasp.org/..."]
    }
  ],
  "statistics": {
    "total_vulnerabilities": 5,
    "severity_breakdown": {"high": 2, "medium": 2, "low": 1}
  }
}
```

## 🛠️ Development

### Setup Development Environment

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Format code
black web_pentest_cli/

# Lint
flake8 web_pentest_cli/

# Type checking
mypy web_pentest_cli/
```

### Project Structure

```
shieldscan/
├── web_pentest_cli/
│   ├── __init__.py
│   ├── cli.py
│   ├── scanner.py
│   ├── http_client.py
│   ├── gather.py
│   ├── vuln_checks.py
│   ├── reporter.py
│   ├── utils.py
│   └── logo.py
├── tests/
│   ├── test_utils.py
│   ├── test_http_client.py
│   └── test_vuln_checks.py
├── examples/
│   ├── consent_template.txt
│   └── example_urls.txt
├── README.md
├── requirements.txt
├── setup.py
└── pyproject.toml
```

## 📚 References

- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [OWASP Testing Guide](https://owasp.org/www-project-web-security-testing-guide/)
- [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/)
- [OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/)

## 📝 License

MIT License - see LICENSE file for details.

## 👨‍💻 Author

**Dr. Ing. [Marzouk Mohamed Amine]**  
📧 Email: med.amine.mzk@gmail.com or mohamedamin.marzouk@sousse.r-iset.tn  
🏛️ Institution: University of Sousse  
🔬 Research: Internet of Vehicles, Security Testing, Traffic Optimization

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

## 📞 Support

For issues, questions, or contributions:
- 🐛 Report bugs: [GitHub Issues](https://github.com/Medamine-mzk/ShieldScan/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/Medamine-mzk/ShieldScan/discussions)
- 📧 Email: med.amine.mzk@gmail.com or mohamedamin.marzouk@sousse.r-iset.tn

## ⚡ Disclaimer

This tool is provided for educational and authorized testing purposes only. The authors and contributors:

- Are not responsible for any misuse or damage caused by this tool
- Do not endorse illegal activities
- Recommend obtaining proper authorization before testing
- Advise consulting legal counsel regarding testing activities

**Always test responsibly and ethically.**

---

Made with ❤️ for the security community