delinea-mcp Server

officiel

Serveur MCP officiel de Delinea pour les API de Delinea Secret Server et de la plateforme

GitHub
46

Documentation

DelineaMCP

Serveur MCP pour les API Delinea Secret Server et Platform

License

Fonctionnalités

  • Authentification automatique auprès de Secret Server
  • Ensemble d'outils Secret Server étendu pour la gestion des dossiers, secrets, utilisateurs, groupes et rôles. Inclut des assistants de boîte de réception et de demande d'accès ainsi que des utilitaires pour agents de codage.
  • Outils de compatibilité ChatGPT (search et fetch) pour des interactions IA contrôlées.
  • Outils optionnels de gestion des utilisateurs de Delinea Platform
  • Prend en charge les modes de transport Server Sent Events ou STDIO
  • OAuth 2.0 avec enregistrement dynamique du client selon la spécification MCP
  • Support TLS pour les connexions sécurisées
  • Image Docker prête à l'emploi et point d'entrée du serveur de développement
  • Testé avec ChatGPT, Claude Desktop, le connecteur Claude distant, VSCode Copilot et openwebui

Installation

[!NOTE]

Ce projet utilise uv (https://github.com/astral-sh/uv), mais si vous préférez exécuter des commandes sans cela, vous pouvez utiliser les commandes pip et venv comme d'habitude si vous le souhaitez.

  • Installer Uv
  • Initialiser le projet : uv pip sync requirements.txt
  • Utiliser uv run server.py --config config.json

Configuration

Les secrets tels que les mots de passe continuent de provenir des variables d'environnement. Fournissez DELINEA_PASSWORD dans votre environnement shell. Les fonctionnalités optionnelles dépendent de variables supplémentaires telles que AZURE_OPENAI_KEY ou PLATFORM_SERVICE_PASSWORD.

Les paramètres non secrets appartiennent à config.json :

{
  "delinea_username": "<username>",
  "delinea_base_url": "https://your-secret-server/SecretServer",
  "platform_hostname": "<tenant>.secureplatform.io",
  "platform_service_account": "<service_account>",
  "platform_tenant_id": "<tenant_id>",
  "azure_openai_endpoint": "https://example.openai.azure.com/",
  "azure_openai_deployment": "<deployment_name>",
  "auth_mode": "none",
  "transport_mode": "stdio",
  "chatgpt_disable_scope_checks": false,
  "port": 8000,
  "debug": false,
  "external_hostname": null,
  "ssl_keyfile": null,
  "ssl_certfile": null,
  "registration_psk": null,
  "jwt_key_path": ".cache/jwt.json",
  "oauth_db_path": ".cache/oauth.db",
  "enabled_tools": []
}

Pour Secret Server Cloud, utilisez simplement l'URL cloud sans /SecretServer. Spécifiez ssl_keyfile et ssl_certfile pour activer HTTPS. Pour Let's Encrypt, utilisez les fichiers privkey.pem et fullchain.pem.

Le fichier de configuration prend en charge les clés suivantes :

  • delinea_username - Nom d'utilisateur Secret Server. Doit être un utilisateur programmatique avec la permission d'effectuer les tâches souhaitées.
  • delinea_base_url - URL de base de votre instance Secret Server.
  • platform_hostname - Nom d'hôte du tenant Platform (active les outils Platform).
  • platform_service_account - Compte de service utilisé avec l'API Platform.
  • platform_tenant_id - ID du tenant pour les requêtes API Platform.
  • azure_openai_endpoint - Point de terminaison Azure OpenAI. Uniquement si vous souhaitez la génération automatique de rapports (la plupart des agents peuvent générer leur propre SQL de rapport, ne l'activez donc pas sauf si nécessaire).
  • azure_openai_deployment - Nom du déploiement pour Azure OpenAI.
  • auth_mode - Mode d'authentification (none ou oauth). OAuth ne fonctionne évidemment pas avec le transport stdio.
  • transport_mode - stdio pour la ligne de commande ou sse pour HTTP/SSE.
  • chatgpt_disable_scope_checks - Ignorer la validation de portée sur les requêtes ChatGPT. Activez uniquement si vous rencontrez des problèmes de connexion à ChatGPT.
  • port - Port pour le serveur HTTP en mode sse.
  • debug - Activer la journalisation verbeuse.
  • external_hostname - Nom d'hôte utilisé lors de la construction des audiences de jeton OAuth. N'ajoutez pas de préfixe HTTP(S) ni de port.
  • ssl_keyfile - Chemin vers la clé SSL pour HTTPS. (par exemple privkey.pem)
  • ssl_certfile - Chemin vers le certificat SSL pour HTTPS. (par exemple fullchain.pem)
  • registration_psk - Clé pré-partagée requise pour enregistrer les clients OAuth. Vous devrez saisir ce secret dans votre navigateur pour approuver les connexions OAuth.
  • jwt_key_path - Emplacement de la paire de clés RSA utilisée pour les jetons OAuth. Par défaut .cache/jwt.json. Généré automatiquement s'il n'existe pas.
  • oauth_db_path - Chemin vers le fichier de base de données OAuth. Par défaut .cache/oauth.db. Généré automatiquement s'il n'existe pas.
  • enabled_tools - Liste des noms d'outils à enregistrer. Une liste vide active tous les outils. Il est fortement recommandé d'activer les outils de manière sélective par cas d'utilisation ou tâche. Voir le dossier docs/ pour quelques exemples.
  • search_objects - Types d'objets autorisés pour l'outil search. Par défaut ["secret"] mais peut inclure user, folder, group et role.
  • fetch_objects - Types d'objets autorisés pour l'outil fetch. Par défaut ["secret"] mais peut inclure les mêmes valeurs que search_objects.

Exécution du serveur

Démarrez le serveur localement en mode développement :

python server.py

Au démarrage, le serveur demande un jeton porteur et le stocke pour les requêtes API ultérieures. Ce projet sera étendu pour s'intégrer davantage à l'API Secret Server.

Outils MCP

Le serveur expose plusieurs outils MCP pour interagir avec Secret Server :

  • run_report(sql_query, report_name=None) - créer et exécuter un rapport temporaire.
  • ai_generate_and_run_report(description) - générer du SQL en utilisant Azure OpenAI et l'exécuter. Nécessite les variables Azure OpenAI.
  • list_example_reports() - lister les exemples de requêtes et les informations sur les tables.
  • get_secret(id, summary=False) - récupérer un secret ou des détails sommaires.
  • get_folder(id) - récupérer les métadonnées et les enfants d'un dossier.
  • search_users(query) - rechercher des utilisateurs actifs.
  • search_secrets(query, lookup=False) - rechercher ou consulter des secrets.
  • search_folders(query, lookup=False) - rechercher ou consulter des dossiers.
  • get_secret_environment_variable(secret_id, environment) - produire un script pour récupérer les informations d'identification secrètes dans le shell spécifié.
  • check_secret_template(template_id) - récupérer les détails du modèle de secret.
  • check_secret_template_field(template_id, field_id) - vérifier si un modèle contient un champ.
  • get_secret_template_field(field_id) - récupérer les détails d'un champ de modèle de secret spécifique par ID.
  • handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) - approuver ou refuser une demande d'accès.
  • get_pending_access_requests() - lister les demandes d'accès en attente.
  • get_inbox_messages(read_status_filter=None, take=20, skip=0) - récupérer les messages de la boîte de réception.
  • mark_inbox_messages_read(message_ids, read=True) - marquer les messages comme lus ou non lus.
  • user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) - opérations utilisateur unifiées. action accepte get, create, update, delete, list_sessions, reset_2fa, reset_password ou lock_out. Fournissez user_id lorsque requis et fournissez le corps de la requête via data pour les actions de création, mise à jour et réinitialisation de mot de passe. Exemple : user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"}).
  • role_management(action, role_id=None, data=None, params=None) - gérer les rôles. action peut être list, get, create ou update. Passez des paramètres de requête optionnels avec params lors de la liste des rôles. Exemple : role_management("update", role_id=3, data={"name": "New Role"}).
  • user_role_management(action, user_id, role_ids=None) - attribuer ou retirer des rôles à un utilisateur. action est get, add ou remove et role_ids est une liste d'identifiants de rôle pour les opérations d'ajout/suppression.
  • group_management(action, group_id=None, data=None, params=None) - gérer les groupes. action peut être get, list, create ou delete. Fournissez group_id pour obtenir/supprimer et data lors de la création d'un groupe.
  • folder_management(action, folder_id=None, data=None, params=None) - gérer les dossiers. action peut être get, list, create, update ou delete. Fournissez folder_id pour obtenir, mettre à jour ou supprimer et fournissez data lors de la création ou de la mise à jour d'un dossier.
  • user_group_management(action, user_id, group_ids=None) - gérer l'appartenance à un groupe pour un utilisateur. action est get, add ou remove. Fournissez une liste de group_ids lors de l'ajout ou de la suppression de l'appartenance.
  • group_role_management(action, group_id, role_ids=None) - contrôler les rôles sur un groupe. Utilisez les actions list, add ou remove. Fournissez role_ids lors de l'ajout ou de la suppression.
  • health_check() - interroger le point de terminaison de vérification de santé de Secret Server et retourner l'état actuel du service.

Utilisez les variables de configuration du serveur décrites ci-dessus pour vous authentifier. L'outil IA est automatiquement désactivé si les variables Azure OpenAI sont manquantes. Seuls les noms d'outils listés dans config.json seront enregistrés. Une liste vide active tous les outils.

Cas d'utilisation

La documentation couvre plusieurs flux de travail pour connecter des outils au serveur :

Démarrage rapide avec Docker

Un Dockerfile est fourni pour exécuter le serveur MCP sans installer les dépendances Python localement.

  1. Construire l'image :
docker build -t dev.local/delinea-mcp:latest .
  1. Exécuter le serveur (passez vos informations d'identification via les variables d'environnement) :
docker run --rm -p 8000:8000 \
  -e DELINEA_PASSWORD=<password> \
  -e PLATFORM_SERVICE_PASSWORD=<password> \
  -e DELINEA_DEBUG=1 \
  -e AZURE_OPENAI_KEY=<your-key-or-appropriate-token> \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v mcp-data:/app/data \
  dev.local/delinea-mcp:latest

Remplissez config.json avec vos noms d'utilisateur et URL comme indiqué ci-dessus.

Le conteneur stocke oauth.db et jwt.json dans /app/data. Montez un volume (indiqué comme mcp-data ci-dessus) pour que ces fichiers et tous les certificats HTTPS persistent entre les exécutions.

Remplacez <https://your-secret-server/SecretServer> par l'URL de base de votre instance Secret Server pour éviter les erreurs de connexion.

Le serveur démarrera sur le port 8000 par défaut en utilisant python server.py. Définissez l'option port dans config.json pour remplacer la valeur par défaut. Activez debug: true pour journaliser toutes les requêtes HTTP entrantes.

Scripts d'exemple

Le script manual_secret_request.py montre comment récupérer un jeton OAuth pour un ID de secret spécifique :

python scripts/manual_secret_request.py <Secret_ID>

Définissez les variables d'environnement SECRET_USERNAME_<id> et SECRET_PASSWORD_<id> pour le secret avant d'exécuter le script. Définissez optionnellement DELINEA_BASE_URL pour remplacer la valeur par défaut https://localhost/SecretServer.

Exécution des tests

Exécutez les tests unitaires avec couverture pour garantir une couverture de code de 100 % :

pip install -r requirements.txt
coverage run -m pytest -q
coverage report --omit "tests/*"

Tests en direct

Certains tests d'intégration nécessitent des informations d'identification valides. Définissez les variables d'environnement suivantes et la variable optionnelle LIVE_SECRET_ID avant d'exécuter la suite :

export DELINEA_PASSWORD=<password>
# Optional secret used by tests/test_live.py
export LIVE_SECRET_ID=<id>
export SECRET_USERNAME_<id>=<secret_username>
export SECRET_PASSWORD_<id>=<secret_password>

Lorsque ces variables sont présentes, les tests en direct effectueront de véritables requêtes API.

Déploiement en production

Les dépendances sont épinglées dans requirements.txt et les versions sont taguées en utilisant Semantic Versioning. Construisez l'image Docker à partir d'un commit tagué et déployez-la dans votre environnement de production, en passant les variables d'environnement requises (DELINEA_USERNAME, DELINEA_PASSWORD, optionnellement DELINEA_BASE_URL). Les fonctionnalités optionnelles dépendent de variables supplémentaires :

  • PLATFORM_SERVICE_PASSWORD avec PLATFORM_HOSTNAME, PLATFORM_SERVICE_ACCOUNT et PLATFORM_TENANT_ID active les outils de gestion des utilisateurs.
  • AZURE_OPENAI_KEY avec AZURE_OPENAI_ENDPOINT et AZURE_OPENAI_DEPLOYMENT active l'assistant de génération de rapports IA.

Lors de l'exécution avec le transport OAuth ou SSE, vous devrez peut-être fournir registration_psk et configurer un external_hostname ou des fichiers de certificat HTTPS.

Structure du dépôt

  • delinea_mcp/ - paquet contenant les outils MCP.
  • server.py - point d'entrée léger qui enregistre tout avec le serveur MCP.
  • docs/ - documentation du projet et le delinea-secret-server-openapi-spec.json généré.
  • scripts/ - exemples d'aide incluant manual_secret_request.py.

Considérations de sécurité

Les points de terminaison OAuth inclus sont destinés au développement et aux tests. La route /oauth/authorize accepte n'importe quel redirect_uri et redirigera l'utilisateur sans validation. Les déploiements doivent restreindre cette valeur aux URL de rappel approuvées ; sinon, des attaquants pourraient fournir une URL malveillante et capturer les codes d'autorisation. Voir Open Redirection pour plus de contexte.

Notes de version

Voir docs/release_notes.md pour un résumé des dernières fonctionnalités et des éléments de la feuille de route.

Feuille de route

  1. Authentification par relais
  2. Support du transport HTTP en streaming
  3. Étendre la couverture des outils sur Delinea Platform et ajouter d'autres produits Delinea

Contribution

Les contributions sont les bienvenues ! Veuillez ouvrir des issues ou des pull requests pour toute amélioration. Tout nouveau code doit inclure des tests unitaires et passer la suite de tests existante.

Licence

Ce projet est sous licence MIT License.