SSH Connector - Documentation

Date creation: 26/01/2026 Derniere MAJ: 26/01/2026 Status: ACTIF Version: 2.0.0

Vue d'ensemble

Le connecteur SSH permet d'executer des commandes sur des serveurs distants via l'API Connectors Hub. Supporte les connexions directes et via Jump Host (bastion), les transferts SFTP, et un terminal WebSocket temps reel.

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Frontend       │────►│  Connectors API │────►│  Serveur SSH    │
│  SshShell.tsx   │     │  /api/ssh/*     │     │  distant        │
│  SshWebTerminal │     │  WebSocket      │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                              │                         ▲
                              │                         │ (optionnel)
                              │                   ┌─────┴─────┐
                        ┌─────────────────┐       │ Jump Host │
                        │  ssh2 (node)    │───────► (Bastion) │
                        │  Credentials    │       └───────────┘
                        │  chiffres AES   │
                        └─────────────────┘

Endpoints API

POST /api/ssh/instance

Cree une nouvelle instance SSH (endpoint dedie).

// Request
{
  "name": "Serveur Prod",
  "host": "192.168.1.10",
  "port": 22,
  "username": "admin",
  "password": "secret",
  "auth_method": "password",
  "jump_host": {
    "host": "bastion.example.com",
    "port": 22,
    "username": "jump-user",
    "password": "jump-pass",
    "auth_method": "password"
  }
}

POST /api/ssh/execute

Execute une commande sur un serveur distant.

// Request
{
  "instance_id": "uuid",
  "command": "ls -la /var/log",
  "cwd": "/home/user",
  "timeout": 30000,
  "force": false
}

// Response
{
  "success": true,
  "stdout": "...",
  "stderr": "...",
  "exit_code": 0,
  "duration_ms": 234
}

Commandes dangereuses: Si une commande est detectee comme dangereuse (rm -rf, mkfs, etc.), retourne un warning. Ajouter "force": true pour executer quand meme.

POST /api/ssh/test

Teste une connexion SSH sans la sauvegarder.

// Request
{
  "host": "192.168.1.10",
  "port": 22,
  "username": "root",
  "password": "secret",
  "auth_method": "password"
}

// Response
{
  "success": true,
  "message": "Connection successful",
  "fingerprint": "SHA256:abc..."
}

POST /api/ssh/upload

Upload un fichier (texte) vers le serveur.

{
  "instance_id": "uuid",
  "content": "#!/bin/bash\necho hello",
  "remote_path": "/tmp/script.sh",
  "mode": "755"
}

POST /api/ssh/download

Download un fichier depuis le serveur.

// Request
{
  "instance_id": "uuid",
  "remote_path": "/var/log/app.log",
  "tail": 100
}

// Response
{
  "success": true,
  "content": "..."
}

POST /api/ssh/setup-key

Configure une cle SSH auto-generee (recommande).

{
  "instance_id": "uuid",
  "password": "current-password"
}

Flow:

Genere une paire RSA 4096
Se connecte avec le password
Ajoute la cle publique dans ~/.ssh/authorized_keys
Stocke la cle privee chiffree
Supprime le password de la BDD

SFTP (nouveau v2.0)

POST /api/ssh/sftp/list

Liste le contenu d'un repertoire distant.

// Request
{
  "instance_id": "uuid",
  "remote_path": "/var/log"
}

// Response
{
  "success": true,
  "entries": [
    {
      "name": "syslog",
      "type": "file",
      "size": 12345,
      "mtime": 1706310000,
      "mode": 33188
    }
  ]
}

POST /api/ssh/sftp/upload

Upload un fichier binaire (base64).

{
  "instance_id": "uuid",
  "content_base64": "SGVsbG8gV29ybGQ=",
  "remote_path": "/tmp/file.bin",
  "mode": "644"
}

POST /api/ssh/sftp/download

Download un fichier binaire (retour base64).

// Request
{
  "instance_id": "uuid",
  "remote_path": "/tmp/file.bin"
}

// Response
{
  "success": true,
  "content_base64": "SGVsbG8gV29ybGQ=",
  "size": 11
}

POST /api/ssh/sftp/delete

Supprime un fichier.

POST /api/ssh/sftp/mkdir

Cree un repertoire.

Limite de taille: 50MB par defaut (configurable via SFTP_MAX_SIZE)

WebSocket Terminal (nouveau v2.0)

WS /api/ssh/shell

Terminal interactif en temps reel via WebSocket.

Connexion:

wss://connectors.33800.nowhere84.com/api/ssh/shell?instance_id=uuid&token=jwt

Messages:

// Client -> Server (input)
{ "type": "input", "data": "ls -la\n" }

// Client -> Server (resize)
{ "type": "resize", "cols": 120, "rows": 40 }

// Server -> Client (output)
{ "type": "output", "data": "..." }

// Server -> Client (status)
{ "type": "ready", "message": "Shell connected" }
{ "type": "close", "message": "Session ended" }
{ "type": "error", "message": "..." }

Jump Host / Double SSH (nouveau v2.0)

Permet d'acceder a un serveur via un bastion intermediaire.

Local -> Jump Host (bastion) -> Serveur cible

Configuration

{
  "host": "192.168.1.10",
  "username": "admin",
  "auth_method": "key",
  "private_key_encrypted": "...",

  "jump_host": {
    "host": "bastion.example.com",
    "port": 22,
    "username": "jump-user",
    "auth_method": "password",
    "password_encrypted": "..."
  }
}

Le tunneling utilise ssh2.forwardOut() pour creer une connexion TCP vers le serveur cible a travers le bastion.

Securite

Chiffrement des credentials

Cle AES-256-CBC derivee de SSH_ENCRYPTION_KEY
IV aleatoire pour chaque valeur
Format: iv_hex:encrypted_hex

Commandes dangereuses detectees

rm -rf .../
mkfs
dd if=
> /dev/
chmod -R 777
shutdown, reboot
systemctl stop sshd

Audit

Toutes les operations SSH sont loggees dans audit_logs:

ssh.execute
ssh.upload
ssh.download
ssh.setup_key
ssh.sftp_list
ssh.sftp_upload
ssh.sftp_download
ssh.sftp_delete
ssh.sftp_mkdir
ssh.shell_start
ssh.shell_end
ssh.create_instance

Frontend

Page /connect/ssh

Formulaire de creation d'une instance SSH:

Nom de la connexion
Host / IP + Port
Username
Auth: Password OU Cle privee PEM
Option: Generer cle SSH automatiquement
Section Jump Host (optionnel)

Composant SshShell

Interface "one-shot" pour commandes:

Historique des commandes
Navigation ↑/↓ dans l'historique
Warning pour commandes dangereuses
Affichage stdout/stderr avec code couleur
Exit code et duree d'execution

Composant SshWebTerminal (nouveau)

Terminal interactif xterm.js:

Connexion WebSocket temps reel
Theme Tokyo Night
Support vim, htop, etc.
Redimensionnement automatique
Raccourcis clavier complets

Base de donnees

Table `user_connectors`

La config SSH est stockee dans token_metadata (JSONB):

{
  "host": "192.168.1.10",
  "port": 22,
  "username": "root",
  "auth_method": "password",
  "password_encrypted": "iv:encrypted",
  "fingerprint": "SHA256:...",
  "jump_host": {
    "host": "bastion.example.com",
    "port": 22,
    "username": "jump-user",
    "auth_method": "key",
    "private_key_encrypted": "..."
  }
}

Variables d'environnement

Variable	Description	Default
SSH_ENCRYPTION_KEY	Cle de chiffrement AES	`default-key-...`
SFTP_MAX_SIZE	Taille max fichier SFTP (bytes)	`52428800` (50MB)

Fichiers sources

Backend (connectors-api)

src/services/ssh.ts - Service SSH principal (execute, SFTP, shell)
src/index.ts - Routes /api/ssh/*, WebSocket handler
src/data/connector-types.ts - Type SSH
src/services/audit.ts - Actions SSH

Frontend (connectors-front)

src/components/SshShell.tsx - Interface commandes one-shot
src/components/SshWebTerminal.tsx - Terminal WebSocket xterm.js
src/routes/connect/ssh/index.tsx - Formulaire creation
src/routes/connect/index.tsx - Carte SSH
src/routes/connectors/instance/[id]/index.tsx - Integration terminals

Dependencies

Backend: ssh2 (npm)
Frontend: @xterm/xterm, @xterm/addon-fit, @xterm/addon-web-links

WireGuard VPN (nouveau 27/01/2026)

Vue d'ensemble

Chaque instance SSH peut configurer un tunnel VPN WireGuard pour acceder a des machines distantes de maniere securisee (derriere NAT, reseaux prives).

Architecture

┌────────────────────────┐     ┌─────────────────────┐     ┌────────────────┐
│   connectors-api       │────►│  wireguard-sidecar  │────►│  Peer distant  │
│   /api/instances/vpn   │     │  (port 5410)        │     │  WireGuard     │
└────────────────────────┘     │  wireguard-go       │     └────────────────┘
                               └─────────────────────┘

Endpoints API

Endpoint	Description
`POST /api/instances/:id/vpn/generate-keys`	Genere paire de cles WireGuard
`PUT /api/instances/:id/vpn`	Configure VPN (endpoint, peer, allowed_ips)
`POST /api/instances/:id/vpn/connect`	Demarre tunnel
`POST /api/instances/:id/vpn/disconnect`	Arrete tunnel
`GET /api/instances/:id/vpn/status`	Status (connected, transfer, handshake)
`GET /api/instances/:id/vpn/config`	Config sans cle privee
`DELETE /api/instances/:id/vpn`	Supprime config VPN
`GET /api/vpn/active`	Liste tunnels actifs

Configuration

{
  "endpoint": "82.67.42.47:51820",
  "peer_public_key": "ABC123...",
  "allowed_ips": "10.0.0.0/24, 192.168.1.0/24",
  "address": "10.0.0.2/24",
  "dns": "1.1.1.1",
  "persistent_keepalive": 25,
  "auto_connect": true
}

Sidecar WireGuard

Container: wireguard-sidecar (port 5410)
Image: Python/FastAPI + wireguard-tools
Reseau: supabase-prod_supabase-prod (partage avec connectors-api)
Capabilities: NET_ADMIN, SYS_MODULE
Volume: /etc/wireguard pour configs

Fichiers sources

Backend (connectors-api):

src/services/wireguard.ts - Service VPN
src/index.ts - Endpoints /api/instances/:id/vpn/*

Sidecar:

/stock_8to/33800-stack/docker/stacks/wireguard-sidecar/
app.py - API FastAPI
Dockerfile - Image Alpine + wireguard-tools

Frontend:

src/components/VpnConfig.tsx - UI configuration VPN
Integration dans page instance SSH

Limites

Max 5 tunnels simultanes par user (configurable)
Taille fichiers SFTP: 50MB
Auto-connect au redemarrage container (optionnel)

Securite

Cles privees chiffrees AES-256-CBC
Audit logs: vpn.generate_keys, vpn.configure, vpn.connect, vpn.disconnect
Validation CIDR pour allowed_ips

SSH Connector - Documentation

Vue d'ensemble

Architecture

Endpoints API

POST /api/ssh/instance

POST /api/ssh/execute

POST /api/ssh/test

POST /api/ssh/upload

POST /api/ssh/download

POST /api/ssh/setup-key

SFTP (nouveau v2.0)

POST /api/ssh/sftp/list

POST /api/ssh/sftp/upload

POST /api/ssh/sftp/download

POST /api/ssh/sftp/delete

POST /api/ssh/sftp/mkdir

WebSocket Terminal (nouveau v2.0)

WS /api/ssh/shell

Jump Host / Double SSH (nouveau v2.0)

Configuration

Securite

Chiffrement des credentials

Commandes dangereuses detectees

Audit

Frontend

Page /connect/ssh

Composant SshShell

Composant SshWebTerminal (nouveau)

Base de donnees

Table user_connectors

Variables d'environnement

Fichiers sources

Backend (connectors-api)

Frontend (connectors-front)

Dependencies

WireGuard VPN (nouveau 27/01/2026)

Vue d'ensemble

Architecture

Endpoints API

Configuration

Sidecar WireGuard

Fichiers sources

Limites

Securite

Table `user_connectors`