WebScanner User Guide - capstone-hermes/hermes-fullstack GitHub Wiki

🐍 HERMES Web Scanner – User Guide

HERMES Web Scanner is a lightweight, educational CLI that automatically verifies a web application against OWASP ASVS Level 1.
It was built for students, junior pentesters and web developers who need a quick, reproducible security sanity-check.

🚀 Quick Start

  1. Clone & install

    git clone [https://github.com/your-org/hermes-fullstack.git](https://github.com/your-org/hermes-fullstack.git)
cd hermes-fullstack
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

  2. Run a scan

    python -m src/main --url [https://demo.vuln-site.com](https://demo.vuln-site.com)

  3. Inspect the results

    • Findings scroll live in the terminal and are written to scanner.log.
    • A structured JSON report is dropped in reports/, e.g. reports/scan-2025-05-07T15-30-00.json.

⚙️ CLI Options

Flag Purpose Default
--depth N Maximum crawl depth 3
--max-pages N Stop after N pages 100
--headful Launch Chrome with a visible window headless
--output FILE Custom JSON path auto-timestamp

Tip: Use --headful to watch the scanner fill forms in real time.

🔑 Key Features

  • Automatic crawling – headless Chromium (pyppeteer) explores same-origin links.
  • ASVS Level 1 coverage
    • V2 – Authentication: weak password policy, truncation, paste blocking, strength meter, …
    • V12 – Files & Resources: oversize upload, path traversal, RFI/LFI, …
  • JSON export – ready for the companion GUI dashboard.
  • Extensible – add new async checks by dropping a coroutine and listing it in function_list.
  • Safe defaults – time-outs and caps prevent accidental DoS on the target.

🧰 Technologies

  • Python 3.12, asyncio
  • pyppeteer – headless Chrome automation
  • BeautifulSoup 4 – DOM inspection
  • Structured logging via the standard logging module
  • Licensed under MIT

📋 Report Schema

Field Description
id ASVS control (e.g. V2.1.1)
title Human-readable summary
url Where the issue was observed
evidence Optional DOM or response snippet

The GUI consumes this file and hyperlinks each control to the OWASP spec.

✅ Best Practices

  • Permission first – only scan systems that you own or have explicit authorisation to test.
  • Ethical use – the tool is educational; misuse is your responsibility.
  • Verify manually – automated findings require human review.
  • Combine tools – complement HERMES with professional scanners and manual techniques.
  • Stay current – pull the latest code and pip install -U -r requirements.txt.

🤝 Who We Are

Created by EPITECH Brussels – Class of 2025 as part of the Hermes Fullstack capstone:

  • 🐍 Web Scanner (this CLI)
  • 💻 Weak Website – intentionally vulnerable React/Vite app for testing
  • 📊 GUI – dark-theme dashboard that visualises the JSON reports

🔗 Fork us on github.com/your-org/hermes-fullstack