# adperem/loxs architecture

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

- Interactive diagram: https://gitdiagram.com/adperem/loxs
- Repository: https://github.com/adperem/loxs

## Overview

##### Project type and purpose
- This is a standalone Python-based CLI tool called “Loxs” that scans web applications for common vulnerabilities (LFI, OR, SQLi, XSS, CRLF).
- It is not a full-stack web app, but a command-line scanner that can optionally drive Selenium/ChromeDriver or direct HTTP clients (aiohttp/requests), parse responses (BeautifulSoup), match success patterns, aggregate results, and generate an HTML report.

##### File structure
- Top level:
- loxs.py – main entrypoint/CLI driver
- filter.sh – auxiliary shell script for post-processing/ filtering output
- payloads/ – directory containing text files of payloads by vulnerability type
- requirements.txt – lists Python dependencies (aiohttp, selenium, flask, rich, etc.)
- No separate frontend/backend directories; this is a modular CLI engine with pluggable HTTP/Selenium backends and payload store.

##### Key insights from README
- Multi-threaded scanning orchestrated via aiohttp or concurrent requests
- Customizable payloads and success‐pattern matching
- Optional Tor proxy integration
- HTML report generation

##### Main components
a. **CLI Interface** (loxs.py)
b. **Configuration Loader** (command-line args + optional YAML)
c. **Payload Manager** (reads payloads/*.txt)
d. **Concurrency Manager** (thread pool or async event loop)
e. **Scanner Engine**
- **HTTP Client Module** (aiohttp/requests)
- **Browser Automation Module** (Selenium + ChromeDriver)
- **Tor Proxy Adapter** (optional SOCKS5 client)
f. **Response Parser** (BeautifulSoup + regex matching)
g. **Result Aggregator** (in-memory data structures + optional file writer)
h. **Report Generator** (HTML template + file output)
i. **Filter Script** (filter.sh) – post-processing
j. **External Targets** (Web Application under test)
k. **External Services** (Tor Network, ChromeDriver)

##### Relationships and data flows
- Configuration Loader → Payload Manager & Concurrency Manager
- Concurrency Manager dispatches tasks to Scanner Engine
- Scanner Engine (choice of HTTP Client or Browser Automation) → External Target via network (optionally through Tor Proxy)
- Response flows back → Response Parser → Result Aggregator
- After scanning completes, Result Aggregator → Report Generator → HTML report file
- Optionally, Filter Script consumes Report or raw output for further filtering

##### Architectural patterns and design principles
- **Modular pipeline**: clear separation of concerns (input, scanning, parsing, reporting)
- **Pluggable backends**: HTTP vs. Selenium vs. Tor adapter
- **Concurrency/async**: high-throughput scanning
- **Configuration over code**: payloads and success patterns loaded at runtime

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Loxs CLI Scanner"
        CLI["CLI Interface"]:::core
        Config["Configuration Loader"]:::core
        PayloadMgr["Payload Manager"]:::core
        Concurrency["Concurrency Manager"]:::core
        Engine["Scanner Engine"]:::core
        HTTP["HTTP Client Module"]:::core
        Browser["Browser Automation Module"]:::core
        Tor["Tor Proxy Adapter"]:::core
        Parser["Response Parser"]:::core
        Aggregator["Result Aggregator"]:::core
        Reporter["Report Generator"]:::core
    end

    PayloadStore["Payload Repository"]:::datastore
    ReportFile["HTML Report File"]:::datastore
    Requirements["Dependency Manifest"]:::datastore

    Target["Web Application Target"]:::external
    TorNetwork["Tor Network"]:::external
    ChromeDriver["ChromeDriver"]:::external

    FilterScript["Filter Script"]:::core

    CLI -->|"start scan"| Config
    Config -->|"load payloads"| PayloadMgr
    Config -->|"init concurrency"| Concurrency
    PayloadMgr -->|"payload list"| PayloadStore
    PayloadStore --> PayloadMgr
    PayloadMgr --> Concurrency
    Concurrency -->|"dispatch tasks"| Engine
    Engine --> HTTP
    Engine --> Browser
    Engine --> Tor
    HTTP -->|"HTTP request"| TorNetwork
    Browser -->|"Browser request"| TorNetwork
    TorNetwork -->|"via Tor proxy"| Target
    HTTP -->|"direct HTTP request"| Target
    Browser -->|"direct browser request"| Target
    Target -->|"HTTP/S response"| Parser
    Parser -->|"parsed response"| Aggregator
    Aggregator -->|"aggregated results"| Reporter
    Reporter -->|"write report"| ReportFile
    FilterScript -->|"post-process"| ReportFile
    Requirements --- CLI

    click CLI "https://github.com/adperem/loxs/blob/main/loxs.py"
    click Config "https://github.com/adperem/loxs/blob/main/loxs.py"
    click PayloadMgr "https://github.com/adperem/loxs/tree/main/payloads/"
    click PayloadStore "https://github.com/adperem/loxs/tree/main/payloads/"
    click Concurrency "https://github.com/adperem/loxs/blob/main/loxs.py"
    click Engine "https://github.com/adperem/loxs/blob/main/loxs.py"
    click HTTP "https://github.com/adperem/loxs/blob/main/loxs.py"
    click Browser "https://github.com/adperem/loxs/blob/main/loxs.py"
    click Tor "https://github.com/adperem/loxs/blob/main/loxs.py"
    click Parser "https://github.com/adperem/loxs/blob/main/loxs.py"
    click Aggregator "https://github.com/adperem/loxs/blob/main/loxs.py"
    click Reporter "https://github.com/adperem/loxs/blob/main/loxs.py"
    click FilterScript "https://github.com/adperem/loxs/blob/main/filter.sh"
    click Requirements "https://github.com/adperem/loxs/blob/main/requirements.txt"

    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef external fill:#ffe5b4,stroke:#cc7a00,color:#cc7a00
    classDef datastore fill:#d4edda,stroke:#155724,color:#155724
```
