How june5079/yurascanner works
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)