Opérations¶
Dernière mise à jour : 28 mai 2026
Cette page couvre les opérations quotidiennes d'AI-Bridge for Cisco UC — démarrage et arrêt du serveur, supervision, sauvegarde & restauration, mises à jour, rotation des clés, vérification d'intégrité et génération de bundle de support.
Démarrage & Arrêt¶
# Démarrer le service
docker compose up -d
# Arrêter le service
docker compose down
# Redémarrer le service
docker compose restart
# Vérifier le statut
docker compose ps
# Suivre les journaux
docker compose logs -f
# Reconstruire après une mise à jour
docker compose up -d --build
Docker inclut un contrôle de santé intégré qui surveille le container toutes les 30 secondes via HTTPS GET sur /health. Consultez l'état de santé avec :
Préservation des données
docker compose down supprime le container mais préserve toutes les données des volumes (secrets, clients, logs, sauvegardes). Utilisez docker compose down -v uniquement si vous souhaitez tout supprimer.
Séquence de Démarrage¶
À chaque démarrage, le serveur effectue automatiquement les étapes suivantes :
| Étape | Action |
|---|---|
| 1 | Charger et valider la configuration .env |
| 2 | Initialiser la journalisation structurée (app.log + audit.log) |
| 3 | Synchroniser les profils RBAC par défaut (profiles/_default/ → profiles/) |
| 4 | Exécuter la vérification d'intégrité du logiciel (manifest.json + manifest.sig) |
| 5 | Vérifier / générer le certificat TLS |
| 6 | Vérifier la paire de clés RSA — générer si absente |
| 7 | Synchroniser les clients (créer / mettre à jour / supprimer selon AUTH_CLIENTS) |
| 8 | Vérifier la licence (secrets/license.jwt) |
| 9 | Charger les modules produit (conditionnel selon le niveau de licence) |
| 10 | Démarrer les processus de surveillance en arrière-plan (Licence, Intégrité, Sauvegarde) |
| 11 | Démarrer le serveur ASGI (HTTPS) |
Arrêt propre
Le serveur gère SIGTERM (docker stop) et SIGINT. Tous les threads de surveillance en arrière-plan sont arrêtés proprement via les gestionnaires atexit avant que le processus ne se termine.
Supervision & Observabilité¶
Fichiers Journaux¶
| Fichier | Emplacement | Contenu |
|---|---|---|
app.log |
LOGGING_DIR (défaut ./logs/) |
Événements applicatifs : démarrage, chargement des modules, erreurs, informations |
audit.log |
LOGGING_DIR |
Piste d'audit de sécurité : tous les événements d'authentification, appels d'outils, opérations sur les identifiants |
Les deux fichiers utilisent le format JSON structuré — un objet JSON par ligne — pour une intégration facile dans des outils SIEM ou d'agrégation de journaux (Elastic, Splunk, Loki, etc.).
Rotation des journaux : déclenchée lorsque app.log ou audit.log dépasse LOGGING_ROTATE_SIZE octets (défaut ~5 Mo). Jusqu'à LOGGING_ROTATE_FILES archives compressées sont conservées à côté du fichier actif.
Sortie console : activée par défaut (LOGGING_CONSOLE_ENABLED=1). La sortie est colorisée par niveau de log pour une utilisation interactive.
Points de Terminaison de Santé & Statut¶
| Point de terminaison | Auth | Description |
|---|---|---|
GET /health |
Aucune | Sonde de vivacité — retourne ok. Sûr pour les vérifications d'équilibreur de charge. |
GET /status |
Bearer | JSON de statut complet du serveur |
La réponse /status inclut :
- Version du serveur et durée de fonctionnement
- État de la licence (
VALID/GRACE/EXPIRED/INVALID), niveau, date d'expiration, produits activés - État de la sauvegarde (horodatage et nom du fichier de la dernière sauvegarde)
- Nombre actuel d'adresses IP en liste noire (Fail2Ban)
- Modules produit chargés
- Nombre de clients actifs
# Example status check
curl -sk -H "Authorization: Bearer <token>" \
https://mcp.domain.com:8443/status | python -m json.tool
Métriques Prometheus¶
GET /metrics — aucune authentification requise. Expose les métriques au format texte Prometheus.
Métriques disponibles :
| Métrique | Description |
|---|---|
| Compteurs de requêtes | Par client, nom d'outil et statut |
| Compteurs d'échecs d'authentification | Total et par client |
| Compteurs de limitation de débit | Par client, produit et service |
| État des surveillances | État des surveillances de licence, intégrité, sauvegarde |
Intervalle de collecte
Un intervalle de collecte de 15 secondes est recommandé. Le point de terminaison /metrics est léger et n'effectue aucune requête vers Cisco UC.
Catégories d'Événements du Journal d'Audit¶
Chaque événement pertinent pour la sécurité est écrit dans audit.log en JSON structuré. Les événements sont organisés par catégorie :
| Catégorie | Ce qui est journalisé |
|---|---|
AUTH |
Succès/échec de connexion, token émis/révoqué, IP source, identité du client |
ACTIONS |
Chaque appel d'outil MCP — client, nom de l'outil, hôte cible, résultat, temps d'exécution |
RATE_LIMITED |
Violations de limitation de débit — par client, produit et service |
CREDENTIAL |
Opérations de stockage / mise à jour / suppression d'identifiants |
TRUSTED |
Décisions de confiance et de rejet des empreintes SSH |
WRITTEN / EXPORTED |
Événements de génération de rapports et d'export PDF |
SERVER |
Démarrage, arrêt, transitions d'état de la licence |
TRANSPORT |
Alertes TLS, en-têtes Host/Origin invalides, tentatives de rebinding DNS |
Intégrité du journal d'audit
audit.log est un journal structuré en ajout seul. Il n'est jamais modifié après l'écriture d'un événement. Traitez-le comme une piste d'audit immuable et transmettez-le à un SIEM pour une conservation à long terme.
Sauvegarde & Restauration¶
Modèle de Chiffrement des Sauvegardes¶
| Couche | Algorithme |
|---|---|
| Chiffrement de l'archive | AES-256-GCM (clé de session aléatoire) |
| Encapsulation de la clé de session | RSA-4096 OAEP (clé publique du serveur) |
| Vérification d'intégrité | Fichier sidecar SHA-512 |
Le serveur peut créer des sauvegardes en utilisant uniquement la clé publique. La restauration nécessite la clé privée RSA.
Déclencher une Sauvegarde¶
Il n'existe pas de commande de déclenchement manuel. Les sauvegardes s'exécutent automatiquement à l'intervalle configuré dans BACKUP_INTERVAL_HOURS (défaut : 168 heures). Pour déclencher plus tôt, vous pouvez :
- Redémarrer le serveur (une sauvegarde s'exécute à chaque démarrage de la surveillance), ou
- Réduire temporairement
BACKUP_INTERVAL_HOURSet redémarrer
Restauration — Extraction Sécurisée¶
Extraire et déchiffrer une sauvegarde sans toucher à l'installation en production. Le script écrit dans un dossier auto-généré restore_<backup_id>/ à la racine du projet — aucun drapeau --output n'est nécessaire :
docker compose exec ai-bridge python scripts/backup_restore.py \
--file backups/backup_202605_hostname_20260508_001207.tar.gz.enc \
--key secrets/rsa_private.pem
Inspectez le contenu extrait dans ./restore_202605_hostname_20260508_001207/ avant de décider de l'appliquer.
Restauration — En Place (--replace)¶
Remplacer les fichiers en production par le contenu de la sauvegarde. Laissez le conteneur en cours d'exécution — le script détecte le processus serveur, demande confirmation interactive, l'arrête, effectue l'extraction en place, puis vous redémarrez la stack :
docker compose exec ai-bridge python scripts/backup_restore.py \
--file backups/backup_202605_hostname_20260508_001207.tar.gz.enc \
--key secrets/rsa_private.pem \
--replace
docker compose up -d
Le script arrête le serveur avant d'écrire
Le mode --replace détecte le PID du serveur dans le conteneur, demande une confirmation interactive (yes), puis envoie SIGTERM avant d'extraire. N'exécutez pas docker compose down au préalable — la commande exec échouerait car le conteneur serait arrêté.
Restauration Après Rotation des Clés RSA¶
Si la sauvegarde a été créée avant une rotation de clés, utilisez la clé archivée :
docker compose exec ai-bridge python scripts/backup_restore.py \
--file backups/old_backup.enc \
--key secrets/rsa_private.pem.archived.20260512
Les clés archivées sont conservées dans secrets/ avec un suffixe .archived.YYYYMMDD après la rotation.
Mise à Jour¶
Présentation¶
Les paquets de mise à jour sont livrés sous forme d'archives .tar.gz signées. Le programme de mise à jour gère automatiquement la vérification de signature, le remplacement des fichiers, la fusion des clés .env et la sauvegarde préalable.
Lisez d'abord la sortie du test à blanc
Exécutez toujours --dry-run avant d'appliquer une mise à jour. Cela affiche toutes les actions sur les fichiers, les modifications de .env et les étapes post-mise à jour requises.
Procédure de Mise à Jour Étape par Étape¶
Étape 1 — Vérifier l'intégrité du paquet
Avant l'installation, vérifiez l'archive en utilisant la somme de contrôle SHA-512 publiée dans le DNS :
# 1. Query the DNS TXT record published by the editor (uses a computer with public DNS resolution)
dig ai-bridge-for-cisco-uc-<version>.sha512.check.consulting.sourdeau.com txt +short
# 2. Compute the SHA-512 hash of the downloaded archive
sha512sum ai-bridge-for-cisco-uc-<version>.tar.gz
# 3. Compare both values — they must match exactly
# 1. Query the DNS TXT record published by the editor (uses a computer with public DNS resolution)
nslookup -q=txt ai-bridge-for-cisco-uc-<version>.sha512.check.consulting.sourdeau.com
# 2. Compute the SHA-512 hash of the downloaded archive
Get-FileHash -Algorithm SHA512 ai-bridge-for-cisco-uc-<version>.tar.gz
# 3. Compare both values — they must match exactly
Ne sautez pas cette étape
Si les valeurs ne correspondent pas, n'allez pas plus loin. Contactez contact@sourdeau.com immédiatement.
Étape 2 — Placer les fichiers dans le répertoire upgrade/
cp ai-bridge-for-cisco-uc-<version>.tar.gz upgrade/
tar -xzf upgrade/ai-bridge-for-cisco-uc-<version>.tar.gz \
ai-bridge-for-cisco-uc-<version>.py -C upgrade/
Étape 3 — Aperçu (test à blanc)
Le rapport de test à blanc affiche :
- Nouvelles fonctionnalités et journal des modifications
- Actions sur les fichiers : remplacés / créés / inchangés
- Modifications de
.env: nouvelles clés ajoutées, clés toujours mises à jour, clés préservées - Actions post-mise à jour requises
Étape 4 — Arrêter le conteneur
Étape 5 — Appliquer la mise à jour
Le programme effectue ces étapes dans l'ordre :
- Vérifie la signature RSA-PSS du paquet de mise à jour
- Extrait et valide le manifeste du paquet
- Vérifie la version (les rétrogradations sont bloquées)
- Crée une sauvegarde chiffrée préalable à la mise à jour
- Applique les modifications de fichiers
- Fusionne les clés
.env
Étape 6 — Reconstruire et redémarrer
Comportement de Fusion des Clés .env¶
| Catégorie de clé | Comportement |
|---|---|
| Nouvelles clés | Ajoutées avec des valeurs par défaut, annotées # ADDED by upgrade vXXXXXX |
| Toujours mises à jour | PROJECT_VERSION, PROJECT_NAME, PROJECT_CREATOR — toujours écrasées |
| Clés client existantes | Jamais écrasées — toujours préservées exactement telles que configurées |
Votre configuration est en sécurité
Le programme de mise à jour n'écrase jamais les clés configurées par le client. Vos identifiants de cluster, définitions de clients et paramètres personnalisés survivent à chaque mise à jour.
Options de Ligne de Commande de la Mise à Jour¶
| Option | Description |
|---|---|
--dry-run |
Prévisualiser toutes les modifications sans rien appliquer |
--no-backup |
Ignorer la sauvegarde automatique préalable (non recommandé) |
Rotation des Clés RSA¶
Quand Effectuer une Rotation¶
- Périodiquement en tant que bonne pratique de sécurité (ex. annuellement)
- Immédiatement après une suspicion de compromission de clé
Procédure de Rotation¶
# Arrêter le conteneur
docker compose down
# Exécuter le script de rotation des clés
docker compose run --rm ai-bridge python scripts/rotate_rsa_keys.py
# Archive les clés actuelles dans : secrets/rsa_private.pem.archived.YYYYMMDD
# Génère une nouvelle paire de clés RSA-4096
# Les clés archivées sont conservées pour déchiffrer les sauvegardes existantes
# Redémarrer le conteneur
docker compose up -d
# Au démarrage : tous les tokens JWT clients sont automatiquement régénérés
# Les nouveaux tokens sont écrits dans clients/<name>/secrets/.token
Impact de la Rotation des Clés¶
| Composant | Impact |
|---|---|
| Tokens JWT | Tous invalidés — nouveaux tokens auto-générés au prochain démarrage |
| Secrets client OAuth | Non affectés (basés sur bcrypt, non dépendants de RSA) |
| Sauvegardes chiffrées avant la rotation | Déchiffrables avec la clé archivée |
| Nouvelles sauvegardes | Chiffrées avec la nouvelle clé publique |
Redistribuez les tokens après la rotation
Après une rotation des clés, tous les utilisateurs d'agents AI doivent mettre à jour leur configuration avec les nouveaux tokens JWT présents dans clients/<name>/secrets/.token. Les anciens tokens sont définitivement invalides.
Vérification d'Intégrité du Logiciel¶
Chaque fichier du projet est couvert par un manifeste SHA-512 (manifest.json) signé avec RSA-PSS (RSA-4096), produisant manifest.sig.
Vérification Automatique¶
- Au démarrage : la vérification d'intégrité s'exécute avant le chargement de tout module
- Surveillance en arrière-plan : se réexécute toutes les 24 heures
Toute altération est journalisée dans app.log et audit.log avec une sévérité CRITICAL.
Vérification Manuelle¶
docker compose exec ai-bridge python -c "from lib.integrity import verify_integrity; print(verify_integrity())"
Si un fichier a été altéré, la sortie liste chaque fichier affecté ainsi que le hash attendu et le hash réel. Le serveur continue de fonctionner mais journalise une alerte d'intégrité critique.
Show Tech (Bundle de Support)¶
Le script show tech assemble un bundle de diagnostic pour les soumissions au support.
docker compose exec ai-bridge python scripts/show_tech.py
# Output: show_tech_<hostname>_<timestamp>.zip
Options :
| Option | Description |
|---|---|
--output <dir> |
Écrire le bundle dans un répertoire spécifique |
--no-logs |
Exclure les fichiers journaux du bundle |
--no-zip |
Produire un répertoire plutôt qu'une archive .zip |
Ce qui Est Inclus¶
| Élément | Inclus |
|---|---|
| Version du serveur, version Python, informations sur l'OS | Oui |
Configuration .env (identifiants et secrets masqués) |
Oui |
app.log et audit.log |
Oui (sauf --no-logs) |
| Résultat de la vérification du manifeste | Oui |
| État de la licence (sans le contenu du fichier de licence) | Oui |
| Liste des clients (noms uniquement) | Oui |
| Versions des dépendances Python | Oui |
Ce qui N'est Jamais Inclus¶
Les données sensibles ne sont jamais collectées
Le script show tech exclut explicitement les éléments suivants — ils ne sont jamais présents dans un bundle de support :
- Clés privées RSA
- Tokens JWT ou secrets client OAuth
- Archives de sauvegarde chiffrées
- Identifiants Cisco UC (mots de passe AXL, mots de passe SSH)
- Le fichier
secrets/license.jwt
Soumettre un Bundle¶
Envoyez le bundle à support@sourdeau.com avec une description du problème.