🛡️ ShieldScan - Professional Web Security Assessment Tool

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

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

pip install shieldscan

🎯 Quick Start

1. Basic Passive Scan (Safe)

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

# Edit consent file with authorization details
cp examples/consent_template.txt my_consent.txt
nano my_consent.txt

Then run active scan:

shieldscan scan \
  --target https://authorized-site.com \
  --mode active \
  --consent-file my_consent.txt \
  --output report.md \
  --format markdown

3. Scan Multiple Targets

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

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:

shieldscan scan \
  --target https://example.com \
  --format all \
  --output comprehensive_report \
  --throttle 2.0 \
  --max-depth 3

Quiet passive scan:

shieldscan scan --target https://example.com --verbosity 0 --no-logo

Active scan with custom rate limit:

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:

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

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

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

# 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
• OWASP Testing Guide
• OWASP Secure Headers Project
• OWASP Cheat Sheet Series

📝 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
• 💬 Discussions: GitHub 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