# un4mezz/xss_server architecture

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

- Interactive diagram: https://gitdiagram.com/un4mezz/xss_server
- Repository: https://github.com/un4mezz/xss_server

## Overview

##### Project Type and Purpose
- This is an educational, monolithic Python web application demonstrating a Stored Cross-Site Scripting (XSS) vulnerability, paired with a simple “attacker” server that collects stolen cookies.

##### File Structure Analysis
- Top-level files:
- server.py – the vulnerable victim web application
- attacker_server.py – the malicious server that logs stolen cookies
- requirements.txt – Python dependencies
- README.md – setup and usage instructions
- Directories:
- templates/ – Jinja-style HTML pages (login, register, profile)
- static/ – CSS for styling
- No external database: user data and stolen credentials are persisted in CSV files (in-memory or file writes).

##### README Insights
- Two servers run concurrently: the victim at port 80 (default) and the attacker at port 9000.
- Workflow:
a. User registers and logs in on the victim server.
b. Attacker injects a `<script>` payload into another user’s profile comments.
c. When the victim views the comment, their browser executes the script and issues an HTTP request to the attacker server, sending `document.cookie`.
d. Attacker server saves stolen cookies (and any credentials) to `stolen_credential.csv`.

##### Main Components
a. Client Browser
- Actions: Registration, Login, Posting comments, Viewing profiles
b. Vulnerable Web Application (server.py)
- Sub-components:
- HTTP Request Router (handles /register, /login, /profile)
- Template Renderer (serves templates/*.html unescaped in comments)
- Static File Server (serves static/styles.css)
- In-Memory User Store or CSV Logger (stores user credentials in .csv or runtime memory)
c. Attacker Server (attacker_server.py)
- Endpoint `/steal` on port 9000
- CSV Logger writing to `stolen_credential.csv`
d. Data Storage
- CSV files: user credentials (optional), stolen credentials

##### Architectural Patterns and Technologies
- Monolithic Python HTTP server (likely Flask or BaseHTTPServer)
- MVC-like separation:
- Controllers: server.py route handlers
- Views: HTML templates
- Model: simple CSV or in-memory data structures
- No complex microservices—two separate single-purpose services (victim + attacker)

##### Capturing Essential Architectural Elements
- Do not over-fragment: keep the victim application as a single monolith but annotate its key sub-components.
- Attacker server as a separate service to show the malicious endpoint.
- Where and how the XSS payload crosses trust boundaries (user → victim → attacker).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Browser
    Browser["Client Browser"]:::browser

    %% Victim Application Subgraph
    subgraph "Victim Web Application"
        Router["HTTP Request Router (/register, /login, /profile)"]:::victim
        Templates["Template Renderer (templates/*.html)"]:::victim
        Static["Static File Server (serves CSS)"]:::victim
        UserStore[(User Credentials CSV Store)]:::data
    end

    %% Attacker Server Subgraph
    subgraph "Attacker Server (port 9000)"
        Attacker["Attacker Endpoint /steal"]:::attacker
        StealLog[(Stolen Credential CSV Store)]:::data
    end

    %% Data Flows
    Browser -->|"HTTP POST /register,/login"| Router
    Router -->|"renders with comments unescaped"| Templates
    Templates -->|"serves HTML pages"| Browser
    Browser -->|"HTTP GET /static/styles.css"| Static
    Router -->|"reads/writes users"| UserStore

    Browser -->|"executes injected <script>"| Attacker
    Attacker -->|"logs cookie"| StealLog

    %% Click Events
    click Router "https://github.com/un4mezz/xss_server/blob/main/server.py"
    click Templates "https://github.com/un4mezz/xss_server/tree/main/templates/"
    click Static "https://github.com/un4mezz/xss_server/blob/main/static/styles.css"
    click Attacker "https://github.com/un4mezz/xss_server/blob/main/attacker_server.py"
    click StealLog "https://github.com/un4mezz/xss_server/blob/main/attacker_server.py"

    %% Styles
    classDef browser fill:#ccffcc,stroke:#339933,stroke-width:2px;
    classDef victim fill:#cce5ff,stroke:#3366cc,stroke-width:2px;
    classDef attacker fill:#ffcccc,stroke:#cc3333,stroke-width:2px;
    classDef data fill:#ffffcc,stroke:#cccc33,stroke-width:2px;
```
