# june5079/yurascanner architecture

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

- Interactive diagram: https://gitdiagram.com/june5079/yurascanner
- Repository: https://github.com/june5079/yurascanner

## Overview

##### Project type and purpose
- YuraScanner is a CLI-driven, Node.js-based, task-driven web application scanner.
- It orchestrates a headless browser, sensors/actuators, and LLM bridges to (a) extract clickable elements, (b) generate and execute tasks via an LLM, and (c) invoke the Black-Widow XSS engine for vulnerability checks.

##### File structure
Top-level directories:
- src/black-widow-scripts – integration of the XSS payload engine
- src/bridge – LLMBridge and vision bridge to talk to GPT-style APIs
- src/common-utils – login, page wrapper, and general helpers
- src/debug – screenshot, evaluation, and statistics modules
- src/modules – attack, form, main control, tasks generation
- src/prompt-templates – prebuilt LLM prompts for each phase
- src/sensors-actuators – page abstraction (Sensors), action mapping, and execution (Actuators)
Config:
- src/config.js, .env for OpenAI API key
Entry point: src/main.js
CLI metadata: package.json

##### Additional README insights
- Three main phases: Task Extraction → Task Execution → Vulnerability Scanning
- Sensors translate live DOM into abstract strings; Bridge queries LLM; Actuators replay actions in the browser.
- Black-Widow library is used to inject XSS payloads into forms gathered during crawling.
- Debug modules hook into each step to log, screenshot, and evaluate.

a. Frontend CLI layer
- User CLI (yurascanner CLI)
- main.js + common-utils (login, config loader)
b. Crawler Core
- Sensors (page → abstract rep)
- ActionsMapping (ID ↔ DOM element store)
- LLMBridge (gpt API calls via OpenAI SDK)
- Actuators (abstract actions → Puppeteer/Playwright calls)
- PromptTemplates (inject into Bridge)
c. Task Manager
- tasks-module (autotask vs. manual file)
- main-module (loops over tasks)
d. Vulnerability Scanner
- attack-module invoking black-widow-scripts (addeventlistener_wrapper, xss_xhr, md5, lib.js)
- form-module (collect and normalize forms)
e. Debug & Logging
- screenshot-module, evaluation-module, statistics-module
f. External Services
- OpenAI API (GPT-3.5/GPT-4 or custom endpoint)
g. Data Stores / I/O
- input/*.txt (task files)
- figures/ (static assets)
- generated screenshots
- logs / output streams

##### Relationships and interactions
- CLI → main-module: parse args → load config
- main-module → tasks-module: generate or read tasks
- For each task:
- Sensors crawl page → abstract representation
- Abstract + current task + history → Bridge → LLM API
- Bridge response → Actuators → browser interaction
- During interactions, form-module records forms
- After task execution: attack-module runs Black-Widow XSS engine on recorded forms
- Debug modules subscribe to events at each step for screenshots, metrics, and logs

##### Architectural patterns & design principles
- Modular layers (CLI, Controller, Sensors/Actuators, Attack)
- Adapter/Bridge pattern for pluggable LLM APIs
- Separation of concerns: prompt templates are decoupled from core logic
- Plugin-like integration of Black-Widow scripts for vulnerability injection

##### What to emphasize
- Clear separation between the two “brains” of the tool: the LLM Bridge and the Attack Engine
- How Sensors and Actuators form a feedback loop mediated by the LLM
- Pluggability: swapping GPT endpoints or adding new vulnerability scripts
- Data persistence points (task files, action mapping, screenshots)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI & Configuration Layer
    subgraph "CLI & Configuration"
        CLI["yurascanner CLI"]:::core
        Main["main.js"]:::core
        Config["config.js & .env"]:::util
        CommonLogin["login-module.js"]:::util
        CommonWrapper["page-wrapper.js"]:::util
        CommonUtil["util.js"]:::util
    end

    %% Crawler Core & Task Manager Layer
    subgraph "Crawler Core & Task Manager"
        subgraph "Sensors & Actuators"
            Sensors["Sensors (sensors.js)"]:::core
            ActionsMap["Actions Mapping (actions-mapping.js)"]:::core
            Actuators["Actuators (actuators.js)"]:::core
        end
        subgraph "Bridges"
            LLMBridge["LLM Bridge (llm-bridge.js)"]:::core
            VisionBridge["Vision Bridge (gpt-vision-bridge.js)"]:::core
        end
        subgraph "Prompt Templates"
            BasePT["base-template.js"]:::util
            MainPT["main-template.js"]:::util
            TasksPT["tasks-template.js"]:::util
            FormPT["form-template.js"]:::util
        end
        subgraph "Task Manager"
            Tasks["Tasks Module (tasks-module.js)"]:::core
            MainModule["Main Module (main-module.js)"]:::core
        end
    end

    %% Vulnerability Scanner & Debug Layer
    subgraph "Vulnerability Scanner & Debug"
        subgraph "Vulnerability Scanner"
            Attack["Attack Module (attack-module.js)"]:::attack
            FormModule["Form Module (form-module.js)"]:::attack
            subgraph "Black-Widow Scripts"
                BW1["addeventlistener_wrapper.js"]:::attack
                BW2["xss_xhr.js"]:::attack
                BW3["md5.js"]:::attack
                BW4["lib.js"]:::attack
            end
        end
        subgraph "Debug & Logging"
            Screenshot["screenshot-module.js"]:::util
            Evaluation["evaluation-module.js"]:::util
            Statistics["statistics-module.js"]:::util
        end
    end

    %% External Services & Data Stores
    OpenAI["OpenAI API"]:::external
    subgraph "Data Stores / I/O"
        TaskFiles["input/*.txt"]:::datastore
        StaticAssets["figures/"]:::datastore
        Screenshots["generated screenshots"]:::datastore
        Logs["logs / output streams"]:::datastore
    end

    %% Connections: CLI & Config
    CLI --> Main
    Main --> Config
    Main --> CommonLogin
    Main --> CommonWrapper
    Main --> CommonUtil

    %% Main control to Task Manager
    Main --> MainModule
    MainModule --> Tasks

    %% Task Manager to Crawler Core
    MainModule --> Sensors
    Tasks --> Sensors

    %% Sensors to ActionsMapping to Bridge
    Sensors --> ActionsMap
    ActionsMap --> LLMBridge

    %% Prompt templates influence Bridge
    BasePT --> LLMBridge
    MainPT --> LLMBridge
    TasksPT --> LLMBridge
    FormPT --> LLMBridge

    %% Bridge interactions
    LLMBridge --> Actuators
    VisionBridge --> LLMBridge
    Actuators --> Sensors

    %% After tasks: Form collection and Attack
    Actuators --> FormModule
    FormModule --> Attack
    Attack --> BW1
    Attack --> BW2
    Attack --> BW3
    Attack --> BW4

    %% Debug subscribers
    Sensors --> Screenshot
    LLMBridge --> Evaluation
    Attack --> Statistics

    %% External service calls
    LLMBridge -->|API calls| OpenAI

    %% Data persistence
    Tasks --> TaskFiles
    Screenshot --> Screenshots
    Logs --> Statistics

    %% Click events
    click Main "https://github.com/june5079/yurascanner/blob/main/src/main.js"
    click Config "https://github.com/june5079/yurascanner/blob/main/src/config.js"
    click CommonLogin "https://github.com/june5079/yurascanner/blob/main/src/common-utils/login-module.js"
    click CommonWrapper "https://github.com/june5079/yurascanner/blob/main/src/common-utils/page-wrapper.js"
    click CommonUtil "https://github.com/june5079/yurascanner/blob/main/src/common-utils/util.js"
    click Sensors "https://github.com/june5079/yurascanner/blob/main/src/sensors-actuators/sensors.js"
    click ActionsMap "https://github.com/june5079/yurascanner/blob/main/src/sensors-actuators/actions-mapping.js"
    click Actuators "https://github.com/june5079/yurascanner/blob/main/src/sensors-actuators/actuators.js"
    click LLMBridge "https://github.com/june5079/yurascanner/blob/main/src/bridge/llm-bridge.js"
    click VisionBridge "https://github.com/june5079/yurascanner/blob/main/src/bridge/gpt-vision-bridge.js"
    click BasePT "https://github.com/june5079/yurascanner/blob/main/src/prompt-templates/base-template.js"
    click MainPT "https://github.com/june5079/yurascanner/blob/main/src/prompt-templates/main-template.js"
    click TasksPT "https://github.com/june5079/yurascanner/blob/main/src/prompt-templates/tasks-template.js"
    click FormPT "https://github.com/june5079/yurascanner/blob/main/src/prompt-templates/form-template.js"
    click Tasks "https://github.com/june5079/yurascanner/blob/main/src/modules/tasks-module.js"
    click MainModule "https://github.com/june5079/yurascanner/blob/main/src/modules/main-module.js"
    click Attack "https://github.com/june5079/yurascanner/blob/main/src/modules/attack-module.js"
    click FormModule "https://github.com/june5079/yurascanner/blob/main/src/modules/form-module.js"
    click BW1 "https://github.com/june5079/yurascanner/blob/main/src/black-widow-scripts/addeventlistener_wrapper.js"
    click BW2 "https://github.com/june5079/yurascanner/blob/main/src/black-widow-scripts/xss_xhr.js"
    click BW3 "https://github.com/june5079/yurascanner/blob/main/src/black-widow-scripts/md5.js"
    click BW4 "https://github.com/june5079/yurascanner/blob/main/src/black-widow-scripts/lib.js"
    click Screenshot "https://github.com/june5079/yurascanner/blob/main/src/debug/screenshot-module.js"
    click Evaluation "https://github.com/june5079/yurascanner/blob/main/src/debug/evaluation-module.js"
    click Statistics "https://github.com/june5079/yurascanner/blob/main/src/debug/statistics-module.js"
    click TaskFiles "https://github.com/june5079/yurascanner/blob/main/input/default-tasks.txt"
    click StaticAssets "https://github.com/june5079/yurascanner/tree/main/figures/"
    click Logs "https://github.com/june5079/yurascanner/tree/main/logs/"

    %% Styles
    classDef core fill:#e6ffe6,stroke:#1f7700,color:#003300
    classDef util fill:#ffffe6,stroke:#777700,color:#777700
    classDef external fill:#e6f2ff,stroke:#0066cc,color:#003366
    classDef attack fill:#ffe6e6,stroke:#cc0000,color:#660000
    classDef datastore fill:#fff0e6,stroke:#cc6600,color:#663300
```
