# altmas5/claro-wifi-pass-solver architecture

> Architecture diagram of the GitHub repository altmas5/claro-wifi-pass-solver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/altmas5/claro-wifi-pass-solver
- Repository: https://github.com/altmas5/claro-wifi-pass-solver

## Overview

##### Tipo y propósito del proyecto (qué estás diagramando)
Por el README y el árbol de archivos, esto no es una app “cliente/servidor” tradicional: es un **tool/utility de automatización para GNU/Linux** que:

- **Escanea redes Wi‑Fi cercanas** (requiere root) usando `iwlist`.
- **Deriva/“calcula” una passphrase** a partir de datos broadcast de la red (E)SSID y BSSID, asumiendo **configuración default** en routers de Claro.
- Incluye **scripts Perl auxiliares** (`check_owning_req.pl`, `0wn3r.pl`) para acciones post‑acceso al router (p.ej. cambiar el nombre de la red), “bajo tu responsabilidad”.

La arquitectura, entonces, es un **pipeline local**: OS/Linux + herramientas del sistema + scripts (shell/perl) + salida (passwords/acciones).

##### Análisis del file tree (componentes reales a reflejar)
Top-level:
- `solve.sh`: **orquestador** (entrypoint) que ejecuta el flujo principal.
- `check_owning_req.pl`: script Perl de verificación/chequeos (probablemente para validar si “sos dueño” o si procede el cambio; no está descrito, pero el README lo asocia a “una vez autenticado”).
- `0wn3r.pl`: script Perl para acciones sobre el router (renombrar SSID y/o otras).
- `check_owning_req.pl` + `0wn3r.pl` dependen de que ya hayas **ingresado al router** (manual o mediante acceso local a su panel).

Además, hay un **dependency clave externa**:
- `/usr/sbin/iwlist` (wireless-tools) → requiere root/sudo. Esto debe aparecer explícito como dependencia del sistema.

##### Señales del README (interacciones, constraints, entorno)
Aspectos que deben aparecer en el diagrama:
- **Entorno**: GNU/Linux.
- **Privilegios**: necesita root para `iwlist scan`.
- **Inputs**: (E)SSID y BSSID (MAC del AP).
- **Algoritmo**: derivación de passphrase (ejemplo: BSSID `64:68:0C:FB:DA:74` y ESSID `CLARO_FBDA73` → passphrase `680CFBDA73`). El diagrama debería mostrar claramente esa transformación.
- **Outputs**:
- Lista de redes alcanzables + password estimada.
- En fase “post-auth”: cambios en router (p.ej. SSID).

##### El nivel de diagramas (recomendación práctica: 3 vistas)
Para máxima precisión sin “sobrepensar”, dibuja **tres diagramas**, cada uno con un objetivo:

##### Context / System Boundary (C4-L1)
Muestra al usuario, el host Linux y las dependencias externas (router/AP, iwlist).
##### Container / Runtime pipeline (C4-L2 adaptado)
Aunque no hay “contenedores”, úsalo para separar: `solve.sh`, herramientas OS, scripts Perl, router.
##### Sequence / Data-flow (DFD o Sequence)
Paso a paso: scan → parse → compute → print → (optional) login → check_owning_req → 0wn3r.

##### Componentes principales (bloques) que tu diagrama debe incluir
Usa estos bloques (separa todo lo que puedas, porque aquí el valor está en el pipeline):

**Actor / Operador**
- Usuario (root/sudoer)

**Sistema local (GNU/Linux host)**
- `solve.sh` (entrypoint/orchestrator)
- “Parser/Extractor” (puede ser una sub-caja dentro de `solve.sh` si parsea stdout de `iwlist`)
- “Password derivation logic” (otra sub-caja: ESSID/BSSID → pass)
- `check_owning_req.pl` (post-auth check)
- `0wn3r.pl` (post-auth change actions)
- Dependencia OS: `/usr/sbin/iwlist`

**Red / Externo**
- Wi‑Fi Access Point / Router Claro (broadcast ESSID/BSSID)
- (Opcional) “Router Admin Web UI” (si los Perl scripts interactúan con HTTP/requests; si no estás seguro, déjalo como “Router management interface (unknown protocol)”)

**Datos**
- ESSID, BSSID, passphrase derivada
- (Opcional) credenciales/sesión de admin una vez autenticado

##### Relaciones e interacciones (flechas)
Tus flechas deberían ser explícitas y direccionales:

##### Usuario → `solve.sh`
“runs with sudo/root”
##### `solve.sh` → `/usr/sbin/iwlist`
“scan wlan”
##### `/usr/sbin/iwlist` → `solve.sh`
“stdout: detected APs + ESSID/BSSID”
##### `solve.sh` → “Parser/Extractor”
“extract ESSID/BSSID”
##### “Parser/Extractor” → “Password derivation logic”
“normalized inputs”
##### “Password derivation logic” → `solve.sh`
“passphrase candidate”
##### `solve.sh` → Usuario
“prints results”

Post-auth branch:
##### Usuario → Router Admin Interface
“login (manual or separate step)”
##### Usuario → `check_owning_req.pl` → Router
“verify preconditions/ownership requirement”
##### Usuario → `0wn3r.pl` → Router
“change SSID (and/or other settings)”

Si no confirmas protocolo (HTTP/CLI/Telnet), etiqueta flecha como “Mgmt interface (unspecified)”.

##### Patrones/diseño implícitos a resaltar
- **Pipeline/ETL local**: Scan (extract) → parse/normalize (transform) → derive pass (compute) → output.
- **Privileged operation boundary**: `iwlist` exige root: dibuja una línea o “trust boundary” entre “unprivileged” y “privileged”.
- **Optional post-compromise step**: los Perl scripts son un segundo módulo “post‑access”.

##### Guías para este tipo de proyecto (tool de seguridad/red)
Como es un “open-source tool” (script-based), el diagrama debe enfocarse en:

- **Core runtime flow** (qué ejecuta, en qué orden).
- **System dependencies** (`iwlist`, interfaz wireless, permisos).
- **Entradas/salidas** (ESSID/BSSID → pass).
- **Extension points**: “post-auth scripts” como módulos aparte.
- **Riesgos/constraints**: requiere root; dependiente de defaults del ISP; funciona en Linux; entorno geográfico (probado en Nicaragua).

##### Convenciones visuales obligatorias (para que sea claro y “ingenieril”)
- **Etiquetas claras** por caja: nombre del archivo + rol (ej. `solve.sh (orchestrator)`).
- **Flechas con verbos**: “scan”, “parse”, “derive”, “apply config”.
- Rectángulos azules: scripts del repo (`solve.sh`, `*.pl`)
- Rectángulos grises: OS/tools (`iwlist`)
- Nubes o rectángulos punteados: elementos externos (Router/AP)
- Figura de persona: usuario
- **Trust boundary**: una línea alrededor de “Requires root” para el bloque `iwlist`/scan.
- **Notas laterales**: “Assumes default router config” y “Tested on GNU/Linux; Nicaragua”.

##### Plantilla concreta (lo que deberías dibujar)

- “User” → “solve.sh”
- “solve.sh” → “iwlist”
- “iwlist” ↔ “Wi‑Fi AP/Router (broadcast ESSID/BSSID)”
- “iwlist stdout” → “solve.sh parser”
- “parser” → “pass derivation”
- “pass derivation” → “output list”
- Rama opcional: “User” → “Router admin interface” → (`check_owning_req.pl`, `0wn3r.pl`)

Esto captura casi toda la arquitectura real del repo, sin inventar componentes que no existen.

##### Qué NO asumir (para mantener precisión)
- No dibujes base de datos, backend, frontend, colas, etc. (no están en el repo).
- No afirmes que los Perl scripts usan HTTP/cURL a menos que lo confirmes leyendo el código; usa “Mgmt interface (unknown)” si no está claro.
- No afirmes que hay persistencia (archivos de estado) si no la ves.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Context / System Boundary
    %% =========================
    subgraph "Context (C4-L1) — Local GNU/Linux automation tool"
        direction TB

        U["User (root/sudoer)"]:::actor

        subgraph "GNU/Linux Host"
            direction TB
            Tool["Local tool scripts (repo)"]:::group
            OS["System tools & wireless stack"]:::os
        end

        R["Wi‑Fi AP / Router (Claro)\nBroadcasts ESSID + BSSID"]:::external
        M["Router management interface\n(unspecified protocol)"]:::external

        U -->|"runs"| Tool
        OS -->|"scans_nearby_networks"| R
        U -->|"manual_login_or_separate_step"| M
        M ---|"admin_access_on_router"| R
    end

    %% =========================
    %% Container / Runtime Pipeline
    %% =========================
    subgraph "Runtime pipeline (C4-L2 adapted)"
        direction TB

        subgraph "Repo scripts"
            direction TB
            S["solve.sh\n(orchestrator / entrypoint)"]:::script

            subgraph "Inside solve.sh"
                direction TB
                P["Parser / Extractor\n(ESSID,BSSID from iwlist stdout)"]:::logic
                D["Password derivation logic\nESSID+BSSID -> passphrase"]:::logic
                O["Output\n(list of networks + estimated pass)"]:::output
            end

            C["check_owning_req.pl\n(post-auth checks)"]:::script
            W["0wn3r.pl\n(post-auth router actions)"]:::script
        end

        subgraph "Privileged system dependency (Requires root)"
            direction TB
            I["/usr/sbin/iwlist\n(wireless-tools)"]:::os
        end
    end

    %% =========================
    %% Main pipeline connections
    %% =========================
    U -->|"sudo/root_exec"| S
    S -->|"scan_wlan"| I
    I -->|"stdout:APs+ESSID+BSSID"| P
    P -->|"normalized_inputs"| D
    D -->|"passphrase_candidate"| O
    O -->|"prints_results"| U

    %% Data source relationship
    I <-->|"radio_scan_results"| R

    %% Derivation example as data-flow note
    EX["Example:\nBSSID 64:68:0C:FB:DA:74\nESSID CLARO_FBDA73\n=> pass 680CFBDA73"]:::note
    D -->|"derives_like"| EX

    %% =========================
    %% Post-auth optional branch
    %% =========================
    U -->|"optional_post_auth"| C
    C -->|"verify_preconditions"| M
    U -->|"optional_post_auth"| W
    W -->|"apply_config_changes(e.g._SSID)"| M

    %% =========================
    %% Constraints / Notes
    %% =========================
    N1["Assumes default router configuration\n(Claro defaults)"]:::note
    N2["Tested on GNU/Linux\n(Reported: Nicaragua)"]:::note
    S -->|"assumption"| N1
    S -->|"environment"| N2

    %% =========================
    %% Click events (component mapping)
    %% =========================
    click S "https://github.com/altmas5/claro-wifi-pass-solver/blob/master/solve.sh"
    click C "https://github.com/altmas5/claro-wifi-pass-solver/blob/master/check_owning_req.pl"
    click W "https://github.com/altmas5/claro-wifi-pass-solver/blob/master/0wn3r.pl"
    click Tool "https://github.com/altmas5/claro-wifi-pass-solver/blob/master/README.md"
    click N1 "https://github.com/altmas5/claro-wifi-pass-solver/blob/master/README.md"
    click N2 "https://github.com/altmas5/claro-wifi-pass-solver/blob/master/README.md"
    click EX "https://github.com/altmas5/claro-wifi-pass-solver/blob/master/README.md"
    click O "https://github.com/altmas5/claro-wifi-pass-solver/blob/master/README.md"
    click P "https://github.com/altmas5/claro-wifi-pass-solver/blob/master/README.md"
    click D "https://github.com/altmas5/claro-wifi-pass-solver/blob/master/README.md"
    click OS "https://github.com/altmas5/claro-wifi-pass-solver/blob/master/README.md"
    click U "https://github.com/altmas5/claro-wifi-pass-solver/blob/master/README.md"
    click N2 "https://github.com/altmas5/claro-wifi-pass-solver/blob/master/TODO.md"

    %% =========================
    %% Styles
    %% =========================
    classDef actor fill:#FFE7B3,stroke:#B7791F,stroke-width:2px,color:#1A202C;
    classDef script fill:#BEE3F8,stroke:#2B6CB0,stroke-width:2px,color:#1A202C;
    classDef logic fill:#C6F6D5,stroke:#2F855A,stroke-width:2px,color:#1A202C;
    classDef output fill:#E9D8FD,stroke:#6B46C1,stroke-width:2px,color:#1A202C;
    classDef os fill:#E2E8F0,stroke:#4A5568,stroke-width:2px,color:#1A202C;
    classDef external fill:#FED7D7,stroke:#C53030,stroke-width:2px,color:#1A202C,stroke-dasharray: 5 5;
    classDef note fill:#FAF089,stroke:#B7791F,stroke-width:1px,color:#1A202C;
    classDef group fill:#CBD5E0,stroke:#2D3748,stroke-width:2px,color:#1A202C;
```
