Aller au contenu

Sécurité et audit

Authentification

Le serveur MCP ne possède pas son propre système d’authentification : il lit l’en-tête Authorization reçu du client, en retire le préfixe Bearer éventuel, puis transmet la valeur telle quelle à canopsis-internal-api dans l’en-tête x-canopsis-authkey. C’est donc l’API Canopsis, avec son mécanisme habituel de validation d’authkey, qui reste seule source de vérité.

Concrètement, chaque appel de tool ou de resource doit porter :

Authorization: Bearer <authkey Canopsis>

Si aucun en-tête Authorization n’est présent, les tools mutables comme les tools de lecture échouent avec une erreur unauthorized.

Une authkey dédiée, à moindre privilège

Utilisez une authkey associée à un compte Canopsis créé spécifiquement pour l’usage MCP, avec uniquement les permissions nécessaires aux actions que vous souhaitez autoriser (par exemple : lecture seule, ou lecture + commentaire, sans forcément aller jusqu’à la création d’alarme). Ne réutilisez pas l’authkey d’un compte administrateur, et ne la committez jamais dans un dépôt de code ou un template partagé : préférez une variable d’environnement ou le mécanisme de secret propre à chaque client.

Autorisation

Chaque tool correspond à un point d’API Canopsis existant et n’ajoute aucun contournement : les permissions du compte propriétaire de l’authkey s’appliquent normalement. Un compte qui n’a pas le droit d’acquitter une alarme via l’API ne l’aura pas davantage via ack_alarm.

Un refus de permission côté API est traduit en erreur MCP forbidden, sans détail interne sensible.

Attribution des actions

Les actions réalisées via MCP restent attribuées à l’utilisateur propriétaire de l’authkey utilisée, exactement comme un appel direct à l’API. Pour distinguer ce trafic dans les journaux et les analyses ultérieures, le serveur ajoute des en-têtes dédiés à chaque appel qu’il transmet à canopsis-internal-api :

En-tête Contenu
X-Canopsis-Caller-Type Toujours mcp
X-Canopsis-Caller-Id Valeur de mcp.caller_id (configurable), identifiant l’intégration ou l’assistant à l’origine de l’appel
X-Canopsis-Mcp-Tool Nom du tool appelé (ack_alarm, search_alarms...)
X-Canopsis-Request-Id Identifiant de corrélation, généré par le serveur ou repris de l’en-tête X-Request-Id du client

Ces en-têtes servent à l’enrichissement des journaux et au filtrage lors d’une investigation ; ils n’interviennent à aucun moment dans la décision d’authentification ou d’autorisation.

Commutateur d’écriture (kill switch)

Le paramètre mcp.write_enabled (variable d’environnement CPS_MCP_WRITE_ENABLED) permet de désactiver globalement et immédiatement tous les tools de mutation :

  • create_alarm, ack_alarm, comment_alarm, snooze_alarm, associate_ticket_to_alarm

Lorsqu’il est à false, ces tools renvoient une erreur forbidden explicite, tandis que les tools et resources de lecture (get_alarm_by_id, get_alarm_by_entity, search_alarms, et les 3 resources) restent pleinement actifs.

Ce commutateur est le mécanisme prévu pour couper rapidement toute action d’écriture initiée par un assistant IA, sans arrêter le service ni couper l’accès en lecture.

CORS

server.cors_allowed_origins liste les origines autorisées à appeler le serveur depuis un navigateur (* autorise toutes les origines). Ce contrôle ne concerne que les clients exécutés dans un navigateur : il ne remplace pas l’authentification et doit rester le plus restrictif possible.

Recommandations d’exposition réseau

  • Ne publiez jamais bind_addr directement sur Internet sans passer par une passerelle HTTPS avec certificat de confiance (reverse proxy, tunnel).
  • Pour un accès depuis une autre machine du réseau interne, remplacez 127.0.0.1 par une adresse joignable, en gardant le flux dans un réseau de confiance.
  • Pour un accès depuis un client hébergé (cloud) qui a besoin de joindre le serveur en HTTPS public, exposez-le via un tunnel HTTPS (par exemple ngrok) plutôt qu’en ouvrant directement le port : le chiffrement du tunnel ne remplace pas le contrôle d’accès, gardez donc une authkey à moindre privilège même dans ce cas.
  • Un serveur ouvert en écriture sur Internet sans TLS, authentification, limitation de débit et journalisation d’audit n’est jamais un scénario recommandé.

Voir la Référence des outils et ressources pour le détail des erreurs renvoyées (unauthorized, forbidden, etc.) et une limitation connue de mapping d’erreur.