# SSH Proxy Transparent — Debian to HPC Gateway Lab

> De Debian vierge à proxy SSH transparent en 30 minutes

## ⚠️ SETUP INITIAL (À FAIRE UNE SEULE FOIS)

```bash
# 1. Générer les clés SSH (créées localement, jamais commitées)
.\init-keys.ps1

# 2. Vérifier que le répertoire keys/ est créé
ls keys/
# lab_rsa, lab_rsa.pub, gateway_rsa, gateway_rsa.pub

# 3. Lancer le lab
docker compose up -d

# 4. Tester
ssh -p 2222 -i keys/lab_rsa testuser@localhost 'hostname'
# Résultat: dest1 ou dest2 ✓
```

**⚠️ Important:**
- Le dossier `keys/` **entier est ignoré par `.gitignore`** — jamais commité
- Chaque développeur génère ses propres clés localement avec `init-keys.ps1`
- À chaque `docker compose down/up`, supprimer l'entrée host:
  ```bash
  ssh-keygen -f ~/.ssh/known_hosts -R "[localhost]:2222"
  ```

**→ Voir:** [doc/SETUP_INITIAL.md](doc/SETUP_INITIAL.md) pour plus de détails

---

## 🎯 Objectif

Créer une **gateway SSH transparente** qui:
- Accepte vos connexions SSH depuis Windows
- Les redirige automatiquement vers l'une des deux machines de destination
- Vous fait atterrir dans un shell sur la destination
- Vous ne voyez pas le passage par la gateway

## 🚀 Quick Start (après setup initial)

```bash
# 1. Lancer
docker compose up -d

# 2. Tester commande
ssh -p 2222 -i keys/lab_rsa testuser@localhost 'hostname'
# Affiche: dest1 ou dest2 (aléatoire) ✓

# 3. Shell interactif
ssh -p 2222 -i keys/lab_rsa testuser@localhost
# testuser@dest1:~$  (ou dest2)

# 4. Arrêter
docker compose down

# 5. Relancer (après avoir nettoyé known_hosts)
ssh-keygen -f ~/.ssh/known_hosts -R "[localhost]:2222"
docker compose up -d
```

## 📚 Documentation

**Vous êtes nouveau?** → [doc/SETUP_INITIAL.md](doc/SETUP_INITIAL.md) (5 min) ⭐⭐⭐

**Vous avez 5 minutes?** → [doc/01_DEMARRAGE_RAPIDE.md](doc/01_DEMARRAGE_RAPIDE.md)

**Vous avez 20 minutes?** → [doc/02_ARCHITECTURE_VUE_ENSEMBLE.md](doc/02_ARCHITECTURE_VUE_ENSEMBLE.md)

**Vous voulez des diagrammes?** → [doc/03_ARCHITECTURE_DIAGRAMMES.md](doc/03_ARCHITECTURE_DIAGRAMMES.md)

**Vous trouvez ça compliqué?** → [doc/04_CONCEPT_EXPLIQUE_SIMPLEMENT.md](doc/04_CONCEPT_EXPLIQUE_SIMPLEMENT.md)

**Vous maîtrisez déjà?** → [doc/05_DETAILS_TECHNIQUES_COMPLETS.md](doc/05_DETAILS_TECHNIQUES_COMPLETS.md)

**Vous débogguez?** → [doc/06_DEBUG_ET_SOLUTIONS.md](doc/06_DEBUG_ET_SOLUTIONS.md)

**Redémarrage/down-up?** → [doc/REDEMARRAGE_QUICK_REFERENCE.md](doc/REDEMARRAGE_QUICK_REFERENCE.md)

**Voir tout l'index:** → [doc/INDEX.md](doc/INDEX.md)

## 📂 Structure

```
sshproxy-lab/
├── README.md                    ← Vous êtes ici
├── STRUCTURE.md                 ← Visualisation du projet
├── .gitignore                   ← Protège keys/ (jamais commité)
├── init-keys.ps1                ← 🔑 À lancer UNE FOIS avant de démarrer
├── docker-compose.yaml          ← Orchestration
├── doc/                         ← 📚 Documentation (16 fichiers)
│   ├── INDEX.md                ← Navigation principale
│   ├── SETUP_INITIAL.md        ← ⭐ Clés SSH et setup
│   ├── REDEMARRAGE_QUICK_REFERENCE.md ← Down/up guide
│   ├── 01_DEMARRAGE_RAPIDE.md
│   ├── 02_ARCHITECTURE_VUE_ENSEMBLE.md
│   └── ...et 10 autres fichiers
├── gateway/                     ← Configuration gateway
│   ├── Dockerfile
│   ├── sshd_config              (ForceCommand crucial!)
│   ├── sshproxy.yaml            (-tt crucial!)
│   └── sshproxy-wrapper.sh
├── dest/                        ← Configuration destinations
│   ├── Dockerfile
│   └── sshd_config
└── keys/                        ← SSH keys (générées par init-keys.ps1)
    └── README.md                ← Explication du workflow
    (Contenu jamais commité dans GitLab - .gitignore)
```

## 🔑 Points clés

### 1. init-keys.ps1 (À FAIRE UNE SEULE FOIS)
```bash
.\init-keys.ps1
```
Crée le répertoire `keys/` et génère les 2 paires de clés SSH **localement uniquement**

### 2. .gitignore (protège les clés)
```
keys/  ← Tout le dossier est ignoré - jamais commité
```

### 3. ForceCommand (gateway/sshd_config)
```
ForceCommand /usr/sbin/sshproxy-wrapper
↑ TOUTE connexion SSH est interceptée et proxifiée
```

### 4. -tt flag (gateway/sshproxy.yaml)
```
args: ["-tt", ...]
↑ Alloue PTY sur destination → shell interactif possible
```

### 5. 2 couches d'authentification
```
Layer 1: lab_rsa    (Windows → Gateway - généré localement)
Layer 2: gateway_rsa (Gateway → Destinations - généré localement)
```

## 🧪 Tests

```bash
# Commande simple
ssh -p 2222 testuser@localhost 'hostname'

# Shell interactif
echo "hostname" | ssh -p 2222 testuser@localhost

# Vérifier round-robin (5 fois)
for i in {1..5}; do ssh -p 2222 testuser@localhost hostname; done

# Voir les logs sshproxy
docker exec sshproxy-gateway tail -f /tmp/sshproxy-testuser.log

# Arrêter
docker compose down -v

# Relancer (nettoyer known_hosts d'abord!)
ssh-keygen -f ~/.ssh/known_hosts -R "[localhost]:2222"
docker compose up -d
```

## 🎓 Ce qui se passe

```
Step 1: ssh -p 2222 -i lab_rsa testuser@localhost
Step 2: Gateway sshd accept (vérifie lab_rsa.pub)
Step 3: Exécute ForceCommand: /usr/sbin/sshproxy-wrapper
Step 4: Wrapper lance: /usr/sbin/sshproxy
Step 5: sshproxy choisit random: dest1 ou dest2
Step 6: sshproxy exécute: ssh -tt -i gateway_rsa testuser@DEST
Step 7: Destination sshd accept (vérifie gateway_rsa.pub)
Step 8: Résultat retourné à Windows
```

## ✨ Pourquoi "transparent"?

Vous avez l'impression de faire `ssh dest1 'cmd'` alors que vous faites vraiment `ssh gateway 'cmd'` qui se redirige tout seul.

## 🐛 Pièges évités

- ❌ Clés commitées → **Solution**: `.gitignore` ignore `keys/` entièrement
- ❌ Permission denied sur gateway_rsa → **Solution**: `chown testuser /etc/sshproxy/gateway_rsa`
- ❌ Exit status 255 → **Solution**: `-tt` flag dans sshproxy.yaml
- ❌ Shell freeze → **Solution**: wrapper shell + sshproxy détection
- ❌ REMOTE HOST IDENTIFICATION HAS CHANGED → **Solution**: `ssh-keygen -f ~/.ssh/known_hosts -R "[localhost]:2222"`

## 📊 Architecture

```
┌─ Windows ─────────────────────────────────────────┐
│  ssh -p 2222 -i lab_rsa testuser@localhost       │
└────────────────────┬────────────────────────────────┘
                     │ Port 2222
                     ↓
         ┌──────────────────────────┐
         │  Gateway (172.30.0.10)   │
         │  ┌────────────────────┐  │
         │  │ SSH Daemon (sshd)  │  │
         │  ├────────────────────┤  │
         │  │ ForceCommand       │  │
         │  │ ↓                  │  │
         │  │ sshproxy-wrapper   │  │
         │  │ ↓                  │  │
         │  │ sshproxy           │  │
         │  │ (random select)    │  │
         │  └────────────────────┘  │
         └────────┬──────────────────┘
          ┌───────┴────────┐
          ↓ 50%           ↓ 50%
    dest1 (172.30.0.11)  dest2 (172.30.0.12)
    Shell normal         Shell normal
```

## 🎯 Cas d'usage

✅ **Fonctionne**:
```bash
ssh gateway 'ls -la'
ssh gateway 'for i in 1..3; do date; done'
ssh gateway                    # Shell interactif
```

❌ **Ne fonctionne pas** (intentionnel):
```bash
ssh gateway -L 3306:dest:3306  # Port forwarding disabled
ssh gateway -X                 # X11 forwarding disabled
```

## 🔧 Customization

### Ajouter une 3e destination
Modifier `gateway/sshproxy.yaml`:
```yaml
dest:
  - "172.30.0.11:22"
  - "172.30.0.12:22"
  - "172.30.0.13:22"  # ← Ajouter ici
```

### Changer la stratégie de sélection
```yaml
route_select: "round_robin"  # Au lieu de "random"
```

### Ajouter de l'audit
Modifier `gateway/sshproxy-wrapper.sh`:
```bash
echo "$(date): $USER executed $SSH_ORIGINAL_COMMAND" >> /var/log/audit.log
exec /usr/sbin/sshproxy
```

## 📈 Prochaines étapes

- [ ] Ajouter etcd pour persistance session
- [ ] Intégrer OpenLDAP pour auth centralisée
- [ ] Implement ACLs (qui peut aller où)
- [ ] Health checks pour destinations
- [ ] Logging/Audit de chaque commande

## 🤝 Documentation

**Besoin d'aide?**
1. Voir [doc/INDEX.md](doc/INDEX.md) pour tous les fichiers
2. Lire [doc/SETUP_INITIAL.md](doc/SETUP_INITIAL.md) pour clés SSH (sécurité)
3. Lire [doc/REDEMARRAGE_QUICK_REFERENCE.md](doc/REDEMARRAGE_QUICK_REFERENCE.md) pour down/up
4. Lire [doc/10_CHEMINS_DE_LECTURE.md](doc/10_CHEMINS_DE_LECTURE.md) pour votre profil
5. Consulter [doc/06_DEBUG_ET_SOLUTIONS.md](doc/06_DEBUG_ET_SOLUTIONS.md) pour les pièges

---

**Commencez par:**
1. [doc/SETUP_INITIAL.md](doc/SETUP_INITIAL.md) ⭐⭐⭐ (5 min - clés SSH)
2. [doc/01_DEMARRAGE_RAPIDE.md](doc/01_DEMARRAGE_RAPIDE.md) (5 min - concept)
3. `docker compose up -d`