# towss-sec/oceanwind-fingerprint-alarm architecture

> Architecture diagram of the GitHub repository towss-sec/oceanwind-fingerprint-alarm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/towss-sec/oceanwind-fingerprint-alarm
- Repository: https://github.com/towss-sec/oceanwind-fingerprint-alarm

## Overview

OceanWind observes browser fingerprinting attempts through a local mitmproxy addon, reports them to a Flask backend, and presents per-site scores and detection logs in a browser dashboard. The backend attributes iframe detections to the top-level site, stores alerts in memory, and delegates scoring to computation.py. The README documents the detection and dashboard workflow; source excerpts show the API and process wiring. Dashboard HTML and CSS are included as served assets, but their contents were not sampled.

Main entry points: [`server.py`](https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/server.py) (Flask API), [`WebUI/dashboard.js`](https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/WebUI/dashboard.js) (Dashboard logic), [`proxy.py`](https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/proxy.py) (API hooks), [`start.py`](https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/start.py) (Process launcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_observe["Traffic observation"]
  node_detector["Detector addon<br/>[proxy.py]"]
  node_injected["API hooks<br/>[proxy.py]"]
end

subgraph group_backend["Detection backend"]
  node_flask["Flask API<br/>[server.py]"]
  node_alert_state[("Alert state<br/>[server.py]")]
  node_scoring["Danger scoring<br/>[computation.py]"]
end

subgraph group_dashboard["Live dashboard"]
  node_dashboard_page["Dashboard page<br/>[dashboard.html]"]
  node_dashboard_logic["Dashboard logic<br/>[dashboard.js]"]
  node_dashboard_style["Dashboard styling<br/>[dashboard.css]"]
end

subgraph group_runtime["Runtime launch"]
  node_launcher["Process launcher<br/>[start.py]"]
end

node_browser(("User browser"))
node_mitmproxy["mitmproxy"]

node_browser -->|"proxies traffic"| node_mitmproxy
node_mitmproxy -->|"loads addon"| node_detector
node_detector -->|"injects script"| node_injected
node_injected -->|"reports visits"| node_flask
node_injected -->|"reports detections"| node_flask
node_flask -->|"records alerts"| node_alert_state
node_flask -->|"computes score"| node_scoring
node_flask -->|"serves page"| node_dashboard_page
node_flask -->|"serves script"| node_dashboard_logic
node_flask -->|"serves stylesheet"| node_dashboard_style
node_browser -->|"opens dashboard"| node_dashboard_page
node_dashboard_logic -->|"polls alerts"| node_flask
node_dashboard_logic -->|"fetches score"| node_flask
node_dashboard_logic -->|"requests background"| node_flask
node_dashboard_logic -->|"deletes alert"| node_flask
node_launcher -->|"starts backend"| node_flask
node_launcher -->|"starts proxy"| node_mitmproxy

click node_detector "https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/proxy.py"
click node_injected "https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/proxy.py"
click node_flask "https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/server.py"
click node_alert_state "https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/server.py"
click node_scoring "https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/computation.py"
click node_dashboard_page "https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/WebUI/dashboard.html"
click node_dashboard_logic "https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/WebUI/dashboard.js"
click node_dashboard_style "https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/WebUI/dashboard.css"
click node_launcher "https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/start.py"

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_detector,node_injected,node_browser toneBlue
class node_flask,node_alert_state,node_scoring toneAmber
class node_dashboard_page,node_dashboard_logic,node_dashboard_style toneMint
class node_launcher toneRose
class node_mitmproxy toneIndigo
```

## Components

### Traffic observation

- [Detector addon](https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/proxy.py): `proxy.py`
- [API hooks](https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/proxy.py): `proxy.py`

### Detection backend

- [Flask API](https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/server.py): `server.py`
- [Alert state](https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/server.py): `server.py`
- [Danger scoring](https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/computation.py): `computation.py`

### Live dashboard

- [Dashboard page](https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/WebUI/dashboard.html): `WebUI/dashboard.html`
- [Dashboard logic](https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/WebUI/dashboard.js): `WebUI/dashboard.js`
- [Dashboard styling](https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/WebUI/dashboard.css): `WebUI/dashboard.css`

### Runtime launch

- [Process launcher](https://github.com/towss-sec/oceanwind-fingerprint-alarm/blob/master/start.py): `start.py`

### Other components

- **User browser**
- **mitmproxy**

## Connections

- User browser → mitmproxy: proxies traffic (evidence: `README.md`)
- mitmproxy → Detector addon: loads addon
- Detector addon → API hooks: injects script (evidence: `proxy.py`)
- API hooks → Flask API: reports visits (evidence: `proxy.py`)
- API hooks → Flask API: reports detections (evidence: `proxy.py`)
- Flask API → Alert state: records alerts (evidence: `server.py`)
- Flask API → Danger scoring: computes score (evidence: `server.py`)
- Flask API → Dashboard page: serves page (evidence: `server.py`)
- Flask API → Dashboard logic: serves script (evidence: `server.py`)
- Flask API → Dashboard styling: serves stylesheet (evidence: `server.py`)
- User browser → Dashboard page: opens dashboard (evidence: `README.md`)
- Dashboard logic → Flask API: polls alerts (evidence: `WebUI/dashboard.js`)
- Dashboard logic → Flask API: fetches score (evidence: `WebUI/dashboard.js`)
- Dashboard logic → Flask API: requests background (evidence: `WebUI/dashboard.js`)
- Dashboard logic → Flask API: deletes alert (evidence: `WebUI/dashboard.js`)
- Process launcher → Flask API: starts backend (evidence: `start.py`)
- Process launcher → mitmproxy: starts proxy (evidence: `start.py`)
