init_guac

guacamole_test_11_26/docs/BULK_SSH_COMMANDS_GUIDE.md

@@ -0,0 +1,238 @@
+# 🔐 Bulk SSH Commands - Массовое выполнение команд
+
+## ✨ Описание
+
+Bulk SSH Commands позволяет выполнять SSH команды на **множестве машин одновременно** с гибкой системой авторизации.
+
+---
+
+## 🎯 **3 Режима Авторизации**
+
+### **1️⃣ Saved Credentials (Рекомендуется)**
+```
+✅ Использование: Saved machines с credentials в БД
+✅ Безопасность: Высокая (encrypted в БД)
+✅ UX: Простой (нет ввода)
+❌ Ограничение: Только для saved machines
+```
+
+**Как работает:**
+- Credentials расшифровываются из БД
+- Автоматически применяются для каждой машины
+- Не требует ввода пароля
+
+---
+
+### **2️⃣ Global Credentials (Простой)**
+```
+✅ Использование: Одинаковые credentials для всех машин
+✅ UX: Быстрый (один ввод)
+✅ Гибкость: Можно override saved credentials
+⚠️ Безопасность: Средняя (один пароль для всех)
+```
+
+**UI:**
+```
+Username: [root        ]
+Password: [************]
+```
+
+---
+
+### **3️⃣ Custom Credentials (Гибкий)**
+```
+✅ Использование: Разные credentials для каждой машины
+✅ Безопасность: Высокая
+✅ Гибкость: Максимальная
+❌ UX: Сложный (много вводить)
+```
+
+**UI:**
+```
+Quick Fill: [username] [password] [Copy to All]
+
+Machine 1: [username] [password]
+Machine 2: [username] [password]
+Machine 3: [username] [password]
+```
+
+---
+
+## 🔐 **Role-based Permissions**
+
+### **Limits:**
+
+| Role | Max Machines | Commands |
+|------|-------------|----------|
+| **GUEST** | ❌ 0 | Forbidden |
+| **USER** | ✅ 20 | Whitelist only |
+| **ADMIN** | ✅ 100 | Any commands |
+| **SUPER_ADMIN** | ✅ 100 | Any commands |
+
+### **USER Whitelist:**
+```python
+allowed_commands = [
+    "uptime",
+    "df -h",
+    "free -m",
+    "top -bn1",
+    "systemctl status",
+    "docker ps",
+    "ps aux",
+    "ls -la",
+    "cat /etc/os-release",
+    "hostname"
+]
+```
+
+---
+
+## 📊 **API Reference**
+
+### **POST /bulk/ssh-command**
+
+**Request:**
+```json
+{
+  "machine_ids": ["abc123...", "def456..."],
+  "command": "systemctl restart nginx",
+  "credentials_mode": "global",
+  "global_credentials": {
+    "username": "root",
+    "password": "secure_password"
+  },
+  "timeout": 30
+}
+```
+
+**Response:**
+```json
+{
+  "total": 2,
+  "success": 2,
+  "failed": 0,
+  "execution_time_ms": 2400,
+  "command": "systemctl restart nginx",
+  "results": [
+    {
+      "machine_id": "abc123...",
+      "machine_name": "web-01",
+      "hostname": "192.168.1.10",
+      "status": "success",
+      "exit_code": 0,
+      "stdout": "nginx restarted",
+      "stderr": "",
+      "execution_time_ms": 1200
+    }
+  ]
+}
+```
+
+---
+
+## 🎨 **UI Flow**
+
+```
+1. Bulk Select → выбрать машины
+2. Click "Run Command" → modal открывается
+3. Выбрать режим: [Saved] [Global] [Custom]
+4. Ввести команду: "systemctl restart nginx"
+5. Заполнить credentials (если нужно)
+6. Execute → параллельное выполнение
+7. Результаты → expandable stdout/stderr
+8. Export CSV / Retry Failed
+```
+
+---
+
+## 🔒 **Security Best Practices**
+
+1. ✅ **Use Saved Credentials** когда возможно
+2. ✅ **Whitelist commands** для USER role
+3. ✅ **Command audit logging** для всех операций
+4. ✅ **Concurrency limits** (max 10 concurrent SSH)
+5. ✅ **Timeout protection** (5-300 seconds)
+
+---
+
+## 📋 **Use Cases**
+
+### **1. Restart service на всех web серверах**
+```
+Select: tags="webserver" (15 machines)
+Command: systemctl restart nginx
+Mode: Saved credentials
+Result: 15/15 success
+```
+
+### **2. Check disk space на prod серверах**
+```
+Select: tags="production" (50 machines)
+Command: df -h
+Mode: Saved credentials
+Result: Export to CSV для анализа
+```
+
+---
+
+## ⚠️ **Production Notes**
+
+### **SSH Implementation:**
+```python
+# Current: DEMO mode (sshpass fallback)
+# Production: Use paramiko
+
+pip install paramiko
+
+import paramiko
+
+client = paramiko.SSHClient()
+client.connect(hostname, username=username, password=password)
+stdin, stdout, stderr = client.exec_command(command)
+```
+
+---
+
+## 🐛 **Troubleshooting**
+
+### **Issue: "Command not in whitelist"**
+```
+Error: USER role tried to run "rm -rf /"
+Solution: 
+  1. Contact administrator for command approval
+  2. Or request ADMIN role upgrade
+```
+
+### **Issue: "No saved credentials available"**
+```
+Cause: Machine не имеет saved credentials
+Solution: 
+  1. Use "Global" mode
+  2. Or save credentials first
+```
+
+---
+
+## 🎓 **Examples**
+
+```typescript
+// Example 1: Check uptime (USER role)
+Command: "uptime"
+Mode: Saved
+Result: ✅ 10/10 success
+
+// Example 2: Restart nginx (ADMIN role)
+Command: "systemctl restart nginx"
+Mode: Global (root/password)
+Result: ✅ 19/20 success, ❌ 1 failed
+
+// Example 3: Custom per machine
+Command: "systemctl status postgresql"
+Mode: Custom (different users)
+Result: ✅ 5/5 success
+```
+
+---
+
+**🎉 Bulk SSH Commands полностью реализованы!**
+