How informaticaeloy/noctua works
Project type and purpose
• This is a full-stack web application named “Noctua Scanner” that automates web-based security scans.
• It exposes a browser-based UI (HTML templates, CSS, JS) and a Flask-based backend (app.py, wsgi.py, routes/) to orchestrate scanning modules, manage VPN profiles, and generate reports.
File structure
Top-level components:
• Configuration (.env, config/dependencies.json)
• Application entrypoints (app.py, wsgi.py)
• Routes/controllers (routes/*.py)
• Scanning modules definitions (modules/*.json) and module helpers (modules_utils/)
• Script code wrappers (scripts/code/*.py) and script definitions (scripts/*.json)
• Data and scan result storage (data/, scans/)
• Static assets (static/css, static/js, static/images) and HTML views (templates/)
• Utility libraries (utils/)
• VPN profiles storage (vpn_profiles/)
• Logs (logs/webscanner.log)
• Requirements (requirements.txt)
Key insights from README
• The app “AUTO ALL WEB BASED” suggests orchestration of multiple third-party tools (nmap, nikto, whatweb, etc.)
• No explicit database—scan metadata and results are JSON-based files under data/ and scans/.
Main components
• Web browser (UI): static assets + HTML templates
• Web server (Flask app.py/wsgi.py): HTTP request router invoking routes/*.py
• Controller layer (routes): scan API, UI pages, status, reports, VPN profile management
• Service layer:
– Module loader (modules_utils/base_module.py)
– Report generator (modules_utils/report_generator.py)
– Generic utilities (utils/file_ops.py, utils/utils.py)
• Scanning engine layer:
– JSON-defined modules (modules/*.json)
– Python script wrappers (scripts/code/*.py)
– External tools (nmap, nikto, whatweb, etc.)
• Data storage:
– Scan definitions & metadata (data/…)
– Scan execution results (scans/…)
– VPN profiles (vpn_profiles/*.ovpn)
– Application logs (logs/webscanner.log)
• Configuration (config/dependencies.json, .env)
Relationships and interactions
1. User triggers scan via browser UI → HTTP POST to Flask route (scan_web or scan_api).
2. Controller reads input, selects modules (modules/*.json), spawns corresponding scripts (scripts/code/*.py) via module_utils.
3. Scripts call external CLI tools; results written to scans/ and data/.
4. Report generator collates JSON output into HTML/PDF; served back via routes/reports.
5. User views scan status and final report in browser; optionally toggles VPN profiles loaded from vpn_profiles/.
6. All steps log events to logs/webscanner.log.
Architectural patterns and design principles
• MVC-style separation:
– Views (templates/, static/)
– Controllers (routes/)
– Services (modules_utils/, scripts/)
• Plugin/extension model: new scan modules added just by dropping JSON definitions and code wrappers.
• File-based persistence: lightweight, JSON first, no RDBMS.
• Config-driven dependencies: external tool paths in config/dependencies.json.
Technologies and frameworks
• Python 3 + Flask (app.py, wsgi.py)
• Jinja2 templates for HTML rendering
• JavaScript (static/js/scan_manager.js) and custom CSS
• Command-line tools: nmap, nikto, whatweb, etc.
• VPN via OpenVPN profiles (.ovpn)