WebScanner Overview - capstone-hermes/hermes-fullstack GitHub Wiki

WebScanner Overview

🚧 Documentation in Progress

This section contains documentation for the Hermes WebScanner component - an automated web vulnerability scanner built with Python.

About the WebScanner Component

The WebScanner is a comprehensive web application security scanner designed for educational and professional penetration testing. It implements automated detection of common web vulnerabilities and provides detailed reporting for security assessment purposes.

Technology Stack

  • Language: Python 3.x
  • Framework: FastAPI (API endpoints)
  • HTTP Library: Requests
  • Testing: pytest
  • Containerization: Docker
  • Code Quality: flake8, black

Key Features

  • Automated Vulnerability Scanning: Detect common web application vulnerabilities
  • Multiple Scan Types: SQL injection, XSS, file upload vulnerabilities, and more
  • API Integration: RESTful API for integration with other components
  • Report Generation: Detailed JSON and CSV reports
  • Educational Focus: Clear vulnerability explanations and remediation guidance
  • Extensible Architecture: Plugin-based vulnerability detection modules

Documentation Structure

User Documentation

Technical Documentation

Scanning Documentation

Development Documentation

Quick Start

Command Line Usage

# Basic scan
python src/main.py https://target-website.com

# Docker usage
docker run web-scanner https://target-website.com

# With output file
python src/main.py https://target-website.com --output results.json

API Usage

# Start API server
python src/api.py

# Initiate scan via API
curl -X POST "http://localhost:8000/scan" \
  -H "Content-Type: application/json" \
  -d '{"target": "https://target-website.com"}'

Vulnerability Detection Capabilities

Current Modules

  • SQL Injection Detection: Automated SQLi payload testing
  • Cross-Site Scripting (XSS): Reflected and stored XSS detection
  • File Upload Vulnerabilities: Malicious file upload testing
  • Input Validation Issues: Parameter pollution and injection testing
  • Authentication Testing: Weak authentication mechanism detection
  • Path Traversal: Directory traversal vulnerability detection
  • Command Injection: OS command injection testing

Detection Techniques

  • Signature-based Detection: Known vulnerability patterns
  • Behavioral Analysis: Response analysis for vulnerability indicators
  • Fuzzing: Input mutation testing
  • Error-based Detection: Error message analysis
  • Time-based Detection: Response timing analysis

Integration with Other Components

GUI Integration

  • Scan Management: Initiate and monitor scans from GUI
  • Result Visualization: Display scan results in user-friendly format
  • Configuration: Configure scanner settings through GUI interface

Weak Website Testing

  • Target Application: Designed to test the weak website component
  • Educational Validation: Verify intentional vulnerabilities
  • Learning Integration: Map detected vulnerabilities to educational content

Scanner Architecture

Core Components

WebScanner/
├── src/
│   ├── main.py              # CLI entry point
│   ├── api.py               # FastAPI server
│   ├── scanner/
│   │   ├── core.py          # Core scanning engine
│   │   ├── modules/         # Vulnerability detection modules
│   │   └── reporting.py     # Report generation
│   └── utils/
│       ├── http_client.py   # HTTP communication
│       └── payloads.py      # Vulnerability payloads

Plugin Architecture

# Example vulnerability module
class SQLInjectionModule(VulnerabilityModule):
    def scan(self, target_url, parameters):
        # Implement SQL injection detection logic
        return vulnerability_results

Report Formats

JSON Report Structure

{
  "target": "https://example.com",
  "scan_time": "2024-01-15T10:30:00Z",
  "vulnerabilities": [
    {
      "type": "SQL Injection",
      "severity": "High",
      "location": "/login",
      "parameter": "email",
      "payload": "' OR '1'='1",
      "description": "SQL injection vulnerability found",
      "remediation": "Use parameterized queries"
    }
  ]
}

Educational Features

Learning Integration

  • Vulnerability Explanations: Detailed explanations of each vulnerability type
  • Remediation Guidance: Step-by-step fix instructions
  • OWASP Mapping: Links to OWASP guidelines and resources
  • Example Payloads: Educational payload examples with explanations

Safe Testing Environment

  • Controlled Targets: Designed for testing controlled environments
  • Educational Warnings: Clear warnings about authorized testing only
  • Learning Objectives: Specific learning goals for each scan type

Coming Soon

This documentation section is actively being developed. Check back for comprehensive guides covering:

  • Advanced scanning techniques
  • Custom module development
  • Integration patterns
  • Performance optimization
  • Reporting customization

Related Documentation