Aller au contenu

FAQ

Dernière mise à jour : 4 juin 2026

Questions fréquemment posées sur AI-Bridge for Cisco UC, organisées par thème.

Général

Qu'est-ce qu'AI-Bridge for Cisco UC ?

AI-Bridge for Cisco UC est un serveur MCP (Model Context Protocol) sur site qui fait le pont entre des agents IA — Claude Desktop, GitHub Copilot, Cursor, ou tout outil compatible MCP — et votre infrastructure Cisco Unified Communications.

Ce n'est pas un service cloud. Il s'exécute entièrement sur une VM Linux au sein de votre réseau, expose un point de terminaison MCP HTTPS sécurisé aux agents IA, et communique avec les nœuds Cisco UC via AXL, RIS et SSH. Aucune donnée ne quitte votre environnement via AI-Bridge.

Nécessite-t-il un accès à Internet ?

Non. AI-Bridge est entièrement capable de fonctionner en mode air gap. Il ne dispose d'aucune télémétrie, d'aucune dépendance au cloud, et d'aucun comportement de rappel vers l'extérieur. Toute la connectivité se fait strictement entre :

  • Votre client agent IA → AI-Bridge (HTTPS/MCP)
  • AI-Bridge → Vos nœuds Cisco UC (AXL/HTTPS, RIS/HTTPS, SSH)

Même la vérification de licence s'effectue hors ligne — le fichier de licence est un JWT signé, validé localement par rapport au nom d'hôte du serveur.

Quels agents IA sont compatibles ?

Tout agent prenant en charge le protocole de transport MCP Streamable HTTP. Par exemple :

  • Claude Desktop
  • VS Code avec l'extension MCP
  • Cursor
  • OpenCode
  • Des outils personnalisés basés sur un LLM utilisant le SDK MCP

AI-Bridge utilise le transport MCP Streamable HTTP standard — tout client conforme MCP fonctionnera.

Puis-je l'utiliser avec un LLM hébergé dans le cloud ?

Oui. Le LLM (OpenAI, Anthropic Claude API, etc.) et l'agent IA peuvent être entièrement hébergés dans le cloud. La seule connexion qui utilise votre réseau interne est l'appel MCP de l'agent vers AI-Bridge.

Il est important de noter qu'aucune donnée Cisco UC n'atteint directement le LLM cloud. L'agent IA reçoit les résultats des outils depuis AI-Bridge et les synthétise localement avant d'envoyer toute requête au LLM. Vous contrôlez précisément quels outils et données l'agent peut accéder via les profils RBAC.

Est-il compatible avec les LLM locaux ?

Oui. Associé à un LLM local (Ollama, LM Studio, llama.cpp, etc.) et à un agent IA fonctionnant localement, l'ensemble de la chaîne opère sans aucune connexion Internet. C'est idéal pour les environnements très réglementés où aucune donnée ne doit quitter le réseau interne.

Licence

Comment obtenir une licence ?

Contactez contact@sourdeau.com pour commander une licence. Une fois émise, vous recevrez un fichier license.jwt. Copiez-le dans secrets/license.jwt et redémarrez le serveur.

cp license.jwt secrets/license.jwt
docker compose restart
Que se passe-t-il à l'expiration de ma licence ?

L'expiration de la licence suit un modèle en deux phases :

  1. Période de grâce (par défaut : 30 jours après l'expiration) : le serveur continue de fonctionner normalement. Un rappel de renouvellement est journalisé au démarrage et émis sur le point de terminaison /status.
  2. Après la période de grâce : les modules produit sont désactivés. Les modules Infra et Common restent disponibles, vous pouvez donc toujours interroger l'état du serveur et gérer les rapports.

Anticipez

Surveillez l'expiration de votre licence via infra_get_license_info ou GET /status. Renouveler avant la fin de la période de grâce garantit une continuité de service sans interruption.

Puis-je utiliser la même licence sur un serveur différent ?

Non. Les licences sont liées au nom d'hôte — chaque licence est émise pour un nom d'hôte de serveur spécifique. Utiliser la même licence sur un nom d'hôte différent entraînera un état INVALID.

Contactez contact@sourdeau.com pour une réémission lors d'une migration vers un nouveau serveur.

La licence est-elle indépendante de la version ?

Oui. Une licence valide continue de fonctionner avec toutes les mises à jour logicielles — il n'y a pas de licence par version. Une fois émise, votre licence est valide jusqu'à sa date d'expiration, quel que soit le nombre de mises à jour effectuées.

Qu'est-ce qu'une licence de démonstration ?

Une licence à durée limitée à des fins d'évaluation. Elle donne accès à l'ensemble des modules produit pour une période d'essai fixe. Disponible sur demande à contact@sourdeau.com.

À quel attribut du serveur la licence est-elle liée ?

La licence est liée au nom d'hôte du serveur (hostname -f). Le nom d'hôte est intégré dans le JWT de licence au moment de l'émission et vérifié à chaque démarrage. Tout changement de nom d'hôte — renommage de VM, migration, mise à jour DNS — invalidera la licence.

Contactez contact@sourdeau.com pour une réémission en cas de changement de nom d'hôte.

Comment vérifier l'état actuel de la licence ?

Utilisez le script dédié :

python scripts/license_checker.py

Cela affiche l'état de la licence, le nom d'hôte lié, la date d'expiration, les produits licenciés, et l'état de la période de grâce — sans nécessiter que le serveur MCP soit en cours d'exécution.

Vous pouvez également utiliser l'outil MCP infra_get_license_info ou GET /status lorsque le serveur est en fonctionnement.

Installation & Configuration

Quelles distributions Linux sont prises en charge ?

AI-Bridge devrait fonctionner sur toute distribution Linux moderne prenant en charge Python 3.11+ et systemd. Les distributions suivantes sont activement testées et recommandées pour une utilisation en production :

Distribution Versions
Ubuntu LTS 22.04, 24.04
RHEL / AlmaLinux 9.x, 10.x
Debian 12, 13

Les autres distributions (Fedora, openSUSE, Arch, etc.) ne sont pas officiellement testées mais devraient fonctionner si les dépendances Python et système sont satisfaites.

Puis-je l'exécuter dans Docker ?

Oui. Le déploiement Docker est entièrement pris en charge. Consultez le guide Démarrage rapide pour les instructions d'installation Docker.

# Éditez .env — configurez AUTH_CLIENTS et les autres paramètres
docker compose up -d

Le déploiement Docker inclut un build multi-stage (Python 3.13), un utilisateur non-root (mcpadmin), un système de fichiers en lecture seule et des contrôles de santé. Toutes les données d'exécution sont persistées via des volumes bind-mount.

Puis-je exécuter plusieurs instances ?

Oui. Vous pouvez exécuter plusieurs instances AI-Bridge sur des hôtes Linux séparés, chacune avec sa propre licence liée au nom d'hôte. C'est l'approche recommandée pour séparer les environnements (par exemple, production vs. lab) ou servir plusieurs équipes avec des pistes d'audit isolées.

Que faire si la vérification de signature RSA-PSS échoue pendant l'installation ?

Ne poursuivez pas l'installation. Un échec de vérification de signature signifie soit :

  • L'archive a été corrompue pendant le téléchargement (relancez le téléchargement et vérifiez le SHA-512)
  • L'archive a été altérée

Contactez contact@sourdeau.com avant de poursuivre. N'exécutez jamais un logiciel dont le contrôle d'intégrité échoue.

Comment reconfigurer après l'installation ?

Éditez .env directement, puis recréez le conteneur :

nano .env
docker compose up -d
Comment changer le port d'écoute (ex. 8443 → 9443) ?

  1. Éditez .env et modifiez la valeur du port :

    MCP_SERVER_PORT=9443

  2. Si vous utilisez la sécurité du transport, mettez à jour les hôtes et origines autorisés pour refléter le nouveau port :

    MCP_SERVER_SECURITY_ALLOWED_HOSTS=localhost:*,127.0.0.1:*,mcp.domain.com:*
MCP_SERVER_SECURITY_ALLOWED_ORIGINS=https://localhost:9443,https://127.0.0.1:9443,https://mcp.domain.com:9443

  3. Recréez le conteneur (le port mapping est mis à jour automatiquement depuis .env) :

    docker compose up -d

  4. Mettez à jour l'URL du point de terminaison dans toutes les configurations d'agents IA pour utiliser le nouveau port.

  5. Le cas échéant, mettez à jour vos règles de pare-feu pour autoriser le nouveau port.

Tip

Le port mapping dans docker-compose.yml utilise ${MCP_SERVER_PORT:-8443} — il lit la valeur depuis .env automatiquement. Aucune modification de docker-compose.yml n'est nécessaire.

Comment désinstaller complètement AI-Bridge ?

Pour supprimer entièrement AI-Bridge d'un serveur, suivez ces étapes :

1. Arrêter et supprimer le conteneur :

docker compose down

2. Supprimer l'image Docker :

# Lister les images AI-Bridge
docker images | grep ai-bridge

# Supprimer l'image
docker rmi ai-bridge-for-cisco-uc:latest

# Supprimer les images résiduelles
docker image prune -f

3. Supprimer le répertoire d'installation :

rm -rf ~/ai-bridge

Après ces étapes, aucun artefact AI-Bridge ne subsiste sur le serveur.

Authentification & Clients

Combien de clients IA puis-je avoir simultanément ?

Le nombre de clients actifs est limité par le champ max_clients de votre licence. Chaque client est une entrée distincte dans AUTH_CLIENTS dans .env. Contactez contact@sourdeau.com si vous avez besoin d'augmenter votre limite de clients.

Comment ajouter un nouveau client ?

Ajoutez une entrée dans AUTH_CLIENTS dans .env et redémarrez le serveur :

AUTH_CLIENTS='alice:sub-alice:admin,bob:sub-bob:operator,carol:sub-carol:auditor'

Au prochain démarrage, un nouveau répertoire client est créé et les identifiants (jeton JWT ou secret OAuth) sont générés automatiquement. Distribuez le jeton depuis clients/<name>/secrets/.token au nouvel utilisateur.

Comment supprimer un client ?

Supprimez l'entrée du client dans AUTH_CLIENTS dans .env et redémarrez le serveur. Le répertoire du client — incluant tous les rapports, jetons et identifiants stockés — est purgé automatiquement.

Avertissement de perte de données

Exportez tous les rapports ou données que vous souhaitez conserver avant de supprimer une entrée client et de redémarrer.

Comment révoquer le jeton d'un client sans supprimer le client ?

Supprimez les fichiers d'identifiants du client et redémarrez le serveur — ils sont régénérés automatiquement :

rm clients/<name>/secrets/.secret
rm clients/<name>/secrets/.secret_hash
rm clients/<name>/secrets/.token
docker compose restart

Après le redémarrage, un nouveau jeton (mode JWT) ou un nouveau secret (mode OAuth) est généré automatiquement. Récupérez les nouvelles valeurs depuis clients/<name>/secrets/.token et .secret avant de les distribuer.

Note

Le point de terminaison POST /revoke est une alternative pour invalider uniquement le jeton sans redémarrage. La méthode fichiers-et-redémarrage est plus complète : elle force la régénération complète des identifiants.

Quelle est la différence entre le mode JWT et le mode OAuth 2.1 ?
Mode JWT Mode OAuth 2.1
Type de jeton Statique, longue durée de vie (par défaut : 365 jours) Dynamique, courte durée de vie (par défaut : 1 heure)
Émission Pré-généré au démarrage À la demande via POST /token
Secret client Aucun Haché avec bcrypt, texte en clair à usage unique
Idéal pour Agents IA interactifs (configuration simple) Pipelines automatisés, CI/CD, sécurité renforcée
Révocation POST /revoke POST /revoke

Les deux modes sont également sécurisés en termes de transport et de signature. OAuth 2.1 limite la fenêtre d'exposition en cas de compromission d'un jeton grâce à sa courte durée de vie.

Que se passe-t-il avec les jetons après une rotation de clé RSA ?

Tous les jetons JWT existants sont immédiatement invalidés — ils ont été signés avec l'ancienne clé privée et ne peuvent pas être vérifiés avec la nouvelle.

Au prochain démarrage, de nouveaux jetons sont automatiquement régénérés pour tous les clients et écrits dans clients/<name>/secrets/.token. Vous devez redistribuer les nouveaux jetons à tous les utilisateurs d'agents IA.

Les secrets clients OAuth (basés sur bcrypt) ne sont pas affectés par la rotation de clé.

Comment configurer le serveur MCP dans OpenCode avec une authentification OAuth ?

En mode OAuth 2.1, OpenCode gère nativement le flux d'authentification — aucun jeton bearer ne doit être codé en dur dans le fichier de configuration.

Éditez opencode.json et déclarez le serveur sans en-tête Authorization :

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cisco-uc-mcp-server": {
      "type": "remote",
      "url": "https://mcp.domain.com:8443/mcp/",
      "enabled": true
    }
  }
}

Avant de démarrer le client desktop OpenCode, exécutez la commande CLI suivante pour vous authentifier :

opencode mcp auth cisco-uc-mcp-server

OpenCode ouvre une page web où vous saisissez votre secret client pour finaliser l'authentification :

┌  MCP OAuth Authentication
│
▲  cisco-uc-mcp-server has expired credentials. Re-authenticating...
│
◇  Authentication successful!
│
└  Done

Tip

Le secret client est généré au premier démarrage et stocké dans clients/<name>/secrets/.secret. Récupérez-le avant la première authentification.

Produit Cisco CUCM

Quelles versions de CUCM sont prises en charge ?

CUCM 14 et 15 sont officiellement pris en charge. Les versions du schéma AXL sont gérées par cluster — téléchargez les schémas correspondant à votre version de CUCM avec cucm_download_axl_schemas.

Peut-il gérer plusieurs clusters CUCM ?

Oui. La prise en charge multi-cluster est intégrée. Chaque cluster possède son propre ensemble d'identifiants nommé, stocké séparément dans le magasin d'identifiants du client. Référencez les clusters par nom dans les opérations AXL, RIS et SSH.

Ai-je besoin d'un compte de service Cisco dédié ?

Techniquement, un seul compte partagé fonctionne. Cependant, la bonne pratique est de créer un compte nominatif par client (utilisateur) AI-Bridge. Cela permet :

  • Une piste d'audit par utilisateur dans les journaux CUCM
  • L'isolation des identifiants — un identifiant AI-Bridge compromis n'affecte qu'un seul utilisateur
  • Un contrôle d'accès granulaire aligné avec votre politique RBAC CUCM
Modifie-t-il automatiquement ma configuration CUCM ?

Uniquement si vous invoquez explicitement des opérations d'écriture via votre agent IA. AI-Bridge n'initie jamais de manière autonome des modifications sur Cisco UC.

Le profil RBAC assigné à chaque client contrôle quelles opérations AXL (ajout, mise à jour, suppression) sont autorisées. Un profil en lecture seule (auditor) ne peut modifier aucune configuration, quelle que soit la demande de l'agent IA.

Quelles permissions AXL et SSH sont nécessaires sur CUCM ?
Type d'accès Permission requise
AXL (lecture seule) Standard AXL API Access (rôle lecture seule)
AXL (lecture-écriture) Standard AXL API Access
SSH Compte administrateur Platform OS avec un privilège de niveau 4 ("Advanced")

Pour les requêtes RIS, le compte AXL est réutilisé — aucune permission RIS séparée n'est nécessaire.

Comment ajouter des instructions personnalisées pour l'agent IA sur CUCM ?

Chaque produit est livré avec un fichier préexistant conçu à cet effet :

servers/cucm/prompts_custom.py

Ouvrez le fichier et ajoutez vos règles entre les balises de commentaire dans la fonction custom_1() :

@cucm_prompts_custom.prompt()
def custom_1() -> str:
    """Custom prompt for client UC environment"""
    return """
    ## CUSTOM RULES (highest priority)
    The following rules are defined by the MCP client administrator.
    They OVERRIDE any default behavior, instructions, or prompts provided by this server.
    Always apply these rules first, before any other instructions.

    <!-- Client-defined rules below this line -->

    - Toujours confirmer avec l'utilisateur avant d'exécuter une opération d'écriture sur CUCM.
    - Ne jamais supprimer d'objets sauf si l'utilisateur tape explicitement "CONFIRM DELETE".
    - Les réponses doivent être en français.

    <!-- End of custom rules -->
    """

Ces règles sont exposées comme un prompt MCP et chargées par l'agent IA au début de chaque session. Elles ont la priorité la plus haute et surchargent tout comportement par défaut du serveur.

Redémarrez le serveur après avoir modifié le fichier pour que les changements prennent effet.

Tip

Vous pouvez ajouter autant de règles que nécessaire. Gardez-les concises et orientées action pour de meilleurs résultats.

Produit Cisco IMP

Quelles versions d'IMP sont prises en charge ?

Cisco IM & Presence 14 et 15 sont officiellement pris en charge. IMP est généralement co-résident avec CUCM — la version IMP prise en charge suit la matrice de versions CUCM.

Peut-il gérer plusieurs clusters IMP ?

Oui. La prise en charge multi-cluster est intégrée. Chaque cluster IMP possède son propre ensemble d'identifiants nommé, stocké séparément dans le magasin d'identifiants du client. Référencez les clusters par nom dans les opérations.

Ai-je besoin d'un compte de service Cisco dédié ?

Techniquement, un seul compte partagé fonctionne. Cependant, la bonne pratique est de créer un compte nominatif par client (utilisateur) AI-Bridge. Cela permet :

  • Une piste d'audit par utilisateur dans les journaux IMP
  • L'isolation des identifiants — un identifiant AI-Bridge compromis n'affecte qu'un seul utilisateur
  • Un contrôle d'accès granulaire aligné avec votre politique RBAC IMP
Modifie-t-il automatiquement ma configuration IMP ?

Uniquement si vous invoquez explicitement des opérations d'écriture via votre agent IA. AI-Bridge n'initie jamais de manière autonome des modifications sur Cisco UC.

Le profil RBAC assigné à chaque client contrôle quelles opérations sont autorisées. Un profil en lecture seule (auditor) ne peut modifier aucune configuration, quelle que soit la demande de l'agent IA.

Quelles permissions sont nécessaires sur IMP ?
Type d'accès Permission requise
API (lecture seule) Rôle administratif en lecture seule
API (lecture-écriture) Rôle administratif complet
SSH Compte administrateur Platform OS avec un privilège de niveau 4 ("Advanced")
Comment ajouter des instructions personnalisées pour l'agent IA sur IMP ?

Chaque produit est livré avec un fichier préexistant conçu à cet effet :

servers/imp/prompts_custom.py

Ouvrez le fichier et ajoutez vos règles entre les balises de commentaire dans la fonction custom_1() :

@imp_prompts_custom.prompt()
def custom_1() -> str:
    """Custom prompt for client IMP environment"""
    return """
    ## CUSTOM RULES (highest priority)
    The following rules are defined by the MCP client administrator.
    They OVERRIDE any default behavior, instructions, or prompts provided by this server.
    Always apply these rules first, before any other instructions.

    <!-- Client-defined rules below this line -->

    - Toujours confirmer avec l'utilisateur avant d'exécuter une opération d'écriture sur IMP.
    - Ne jamais supprimer d'objets sauf si l'utilisateur tape explicitement "CONFIRM DELETE".
    - Les réponses doivent être en français.

    <!-- End of custom rules -->
    """

Ces règles sont exposées comme un prompt MCP et chargées par l'agent IA au début de chaque session. Elles ont la priorité la plus haute et surchargent tout comportement par défaut du serveur.

Redémarrez le serveur après avoir modifié le fichier pour que les changements prennent effet.

Tip

Vous pouvez ajouter autant de règles que nécessaire. Gardez-les concises et orientées action pour de meilleurs résultats.

Produit Cisco CUC

Quelles versions de CUC sont prises en charge ?

Cisco Unity Connection 14 et 15 sont officiellement pris en charge. CUC expose son API de provisioning via CUPI (REST sur https://<host>:8443/vmrest/) — il n'y a aucun toolkit AXL/SOAP ni de schéma WSDL à télécharger.

Peut-il gérer plusieurs nœuds CUC ?

Oui. CUC n'a pas de notion de cluster dans AI-Bridge — les informations d'identification et les opérations sont gérées par hôte. Ajoutez autant d'hôtes CUC que nécessaire via cuc_store_credentials (CUPI) et cuc_os_store_credentials (SSH) ; chaque hôte est stocké séparément dans le magasin d'identifiants du client.

Ai-je besoin d'un compte de service Cisco dédié ?

Techniquement, un seul compte partagé fonctionne. Cependant, la bonne pratique est de créer un compte nominatif par client (utilisateur) AI-Bridge. Cela permet :

  • Une piste d'audit par utilisateur dans les journaux CUC
  • L'isolation des identifiants — un identifiant AI-Bridge compromis n'affecte qu'un seul utilisateur
  • Un contrôle d'accès granulaire aligné avec votre politique RBAC CUC
Modifie-t-il automatiquement ma configuration CUC ?

Uniquement si vous invoquez explicitement des opérations d'écriture via votre agent IA. AI-Bridge n'initie jamais de manière autonome des modifications sur Cisco UC.

Le profil RBAC assigné à chaque client contrôle quels verbes CUPI (POST / PUT / DELETE) et quels chemins /vmrest/ sont autorisés. Un profil en lecture seule (auditor) est restreint à GET /vmrest/ et ne peut modifier aucune configuration, quelle que soit la demande de l'agent IA.

Quelles permissions CUPI et SSH sont nécessaires sur CUC ?
Type d'accès Permission requise
CUPI (lecture seule) Compte administrateur Unity Connection avec le rôle "System Administrator"
CUPI (lecture-écriture) Compte administrateur Unity Connection avec un modèle de rôles couvrant les endpoints ciblés (users, call handlers, schedules, etc.)
SSH Compte administrateur Platform OS avec un privilège de niveau 4 ("Advanced")
Comment ajouter des instructions personnalisées pour l'agent IA sur CUC ?

Chaque produit est livré avec un fichier préexistant conçu à cet effet :

servers/cuc/prompts_custom.py

Ouvrez le fichier et ajoutez vos règles entre les balises de commentaire dans la fonction custom_1() :

@cuc_prompts_custom.prompt()
def custom_1() -> str:
    """Custom prompt for client CUC environment"""
    return """
    ## CUSTOM RULES (highest priority)
    The following rules are defined by the MCP client administrator.
    They OVERRIDE any default behavior, instructions, or prompts provided by this server.
    Always apply these rules first, before any other instructions.

    <!-- Client-defined rules below this line -->

    - Toujours confirmer avec l'utilisateur avant d'exécuter une opération d'écriture sur CUC.
    - Ne jamais supprimer d'objets sauf si l'utilisateur tape explicitement "CONFIRM DELETE".
    - Les réponses doivent être en français.

    <!-- End of custom rules -->
    """

Ces règles sont exposées comme un prompt MCP et chargées par l'agent IA au début de chaque session. Elles ont la priorité la plus haute et surchargent tout comportement par défaut du serveur.

Redémarrez le serveur après avoir modifié le fichier pour que les changements prennent effet.

Tip

Vous pouvez ajouter autant de règles que nécessaire. Gardez-les concises et orientées action pour de meilleurs résultats.

Sécurité

Où sont stockés les identifiants Cisco UC ?

Les identifiants sont chiffrés sur le disque, par client, à l'aide du chiffrement Fernet (AES-128-CBC + HMAC-SHA256). La clé Fernet est dérivée par client via PBKDF2-SHA512 avec 600 000 itérations, initialisée à partir d'un UUID stable unique à chaque client (clients/<name>/secrets/.uuid).

Les identifiants ne sont jamais stockés en clair dans .env, les journaux, ou tout autre fichier.

Le serveur peut-il lire ses propres sauvegardes ?

Non. Les sauvegardes sont chiffrées à l'aide de la clé publique RSA (RSA-4096 OAEP). Le serveur peut créer des sauvegardes sans la clé privée, mais le déchiffrement nécessite explicitement la clé privée RSA. C'est intentionnel — cela limite le rayon d'impact si le processus serveur est compromis.

Comment fonctionne le journal d'audit ?

Chaque événement d'authentification, appel d'outil, opération sur les identifiants et anomalie de sécurité est écrit dans audit.log sous forme d'objet JSON structuré. Le journal est en ajout seul — les entrées ne sont jamais modifiées après avoir été écrites.

La rotation des journaux crée des archives compressées, préservant l'historique complet. Pour la rétention à long terme et l'intégration SIEM, transférez audit.log vers votre infrastructure d'agrégation de journaux.

Que se passe-t-il si quelqu'un altère les fichiers du serveur ?

Le gardien d'intégrité exécute une vérification du manifeste SHA-512 sur tous les fichiers du projet au démarrage et toutes les 24 heures ensuite. Le manifeste est signé avec RSA-PSS (RSA-4096) et ne peut pas être falsifié sans la clé de signature de l'éditeur.

Si une altération est détectée au démarrage, le serveur refuse de démarrer et journalise les fichiers concernés au niveau CRITICAL dans app.log et audit.log.

Si une altération est détectée lors d'une vérification périodique (en cours d'exécution) :

  • Les fichiers concernés et les incohérences de hachage sont journalisés dans app.log et audit.log au niveau CRITICAL
  • L'échec d'intégrité est mis en évidence dans /status et les métriques Prometheus

Réagissez immédiatement aux échecs d'intégrité

Une alerte d'intégrité est un événement de sécurité grave. Isolez le serveur, examinez les fichiers concernés, et restaurez depuis une sauvegarde connue comme saine.

Comment signaler une vulnérabilité de sécurité ?

Envoyez un e-mail privé à security@sourdeau.com avec une description de la vulnérabilité. N'ouvrez pas une issue GitHub publique pour les découvertes de sécurité — la divulgation responsable protège tous les utilisateurs.

Vous recevrez un accusé de réception dans les 48 heures.

Dépannage

Les modules produit ne sont pas chargés — que dois-je vérifier ?

Vérifiez l'état de la licence avec l'outil infra_get_server_status ou GET /status. Causes courantes :

État Cause Résolution
INVALID secrets/license.jwt manquant, altéré, ou nom d'hôte non correspondant Vérifiez que le fichier existe et que le nom d'hôte du serveur correspond à la licence
EXPIRED Licence au-delà de la période de grâce Renouveler via contact@sourdeau.com
GRACE Dans la période de grâce Renouveler bientôt — modules toujours chargés

Si le serveur MCP ne démarre pas du tout, vérifiez la licence manuellement avec :

python scripts/license_checker.py

Cela s'exécute indépendamment du serveur et affiche l'état complet de la licence, le nom d'hôte lié, et les détails des erreurs.

Mon agent IA ne peut pas se connecter à AI-Bridge — que dois-je vérifier ?

Parcourez cette liste de contrôle dans l'ordre :

  1. URL et port du point de terminaison — vérifiez que l'agent est configuré avec la bonne URL (par exemple, https://mcp.domain.com:8443/mcp)
  2. Validité du jeton Bearer — confirmez que le jeton dans clients/<name>/secrets/.token correspond à celui utilisé par l'agent
  3. Confiance du certificat TLS — l'agent IA doit faire confiance au certificat TLS d'AI-Bridge. Soit faites confiance au certificat auto-signé dans le magasin de confiance de l'agent, soit remplacez-le par un certificat signé par une CA
  4. Réseau / pare-feu — confirmez que le port TCP 8443 est accessible depuis l'hôte de l'agent vers l'hôte AI-Bridge
L'authentification échoue avec HTTP 401 — quelles sont les causes possibles ?
Cause Résolution
Jeton expiré Récupérez un nouveau jeton depuis clients/<name>/secrets/.token (il est renouvelé après un redémarrage)
Jeton révoqué Le jeton a été explicitement révoqué via POST /revoke. Un nouveau jeton est généré au prochain démarrage.
Clé RSA tournée Tous les jetons JWT sont invalidés après une rotation de clé. Récupérez le nouveau jeton généré après la rotation.
Format de jeton incorrect Assurez-vous que l'en-tête Authorization utilise exactement le format Bearer <token>
Mon IP est bloquée et je reçois HTTP 429 — que dois-je faire ?

Le mécanisme Fail2Ban a bloqué votre IP après des échecs d'authentification répétés. La liste noire est en mémoire uniquement — elle n'est pas persistée dans un fichier et est automatiquement effacée au redémarrage du serveur.

Options :

  • Attendre que la durée de la liste noire expire (par défaut : 15 minutes, configurée dans AUTH_BLACKLIST_DURATION_SECONDS)
  • Redémarrer le serveur pour effacer immédiatement toutes les entrées de la liste noire (docker compose restart)

Pour voir quelles IP ont été bloquées et pourquoi, recherchez dans audit.log les événements AUTH_BLOCKED :

grep AUTH_BLOCKED logs/audit.log | tail -20

Après le déblocage, identifiez et résolvez la cause des échecs d'authentification avant de vous reconnecter.

La licence affiche INVALID — que dois-je vérifier ?

Vérifiez ces trois points dans l'ordre :

  1. Fichier présent — ls -la secrets/license.jwt — le fichier doit être présent et lisible
  2. Correspondance du nom d'hôte — le nom d'hôte du serveur (hostname -f) doit correspondre exactement au nom d'hôte dans la licence. Un renommage de VM ou une migration cassera cela.
  3. Intégrité du fichier — si le fichier a été transféré via un outil qui peut avoir modifié les fins de ligne ou l'encodage, re-transférez-le en mode binaire
La demande de jeton OAuth échoue avec 401 invalid_client — que s'est-il passé ?

La cause la plus courante : le fichier .secret en clair a été automatiquement supprimé après la première authentification réussie du client, et le .secret_hash ne correspond plus à ce qui est envoyé.

Pour régénérer les identifiants OAuth d'un client :

  1. Supprimez clients/<name>/secrets/.secret_hash
  2. Redémarrez le serveur — de nouveaux identifiants sont générés automatiquement
  3. Récupérez le nouveau secret en clair depuis clients/<name>/secrets/.secret avant la première utilisation
Mon client OpenCode ne peut pas se connecter (erreur ERR_TLS_CERT_ALTNAME_INVALID) — que dois-je vérifier ?

Cette erreur signifie que le certificat TLS présenté par le serveur ne contient pas le FQDN du serveur dans l'extension Subject Alternative Name (SAN).

Node.js v17+ (et tous les clients TLS modernes) exigent l'extension SAN — le champ CN seul n'est plus accepté pour la validation du nom d'hôte (RFC 6125).

Pour corriger cela, régénérez le certificat avec un SAN approprié à l'aide du générateur de CSR intégré (le serveur doit être en fonctionnement) :

docker compose exec ai-bridge python scripts/certificate_generate_csr.py

Faites ensuite signer la CSR générée par votre CA interne à l'aide de la commande openssl x509 affichée par le script, et redéployez le nouveau certificat. Assurez-vous que TLS_CA_SIGNED_CERT_FILE et TLS_CA_SIGNED_KEY_FILE dans .env pointent vers les nouveaux fichiers, puis redémarrez le serveur.

Tip

Si votre CA n'est pas approuvée par le runtime Node.js d'OpenCode, définissez également NODE_EXTRA_CA_CERTS=/path/to/ca.crt dans votre environnement (ou exportez-le depuis ~/.bashrc).