kalexnolasco/webgate repository overview

export WEBGATE_SECRET_KEY=$(openssl rand -hex 32)
docker compose up -d
# open http://localhost:8443/ — login: admin / admin

docker compose pull && docker compose up -d

flowchart TB
    subgraph internet ["Internet"]
        YOU["Your Team"]
    end
    subgraph firewall ["Client Firewall"]
        GW["Gateway Server<br/>(HTTP only)"]
        subgraph internal ["Internal Network"]
            DB1[(PostgreSQL<br/>10.0.1.10)]
            DB2[(MySQL<br/>10.0.1.11)]
            APP1["App Server<br/>10.0.1.20"]
            APP2["App Server<br/>10.0.1.21"]
            WORKER["Worker<br/>10.0.1.30"]
            REDIS["Redis<br/>10.0.1.40"]
        end
    end
    YOU -- "HTTPS :443" --> GW
    GW -. "SSH :22" .-> DB1
    GW -. "SSH :22" .-> DB2
    GW -. "SSH :22" .-> APP1
    GW -. "SSH :22" .-> APP2
    GW -. "SSH :22" .-> WORKER
    GW -. "SSH :22" .-> REDIS
    style internet fill:none,stroke:#4a90d9,stroke-width:2px
    style firewall fill:none,stroke:#ff9800,stroke-width:2px
    style internal fill:none,stroke:#5cb85c,stroke-width:2px
    style GW fill:#ffcc02,stroke:#e6a800,color:#333
    style YOU fill:#4a90d9,stroke:#2a6cb5,color:#fff

flowchart TB
    subgraph internet ["Internet"]
        ENG1["Engineer 1<br/>(Browser)"]
        ENG2["Engineer 2<br/>(Browser)"]
        ENG3["Engineer 3<br/>(Browser)"]
    end
    subgraph firewall ["Client Firewall"]
        WG["webgate<br/>Gateway Server :443"]
        subgraph internal ["Internal Network"]
            DB1[(PostgreSQL)]
            APP1["App Server"]
            WORKER["Worker"]
            REDIS["Redis"]
        end
    end
    ENG1 -- "HTTPS" --> WG
    ENG2 -- "HTTPS" --> WG
    ENG3 -- "HTTPS" --> WG
    WG -- "SSH/SFTP" --> DB1
    WG -- "SSH/SFTP" --> APP1
    WG -- "SSH/SFTP" --> WORKER
    WG -- "SSH/SFTP" --> REDIS
    style internet fill:none,stroke:#4a90d9,stroke-width:2px
    style firewall fill:none,stroke:#ff9800,stroke-width:2px
    style internal fill:none,stroke:#5cb85c,stroke-width:2px
    style WG fill:#5cb85c,stroke:#449d44,color:#fff
    style ENG1 fill:#4a90d9,stroke:#2a6cb5,color:#fff
    style ENG2 fill:#4a90d9,stroke:#2a6cb5,color:#fff
    style ENG3 fill:#4a90d9,stroke:#2a6cb5,color:#fff

src/webgate/
├── __main__.py          uvicorn launcher
├── app.py               FastAPI factory, lifespan, middleware
├── config.py            boot settings (env only); the rest live in the admin panel
├── agent/               per-server AI chat: provider, tools, SFTP-only tools, cache
├── audit/               immutable action log
├── auth/                JWT + bcrypt, 2FA TOTP, API keys, LDAP, user management
├── backup/              full-state export/import, passphrase-encrypted
├── branding/            white-label store: name, logo, colours, favicon
├── db/                  async engine + additive, append-only migrations
├── files/
│   ├── sftp_service.py  SFTP operations, chunked reads, ZIP builders
│   ├── pool.py          connection reuse, 300 s TTL
│   ├── limits.py        per-request transfer budget
│   └── routes.py        REST endpoints
├── recordings/          asciinema cast v2 writer + browser replay
├── runtime_config/
│   ├── registry.py      every setting an admin may change, with its validation
│   ├── store.py         key/value rows, encrypted secrets, in-process snapshot
│   └── routes.py        /api/settings
├── servers/
│   ├── hostkeys.py      trust-on-first-use pinning and verification
│   ├── monitor.py       leader-elected status sweep
│   ├── crypto.py        Fernet credential encryption
│   └── service.py       registry CRUD, jump-host resolution
├── snippets/            per-user command library
├── terminal/
│   ├── ssh_session.py   asyncssh wrapper, optional jump tunnel
│   ├── shared.py        SharedSession registry: 1 PTY ↔ N WebSockets, idle watchdog
│   ├── ws_handler.py    input multiplex / output broadcast
│   └── routes.py        WS endpoints + share-token mint/revoke
├── webhooks/            HMAC-signed event dispatcher
└── static/index.html    single-file frontend (Alpine.js + xterm.js + CodeMirror)

flowchart LR
  subgraph people["People"]
    B["Browser<br/>Alpine.js + xterm.js"]
  end

  subgraph gw["Gateway — the only host with both routes"]
    W["webgate<br/>FastAPI :8443"]
    DB[("SQLite or PostgreSQL<br/>credentials encrypted<br/>with Fernet")]
  end

  subgraph fleet["Internal network — no inbound internet"]
    BAS["Bastion"]
    S1["prod-web-01 :22"]
    S2["prod-db-primary :22"]
    S3["SFTP-only host"]
  end

  subgraph ext["Outbound, optional"]
    LD["LDAP / AD"]
    AI["Ollama or OpenRouter"]
    WH["Webhook receivers"]
  end

  B -->|"HTTPS + WebSocket"| W
  W --- DB
  W -->|"SSH / SFTP"| BAS
  BAS -.->|"tunnel"| S1
  BAS -.->|"tunnel"| S2
  W -->|"SFTP only"| S3
  W -->|"bind + search"| LD
  W -->|"chat completions"| AI
  W -->|"HMAC-signed POST"| WH

flowchart LR
    B["Browser"]
    WG["webgate"]
    BAST["bastion<br/>10.0.0.1"]
    INT["internal-app<br/>10.0.1.50"]
    B -- "HTTPS / WSS" --> WG
    WG -- "SSH" --> BAST
    BAST -- "SSH (tunneled)" --> INT
    style B fill:#4a90d9,stroke:#2a6cb5,color:#fff
    style WG fill:#5cb85c,stroke:#449d44,color:#fff
    style BAST fill:#ffcc02,stroke:#e6a800,color:#333
    style INT fill:#b25e00,stroke:#ff9800,color:#fff

flowchart LR
    O["Owner WS"]
    J1["Joiner WS (rw)"]
    J2["Joiner WS (ro)"]
    SS["SharedSession"]
    PTY["asyncssh PTY"]
    REMOTE["Remote SSH server"]
    REC["CastRecorder<br/>(if recording on)"]

    O -- "input" --> SS
    J1 -- "input" --> SS
    J2 -. "no input" .-> SS
    SS -- "write stdin" --> PTY
    PTY -- "stdout" --> SS
    SS -- "broadcast" --> O
    SS -- "broadcast" --> J1
    SS -- "broadcast" --> J2
    SS -. "tee" .-> REC
    PTY <--> REMOTE

    style SS fill:#5cb85c,stroke:#449d44,color:#fff
    style PTY fill:#ffcc02,stroke:#e6a800,color:#333
    style REC fill:#a78bfa,stroke:#7c3aed,color:#fff

flowchart LR
    subgraph LDAP
        L1["alice ∈ cn=devs"]
        L2["alice ∈ cn=admins"]
    end
    subgraph MAP["Group mapping<br/>Admin &rarr; Settings &rarr; LDAP"]
        M["{<br/>  &quot;devs&quot;: &quot;production&quot;,<br/>  &quot;sre&quot;: &quot;all&quot;<br/>}"]
    end
    subgraph User
        U["alice.allowed_groups<br/>= [&quot;production&quot;]"]
    end
    subgraph Servers
        S1["app-1<br/>group=production ✅"]
        S2["app-2<br/>group=staging ❌"]
        S3["db-1<br/>group=production ✅"]
    end
    L1 -- mapped --> M
    L2 -. ignored<br/>(not in map) .-> M
    M --> U
    U --> S1
    U --> S3

sequenceDiagram
    participant Browser
    participant webgate
    participant LDAP

    Browser->>webgate: POST /api/auth/login (alice, ****)
    webgate->>webgate: try local password (miss)
    webgate->>LDAP: bind(svc-DN, svc-password)
    LDAP-->>webgate: ok
    webgate->>LDAP: search(uid=alice) under user_base
    LDAP-->>webgate: dn=uid=alice,ou=people,...
    webgate->>LDAP: re-bind(user-DN, user-password)
    LDAP-->>webgate: ok ✅
    webgate->>LDAP: search(member=user-DN) under group_base
    LDAP-->>webgate: [devs, admins]
    webgate->>webgate: map → allowed_groups, is_admin
    webgate->>webgate: upsert local User row
    webgate-->>Browser: JWT