# informaticaeloy/noctua architecture

> Architecture diagram of the GitHub repository informaticaeloy/noctua, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/informaticaeloy/noctua
- Repository: https://github.com/informaticaeloy/noctua

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "User Browser" 
        direction TB
        UI["Web UI<br/><i>HTML/CSS/JS</i>"]:::client
    end

    %% Web Server Layer
    subgraph "Web Server (Flask)" 
        direction TB
        ENV[".env"]:::config
        DEP_CFG["config/dependencies.json"]:::config

        ENTRY_APP["app.py"]:::server
        ENTRY_WSGI["wsgi.py"]:::server

        subgraph "Controllers (routes)" 
            direction TB
            R_SCAN_WEB["scan_web.py"]:::server
            R_SCAN_API["scan_api.py"]:::server
            R_MODULES["modules.py"]:::server
            R_REPORTS["reports.py"]:::server
            R_STATUS["status.py"]:::server
            R_VPN["vpn_profiles.py"]:::server
            R_SCRIPTS["scripts.py"]:::server
            R_SCANNER["scanner.py"]:::server
        end

        subgraph "Services" 
            direction TB
            MOD_LOADER["base_module.py"]:::service
            REP_GEN["report_generator.py"]:::service

            subgraph "Utilities"
                direction TB
                U_FILE["file_ops.py"]:::service
                U_UTILS["utils.py"]:::service
                U_DEPS["dependencies.py"]:::service
            end
        end
    end

    %% Scan Engine Layer
    subgraph "Scan Engine (Plugin Model)" 
        direction TB
        MDL_JSON["modules/*.json"]:::external
        SCR_PY["scripts/code/*.py"]:::external
        SCR_JSON["scripts/*.json"]:::external
        CLI["External Tools<br/>(nmap, nikto, whatweb, etc.)"]:::external
    end

    %% Data Storage Layer
    subgraph "Data & Logs" 
        direction TB
        DATA_META["data/*/info.json"]:::storage
        SCAN_RESULTS["scans/*"]:::storage
        VPN_PROFILES["vpn_profiles/*.ovpn"]:::storage
        LOGS["logs/webscanner.log"]:::storage
    end

    %% Configuration & Requirements
    REQ["requirements.txt"]:::config

    %% Relationships
    UI -->|"HTTP Request"| ENTRY_APP
    ENTRY_APP --> ENTRY_WSGI
    ENTRY_WSGI --> R_SCAN_WEB
    ENTRY_WSGI --> R_SCAN_API
    ENTRY_WSGI --> R_MODULES
    ENTRY_WSGI --> R_REPORTS
    ENTRY_WSGI --> R_STATUS
    ENTRY_WSGI --> R_VPN
    ENTRY_WSGI --> R_SCRIPTS
    ENTRY_WSGI --> R_SCANNER

    R_SCAN_WEB --> MOD_LOADER
    R_SCAN_API --> MOD_LOADER
    R_MODULES --> MOD_LOADER
    R_SCRIPTS --> MOD_LOADER

    MOD_LOADER --> MDL_JSON
    MOD_LOADER --> SCR_PY
    SCR_PY --> CLI
    CLI --> SCAN_RESULTS
    CLI --> DATA_META

    REP_GEN --> DATA_META
    REP_GEN --> SCAN_RESULTS
    R_REPORTS --> REP_GEN
    R_REPORTS --> UI

    R_STATUS --> SCAN_RESULTS
    R_VPN --> VPN_PROFILES

    ENTRY_APP --> ENV
    ENTRY_APP --> DEP_CFG
    U_DEPS --> DEP_CFG

    ENTRY_APP --> U_FILE
    ENTRY_APP --> U_UTILS

    ENTRY_APP --> REQ

    %% Click Events
    click ENTRY_APP "https://github.com/informaticaeloy/noctua/blob/main/app.py"
    click ENTRY_WSGI "https://github.com/informaticaeloy/noctua/blob/main/wsgi.py"
    click ENV "https://github.com/informaticaeloy/noctua/blob/main/.env"
    click DEP_CFG "https://github.com/informaticaeloy/noctua/blob/main/config/dependencies.json"
    click R_SCAN_WEB "https://github.com/informaticaeloy/noctua/blob/main/routes/scan_web.py"
    click R_SCAN_API "https://github.com/informaticaeloy/noctua/blob/main/routes/scan_api.py"
    click R_MODULES "https://github.com/informaticaeloy/noctua/blob/main/routes/modules.py"
    click R_REPORTS "https://github.com/informaticaeloy/noctua/blob/main/routes/reports.py"
    click R_STATUS "https://github.com/informaticaeloy/noctua/blob/main/routes/status.py"
    click R_VPN "https://github.com/informaticaeloy/noctua/blob/main/routes/vpn_profiles.py"
    click R_SCRIPTS "https://github.com/informaticaeloy/noctua/blob/main/routes/scripts.py"
    click R_SCANNER "https://github.com/informaticaeloy/noctua/blob/main/routes/scanner.py"
    click MOD_LOADER "https://github.com/informaticaeloy/noctua/blob/main/modules_utils/base_module.py"
    click REP_GEN "https://github.com/informaticaeloy/noctua/blob/main/modules_utils/report_generator.py"
    click U_FILE "https://github.com/informaticaeloy/noctua/blob/main/utils/file_ops.py"
    click U_UTILS "https://github.com/informaticaeloy/noctua/blob/main/utils/utils.py"
    click U_DEPS "https://github.com/informaticaeloy/noctua/blob/main/utils/dependencies.py"
    click MDL_JSON "https://github.com/informaticaeloy/noctua/tree/main/modules"
    click SCR_PY "https://github.com/informaticaeloy/noctua/tree/main/scripts/code"
    click SCR_JSON "https://github.com/informaticaeloy/noctua/tree/main/scripts"
    click DATA_META "https://github.com/informaticaeloy/noctua/tree/main/data"
    click SCAN_RESULTS "https://github.com/informaticaeloy/noctua/tree/main/scans"
    click VPN_PROFILES "https://github.com/informaticaeloy/noctua/tree/main/vpn_profiles"
    click LOGS "https://github.com/informaticaeloy/noctua/blob/main/logs/webscanner.log"
    click REQ "https://github.com/informaticaeloy/noctua/blob/main/requirements.txt"

    %% Styles
    classDef client fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1
    classDef server fill:#E8EAF6,stroke:#3F51B5,color:#1A237E
    classDef service fill:#F1F8E9,stroke:#8BC34A,color:#33691E
    classDef external fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef storage fill:#EFEBE9,stroke:#6D4C41,color:#3E2723
    classDef config fill:#FCE4EC,stroke:#D81B60,color:#880E4F
```
