Installation & Configuration¶

Dernière mise à jour : 4 juin 2026

Cette page couvre tous les sujets de configuration d'AI-Bridge for Cisco UC — variables d'environnement, modes d'authentification, gestion des clients, profils RBAC, configuration TLS et paramètres de sauvegarde.

Le fichier `.env`¶

Toute la configuration d'exécution réside dans un seul fichier .env à la racine du projet. Il est créé automatiquement par l'assistant de configuration et conservé intact lors des mises à jour.

Protégez votre .env

Le fichier .env contient les chemins des clés RSA, les définitions des clients et d'autres valeurs sensibles pour la sécurité. Assurez-vous qu'il est lisible uniquement par le compte de service exécutant AI-Bridge (chmod 600 .env).

Un modèle commenté avec toutes les clés disponibles est fourni dans .env.example.

Seul .env est lu — les overrides os.environ ne sont pas pris en compte

Le serveur charge sa configuration exclusivement depuis le fichier .env à la racine du projet (via dotenv_values de python-dotenv). Les variables d'environnement exportées par le shell (p.ex. export AUTH_ISSUER=…) ou injectées par Docker (-e AUTH_ISSUER=…, bloc environment: dans docker-compose.yml) sont délibérément ignorées.

Justification : source de vérité unique, auditabilité totale (un seul fichier sur disque, couvert par le manifeste d'intégrité, les sauvegardes et les rapports show_tech), parité de redémarrage entre déploiement bare-metal et Docker. Pour redéfinir une valeur, éditez .env (ou templatez-le depuis votre CI/CD) — ne comptez jamais sur une injection via os.environ.

Référence des variables d'environnement¶

Métadonnées du projet¶

Ces clés identifient l'installation. Elles sont gérées automatiquement par le programme de mise à jour — ne les modifiez pas manuellement.

Clé	Description	Exemple
`PROJECT_NAME`	Identifiant interne	`ai-bridge-for-cisco-uc`
`PROJECT_CREATOR`	Éditeur	`Pierre SOURDEAU`
`PROJECT_VERSION`	Version de build `YYYYMM`	`202605`

Clés gérées automatiquement

PROJECT_NAME, PROJECT_CREATOR et PROJECT_VERSION sont écrasées automatiquement à chaque mise à jour. Toute modification manuelle sera perdue.

Serveur MCP¶

Clé	Description	Défaut
`MCP_SERVER_NAME`	Nom lisible affiché aux agents IA	`AI-Bridge for Cisco UC`
`MCP_SERVER_INSTRUCTIONS`	Description injectée dans le contexte de l'agent	`MCP SERVER for Cisco UC`
`MCP_SERVER_TRANSPORT`	Type de transport	`streamable-http`
`MCP_SERVER_HOST`	Adresse IP d'écoute dans le conteneur	`0.0.0.0`
`MCP_SERVER_PORT`	Port d'écoute HTTPS	`8443`
`MCP_SERVER_URL_PATH`	Chemin de l'endpoint MCP	`/mcp`

Déploiement Docker

MCP_SERVER_HOST doit rester à 0.0.0.0 pour que le port mapping Docker fonctionne. Le namespace réseau du conteneur est isolé — un bind sur une IP de l'hôte échouerait. Contrôlez l'accès externe avec votre pare-feu hôte et MCP_SERVER_SECURITY_ALLOWED_HOSTS.

Transport

streamable-http est actuellement le seul transport pris en charge. Le transport SSE n'est pas proposé (héritage).

Paramètres Docker¶

Clé	Description	Défaut
`UID`	UID de l'utilisateur hôte — le processus du conteneur s'exécute avec cet UID	`1000`
`GID`	GID de l'utilisateur hôte — le processus du conteneur s'exécute avec ce GID	`1000`

Exécutez id -u && id -g sur l'hôte Docker pour trouver vos valeurs. Elles doivent correspondre au propriétaire des répertoires de volumes montés (secrets/, clients/, logs/, etc.).

Authentification & Cryptographie¶

Clé	Description	Défaut
`AUTH_RSA_PUBLIC_KEY_FILE`	Chemin vers la clé publique RSA (PEM) — utilisée pour la vérification de signature JWT	`./secrets/rsa_public.pem`
`AUTH_RSA_PRIVATE_KEY_FILE`	Chemin vers la clé privée RSA (PEM) — utilisée pour la signature JWT et le déchiffrement des sauvegardes	`./secrets/rsa_private.pem`
`AUTH_ISSUER`	Valeur du claim émetteur JWT et URL de base du serveur d'autorisation OAuth 2.1 — doit être l'URL HTTPS publiquement accessible	`https://mcp.domain.com:8443`
`AUTH_AUDIENCE`	Valeur attendue du claim JWT `aud` — doit correspondre à la valeur configurée dans les clients agents IA	`mcp-clients`
`AUTH_CLIENTS`	Définitions des clients (voir la section Gestion des clients ci-dessous)	(doit être configuré)
`CRYPTO_SECRETS_DIR`	Répertoire pour les secrets générés automatiquement (tokens, clés, hachages bcrypt)	`./secrets/`
`AUTH_MODE`	Mode d'authentification global	`jwt`
`AUTH_RSA_KEY_SIZE`	Taille de la clé RSA en bits utilisée lors de la génération d'une nouvelle paire de clés	`4096`
`AUTH_TOKEN_EXPIRY_DAYS`	Durée de validité du token JWT en jours	`365`
`AUTH_OAUTH_TOKEN_EXPIRY_SECONDS`	Durée de validité du token d'accès OAuth 2.1 en secondes	`3600`
`AUTH_FAIL_LIMIT`	Nombre de tentatives d'authentification échouées avant le blocage de l'IP	`10`
`AUTH_FAIL_WINDOW_SECONDS`	Durée de la fenêtre glissante pour le comptage des échecs (secondes)	`300`
`AUTH_BLACKLIST_DURATION_SECONDS`	Durée de blocage de l'IP après dépassement de la limite d'échecs (secondes)	`900`
`AUTH_OAUTH_REDIRECT_URIS`	Dict JSON `{"client": ["uri", ...]}` — allowlist par client des `redirect_uri` OAuth 2.1 acceptés (wildcard `*` autorisé)	(vide — aucune whitelist)
`AUTH_OAUTH_REDIRECT_URI_ENFORCEMENT`	`off` (défaut, rétro-compatible) ou `strict` (recommandé en production — rejette tout `redirect_uri` inconnu)	`off`
`INTEGRITY_CHECK_INTERVAL_HOURS`	Intervalle entre deux balayages du manifeste d'intégrité par le watchdog	`24`
`BACKUP_SFTP_KNOWN_HOSTS`	Fichier OpenSSH `known_hosts` épinglant la hostkey du serveur SFTP (cf. Configuration de la sauvegarde plus bas)	`./secrets/sftp_known_hosts`

Valeurs valides pour AUTH_MODE : jwt / oauth2 / jwt+oauth2

Valeurs valides pour AUTH_RSA_KEY_SIZE : 2048 / 3072 / 4096

Journalisation¶

Clé	Description	Défaut
`LOGGING_LEVEL`	Niveau de verbosité des journaux	`info`
`LOGGING_DIR`	Répertoire des fichiers journaux	`./logs/`
`LOGGING_ROTATE_SIZE`	Taille maximale du fichier journal avant rotation (octets)	`5000000` (~5 Mo)
`LOGGING_ROTATE_FILES`	Nombre d'archives tournantes à conserver	`3`
`LOGGING_CONSOLE_ENABLED`	Activer la sortie console colorisée	`1`

Valeurs valides pour LOGGING_LEVEL : debug / info / warning / error / critical

Graphiques de rapport¶

Clé	Défaut
`REPORT_CHARTS_COLORS`	`PASS=#78F5AE,WARN=#FFBE54,FAIL=#FF6F61,INFO=#69C2FF,N/A=#BACCCC`

Serveur CUCM¶

Clé	Défaut
`SERVER_CUCM_AXL_PORT`	`8443`
`SERVER_CUCM_RIS_PORT`	`8443`
`SERVER_CUCM_SSH_PORT`	`22`
`SERVER_CUCM_SSH_TIMEOUT`	`30`
`SERVER_CUCM_ZEEP_TIMEOUT`	`30`
`SERVER_CUCM_AXL_SCHEMAS_DIR`	`./servers/cucm/axl-schemas/`
`SERVER_CUCM_RIS_SCHEMAS_DIR`	`./servers/cucm/ris-schemas/`
`SERVER_CUCM_AXL_WSDL_TIMEOUT`	`10`
`SERVER_CUCM_RIS_WSDL_TIMEOUT`	`15`
`SERVER_CUCM_SSH_TERM`	`dumb`
`SERVER_CUCM_SSH_TERM_WIDTH`	`220`
`SERVER_CUCM_SSH_TERM_HEIGHT`	`50`
`SERVER_CUCM_PHONE_SCREENSHOT_TIMEOUT`	`10`
`SERVER_CUCM_ZEEP_CACHE_MAX`	`64`
`SERVER_CUCM_WSDL_CACHE_MAX`	`32`
`SERVER_IMP_ZEEP_CACHE_MAX`	`64`
`SERVER_IMP_WSDL_CACHE_MAX`	`32`
`PROFILE_SCHEMA_STRICT`	`1`

Vérification SSL des téléphones

La vérification des certificats SSL est automatiquement désactivée pour les connexions web aux téléphones. Les certificats des téléphones IP Cisco (MIC/LSC) ne sont pas conformes à la validation X.509 stricte de Python 3.13+ : ils ne contiennent pas l'extension Authority Key Identifier (AKI) et utilisent un CN basé sur l'adresse MAC (ex: SEP001122334455) au lieu de l'adresse IP. La sécurité des connexions aux téléphones repose sur l'isolation VLAN, l'authentification HTTP Basic Auth, et l'obtention de l'IP depuis une source de confiance (CUCM RIS/AXL).

Serveur IMP¶

Clé	Défaut
`SERVER_IMP_AXL_PORT`	`8443`
`SERVER_IMP_SSH_PORT`	`22`
`SERVER_IMP_SSH_TIMEOUT`	`120`
`SERVER_IMP_ZEEP_TIMEOUT`	`30`
`SERVER_IMP_AXL_SCHEMAS_DIR`	`./servers/imp/axl-schemas/`
`SERVER_IMP_AXL_WSDL_TIMEOUT`	`10`
`SERVER_IMP_SSH_TERM`	`dumb`

Délai SSH IMP

Les sessions SSH IMP peuvent exécuter des diagnostics plus longs que CUCM. La valeur par défaut SERVER_IMP_SSH_TIMEOUT=120 est intentionnellement plus élevée.

Serveur CUC¶

Clé	Défaut
`SERVER_CUC_CUPI_PORT`	`8443`
`SERVER_CUC_CUPI_TIMEOUT`	`30`
`SERVER_CUC_SSH_PORT`	`22`
`SERVER_CUC_SSH_TIMEOUT`	`60`
`SERVER_CUC_SSH_TERM`	`dumb`
`SERVER_CUC_SSH_TERM_WIDTH`	`220`
`SERVER_CUC_SSH_TERM_HEIGHT`	`50`

Pas d'AXL / RIS / cluster sur CUC

CUC n'expose que CUPI (REST sur tcp/8443) et SSH (tcp/22). Il n'y a pas de toolkit AXL, pas de RIS et aucune notion de cluster — les informations d'identification et les opérations sont gérées par hôte.

Sécurité du transport¶

Clé	Description	Défaut
`MCP_SERVER_SECURITY_TRANSPORT_ENABLED`	Activer la protection contre le DNS rebinding	`1`
`MCP_SERVER_SECURITY_ALLOWED_HOSTS`	Valeurs autorisées de l'en-tête `Host`, séparées par virgule	`localhost:,127.0.0.1:,mcp.domain.com:*`
`MCP_SERVER_SECURITY_ALLOWED_ORIGINS`	Valeurs autorisées de l'en-tête `Origin`, séparées par virgule	`https://localhost:8443,https://127.0.0.1:8443,https://mcp.domain.com:8443`

Le joker * dans ALLOWED_HOSTS correspond à n'importe quel port sur ce nom d'hôte (p. ex., localhost:* autorise localhost:8443, localhost:4433, etc.).

Vérification SSL par produit¶

Le même schéma s'applique à CUCM, IMP et CUC :

CUCMIMPCUC

Clé	Description	Défaut
`SERVER_CUCM_SSL_VERIFY`	Vérifier le certificat TLS des nœuds CUCM	`True`
`SERVER_CUCM_SSL_CA_BUNDLE`	Chemin vers le bundle CA pour la vérification TLS CUCM (vide = CA système de confiance), ou bundle de certificats produit	(vide)

Clé	Description	Défaut
`SERVER_IMP_SSL_VERIFY`	Vérifier le certificat TLS des nœuds IMP	`True`
`SERVER_IMP_SSL_CA_BUNDLE`	Chemin vers le bundle CA pour la vérification TLS IMP (vide = CA système de confiance), ou bundle de certificats produit	(vide)

Clé	Description	Défaut
`SERVER_CUC_SSL_VERIFY`	Vérifier le certificat TLS des nœuds CUC (CUPI/REST)	`True`
`SERVER_CUC_SSL_CA_BUNDLE`	Chemin vers le bundle CA pour la vérification TLS CUC (vide = CA système de confiance), ou bundle de certificats produit	(vide)

CA personnalisée pour les connexions Cisco UC

Pour faire confiance à une CA interne pour les connexions AXL/CUPI/HTTPS sortantes vers les nœuds Cisco UC, spécifiez le chemin du bundle CA dans SERVER_CUCM_SSL_CA_BUNDLE / SERVER_IMP_SSL_CA_BUNDLE / SERVER_CUC_SSL_CA_BUNDLE. Les fichiers placés dans certs-trust-store/ ne sont pas appliqués automatiquement à ces connexions.

Configuration des sauvegardes¶

Clé	Description	Défaut
`BACKUP_ENABLED`	Activer les sauvegardes planifiées (`0` / `1`)	`0`
`BACKUP_DIR`	Répertoire local de sauvegarde	`./backups/`
`BACKUP_EXCLUDE_DIRS`	Répertoires exclus de l'archive (séparés par virgules)	`./backups/,./.git/,./__pycache__/`
`BACKUP_RETENTION`	Nombre d'archives locales à conserver	`4`
`BACKUP_INTERVAL_HOURS`	Intervalle de sauvegarde (heures)	`168`
`BACKUP_SFTP_HOST`	FQDN ou IP du serveur SFTP (optionnel)	(vide)
`BACKUP_SFTP_PORT`	Port TCP du serveur SFTP	`22`
`BACKUP_SFTP_USER`	Nom d'utilisateur SFTP (optionnel)	(vide)
`BACKUP_SFTP_AUTH`	Méthode d'authentification SFTP : `key` ou `password`	`key`
`BACKUP_SFTP_KEY_FILE`	Chemin de la clé privée SSH (si `BACKUP_SFTP_AUTH=key`)	`./secrets/backup_ssh_key`
`BACKUP_SFTP_KNOWN_HOSTS`	Fichier OpenSSH `known_hosts` utilisé pour vérifier la hostkey SFTP	`./secrets/sftp_known_hosts`
`BACKUP_SFTP_PASSWORD_ENC`	Mot de passe SFTP chiffré (généré par `encrypt_sftp_password.py`)	(vide)
`BACKUP_SFTP_REMOTE_PATH`	Répertoire distant pour les transferts SFTP	`/backups/ai-bridge/`
`BACKUP_SFTP_RETENTION`	Nombre d'archives distantes à conserver	`52`

!!! "Vérification de la hostkey SFTP obligatoire" Avant le tout premier transfert SFTP, renseignez BACKUP_SFTP_KNOWN_HOSTS avec la hostkey de confiance du serveur distant. Si le fichier est absent ou ne contient pas d'entrée pour l'hôte, le transfert est immédiatement abandonné — aucun identifiant n'est envoyé à un serveur non vérifié (protection anti-MITM).

```bash
# Emplacement par défaut : ./secrets/sftp_known_hosts
ssh-keyscan -p 22 sftp.example.com >> ./secrets/sftp_known_hosts
# Port non standard : l'entrée est stockée sous la forme "[host]:port"
ssh-keyscan -p 2222 sftp.example.com >> ./secrets/sftp_known_hosts
```

**Vérifiez l'empreinte hors bande** (appel à l'admin SFTP, wiki interne, etc.) avant de faire confiance au fichier. Le format est le format standard OpenSSH `known_hosts`.

Chiffrement du mot de passe SFTP

Lors de l'utilisation de BACKUP_SFTP_AUTH=password, le mot de passe doit être chiffré avant d'être stocké dans .env. Utilisez le script dédié :

python scripts/encrypt_sftp_password.py

Le token généré est automatiquement copié dans .env sous la clé BACKUP_SFTP_PASSWORD_ENC. Il n'est jamais stocké en clair. Voir la page Operations pour les détails.

Modes d'authentification¶

Mode JWT (par défaut)¶

JWT est le mode de déploiement le plus simple. Les tokens sont pré-générés au démarrage et stockés sur disque.

Fonctionnement :

Un JWT RS256 signé est généré pour chaque client au démarrage
Les tokens sont écrits dans clients/<name>/secrets/.token
La durée de vie des tokens est contrôlée par AUTH_TOKEN_EXPIRY_DAYS (défaut : 365 jours)
Les tokens sont automatiquement renouvelés au démarrage lorsqu'ils sont : absents, corrompus, à signature invalide, avec des claims modifiés ou un sujet modifié

Structure des claims JWT :

Claim	Description
`sub`	Sujet du client (issu de `AUTH_CLIENTS`)
`iss`	Émetteur (`AUTH_ISSUER`)
`aud`	Audience (`AUTH_AUDIENCE`)
`iat`	Horodatage d'émission
`exp`	Horodatage d'expiration
`jti`	Identifiant unique du token (révocation)
`client_id`	Nom du client

Révoquer un token JWT :

curl -sk -X POST https://mcp.domain.com:8443/revoke \
  -H "Authorization: Bearer <token>"

Mode OAuth 2.1¶

OAuth 2.1 utilise des tokens dynamiques à courte durée de vie, mieux adaptés aux pipelines automatisés et aux environnements avec des exigences strictes en matière de sécurité des identifiants.

Fonctionnement :

Deux types de flux sont pris en charge :
- authorization_code + PKCE (RFC 7636) — pour les clients interactifs tels que les IDE IA (OpenCode, Claude Desktop). Le client ouvre une page de connexion dans le navigateur, l'utilisateur s'authentifie et un token à courte durée de vie est émis automatiquement.
- client_credentials (RFC 6749 §4.4) — pour les clients M2M sans interface graphique utilisant curl ou des scripts.
La durée de vie des tokens est contrôlée par AUTH_OAUTH_TOKEN_EXPIRY_SECONDS (défaut : 3600 s)
client_id = nom du client ; client_secret est stocké sous forme de hachage bcrypt dans .secret_hash
Le fichier .secret en clair est automatiquement supprimé après la première authentification réussie
Révocation de token : POST /revoke (RFC 7009)
Métadonnées du serveur d'autorisation : GET /.well-known/oauth-authorization-server (RFC 8414)
Métadonnées de la ressource protégée : GET /.well-known/oauth-protected-resource (RFC 9728) — requis par les clients conformes MCP 2025-03-26

Flux de connexion interactif (IDE IA — authorization_code + PKCE) :

Lorsqu'un client MCP conforme (OpenCode, etc.) se connecte à l'endpoint MCP, il effectue automatiquement :

Détection de la réponse 401 et découverte OAuth
Ouverture de la page de connexion AI Bridge dans votre navigateur (GET /authorize)
Saisie de votre client_id et client_secret
Redirection du navigateur vers le client avec un code d'autorisation
Échange du code contre un token Bearer par le client (POST /token)

Aucune étape manuelle n'est requise après la configuration initiale.

Demande de token M2M (flux client_credentials) :

curl -sk -X POST https://mcp.domain.com:8443/token \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=client_credentials"

Secret à usage unique

Le fichier .secret en clair est un identifiant à usage unique. Copiez-le avant la première authentification du client — il sera supprimé automatiquement à la première utilisation. Seul le hachage bcrypt (.secret_hash) est conservé.

Mode hybride JWT + OAuth 2.1¶

Définir AUTH_MODE=jwt+oauth2 active les deux modes simultanément. Chaque client déclare indépendamment son propre mode d'authentification en tant que 4e champ dans AUTH_CLIENTS.

AUTH_CLIENTS='alice:sub-alice:admin:jwt,bob:sub-bob:operator:oauth2'

Cela permet des environnements mixtes où certains clients utilisent des tokens JWT statiques (p. ex., agents IA interactifs) tandis que d'autres utilisent des tokens OAuth dynamiques (p. ex., pipelines automatisés).

Gestion des clients¶

Syntaxe de `AUTH_CLIENTS`¶

Clé	Description	Défaut
`CLIENTS_DIR`	Répertoire de base pour les données clients	`./clients/`

# Mode JWT ou OAuth 2.1 (3 champs)
AUTH_CLIENTS='name:subject:profile'

# Mode hybride (4 champs — valide uniquement si AUTH_MODE=jwt+oauth2)
AUTH_CLIENTS='name:subject:profile:auth_mode'

# Plusieurs clients (séparés par virgule)
AUTH_CLIENTS='alice:sub-alice:admin:jwt,bob:sub-bob:operator:oauth2,carol:sub-carol:auditor:jwt+oauth2'

Définition des champs :

Champ	Règles
`name`	Identifiant unique ; utilisé comme nom de répertoire client. Alphanumérique + tirets.
`subject`	Claim JWT `sub`. Format recommandé : `sub-<name>-YYYYMMDD`. Immuable une fois les tokens distribués — toute modification invalide tous les tokens émis.
`profile`	Nom du profil RBAC. Doit correspondre à un fichier `.json` dans `profiles/`.
`auth_mode`	`jwt` / `oauth2` / `jwt+oauth2`. Valide uniquement en mode global hybride.

Immuabilité du sujet

Le champ subject est intégré dans chaque token JWT émis. Modifier le sujet d'un client invalide tous les tokens précédemment émis et force une nouvelle émission. Planifiez soigneusement les valeurs de sujet avant de distribuer des tokens.

Structure du répertoire client¶

Chaque client obtient un répertoire dédié sous CLIENTS_DIR :

clients/<name>/
├── secrets/
│   ├── .uuid           # UUID stable utilisé pour la dérivation de clé de chiffrement des identifiants
│   ├── .token          # Token Bearer JWT (mode jwt)
│   ├── .secret         # Secret client OAuth — en clair, usage unique
│   ├── .secret_hash    # Secret client OAuth — hachage bcrypt (permanent)
│   └── ...
├── reports/            # Rapports Markdown et exports PDF
└── custom/
    └── logo.png        # Logo personnalisé intégré dans les rapports PDF

Cycle de vie du client au démarrage¶

À chaque démarrage, le serveur synchronise le répertoire clients/ avec AUTH_CLIENTS :

Condition	Action
Client dans `AUTH_CLIENTS` mais sans répertoire	Répertoire créé, identifiants générés
Client existant, token valide	Aucune action
Client existant, token invalide (expiré, mauvaise signature, claims modifiés)	Token renouvelé automatiquement
Client dans le répertoire mais absent de `AUTH_CLIENTS`	Répertoire supprimé définitivement

Suppression automatique

Retirer un client de AUTH_CLIENTS et redémarrer le serveur supprime définitivement le répertoire du client, y compris tous les rapports et identifiants. Exportez toutes les données nécessaires avant de supprimer un client.

Profils RBAC¶

Profils prédéfinis¶

Trois profils sont livrés dans le répertoire profiles/_default/ :

Profil	Périmètre produit	Opérations AXL	Accès SSH	Accès RIS	Téléphone	Accès CUPI (CUC)	Limites de débit (req/min)
`admin`	Tous	Tous les préfixes + SQL Update	Toutes les commandes	Toutes les classes	Capture d'écran	Tous les verbes (`GET`/`POST`/`PUT`/`DELETE`)	60 / 5 / 20 / 10 / 60
`operator`	cucm, imp, cuc	get, list + écriture téléphone + SQLQuery	`show` uniquement	Téléphones uniquement	Capture d'écran	`GET` + `PUT` ciblés (users, callhandlers)	30 / 5 / 20 / 10 / 30
`auditor`	cucm, imp, cuc	get, list + SQLQuery	`show` + utilitaires d'audit	Toutes les classes	Capture d'écran	`GET /vmrest/` uniquement (lecture seule)	30 / 5 / 20 / 5 / 30

Colonnes de limites de débit

Les colonnes de limites de débit représentent : AXL / SSH / RIS / Téléphone / Common (rapport) requêtes par minute, par client.

Synchronisation des profils par défaut

Au démarrage, les trois profils par défaut sont automatiquement copiés depuis profiles/_default/ vers profiles/. Cela garantit qu'ils restent à jour après une mise à jour. Les profils personnalisés créés dans profiles/ ne sont jamais écrasés.

Structure JSON d'un profil personnalisé¶

Créez un fichier .json dans profiles/ avec la structure suivante :

{
  "description": "Profile description",
  "product_scope": ["cucm", "imp", "all"],
  "cucm": {
    "axl": {
      "rate_limit": 30,
      "allowed_prefixes": ["get", "list"],
      "allowed_exact": ["executeSQLQuery"]
    },
    "ris": {
      "rate_limit": 10,
      "allowed_device_classes": ["Phone"],
      "allowed_statuses": ["Any"]
    },
    "ssh": {
      "rate_limit": 20,
      "allowed_prefixes": ["show"]
    }
  },
  "imp": {
    "axl": { "rate_limit": 30, "allowed_prefixes": ["get", "list"] },
    "ssh": { "rate_limit": 20, "allowed_prefixes": ["show"] }
  },
  "cuc": {
    "cupi": {
      "rate_limit": 30,
      "allowed_prefixes": ["GET /vmrest/", "PUT /vmrest/users"]
    },
    "ssh": {
      "rate_limit": 5,
      "allowed_prefixes": ["show"]
    }
  },
  "common": {
    "report": { "rate_limit": 30 }
  }
}

Règles de correspondance :

Portée	Règle	Exemple
Préfixe AXL	Toute opération commençant par le préfixe est autorisée	`list` → autorise `listPhone`, `listLine`, `listUser`, …
Exact AXL	Correspondance exacte du nom d'opération uniquement	`executeSQLQuery` → autorise uniquement cet appel exact
Préfixe SSH	La commande doit être égale au préfixe ou commencer par `<prefix>` (séparation par espace)	`show` → autorise `show version`, `show interface`, …
Filtres RIS	`allowed_device_classes` et `allowed_statuses` sont optionnels ; si absents, aucun filtre n'est appliqué	`["Phone"]` → restreint aux enregistrements de téléphones
Préfixe CUPI	Appels CUPI autorisés — correspondance par préfixe complet `<METHODE> <chemin>` (CUC uniquement)	`GET /vmrest/` → autorise tout GET sous `/vmrest/`

Omission de la section SSH

Si la section ssh est absente d'un produit dans le profil, l'accès SSH est refusé pour ce produit.

Déployer un profil personnalisé :

Créer profiles/my_profile.json
L'assigner dans AUTH_CLIENTS : name:subject:my_profile
Les profils sont rechargés à chaud lors d'une modification de fichier — aucun redémarrage du serveur n'est nécessaire

TLS & Sécurité du transport¶

Certificat auto-signé (par défaut)¶

Au premier démarrage, si aucun certificat signé par une CA n'est déjà déployé (TLS_CA_SIGNED_CERT_FILE / TLS_CA_SIGNED_KEY_FILE), AI-Bridge génère automatiquement un certificat TLS auto-signé avec des entrées SAN dérivées de MCP_SERVER_SECURITY_ALLOWED_HOSTS. Le certificat est stocké dans secrets/server.crt et secrets/server.key.

Renouvellement en cours de vie : le certificat est automatiquement renouvelé lorsque moins de 50 % de sa période de validité reste.

Certificat signé par une CA¶

Pour remplacer le certificat auto-signé par un certificat émis par une CA :

# Placez votre certificat et votre clé privée :
secrets/server.crt   # Certificat encodé PEM (incluez la chaîne complète)
secrets/server.key   # Clé privée encodée PEM

Si les deux fichiers existent au démarrage, le serveur les utilise à la place du certificat auto-généré.

Recommandé en production

L'utilisation d'un certificat signé par une CA élimine les avertissements de confiance TLS sur les clients agents IA et est fortement recommandée pour tout déploiement en production.

Paramètres de sécurité du transport¶

Clé	Description	Exemple / Défaut
`MCP_SERVER_SECURITY_TRANSPORT_ENABLED`	Activer la protection contre le DNS rebinding (valide les en-têtes `Host` et `Origin`)	`1`
`MCP_SERVER_SECURITY_ALLOWED_HOSTS`	Valeurs autorisées de l'en-tête `Host`, séparées par virgule. Supporte `*` comme joker de port	`mcp.domain.com:8443,localhost:*`
`MCP_SERVER_SECURITY_ALLOWED_ORIGINS`	Valeurs autorisées de l'en-tête `Origin`, séparées par virgule	`https://mcp.domain.com:8443`

Protection contre le DNS rebinding

Définir MCP_SERVER_SECURITY_TRANSPORT_ENABLED=0 désactive la validation des en-têtes Host/Origin. Ne désactivez cela que dans des environnements réseau totalement isolés où les attaques de DNS rebinding ne sont pas une préoccupation.

Configuration des sauvegardes¶

Modèle de chiffrement¶

Les sauvegardes AI-Bridge utilisent un chiffrement hybride :

Une clé de session AES-256-GCM aléatoire chiffre l'archive de sauvegarde
La clé de session est encapsulée avec RSA-4096 OAEP à l'aide de la clé publique du serveur
Un fichier annexe SHA-512 garantit l'intégrité avant la restauration

Cela signifie que les sauvegardes peuvent être créées par tout processus ayant accès à la clé publique, mais le déchiffrement nécessite la clé privée RSA.

Activer les sauvegardes¶

BACKUP_ENABLED=1
BACKUP_DIR=./backups/
BACKUP_RETENTION=4
BACKUP_INTERVAL_HOURS=168

Export SFTP (optionnel)¶

Transférez automatiquement les sauvegardes vers un serveur SFTP distant après chaque sauvegarde locale :

BACKUP_SFTP_HOST=sftp.domain.com
BACKUP_SFTP_PORT=22
BACKUP_SFTP_USER=aibridge
BACKUP_SFTP_AUTH=key          # ou : password
BACKUP_SFTP_KEY_FILE=./secrets/backup_ssh_key
BACKUP_SFTP_KNOWN_HOSTS=./secrets/sftp_known_hosts
BACKUP_SFTP_REMOTE_PATH=/backups/ai-bridge/
BACKUP_SFTP_RETENTION=52

Faire d'abord confiance à la hostkey SFTP

La toute première étape consiste à enregistrer la hostkey du serveur SFTP distant dans BACKUP_SFTP_KNOWN_HOSTS. Sans cette entrée, aucun transfert n'aura jamais lieu — le serveur abandonne avant d'envoyer le moindre identifiant (protection anti-MITM).

ssh-keyscan -p ${BACKUP_SFTP_PORT:-22} ${BACKUP_SFTP_HOST} >> ./secrets/sftp_known_hosts
chmod 600 ./secrets/sftp_known_hosts

Comparez l'empreinte affichée avec celle publiée par l'administrateur SFTP (hors bande) avant de conserver le fichier.

Authentification par clé SSHAuthentification par mot de passe

Placez la clé privée SSH dans secrets/backup_ssh_key (ou redéfinissez le chemin via BACKUP_SFTP_KEY_FILE). La clé publique correspondante doit être autorisée sur le serveur SFTP.

BACKUP_SFTP_AUTH=key
BACKUP_SFTP_KEY_FILE=./secrets/backup_ssh_key

Définissez BACKUP_SFTP_AUTH=password. Le mot de passe doit être chiffré avant le stockage à l'aide de :

python scripts/encrypt_sftp_password.py

Le token généré est automatiquement copié dans .env sous la clé BACKUP_SFTP_PASSWORD_ENC. Il n'est jamais stocké en clair. Pour vérifier un token chiffré existant sans en générer un nouveau :

python scripts/encrypt_sftp_password.py --verify <token>

Voir la page Operations pour les détails.

BACKUP_SFTP_AUTH=password

Permissions de la clé SFTP

Le fichier de clé privée secrets/backup_ssh_key doit avoir les permissions chmod 600 et appartenir au compte de service.

Installation & Configuration¶

Le fichier .env¶

Référence des variables d'environnement¶

Métadonnées du projet¶

Serveur MCP¶

Paramètres Docker¶

Authentification & Cryptographie¶

Journalisation¶

Graphiques de rapport¶

Serveur CUCM¶

Serveur IMP¶

Serveur CUC¶

Sécurité du transport¶

Vérification SSL par produit¶

Configuration des sauvegardes¶

Modes d'authentification¶

Mode JWT (par défaut)¶

Mode OAuth 2.1¶

Mode hybride JWT + OAuth 2.1¶

Gestion des clients¶

Syntaxe de AUTH_CLIENTS¶

Structure du répertoire client¶

Cycle de vie du client au démarrage¶

Profils RBAC¶

Profils prédéfinis¶

Structure JSON d'un profil personnalisé¶

TLS & Sécurité du transport¶

Certificat auto-signé (par défaut)¶

Certificat signé par une CA¶

Paramètres de sécurité du transport¶

Configuration des sauvegardes¶

Modèle de chiffrement¶

Activer les sauvegardes¶

Export SFTP (optionnel)¶

Le fichier `.env`¶

Syntaxe de `AUTH_CLIENTS`¶