qa360 2.1.2 → 2.1.4

package/docs/secrets.md

@@ -0,0 +1,392 @@
+# QA360 Secrets - Gestion Sécurisée des Credentials
+
+## 🔐 Vue d'ensemble
+
+Le système **QA360 Secrets** fournit une gestion sécurisée, locale et chiffrée des credentials pour vos tests. Aucune dépendance cloud, chiffrement AES-256-GCM, et intégration transparente avec les packs de tests.
+
+**Principe** : Local-first, zero-trust, jamais de secrets en clair dans logs ou rapports.
+
+## 🏗️ Architecture Sécurisée
+
+### Chiffrement AES-256-GCM
+
+```
+Secrets en clair → PBKDF2 → AES-256-GCM → .qa360/secrets.enc
+     ↓                ↓           ↓              ↓
+ Utilisateur    Clé dérivée  Chiffrement    Stockage local
+```
+
+### Composants
+
+- **SecretsCrypto** : Chiffrement/déchiffrement AES-256-GCM
+- **SecretsManager** : Gestion CRUD des secrets
+- **SecurityRedactor** : Masquage automatique dans logs
+- **CLI Commands** : Interface utilisateur intuitive
+
+## 🔑 Gestion des Clés
+
+### Sources de Clés (par priorité)
+
+1. **Variable d'environnement** : `QA360_SECRETS_PASSWORD`
+2. **Keychain système** :
+   - **macOS** : Keychain Access
+   - **Linux** : secret-tool (libsecret)
+   - **Windows** : Credential Manager
+3. **Clé dérivée machine** : Hash déterministe (fallback)
+
+### Génération Automatique
+
+```bash
+# Première utilisation - génération automatique
+qa360 secrets add API_TOKEN
+# → Crée automatiquement clé maître si inexistante
+# → Stocke dans keychain système
+# → Permissions 600 sur fichier secrets.enc
+```
+
+## 📋 Commandes CLI
+
+### Ajouter un Secret
+
+```bash
+# Mode interactif
+qa360 secrets add
+# → Demande nom et valeur de manière sécurisée
+
+# Mode direct
+qa360 secrets add API_TOKEN
+# → Demande uniquement la valeur (masquée)
+
+# Validation automatique
+# ✅ Détecte si la valeur ressemble à un secret
+# ⚠️  Avertit si format inhabituel
+```
+
+### Lister les Secrets
+
+```bash
+qa360 secrets list
+# Affiche :
+# • API_TOKEN (créé: 01/01/2025, modifié: 02/01/2025)
+# • DATABASE_URL (créé: 01/01/2025)
+# • STRIPE_KEY (créé: 03/01/2025)
+```
+
+### Supprimer un Secret
+
+```bash
+# Mode interactif
+qa360 secrets remove
+# → Liste pour sélection
+
+# Mode direct
+qa360 secrets remove API_TOKEN
+# → Confirmation requise
+```
+
+### Diagnostic
+
+```bash
+qa360 secrets doctor
+# Vérifie :
+# ✅ Fichier secrets.enc accessible
+# ✅ Clé de déchiffrement valide
+# ✅ Nombre de secrets configurés
+# ❌ Erreurs de permissions/corruption
+```
+
+### Export Debug
+
+```bash
+# Export redacted (sécurisé)
+qa360 secrets export --redacted
+# API_TOKEN: sk-***
+# DATABASE_URL: pos***ost
+# STRIPE_KEY: pk_***
+
+# Export complet (DANGEREUX)
+qa360 secrets export --no-redacted
+# ⚠️  Confirmation requise
+# ⚠️  Valeurs en clair affichées
+```
+
+## 🔗 Intégration Pack v1
+
+### Références dans pack.yml
+
+```yaml
+environment:
+  # Référence secret chiffré
+  API_KEY: "${{ secrets.API_KEY }}"
+  
+  # Référence avec validation
+  DATABASE_URL: "${{ secrets.DATABASE_URL }}"
+  
+  # Variables normales (non sensibles)
+  NODE_ENV: "production"
+  LOG_LEVEL: "info"
+```
+
+### Interpolation Automatique
+
+```yaml
+# Dans pack.yml
+targets:
+  api:
+    baseUrl: "https://api.example.com"
+    headers:
+      Authorization: "Bearer ${{ secrets.API_TOKEN }}"
+
+# Lors de l'exécution
+# → secrets.API_TOKEN est remplacé par la valeur déchiffrée
+# → Jamais visible dans logs ou rapports
+# → Masqué automatiquement par SecurityRedactor
+```
+
+### Validation Références
+
+```bash
+# Validation automatique lors de qa360 run
+qa360 run
+# ✅ Tous les secrets référencés existent
+# ❌ Secret manquant → Erreur claire avec suggestion
+
+# Validation manuelle
+qa360 pack validate
+# Vérifie cohérence références secrets
+```
+
+## 🛡️ Sécurité Opérationnelle
+
+### Redaction Automatique
+
+Le **SecurityRedactor** masque automatiquement :
+
+```javascript
+// Patterns détectés et masqués
+{
+  "password": "***",
+  "token": "***", 
+  "authorization": "Bearer ***",
+  "api_key": "***",
+  "${{ secrets.API_TOKEN }}": "${{ secrets.*** }}"
+}
+```
+
+### Règles de Redaction
+
+| Pattern | Exemple | Redacted |
+|---------|---------|----------|
+| Password fields | `"password": "secret123"` | `"password": "***"` |
+| Bearer tokens | `Bearer abc123xyz` | `Bearer ***` |
+| API keys | `?api_key=abc123` | `?api_key=***` |
+| Secret references | `${{ secrets.API_KEY }}` | `${{ secrets.*** }}` |
+| GitHub tokens | `ghp_abc123...` | `ghp_***` |
+| JWT tokens | `eyJ...` | `eyJ***` |
+
+### Permissions Fichiers
+
+```bash
+# Permissions automatiques
+.qa360/secrets.enc → 600 (rw-------)
+.qa360/keys/       → 700 (rwx------)
+
+# Vérification
+ls -la .qa360/
+# -rw------- secrets.enc
+# drwx------ keys/
+```
+
+## 🔄 Flux de Travail
+
+### Développement Local
+
+```bash
+# 1. Configuration initiale
+qa360 secrets add API_TOKEN
+qa360 secrets add DATABASE_URL
+
+# 2. Création pack avec références
+cat > .qa360/pack.yml << EOF
+version: 1
+name: my-app-tests
+gates: ["api_smoke"]
+environment:
+  API_KEY: "\${{ secrets.API_TOKEN }}"
+  DB_URL: "\${{ secrets.DATABASE_URL }}"
+EOF
+
+# 3. Validation
+qa360 pack validate
+
+# 4. Exécution
+qa360 run
+# → Secrets interpolés automatiquement
+# → Jamais visibles dans logs
+```
+
+### CI/CD Pipeline
+
+```yaml
+# GitHub Actions
+- name: Setup QA360 Secrets
+  env:
+    QA360_SECRETS_PASSWORD: ${{ secrets.QA360_MASTER_KEY }}
+  run: |
+    echo "${{ secrets.API_TOKEN }}" | qa360 secrets add API_TOKEN
+    echo "${{ secrets.DATABASE_URL }}" | qa360 secrets add DATABASE_URL
+
+- name: Run QA360 Tests
+  run: qa360 run
+```
+
+### Environnements Multiples
+
+```bash
+# Profils par environnement
+qa360 secrets add API_TOKEN_DEV
+qa360 secrets add API_TOKEN_STAGING  
+qa360 secrets add API_TOKEN_PROD
+
+# Pack avec profil conditionnel
+environment:
+  API_KEY: "${{ secrets.API_TOKEN_${ENVIRONMENT} }}"
+```
+
+## 🚨 Gestion d'Incidents
+
+### Secret Compromis
+
+```bash
+# 1. Rotation immédiate
+qa360 secrets remove API_TOKEN
+qa360 secrets add API_TOKEN  # Nouvelle valeur
+
+# 2. Vérification utilisation
+grep -r "API_TOKEN" .qa360/
+grep -r "secrets.API_TOKEN" .
+
+# 3. Audit logs (si activé)
+qa360 secrets doctor
+```
+
+### Perte Clé Maître
+
+```bash
+# 1. Sauvegarde impossible - secrets perdus
+# 2. Recréation complète
+rm .qa360/secrets.enc
+qa360 secrets add API_TOKEN  # Nouvelle clé générée
+
+# 3. Reconfiguration tous secrets
+qa360 secrets add DATABASE_URL
+qa360 secrets add STRIPE_KEY
+```
+
+### Corruption Fichier
+
+```bash
+# Diagnostic
+qa360 secrets doctor
+# → Erreur: "Failed to load secrets: Invalid password or corrupted store"
+
+# Solutions
+# 1. Restauration backup (si disponible)
+cp .qa360/secrets.enc.backup .qa360/secrets.enc
+
+# 2. Recréation (perte données)
+rm .qa360/secrets.enc
+qa360 secrets add API_TOKEN
+```
+
+## 🔧 Configuration Avancée
+
+### Variables d'Environnement
+
+```bash
+# Clé maître personnalisée
+export QA360_SECRETS_PASSWORD="my-custom-master-key"
+
+# Répertoire QA360 personnalisé
+export QA360_DIR="/custom/path/.qa360"
+
+# Mode debug (plus de logs)
+export QA360_DEBUG_SECRETS=true
+```
+
+### Intégration Vault Enterprise
+
+```bash
+# Script d'intégration Vault
+#!/bin/bash
+vault kv get -field=value secret/qa360/api-token | \
+  qa360 secrets add API_TOKEN
+
+vault kv get -field=value secret/qa360/database-url | \
+  qa360 secrets add DATABASE_URL
+```
+
+### Backup Automatique
+
+```bash
+# Script backup quotidien
+#!/bin/bash
+DATE=$(date +%Y%m%d)
+cp .qa360/secrets.enc ".qa360/secrets.enc.backup.$DATE"
+
+# Rétention 30 jours
+find .qa360/ -name "secrets.enc.backup.*" -mtime +30 -delete
+```
+
+## 📊 Métriques et Monitoring
+
+### Métriques Collectées
+
+- Nombre de secrets configurés
+- Fréquence d'accès aux secrets
+- Échecs de déchiffrement
+- Tentatives d'accès non autorisées
+
+### Alertes Recommandées
+
+```bash
+# Échec déchiffrement répété
+qa360 secrets doctor | grep -q "Failed to load secrets" && \
+  echo "ALERT: Secrets decryption failing"
+
+# Fichier secrets manquant
+[ ! -f .qa360/secrets.enc ] && \
+  echo "ALERT: Secrets file missing"
+
+# Permissions incorrectes
+[ "$(stat -c %a .qa360/secrets.enc)" != "600" ] && \
+  echo "ALERT: Secrets file permissions incorrect"
+```
+
+## 🏆 Bonnes Pratiques
+
+### Sécurité
+
+- ✅ **Rotation régulière** : Changez les secrets tous les 90 jours
+- ✅ **Principe du moindre privilège** : Un secret par service
+- ✅ **Audit trail** : Loggez les accès aux secrets
+- ✅ **Backup chiffré** : Sauvegardez `.qa360/secrets.enc`
+- ❌ **Jamais en VCS** : `.qa360/secrets.enc` dans `.gitignore`
+
+### Opérationnel
+
+- ✅ **Nommage cohérent** : `SERVICE_CREDENTIAL_TYPE` (ex: `API_TOKEN_PROD`)
+- ✅ **Documentation** : Documentez l'usage de chaque secret
+- ✅ **Monitoring** : Surveillez les échecs de déchiffrement
+- ✅ **Tests** : Validez les références avant déploiement
+
+### Développement
+
+- ✅ **Environnements séparés** : Secrets différents par environnement
+- ✅ **Validation locale** : `qa360 secrets doctor` avant commit
+- ✅ **CI/CD intégration** : Variables d'environnement pour clé maître
+- ✅ **Fallback gracieux** : Gestion d'erreur si secret manquant
+
+---
+
+**🔐 QA360 Secrets - Sécurité locale, chiffrement fort, intégration transparente pour des tests sécurisés et reproductibles.**