🔐 MCP Vault

Gestion sécurisée des secrets pour agents IA — OpenBao embedded

🇬🇧 English version

MCP Vault est un serveur MCP qui fournit un coffre-fort de secrets pour les agents IA et les missions. Il embarque OpenBao (fork open-source de HashiCorp Vault, Linux Foundation) comme moteur de chiffrement.

Pensez 1Password, mais pour vos agents IA.

📸 Console d'administration

📖 Documentation

Related MCP server: agentkeychain

⚡ Démarrage rapide

# 1. Cloner et configurer
cp .env.example .env
# Adapter les credentials S3 dans .env

# 2. Build et démarrer
docker compose build
docker compose up -d

# 3. Vérifier (depuis le conteneur)
docker compose exec mcp-vault python scripts/mcp_cli.py health

# 4. Tester (349 tests e2e)
docker compose exec mcp-vault python tests/test_e2e.py

Lifecycle automatique

Au démarrage, MCP Vault :

1. Charge les tokens depuis S3

2. Restaure les données OpenBao (volume Docker en priorité ; sinon S3 — un échec S3 ambigu, ex. réseau, refuse le démarrage plutôt que d'initialiser un coffre vide par-dessus une sauvegarde distante valide)

3. Démarre OpenBao, l'initialise (1ère fois) et le déverrouille

4. Clés unseal : chiffrées (AES-256-GCM) sur S3, jamais en clair sur disque — uniquement en mémoire

5. Active le sync S3 périodique (60s, conditionnel : un PUT n'est effectué que si l'état a changé depuis le dernier upload réussi — cf. s3_sync.py)

À l'arrêt (docker compose stop) :

1. Scelle OpenBao 🔒

2. Upload final vers S3 📤

3. Arrête le processus — clés effacées de la mémoire

🛠️ Outils MCP (39)

System (2)

💡 Introspection : l'endpoint /admin/api/whoami et la commande CLI whoami permettent de vérifier l'identité et les permissions du token courant.

Vaults — coffres de secrets (5)

Secrets (6)

SSH Certificate Authority (5)

Chaque vault possède sa propre CA SSH isolée — les CA sont cryptographiquement différentes entre vaults. Un certificat signé par la CA d'un vault ne fonctionne PAS sur les serveurs configurés pour un autre vault.

Accès SSH JIT opérateur (2) (v0.9.0)

Le demandeur ne choisit jamais le coffre CA, le rôle, le principal, la cible ou le TTL. L'identité de l'opérateur repose sur un bearer token nominatif scopé par une policy dédiée (même mécanisme que le reste du système), plus une clé publique SSH standard (ssh-ed25519/ecdsa-sha2-nistp256) pré-enrôlée par empreinte. Ce parcours humain exceptionnel reste distinct du breaking-glass externe et du parcours agentique. Les profils peuvent être fournis par SSH_OPERATOR_PROFILES_JSON ou, pour un renderer .env strict, par son équivalent Base64 URL-safe SSH_OPERATOR_PROFILES_B64 ; les deux sources sont mutuellement exclusives.

Policies MCP — contrôle d'accès granulaire (4)

Les policies permettent de restreindre finement les outils accessibles par token, avec support des wildcards (system_*, ssh_*...) et des règles par vault (prod-* → lecture seule).

📋 6 policies prêtes à l'emploi documentées dans ARCHITECTURE.md §6.4.1 : readonly, operator-ssh-jit, developer, prod-reader-dev-writer, ci-cd-agent, security-auditor

🔒 Fail-close sur panne S3 (v0.8.3, #86) : après expiration du cache (5 min), une panne ou une corruption S3 détectée fait refuser explicitement les décisions de policy, plutôt que de continuer à servir silencieusement d'anciennes règles.

Token Management (1)

Purge des tokens révoqués (v0.7.0 — opération admin, exposée en REST / CLI / SPA ; ce n'est PAS un outil MCP) : supprime définitivement les tokens révoqués depuis plus de N jours (rétention, défaut 30). Fail-close (jamais un token actif ni un token expiré non révoqué), dry-run + confirmation, rollback si S3 indisponible, chaque purge auditée. Via POST /admin/api/tokens/purge, la commande CLI token purge-revoked, ou le bouton « 🧹 Purger révoqués » de la console /admin.

🔒 Validation stricte (v0.8.3, #86) : permissions/allowed_resources sont désormais validés strictement à la création, la modification et le chargement — jamais permissifs par défaut sur une entrée malformée (corrige une élévation de privilège possible via une valeur du mauvais type).

PKI interne — CA + ACME (8) (v0.5.0)

CA souveraine pour l'écosystème : les WAF Caddy s'enrôlent via ACME exactement comme avec Let's Encrypt, mais sur une CA interne isolée du réseau public. Utilisable en lab (*.lesur.lan) et en prod air-gapped.

Endpoints publics (non-auth, standard ACME/PKI) : /acme/directory, /pki/ca/root.pem, /pki/ca/chain.pem, /pki/ca/crl.pem

PKI_BASE_URL (optionnel) : URL de base pour les CDPs et le cluster path OpenBao ACME. Vide = déduit de MCP_ALLOWED_HOSTS. Override test Docker : http://mcp-vault:8030. Doit être http(s)://.

JIT Wrap Broker + consommation médiée — C18 (5) (v0.4.13 / v0.6.x)

Contrat pour le CredentialBrokerService de mcp-mission : livraison de credentials single-use via response wrapping OpenBao (cubbyhole), registry write-ahead sur S3 pour la compensation des orphelins, et validation anti-confused-deputy (C18).

⚠️ ttl_seconds borne la fenêtre pour OBTENIR le secret, PAS la durée de vie du secret OBTENU (#156). L'enveloppe est à usage unique et meurt à son TTL (borné ici entre 60 s et 3600 s ; mcp-mission se plafonne à 300 s, ce qui est son choix et non notre plafond). MCP Vault n'impose aucune expiration au secret KV ni au credential qu'il contient, et sa validité réelle dépend de son émetteur — pas de nous. ⚠️ Et ni l'un ni l'autre de nos deux verbes ne suffit à l'invalider : secret_write ajoute une version (la précédente reste lisible par son numéro), et secret_delete retire les versions du coffre, pas le mot de passe de la machine ni la clé chez son fournisseur. Seule une révocation ou une rotation coordonnée chez l'émetteur invalide effectivement un credential externe. ⇒ Si une mission meurt après un déballage, la durée d'exposition n'est bornée par personne, et le remède n'est pas dans cet outil. Ce que nous ne gardons pas : aucune copie de la valeur déballée. Elle est rendue à l'appelant sans être stockée, le champ data est retiré de la piste d'audit, et aucun journal ne la porte. L'entrée de registre conserve l'accessor, vault_id et secret_path — jamais la valeur.

(#115) Permission wrap (ou admin) : un jeton wrap non-admin doit porter allowed_resources non vide et une policy explicite (allowed_tools nommés, path_rule avec allowed_paths non vides — évaluation stricte). Un jeton wrap-only (sans read/write/admin) est confiné à ces 4 outils (MCP) et refusé sur tout /admin/api/*. ⚠️ Downgrade ≤ 0.9.2 : révoquer/purger les jetons wrap d'abord (sinon tokens.json rejeté en bloc, cf. CHANGELOG). Activer la validation C18 avec ENFORCE_MISSION_TOKEN_VALIDATION=true. Par défaut (false) : un jeton invalide est journalisé puis non opposé — zéro impact standalone sans mcp-mission. ⚠️ Rectifié en v0.16.3 (#154) : « continue » était trompeur. Sans enforcement, un échec de validation laisse mission_id vide, donc la clé composite ne correspond à rien et la consommation est refusée au registre. Et surtout, ce qui exprime notre propre incapacité — service de clés injoignable, audience non résolue, validateur non initialisé — est refusé dans les deux postures, en backend_unavailable ou misconfigured : enforce arbitre si un jeton invalide est fatal, il n'arbitre pas si nous disons la vérité sur le motif du refus. tenant_id et expected_aud dans secret_wrap alimentent le binding C18 complet côté secret_consume (v0.6.8). ⚠️ (#86) Dès que ENFORCE_MISSION_TOKEN_VALIDATION=true (seul, ou via le PEP /mcp ci-dessous), MISSION_JWKS_URL, MCP_INSTANCE_ID/MISSION_TOKEN_AUD et MISSION_STATUS_URL deviennent obligatoires (fail-fast au boot) — sans quoi une mission abortée conserverait l'accès jusqu'à expiration du mission_token. ⚠️ (#86) Le validateur applique désormais EXACTEMENT le même contrat que le PEP /mcp ci-dessous (mêmes claims requis, même vérification component_id) — un JWT authentique mais destiné à une autre instance vault est rejeté par les deux points d'application, pas seulement le premier.

Matrice d'effet externe — ce qu'un code d'erreur permet de DÉDUIRE (v0.14.0)

Tous les codes métier arrivent en ENVELOPPE, isError = false. Un appelant qui ne regarde que isError les prend pour des succès. Lire status, puis error_type — dans cet ordre, car certains refus n'ont pas encore de code (voir la note en fin de section).

isError = true ne signale que deux choses : une non-conformité au schéma (paramètre requis absent ou de mauvais type — le corps de l'outil n'a pas tourné, donc aucune écriture, aucun appel OpenBao, aucune révocation), ou un défaut non prévu. Un paramètre conforme au schéma mais refusé sémantiquement revient en enveloppe.

secret_wrap — le nom du code ne suffit pas : une ressource peut exister.

⚠️ backend_error peut suivre un appel qu'OpenBao a reçu (délai dépassé, coupure) ; not_found est déduit d'un motif cherché dans le texte de l'exception, donc non prouvé. Dans les deux cas l'intention passe failed sans accessor.

La clé est alors BLOQUÉE DÉFINITIVEMENT — un rejeu rend operation_failed, sans aucun appel OpenBao. (Jusqu'en v0.12.1 elle redevenait rejouable, et le rejeu créait un second wrap pendant que le premier pouvait vivre.) Si la persistance du marquage échoue, l'entrée revient pending et la clé est bloquée sous operation_pending : le blocage est le même, seul le code diffère. Reprise = nouvel operation_id, dans tous les cas.

⚠️ v0.14.0 — UNE CLÉ EST À USAGE UNIQUE, SANS CONDITION. La moindre entrée pour le couple (operation_id, mission_id) bloque secret_wrap, quel que soit son état, entrée corrompue comprise : une entrée illisible est une raison de refuser, jamais d'autoriser. Plus rien ne libère une clé.

En v0.13.0, revoked, consumed et unusable la rouvraient — pour préserver la reprise « révoquer puis recréer » du broker. Celle-ci a été retirée de sa conception, et le recensement des porteurs de jeton wrap en production n'en a trouvé qu'un seul. Cette libération était aussi le dernier chemin par lequel un jeton étranger présenté à secret_consume pouvait marquer une entrée unusable — et libérer une clé dont le wrap réel vivait encore.

⚠️ La garde ne porte QUE sur la création. secret_revoke_wrap, secret_wrap_status et secret_wrap_lookup restent ouverts sur une clé engagée : sans cela l'appelant serait enfermé avec des ressources qu'il ne pourrait plus ni voir ni couper. Un test compte les appelants de la garde et échoue s'il en apparaît un second.

⚠️ Deux contournements ne sont PAS fermés : la perte du fichier de registre (registre vide = toutes les clés redeviennent vierges) et la course entre deux instances, faute de CAS/ETag (#51). Ce ne sont pas des libérations métier, mais l'unicité n'est pas absolue pour autant.

⚠️ Ce premier contournement était plus large que cette phrase ne le disait, jusqu'à v0.15.0 incluse (#149, corrigé en v0.16.0). Il ne fallait pas perdre le fichier : il suffisait d'une erreur de stockage mal lue. Le registre concluait « objet absent » dès que le texte de l'erreur contenait « 404 » — un identifiant de requête, un port, un 404 émis par un intermédiaire — puis repartait vide en se déclarant fiable, si bien que le refus fail-close ne se déclenchait pas et que la sonde ne signalait rien. Une seconde porte menait au même effet sans aucune erreur : une lecture qui réussissait en renvoyant un JSON valide mais sans la clé wraps (un {}, un corps tronqué) était prise pour un registre vide. Désormais, seule une absence authentifiée par le champ d'erreur structuré (NoSuchKey) vide le registre, et le document est validé avant toute mutation d'état ; tout le reste refuse la création. C'est la règle que les trois magasins d'autorisation appliquent depuis #69.

Une intention failed (ou pending) sans accessor rend found_unattached sur secret_wrap_lookup : aucune révocation n'est possible, seul le TTL borne la ressource éventuelle. ⚠️ Ce verdict ne dit pas qu'une ressource existe — il dit que nous ne pouvons pas l'exclure. (v0.12.1 : ce cas répondait already_revoked, affirmant une révocation inexistante.)

Les quatre autres outils, sur les codes d'indisponibilité :

⚠️ UN EFFET CONFIRMÉ PEUT NE PAS SURVIVRE À UN REDÉMARRAGE (limite structurelle, #140 — arbitrée, cf. #123). Quand une révocation réussit côté coffre mais que l'écriture du registre échoue, le fait n'est inscrit nulle part de durable : au redémarrage, l'entrée peut réapparaître non révoquée, dans un état que nous venons d'annoncer révoqué à l'appelant.

« Peut » et non « va » : une exception S3 ne prouve pas que l'écriture n'a pas abouti — un délai d'attente peut suivre une écriture déjà acceptée — et le registre est en dernier-écrivain-gagne sans verrou, une autre instance a pu écrire entre-temps. L'appelant ne peut donc pas déduire l'état durable de l'échec ; il ne peut que le tenir pour indéterminé.

Ce n'est pas réparable avec un seul support durable — inscrire le fait exigerait un support disponible au moment précis où le support habituel ne l'est pas. Le tenir supposerait un second support : un journal local, rejoué en réconciliation avant de resservir le registre. Le volume local existe déjà dans le déploiement ; le mécanisme, non — et il serait local à l'instance, invisible d'une autre et perdu avec l'hôte.

⚠️ DÉCISION (#123) : ce second support ne sera pas construit. La limite est assumée et publiée, elle n'est pas en attente d'un correctif. Ne dimensionnez pas votre contrat en supposant qu'elle disparaîtra.

Ce que nous faisons à la place, depuis v0.14.1 : nous ne rendons pas le fait durable, mais nous le disons — la réponse porte alors registry_persisted: false et un warning. Le champ est absent sur le chemin nominal.

⚠️ Le signal a la MÊME forme sur les DEUX verbes de révocation — secret_revoke_wrap et secret_wrap_lookup : registry_persisted: false, count_not_persisted (le nombre d'entrées effectivement muées et non inscrites) et un warning. Sur la compensation il est porté aussi par les sorties partial_revocation et consume_terminal — l'appelant y gère déjà un incident, c'est le pire moment pour lui taire une révocation non consignée.

⇒ Conduite : traiter un retour portant registry_persisted: false comme une révocation réelle mais non consignée — ne pas clore son propre registre dessus, et repasser la compensation plus tard. La même limite touche la révocation d'urgence de secret_wrap, où l'entrée reste pending et où secret_wrap_lookup répondra found_unattached pour une ressource que nous tenons pour morte — le serveur traite un retour OpenBao sans exception comme une révocation confirmée, il ne relit rien pour l'attester.

secret_wrap_status ne mute ni OpenBao ni le registre (cache et journal d'audit, eux, bougent). Il ne distingue pas le transitoire du durable : instantané best-effort. ⚠️ Corrigé en v0.15.0 — une panne S3 survenant pendant la fenêtre de cache n'était alors pas détectée du tout ; le rafraîchisseur de fond la constate désormais à sa prochaine tentative (mi-TTL, puis toutes les 10 s), et status bascule en backend_unavailable. La détection n'est donc pas instantanée, mais elle a lieu.

Ce que le registre PROUVE — et ce qu'il ne prouve pas

🔴 secret_wrap_status rend ce que le REGISTRE CROIT, pas un constat OpenBao. Aucun client OpenBao n'est appelé. Chaque réponse est une croyance datée :

• active ne prouve pas qu'un wrap vit — il a pu expirer, être consommé ou révoqué chez OpenBao sans qu'aucune transition de registre ne soit écrite.

• consuming n'atteste pas qu'un déballage soit parti : l'état est persisté avant l'appel d'unwrap.

• consumed, revoked, unusable ne parlent que d'UNE entrée, jamais du couple : plusieurs entrées peuvent coexister pour un même (operation_id, mission_id) — historiquement, parce que le verrou de clé ne regardait que pending jusqu'en v0.12.1. ⚠️ Un état terminal sur l'une ne dit rien des autres : une entrée unusable peut coexister avec une active.

• revoked est aussi posé quand OpenBao répond 400/404 : c'est de l'idempotence, pas une preuve du sort du jeton.

⚠️ ambiguous de secret_wrap_status et ambiguous de secret_wrap_lookup ne sont pas le même mot. Le status est pur ; le lookup est destructif — face à plusieurs entrées il révoque les actives. Ne jamais appeler secret_wrap_lookup pour comprendre un ambiguous : il détruirait ce qu'on cherche à diagnostiquer. Aucun verbe ne détaille un ambiguous (ni cardinalité, ni état individuel) : c'est un refus terminal, sans investigation.

Quand peut-on recréer après secret_revoke_wrap ?

secret_consume — « aucun appel émis » ne veut pas dire « jeton intact » : sur ces chemins nous ne regardons pas le jeton, qui peut avoir expiré ou avoir été consommé en parallèle.

⚠️ Là où l'état est « non constaté », détruire l'accès de son propre fait est une perte sèche. Mais une nouvelle tentative n'est pas une sonde : si la cause du refus est levée, elle peut consommer le wrap. ⚠️ backend_error n'est pas atteignable sur secret_consume (toute exception d'unwrap tombe en wrap_unusable ou consume_outcome_unknown), et wrap_expired n'existe pas — il a figuré à tort dans une version antérieure de ce contrat. ⚠️ already_consumed regroupe consumed et revoked ; secret_wrap_status ne désambiguïse que s'il n'existe qu'une entrée, sinon il rend ambiguous.

Refus sans error_type — la taxonomie fermée (unauthenticated, permission_denied, access_denied, invalid_input, invalid_token, policy_store_unavailable) couvre les gardes d'autorisation partagées. Des refus de validation propres à des outils hors périmètre wrapping (secret_list, surfaces /admin/api) rendent encore une enveloppe sans code. Tester status avant error_type.

PEP mission JWT — porte /mcp (v0.8.0, #47 + #69)

Second point d'application (PEP) du mission_token JWT ES256 de mcp-mission, à l'entrée /mcp (le premier étant secret_consume/C18, à la consommation). Piloté par MCP_AUTH_MODE :

En jwt/dual-stack, le middleware refuse activement : 401 (token absent/opaque/JWT invalide), 403 (aud/component_id ≠ instance, mission inactive), 503 (JWKS indisponible — fail-close). Un JWT invalide ne retombe jamais sur le bearer. Le token est vérifié contre le contrat réel mcp-mission (aud contient MCP_INSTANCE_ID, component_id[MCP_COMPONENT_KIND] == MCP_INSTANCE_ID, iss, exp leeway 0, iat anti-skew). La bootstrap key admin reste acceptée (break-glass).

Une identité mission valide est authentifiée et liée à l'instance, puis mcp-vault (PDP local) lui résout un périmètre vault provisionné localement. Sans octroi, aucun accès (deny-by-default) ; les outils d'infra (system_*, inventaire PKI) et l'admin-plane (vault_create/delete, ssh_*) lui sont refusés. L'endpoint admin POST /admin/api/auth/jwks/reload force le rechargement du JWKS (révocation urgente de kid).

Octroi de périmètre vault — MissionBindingStore (#69)

Le mission_token ne porte aucune autorisation vault : l'octroi est provisionné localement, indexé par tenant_id (claim stable), et stocké un fichier par instance sur S3.

• Un octroi (« binding ») = {tenant_id, allowed_resources:[coffres…], permissions, policy_id?, enabled, expires_at?}.

• Permissions strictes : read ou read,write (jamais write seul, jamais admin). Data-plane uniquement : lire/écrire des secrets dans les coffres autorisés — jamais créer/détruire un coffre ni gérer une CA SSH.

• Fail-close : binding absent/désactivé/expiré → aucun accès. Registre indisponible/corrompu → 503 (refus observable, jamais un deny silencieux ni un écrasement destructeur).

• Administration (bearer/bootstrap admin uniquement — jamais via mission JWT) :

# Octroyer un périmètre lecture à un client mission
mcp-cli mission-binding create acme-corp --vaults prod-app --permissions read
# Lecture + écriture sur plusieurs coffres
mcp-cli mission-binding create acme-corp --vaults prod-app,staging --permissions read,write
mcp-cli mission-binding list
mcp-cli mission-binding get acme-corp
mcp-cli mission-binding delete acme-corp
mcp-cli mission-binding purge --older-than 30 --dry-run   # bindings expirés

Granularité tenant : toutes les missions actives d'un même client (tenant_id) partagent le périmètre octroyé. Le grain fin par mission existe déjà à la consommation (secret_consume/C18).

Audit (1)

Traçabilité du cycle de vie des accès (v0.7.0 — conformité SecNumCloud/HDS) : toute mutation du plan de contrôle — création / mise à jour / révocation / purge de token, création / suppression de policy — est journalisée, via l'API REST admin comme via les outils MCP. Les échecs de persistance des opérations de retrait (révocation, purge, suppression de policy — celles qui laissent un accès actif si elles échouent) sont également tracés. La trace vit dans audit-mcp.jsonl, physiquement indépendant de _system/tokens.json → elle survit à une purge. Le token brut n'apparaît jamais dans le détail d'audit.

# 1. Setup initial (ONE-TIME) — créer vault + rôles SSH
vault_create("llmaas-infra", description="SSH CA LLMaaS")
ssh_ca_setup("llmaas-infra", "adminct", allowed_users="adminct", ttl="1h")
ssh_ca_setup("llmaas-infra", "agentic", allowed_users="agentic,iaagentic", ttl="30m")

# 2. Déployer la CA sur les serveurs (ONE-TIME)
result = ssh_ca_public_key("llmaas-infra")
# → Mettre result["public_key"] dans /etc/ssh/trusted-user-ca-keys.pem

# 3. Usage quotidien — signer une clé publique
cert = ssh_sign_key("llmaas-infra", "adminct", public_key="ssh-ed25519 AAAA...", ttl="1h")
# → cert["signed_key"] = certificat signé, valide 1h
# → OpenSSH l'utilise automatiquement si placé à côté de la clé privée

🔑 Types de secrets (style 1Password)

Chaque secret supporte : tags, favorite, versioning KV v2 automatique.

🔒 Authentification

⚠️ Seul le header Authorization: Bearer <token> est accepté. L'authentification par query string (?token=) a été supprimée pour des raisons de sécurité (v0.3.1).

Authorization: Bearer <token>

3 couches d'isolation :

1. Vault-level : allowed_resources=[] → owner-based (seuls les vaults créés par le token), ou liste explicite

2. Tool-level : policies avec allowed_tools/denied_tools (wildcards fnmatch)

3. Path-level : allowed_paths dans les path_rules → contrôle par secret individuel

🖥️ CLI

MCP Vault inclut un CLI complet avec Click + Rich :

# Commandes scriptables
python scripts/mcp_cli.py health
python scripts/mcp_cli.py about
python scripts/mcp_cli.py whoami                       # Identité du token courant
python scripts/mcp_cli.py vault list
python scripts/mcp_cli.py vault create serveurs-prod -d "Clés SSH prod"
python scripts/mcp_cli.py secret write serveurs-prod web/github -d '{"username":"me","password":"s3cr3t"}' -t login
python scripts/mcp_cli.py secret read serveurs-prod web/github
python scripts/mcp_cli.py secret password -l 32
python scripts/mcp_cli.py token create agent-sre --vaults prod --policy readonly
python scripts/mcp_cli.py token list
python scripts/mcp_cli.py token purge-revoked --older-than 30 --dry-run    # aperçu (rien supprimé)
python scripts/mcp_cli.py token purge-revoked --older-than 30 --yes        # purge effective
python scripts/mcp_cli.py policy create no-ssh -d "Pas de SSH" --denied "ssh_*"
python scripts/mcp_cli.py policy create team-x --allowed "secret_*" --path-rules '[{"vault_pattern":"shared-*","allowed_paths":["shared/*"]}]'
python scripts/mcp_cli.py audit --status denied --limit 10

# Accès SSH JIT opérateur
python scripts/mcp_cli.py ssh profiles
python scripts/mcp_cli.py ssh request bastion-prod \
  --key ~/.ssh/id_ed25519.pub --reason "INC-230 maintenance bastion"

# PKI interne (v0.5.0)
python scripts/mcp_cli.py pki setup --lab --domains '*.lesur.lan,lesur.lan'
python scripts/mcp_cli.py pki ca-key
python scripts/mcp_cli.py pki certs
python scripts/mcp_cli.py pki revoke 12:34:ab:cd:ef:12:34:56

L'aide --help de chaque commande explique le modèle de sécurité à 3 couches et guide l'utilisateur.

Voir scripts/README.md pour la documentation complète du CLI.

⚙️ Variables d'environnement

Copier .env.example → .env et adapter. .env.example est le contrat de configuration de référence : il déclare exactement les 45 variables consommées par Settings (src/mcp_vault/config.py), ni plus ni moins, et il est vérifié par tests/test_env_example_contract.py.

⚠️ extra="forbid" : une clé absente de ce contrat, portant une valeur non vide dans votre .env, fait échouer le démarrage. Ne composez jamais un .env depuis une autre source que .env.example.

Marqueur REQUIRED : une variable dont la valeur d'exemple est REQUIRED n'a aucun défaut utilisable. Le marqueur échoue volontairement la validation — le service refuse de démarrer tant qu'un déploiement ne l'a pas substitué par une vraie valeur.

Tokens sensibles du CLI — ce ne sont PAS des variables du serveur. VAULT_WRAP_TOKEN et VAULT_MISSION_TOKEN sont lus uniquement par le CLI (scripts/cli/) et ne figurent pas dans Settings : les placer dans .env ferait échouer le démarrage du serveur. Ils changent à chaque opération (usage unique, TTL court) — les passer inline devant la commande, jamais dans un fichier, sinon ils fuitent dans l'historique de votre shell système :

VAULT_WRAP_TOKEN=hvs.CAES... mcp-vault secret consume op-123

Voir .env.example pour la documentation détaillée de chaque variable.

🏗️ Architecture

📐 Documentation complète : le dossier DESIGN/mcp-vault/ contient la spécification détaillée (ARCHITECTURE.md — vision, sécurité, SSH CA, policies, roadmap HSM) et la documentation technique (TECHNICAL.md — modules, Docker, tests, dépendances).

Internet → WAF (Caddy + Coraza :8085) → MCP Vault (Python :8030) → OpenBao (:8200 localhost)
                  ↕ OWASP CRS v4                  ↕
              Protection L7                 S3 Dell ECS (persistance)

WAF — Caddy + Coraza (OWASP CRS v4)

Le WAF protège l'API contre les attaques L7 (injections SQL, XSS, LFI, RCE, SSRF) :

• Caddy v2.11.2 compilé avec coraza-caddy v2.5.0 (coraza v3.7.0) via xcaddy — montée depuis v2.2.0/coraza 3.3.3 en v0.9.2, requise par SecRequestBodyJsonDepthLimit (cf. #107)

• 23 fichiers de règles OWASP CoreRuleSet v4.7.0 chargés (décompte vérifiable : grep -c '^Include /opt/crs/rules/' waf/coraza.conf)

• Mode Blocking sur TOUS les endpoints (health, /mcp, /admin/api)

• Corps JSON-RPC réellement parsé sur POST /mcp (ctl:requestBodyProcessor=JSON, v0.9.2). Sans ce réglage, Coraza traitait le corps entier comme une variable unique : toute chaîne d'une liste de phrases CRS présente n'importe où — y compris dans une valeur de secret — déclenchait un blocage, et aucun ciblage fin d'exclusion n'était possible

• Exclusions de RÈGLES (ctl:ruleRemoveById) déclarées avant l'Include CRS — pattern « exclusions before CRS », requis pour neutraliser les règles évaluées en phase:1. Faux positifs couverts : Unicode français 920540, noms PowerShell 932120, distribution CA/CRL .pem 920440, Content-Type JOSE ACME 920420

• Exclusions de CIBLES (SecRuleUpdateTargetById) déclarées après l'Include CRS — sémantique inverse : cette directive modifie la définition de la règle, qui doit donc être déjà chargée. Couvre le faux positif 930120 sur .env (v0.9.2) : les noms d'arguments sous l'enveloppe MCP params._meta et les valeurs de la charge opaque de secret_write (seul outil à en recevoir une — transmise à OpenBao, qui la chiffre au repos). Le reste demeure inspecté — chemin, nom de coffre, étiquettes, nom d'outil, et toutes les règles de path traversal

• Profondeur JSON bornée à 32 sur POST /mcp (SecRequestBodyJsonDepthLimit, v0.9.2). Sans elle, un corps de 15 Ko d'imbrication — JSON valide, 2 octets par niveau — faisait tomber le WAF en OOM. La limite seule créait toutefois une évasion silencieuse (au-delà du seuil, plus aucune inspection) : la règle 10011 refuse donc explicitement (400) tout corps déclaré non analysable par REQBODY_ERROR. ⚠️ Limite de compatibilité : un secret dont data dépasse ~28 niveaux d'imbrication interne est refusé — les types de secrets du produit sont des dictionnaires plats, aucun usage connu n'y touche

• Gardes anti-évasion 10009/10010 (v0.9.2). Ces exclusions sont des directives globales dont le sélecteur est un nom d'argument, donc une chaîne choisie par le client : ARGS/ARGS_NAMES agrègent aussi query string et formulaire. Avant ces gardes, GET /health?json.params.arguments.data.x=.env passait (200) là où GET /health?legit=.env était refusé (403) — soit une neutralisation globale de 930120 par simple choix du nom de paramètre. Les gardes refusent désormais tout nom préfixé json. hors du corps JSON MCP analysé, discriminé par un drapeau serveur non forgeable. La propriété est imposée, pas supposée

• Headers de sécurité : CSP, X-Frame-Options DENY, X-XSS-Protection, nosniff

• Méthodes autorisées adaptées au protocole MCP : GET, POST, DELETE, PUT, PATCH

Stack ASGI (6 couches)

PkiMiddleware → AdminMiddleware → HealthCheckMiddleware → AuthMiddleware → LoggingMiddleware → MCPServer

PkiMiddleware (v0.5.0) est la couche la plus externe — intercepte /acme/* et /pki/ca/*.pem avant l'auth (endpoints publics par design PKI/ACME).

Depuis la v0.20.0, le serveur utilise mcp==2.1.1 et accepte à la fois le protocole moderne 2026-07-28 et les clients legacy jusqu'à 2025-11-25. Le transport HTTP est stateless dans les deux ères : il n'exige plus d'affinité de session. MCP Vault reste néanmoins mono-instance : OpenBao embarqué, la synchronisation S3 last-write-wins et les caches d'autorisation ne permettent pas encore un déploiement multi-réplica sûr. Le SDK annonce automatiquement la capability subscriptions/listen, mais MCP Vault ne publie ni ressource ni événement et ne configure aucun store de reprise ; cette capability est donc inerte et doit être réauditée à chaque montée de version du SDK.

Après une fermeture de connexion sans réponse terminale, un client ne doit pas réessayer automatiquement une mutation : son effet peut déjà avoir eu lieu. Cela vaut notamment pour secret_wrap_lookup, qui révoque des wraps malgré son nom de consultation.

Le point de décision lit la mémoire, jamais le réseau (v0.15.0, #123)

Un appel S3 bloquant ne gelait pas une requête : il gelait le service entier, sonde de santé comprise — 488 s mesurées en production (#110). La cause est toujours la même : boto3 est synchrone, et un appel synchrone dans la boucle asyncio monopolise l'unique thread qui sert toutes les requêtes.

Le lot 1 (v0.10.1) a borné la durée de ces appels, le lot 2 (#122) en a sorti cinq de la boucle. Ce lot ferme les derniers, et ce sont les plus fréquents : les magasins d'autorisation, interrogés à chaque requête authentifiée.

Plus aucun appel S3 ne part d'un point de décision. Les gardes (check_policy, check_path_policy, check_wrap_*, get_by_hash, resolve) lisent un instantané publié en mémoire. Des tâches de fond — une par magasin — le renouvellent hors boucle, à la moitié du TTL, et toutes les 10 s après une panne.

✅ Le dernier appel réseau synchrone du chemin d'authentification est fermé (v0.16.1, #148). Le rafraîchissement du cache JWKS (mission_jwt.py, httpx.get synchrone) était déclenché depuis la validation d'un jeton mission, appelée sans await dans une coroutine. Même classe de défaut que #110, sur un chemin aussi chaud. Il était déclaré ici comme résidu depuis v0.15.0 ; il ne l'est plus.

Mesuré en production le 17/08 avant correction : 117,2 ms de gel du service entier par rafraîchissement, au plus une fois par TTL de 60 s. Trois chemins y menaient, tous des coroutines, et les trois sont déportés hors boucle par run_blocking :

⚠️ JWKSCache n'est PAS réécrit. Il est déjà thread-safe (threading.Lock) : plusieurs threads d'exécuteur s'y sérialisent, un seul fait le fetch, les autres trouvent l'instantané frais. Son fail-close (un cache périmé n'est jamais servi), son backoff et son throttle « kid inconnu » sont inchangés — les déplacer aurait transformé un gel en martèlement de l'endpoint de mcp-mission.

⚠️ MISSION_JWKS_CACHE_TTL n'est pas un réglage de latence. Une clé révoquée disparaît du JWKS de mcp-mission : ce TTL est donc la fenêtre de propagation d'une révocation de clé de signature. Il vaut 60 s, cinq fois plus strict que le max-age=300 qu'ils publient, et il ne doit pas être allongé pour espacer les appels.

Deux horloges, pas une. Le code historique n'en portait qu'une, qui servait à la fois à dater l'instantané et à brider les re-tentatives. Une panne les mettait en désaccord : repousser la date pour ne pas marteler S3 rajeunissait aussi, mécaniquement, un instantané jamais rechargé — un magasin en panne restait donc « frais » indéfiniment. Elles sont désormais séparées, et en temps monotone : un recul d'horloge murale ne peut plus rajeunir un état périmé.

Copy-on-write sur les trois magasins d'autorisation : une mutation construit un candidat, le persiste, et ne le publie qu'après confirmation du PUT. Une garde synchrone ne peut donc plus observer une policy créée mais non persistée, ni une suppression que l'échec du PUT annulera. Les rollbacks disparaissent — donc aussi le risque d'en oublier un.

⚠️ Le registre wrap n'a délibérément PAS de copy-on-write. Aucun lecteur synchrone ne l'interroge, et la publication-après-PUT y détruirait un acquis de v0.14.1 : mark_entries_revoked conserve volontairement en mémoire une révocation confirmée mais non inscrite, parce que la mémoire y dit la vérité et que c'est le support durable qui est en retard.

Observabilité. system_health porte désormais la fraîcheur de chaque magasin (stores, et stores_stale s'il y a lieu). Sans cela, un rafraîchisseur mort ne se verrait qu'au premier refus : le service répondrait normalement, puis refuserait tout d'un coup.

Le registre wrap y ajoute sa volumétrie (v0.16.0, #146) : entries, le nombre d'entrées, et last_write_bytes, le poids du dernier corps écrit — null tant qu'aucune écriture n'a eu lieu depuis le démarrage. Le registre n'a ni purge ni écriture incrémentale : il est réécrit intégralement à chaque transition, et nous n'avions aucun chiffre pour dimensionner ce coût.

⚠️ last_write_bytes est relevé à l'écriture, jamais calculé par la sonde. Sérialiser le registre à chaque appel de supervision ferait de la sonde une cause du problème qu'elle mesure. entries, lui, est un simple décompte en mémoire.

/health et /ready lisent désormais la fraîcheur en mémoire : un magasin configuré jamais chargé ou périmé rend le service 503 unavailable, car les décisions d'autorisation ne peuvent plus être garanties. Ces sondes ne font aucun appel S3 ; les rafraîchisseurs existants peuvent les rétablir sans redémarrage. /healthz reste une liveness indépendante. system_health reste plus strict et vérifie en plus la connectivité S3 courante.

Ce fail-close de readiness est uniforme, y compris pour le Token Store : il ne bloque pas lui-même une requête MCP déjà routée, mais demande à l'orchestrateur de retirer l'instance. Le produit étant mono-instance, une panne S3 assez longue pour périmer tous les magasins provoque donc une indisponibilité totale côté load balancer. C'est le contrat explicitement retenu en v0.20.1 : une décision d'autorisation non garantie ne doit pas être annoncée disponible.

⚠️ Limite inchangée : rien ici ne ferme la race d'écriture multi-instance (#13/#51). Le dernier écrivain gagne toujours, et un rafraîchissement de fond élargit même la fenêtre pendant laquelle deux instances peuvent diverger sans le savoir.

Sondes de santé (v0.11.0, #103)

Deux questions distinctes, deux contrats :

status appartient à une énumération fermée, une par question : healthy | sealed | unavailable pour la disponibilité, alive pour la liveness. Un coffre scellé est donc identifiable de l'extérieur, sans qu'aucun détail de dépendance ne soit exposé — le diagnostic reste dans les journaux et sur /admin/api/health, qui exige un bearer valide.

Le HEALTHCHECK du conteneur vise /health : un coffre indisponible apparaît désormais unhealthy. Branchez une éventuelle sonde de liveness ou un autoheal sur /healthz, jamais sur /health — redémarrer un coffre scellé ne le descelle pas, et redémarrer ne rétablit pas S3.

Après un démarrage non abouti, l'état est latché : le signal ne repasse pas au vert tout seul, un redémarrage est requis. Cette règle ne concerne pas un magasin temporairement périmé après un démarrage abouti : son refresher peut rétablir /health sans nouvelle génération.

Lifecycle OpenBao

STARTUP:  S3 download (3 états : restauré / absence confirmée / échec ambigu —
          un échec ambigu refuse le démarrage) → bao server → init/unseal → periodic sync
RUNTIME:  secrets via hvac → sync S3 toutes les 60s, SEULEMENT si l'état a changé
SHUTDOWN: seal → S3 upload final (sauté si le démarrage n'a pas abouti, pour ne pas écraser une sauvegarde valide) → stop process
CRASH:    Docker volume local → redémarrage immédiat

Sécurité des clés unseal

Les clés unseal d'OpenBao sont protégées par séparation physique à 3 facteurs :

Invariants : les clés unseal ne sont jamais en clair sur disque — uniquement en mémoire pendant le runtime. Un crash efface automatiquement les clés.

Roadmap sécurité :

📖 Voir DESIGN/mcp-vault/ARCHITECTURE.md §8 et §11 pour les détails complets.

📋 Tests (~1500 unitaires mockés + 349 e2e réels)

📖 Voir tests/README.md pour le guide complet d'exécution.

# 1. Tests CLI — parsing + affichage (197 tests, SANS serveur)
python tests/test_cli_all.py

# 2. Tests CLI LIVE — cycle complet (79 tests, serveur réel)
MCP_URL=http://localhost:8085 MCP_TOKEN=<key> python tests/test_cli_live.py

# 3. Tests e2e MCP (349 tests, dans Docker)
docker compose exec mcp-vault python tests/test_e2e.py

# 4. Tests crypto (18 tests, SANS serveur — AES-256-GCM + AAD + validation entropie)
python tests/test_crypto.py

# Un seul groupe CLI
python tests/test_cli_all.py --only policy

# Un seul groupe e2e
docker compose exec mcp-vault python tests/test_e2e.py --test enforcement

Couverture e2e (349 tests, 15 catégories)

📁 Structure du projet

mcp-vault/
├── .env.example              # Configuration (copier en .env)
├── docker-compose.yml        # WAF + MCP Vault + volumes
├── Dockerfile                # Multi-stage (OpenBao 2.5.1 + Python 3.12)
├── requirements.txt          # Dépendances Python
├── requirements.lock         # Dépendances pinnées (versions exactes)
├── VERSION                   # version courante du service
├── DESIGN/mcp-vault/
│   ├── ARCHITECTURE.md       # Spécification détaillée (v0.15.0)
│   ├── TECHNICAL.md          # Documentation technique (v0.15.0)
│   └── SECURITY_AUDIT.md     # Rapport d'audit consolidé (60 findings V2.1)
├── scripts/
│   ├── mcp_cli.py            # CLI entry point
│   ├── README.md             # Documentation CLI
│   └── cli/                  # Module CLI (Click + Rich)
│       ├── __init__.py       # Config (.env, BASE_URL, TOKEN)
│       ├── client.py         # MCPClient (Streamable HTTP)
│       ├── commands.py       # Groupes Click
│       └── display.py        # Affichage Rich
├── src/mcp_vault/
│   ├── config.py             # Configuration pydantic-settings
│   ├── server.py             # MCPServer + 39 outils MCP + lifecycle + audit
│   ├── lifecycle.py          # Orchestrateur startup/shutdown
│   ├── s3_client.py          # Client S3 hybride SigV2/SigV4
│   ├── s3_sync.py            # Sync file backend ↔ S3
│   ├── auth/                 # Bearer tokens, check_access, ContextVar
│   ├── admin/                # Console web /admin + API REST
│   ├── openbao/              # Process manager, HCL config, lifecycle
│   ├── vault/                # Spaces, secrets, SSH CA, types
│   └── static/               # Console admin SPA (parité CLI 100%)
│       ├── admin.html        # HTML structure + 7 modals
│       ├── css/admin.css     # Design Cloud Temple (dark theme)
│       ├── js/               # 9 modules JS (config, api, app, dashboard, vaults, tokens, policies, activity, pki)
│       └── img/              # logo-cloudtemple.svg
├── tests/
│   ├── README.md             # Guide d'exécution des tests (auditeurs)
│   ├── TEST_CATALOG.md       # Catalogue des tests pour auditeurs
│   ├── test_cli_all.py       # 197 tests CLI parsing (sans serveur)
│   ├── test_cli_live.py      # 79 tests CLI live (serveur réel)
│   ├── test_e2e.py           # 349 tests MCP e2e (15 catégories)
│   ├── test_crypto.py        # 18 tests AES-256-GCM + AAD
│   ├── test_service.py       # 78 tests bas niveau
│   ├── test_integration.py   # Tests pytest
│   └── cli/                  # Tests CLI découpés par groupe (7 fichiers)
└── waf/                      # WAF Caddy + Coraza (OWASP CRS v4)
    ├── Dockerfile            # Multi-stage (xcaddy + CRS v4.7.0)
    ├── Caddyfile             # Reverse proxy + coraza_waf
    └── coraza.conf           # Config Coraza + exceptions MCP

🌐 Écosystème MCP Cloud Temple

Licence : Apache 2.0 | Auteur : Cloud Temple | Version : 0.20.1