# bugatsec/blind-xsstrace architecture

> Architecture diagram of the GitHub repository bugatsec/blind-xsstrace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bugatsec/blind-xsstrace
- Repository: https://github.com/bugatsec/blind-xsstrace

## Overview

XSSTrace is a self-hosted Blind XSS callback server and hit dashboard. Testers place marker-specific payloads in injection points; when a payload fires, the server records callback details, groups and displays hits for an authenticated user, and can notify Discord. The README documents import/export, filters, page actions, and persistent storage. The source excerpt is partial, so uncertain API-to-storage wiring is omitted; the dashboard and server are monolithic files.

Main entry points: [`index.html`](https://github.com/bugatsec/blind-xsstrace/blob/main/index.html) (Dashboard Client), [`server.js`](https://github.com/bugatsec/blind-xsstrace/blob/main/server.js) (Callback Capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Payload Capture"]
  node_server["Express Server<br/>[server.js]"]
  node_marker["Marker Payload Route<br/>[server.js]"]
  node_capture_hit["Callback Capture<br/>[server.js]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_auth["Dashboard Login<br/>[server.js]"]
  node_dashboard_ui["Dashboard UI<br/>[server.js]"]
  node_dashboard_client["Dashboard Client<br/>[index.html]"]
  node_hit_views["Hit Views and Filters<br/>[server.js]"]
  node_page_actions["Page Group Actions<br/>[server.js]"]
  node_import_export["Import and Export<br/>[server.js]"]
  node_health["Health Check<br/>[server.js]"]
end

subgraph group_state["Hit State and Alerts"]
  node_hit_store[("Callback Log<br/>[server.js]")]
end

node_tester(("Security Tester"))
node_browser(("Affected Browser"))
node_discord(("Discord Webhook"))
node_persistent_disk[("Persistent Disk")]

node_tester -->|"embeds payload"| node_browser
node_browser -->|"requests marker"| node_marker
node_marker -->|"captures hit"| node_capture_hit
node_capture_hit -->|"records hit"| node_hit_store
node_capture_hit -.->|"sends alert"| node_discord
node_tester -->|"opens dashboard"| node_dashboard_auth
node_dashboard_auth -->|"serves page"| node_dashboard_ui
node_dashboard_ui -->|"loads client"| node_dashboard_client
node_dashboard_client -->|"requests and filters"| node_hit_views
node_hit_views -->|"reads hits"| node_hit_store
node_dashboard_client -->|"requests actions"| node_page_actions
node_dashboard_client -->|"imports or exports"| node_import_export
node_dashboard_client -->|"checks status"| node_health
node_hit_store -.->|"persists log"| node_persistent_disk

click node_server "https://github.com/bugatsec/blind-xsstrace/blob/main/server.js"
click node_marker "https://github.com/bugatsec/blind-xsstrace/blob/main/server.js"
click node_capture_hit "https://github.com/bugatsec/blind-xsstrace/blob/main/server.js"
click node_dashboard_auth "https://github.com/bugatsec/blind-xsstrace/blob/main/server.js"
click node_dashboard_ui "https://github.com/bugatsec/blind-xsstrace/blob/main/server.js"
click node_dashboard_client "https://github.com/bugatsec/blind-xsstrace/blob/main/index.html"
click node_hit_views "https://github.com/bugatsec/blind-xsstrace/blob/main/server.js"
click node_page_actions "https://github.com/bugatsec/blind-xsstrace/blob/main/server.js"
click node_import_export "https://github.com/bugatsec/blind-xsstrace/blob/main/server.js"
click node_health "https://github.com/bugatsec/blind-xsstrace/blob/main/server.js"
click node_hit_store "https://github.com/bugatsec/blind-xsstrace/blob/main/server.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_marker,node_capture_hit,node_browser toneBlue
class node_dashboard_auth,node_dashboard_ui,node_dashboard_client,node_hit_views,node_page_actions,node_import_export,node_health,node_persistent_disk toneAmber
class node_hit_store,node_discord toneMint
class node_tester toneIndigo
```

## Components

### Payload Capture

- [Express Server](https://github.com/bugatsec/blind-xsstrace/blob/main/server.js): `server.js`
- [Marker Payload Route](https://github.com/bugatsec/blind-xsstrace/blob/main/server.js): `server.js`
- [Callback Capture](https://github.com/bugatsec/blind-xsstrace/blob/main/server.js): `server.js`

### Dashboard

- [Dashboard Login](https://github.com/bugatsec/blind-xsstrace/blob/main/server.js): `server.js`
- [Dashboard UI](https://github.com/bugatsec/blind-xsstrace/blob/main/server.js): `server.js`
- [Dashboard Client](https://github.com/bugatsec/blind-xsstrace/blob/main/index.html): `index.html`
- [Hit Views and Filters](https://github.com/bugatsec/blind-xsstrace/blob/main/server.js): `server.js`
- [Page Group Actions](https://github.com/bugatsec/blind-xsstrace/blob/main/server.js): `server.js`
- [Import and Export](https://github.com/bugatsec/blind-xsstrace/blob/main/server.js): `server.js`
- [Health Check](https://github.com/bugatsec/blind-xsstrace/blob/main/server.js): `server.js`

### Hit State and Alerts

- [Callback Log](https://github.com/bugatsec/blind-xsstrace/blob/main/server.js): `server.js`

### Other components

- **Security Tester**
- **Affected Browser**
- **Discord Webhook**
- **Persistent Disk**

## Connections

- Security Tester → Affected Browser: embeds payload
- Affected Browser → Marker Payload Route: requests marker
- Marker Payload Route → Callback Capture: captures hit
- Callback Capture → Callback Log: records hit
- Callback Capture → Discord Webhook: sends alert
- Security Tester → Dashboard Login: opens dashboard
- Dashboard Login → Dashboard UI: serves page
- Dashboard UI → Dashboard Client: loads client
- Dashboard Client → Hit Views and Filters: requests and filters
- Hit Views and Filters → Callback Log: reads hits
- Dashboard Client → Page Group Actions: requests actions
- Dashboard Client → Import and Export: imports or exports
- Dashboard Client → Health Check: checks status
- Callback Log → Persistent Disk: persists log