Gatekeeper

Tes agents proposent le SQL. Tu approuves ce qui s’exécute.

Gatekeeper est une passerelle validée par un humain entre les agents IA et ta base de données. Un agent propose une requête via MCP ; par défaut, rien ne s’exécute tant que tu ne l’as pas approuvée dans Beekeeper Studio, sur le texte SQL, avant exécution. La requête tourne ensuite sur la connexion que Beekeeper a déjà ouverte, et les lignes reviennent à l’agent.

Lecture seule par défaut. Une écriture ne s’exécute que dans un mode que tu actives toi-même dans le plugin, et ce mode est éphémère. L’agent n’a jamais accès aux identifiants de ta base de données.

Musique de #Uppbeat

Shine par Swoop : https://uppbeat.io/t/swoop/shine

Astuce

Mode auto (bêta) : active explicitement l’approbation automatique pour un sous-ensemble restreint de lectures PostgreSQL. Les vérifications locales et Jev doivent toutes deux réussir. Consulte Mode auto pour la configuration, le partage avec le fournisseur et les limites.

Les trois composants

Composant	Ce qu’il fait	Où il tourne
Plugin Beekeeper Studio	Affiche chaque requête proposée, évalue son risque et l’exécute sur ta connexion une fois que tu l’as approuvée	Dans Beekeeper Studio
Serveur MCP	Le côté agent : les outils qu’un agent appelle pour proposer une requête et récupérer son résultat	Sur ta machine, lancé par ton agent
Skill d’agent	Apprend à n’importe quel agent à bien utiliser ces outils	Dans le dossier de skills de ton agent

Ils sont livrés ensemble sous une même version, et ils ne servent qu’ensemble : sans le serveur, le plugin n’a rien à approuver ; sans le plugin, le serveur n’a personne à qui demander.

Pourquoi

• Approbation manuelle par défaut. Le mode auto est facultatif et éphémère. La source de l’approbation et l’attribution à l’évaluateur, si disponible, sont enregistrées.
• Aucun identifiant de base de données ne quitte Beekeeper. Les requêtes passent par sa connexion déjà authentifiée. Fais pointer Beekeeper vers un réplica en lecture ou un rôle en lecture seule pour un garde-fou solide.
• Le risque est évalué, pas supposé. Un parseur qui connaît chaque dialecte classe chaque requête en lecture, écriture ou destructive, et le bouton Approuver reste bloqué tant que le mode correspondant n’est pas activé.

Comment ça marche

  MCP client                     Gatekeeper server (127.0.0.1)          Beekeeper Studio
 ┌────────────────────┐   MCP    ┌───────────────────────────┐  fetch   ┌────────────────────┐
 │ submit_query(sql)  │ ───────► │ MCP server + HTTP broker  │ ◄─────── │ Plugin (iframe)    │
 │ get_query_result() │ ◄─────── │ SQLite lease queue + audit│  poll    │ 1. show SQL        │
 │ cancel_query()     │          │ /pending /executing       │ ───────► │ 2. human approves  │
 │                    │          │ /result  /lease/renew     │  result  │ 3. runQuery()      │
 └────────────────────┘          └───────────────────────────┘          │ 4. post result     │
                                                                        └────────────────────┘

1. L’agent soumet une proposition et reçoit immédiatement un identifiant de requête. Rien ne bloque.
2. Le plugin interroge le broker local, réserve la proposition avec un bail et affiche le SQL.
3. Tu approuves ou tu refuses. Si tu approuves, Beekeeper exécute la requête sur ta connexion.
4. Le plugin renvoie le résultat, et l’agent le récupère dès qu’il est prêt.

Le plugin tourne dans une iframe sandboxée, il ne peut donc jamais recevoir de connexion entrante : c’est lui qui interroge le broker. Cette seule contrainte explique toute l’architecture. Tous les détails dans Architecture.

Bien démarrer

Prérequis : Beekeeper Studio >= 5.4 et Node >= 22. Si tu utilises Claude Code ou Codex CLI, tu as déjà Node. Aucun service en arrière-plan à installer : ton agent lance le serveur à l’ouverture de sa session, et celui-ci s’arrête à la fin de la session.

Attention

macOS uniquement, pour l’instant. Gatekeeper est développé et testé sur macOS. Windows et Linux ne sont pas encore testés, considère-les donc comme non pris en charge jusqu’à ce que quelqu’un fasse un retour. Rien dans le code livré n’est propre à macOS (le serveur résout les chemins depuis ton dossier personnel, le plugin est une webview Beekeeper standard), donc les deux devraient fonctionner, mais « devrait » n’est pas « vérifié ». Les retours sur l’une ou l’autre plateforme sont les bienvenus.

Installation rapide

Un skill dédié configure tout pour toi : le plugin, le serveur MCP, le skill compagnon et l’appairage. Ajoute les skills à ton agent :

npx skills add Gldywn/gatekeeper

Ensuite, demande à ton agent d’installer Gatekeeper, ou lance directement le skill :

/install-gatekeeper

Il effectue toutes les étapes que ton environnement permet et te donne une courte checklist pour le reste, comme redémarrer Beekeeper. Plus tard, /update-gatekeeper vérifie les trois composants et ne met à jour que ce qui est en retard.

Installation manuelle

Tu préfères le faire à la main, ou voir exactement ce qui se passe ?

Important

Pas encore dans le registre de plugins de Beekeeper. Une soumission est en cours auprès des mainteneurs de Beekeeper. Tant qu’elle n’est pas fusionnée, Gérer les plugins n’affichera pas Gatekeeper et l’installation en un clic n’est pas disponible : l’étape 1 ci-dessous est donc la méthode manuelle. Rien d’autre ne change.

1. Installe le plugin dans Beekeeper Studio. Télécharge gatekeeper-<version>.zip depuis la dernière release, extrais-le dans le dossier de plugins de Beekeeper, puis redémarre Beekeeper :

OS	Dossier des plugins
macOS	~/Library/Application Support/beekeeper-studio/plugins/
Linux	~/.config/beekeeper-studio/plugins/
Windows	%APPDATA%\beekeeper-studio\plugins\

Le dossier extrait doit s’appeler exactement gatekeeper. Le zip s’extrait en gatekeeper-<version>/, renomme-le donc après extraction. Beekeeper compare le nom du dossier à l’id du plugin et ignore sans rien dire tout dossier qui ne correspond pas : aucune erreur, aucune entrée dans Gérer les plugins, rien à cliquer. C’est de loin la raison la plus fréquente pour laquelle une installation manuelle semble ne rien faire.

2. Enregistre le serveur MCP auprès de ton agent. C’est aussi l’installation du serveur : npx le télécharge et le met en cache au premier lancement.

# Claude Code
claude mcp add gatekeeper --scope user -- npx -y @gldywn/gatekeeper-mcp-server

# Codex CLI, in ~/.codex/config.toml
[mcp_servers.gatekeeper]
command = "npx"
args = ["-y", "@gldywn/gatekeeper-mcp-server"]

Tu préfères pnpm ? pnpm dlx @gldywn/gatekeeper-mcp-server est l’équivalent direct de la ligne npx. Pour résoudre le paquet une seule fois plutôt qu’à chaque lancement de l’agent, installe-le avec pnpm add -g @gldywn/gatekeeper-mcp-server et fais pointer ton client vers le binaire gatekeeper-mcp-server qu’il ajoute à ton PATH.

Tout client qui lit .mcp.json peut utiliser .mcp.json.example tel quel. Fixe la version (@gldywn/gatekeeper-mcp-server@<version>) si tu préfères auditer les mises à jour plutôt que les subir : sans version fixée, npx résout à nouveau la dernière release à chaque lancement de l’agent, ce qui te garde à jour mais signifie qu’un processus ayant accès à ta base de données change sans que tu le voies.

3. Installe le skill d’agent.

npx skills add Gldywn/gatekeeper

La CLI est interactive : elle te demande pour quels agents installer et s’il faut installer globalement. Elle fonctionne avec Claude Code, Codex, Cursor et les autres.

4. Appaire le plugin, une fois par machine. Lance ton agent, puis demande-lui n’importe quoi qui nécessite la base de données. Tant que le plugin n’est pas appairé, chaque outil Gatekeeper répond avec un code à 6 chiffres : saisis ce code dans le plugin (Outils -> Gatekeeper). Le code est à usage unique et dure environ cinq minutes, et http://127.0.0.1:9999/pair affiche toujours le code en cours. Le jeton de capacité qu’il transmet est conservé dans le stockage chiffré de Beekeeper.

Rien ne répond sur ce port tant que ton agent n’a pas lancé le serveur au moins une fois. Si tu ouvres le plugin avant, il te le signale au lieu d’afficher un champ d’appairage inutilisable.

5. Utilise-le. Demande à ton agent quelque chose qui nécessite la base de données. Il propose du SQL, la requête apparaît dans le plugin, tu approuves, et les lignes reviennent à l’agent. Les lectures fonctionnent tout de suite ; une écriture ne s’exécute qu’une fois le mode Écriture ou Destructif activé.

La compilation depuis les sources est documentée dans Development.

Si le plugin n’apparaît jamais

Beekeeper est livré avec son système de plugins verrouillé, donc une installation neuve peut ignorer complètement un plugin tiers. Trois points à vérifier, dans l’ordre :

1. Le nom du dossier. Exactement gatekeeper, pas gatekeeper-0.1.1. Un nom différent est ignoré silencieusement, comme expliqué plus haut.

2. Le système de plugins est activé. Les paramètres par défaut de Beekeeper définissent pluginSystem.disabled = true, avec une liste blanche qui ne contient que ses deux propres plugins. Ajoute ceci à ta config utilisateur, puis redémarre :

[pluginSystem]
disabled = false

3. Les plugins communautaires sont activés. communityDisabled = true est aussi une valeur par défaut, et désactive tout plugin que Beekeeper classe comme communautaire. Si le gestionnaire de plugins affiche « Community plugins are disabled via configuration », ajoute communityDisabled = false dans le même bloc.

OS	Fichier de config utilisateur
macOS	~/Library/Application Support/beekeeper-studio/user.config.ini
Linux	~/.config/beekeeper-studio/user.config.ini
Windows	%APPDATA%\beekeeper-studio\user.config.ini

Modes d’accès

Par défaut, chaque requête exige un clic humain sur son texte. Le mode d’exécution détermine quelles classes de risque peuvent s’exécuter. Le mode auto est distinct et impose la lecture seule tant qu’il est activé.

Mode	Autorise	Activé par
Lecture (par défaut)	SELECT et compagnie	Rien à faire
Écriture	INSERT, UPDATE	Toi, dans le plugin, avec une seconde confirmation
Destructif	DELETE, DROP, TRUNCATE, ALTER	Toi, dans le plugin, avec une seconde confirmation

Le mode activé est uniquement en mémoire, jamais persisté, et revient en lecture seule lors d’un changement de connexion ou d’un nouvel appairage. Le plugin reclasse et revérifie au moment de l’exécution, donc activer ou désactiver un mode prend effet immédiatement.

La carte lit la requête pour toi : un coup d’œil suffit pour décider, sans analyse minutieuse. Le SQL arrive formaté et coloré, avec les caractères invisibles et d’inversion de direction affichés sous forme de marqueurs explicites, pour que ce que tu lis soit bien ce qui s’exécute. Une instruction d’écriture ou destructive porte un badge de classe coloré et indique son verbe et ses tables cibles, et une instruction que le parseur ne sait pas lire le signale par un texte permanent et est traitée comme destructive.

Sous le SQL, une annotation indique les tables lues par la requête et les colonnes sensibles parmi elles : les données personnelles dans une couleur, les données d’entreprise et commerciales dans une autre, une valeur sensible signalée même si elle n’apparaît que dans un filtre WHERE, et un SELECT * développé en vraies colonnes pour que rien ne se cache derrière l’étoile. Un point sur l’icône de base de données de l’en-tête indique si la dernière vérification de connexion a réussi, et l’icône ouvre les détails : cette vérification, puis les trois couches de lecture seule (le mode activé, la connexion Beekeeper et l’endpoint de la base). Le robot à côté montre le lien vers le serveur Gatekeeper auquel tes agents envoient leurs requêtes. Il est vert quand le serveur répond, orange pendant la connexion et barré en rouge quand il est injoignable ; le survoler indique quand le serveur a répondu pour la dernière fois.

Chaque détecteur s’active ou se désactive dans les paramètres du plugin, ils tournent tous sur ta machine, et rien de ce qu’ils remontent n’est jamais envoyé à l’agent. Ils se basent sur les noms de colonnes et la forme des valeurs : considère-les comme un repère rapide sur ce qui mérite un second regard, pas comme la preuve qu’une requête est saine. L’absence de signalement peut aussi vouloir dire que l’annotation n’a jamais abouti.

Sécurité

• Le contrôle vit là où vit l’exécution. Le plugin est le seul composant capable d’exécuter une requête, c’est donc là que se trouvent le classificateur et la vérification du mode.
• Jeton de capacité sur chaque requête. Sans lui, le broker répond 401. Il est généré au premier lancement, stocké en 0600 sous ~/.gatekeeper, et conservé par le plugin dans le stockage chiffré de Beekeeper.
• Appairage par code. Le broker ne peut pas distinguer le plugin d’une page web que tu visites, donc le jeton transite par un canal qu’une page ne peut pas observer : un code à 6 chiffres à usage unique que tu lis de tes propres yeux, valable cinq minutes, invalidé après cinq essais ratés.
• Loopback uniquement. Le broker écoute sur 127.0.0.1 et rejette les en-têtes Host inattendus, donc une page de DNS rebinding reçoit un 421.
• Résultats plafonnés, audit minimal. Les lignes transmises sont plafonnées en nombre et en octets pour qu’une lecture massive ne sature jamais le contexte de l’agent. L’audit côté agent conserve la décision et un condensé du SQL, jamais le SQL brut ni les lignes.

La lecture ne garantit pas l’absence d’effets de bord : un SELECT peut appeler une fonction volatile, et c’est justement pour ça que l’approbation se fait sur le SQL visible. SECURITY.md détaille le modèle de menace, la frontière de confiance au niveau de l’utilisateur, les durées de conservation et la politique de chaîne d’approvisionnement.

Documentation

Document	Contenu
Architecture	Les deux canaux, la boucle d’approbation, la file à bail, les plafonds de résultats
Outils MCP	Chaque outil qu’un agent peut appeler, la forme du ticket, le contrat d’attente
Configuration	Variables d’environnement et notifications bureau
Sécurité	Modèle de menace, frontière de confiance, conservation, chaîne d’approvisionnement
Développement	Compilation depuis les sources, câblage de dev, structure du repo, stack technique
Publication	Comment un commit devient une release du plugin et un paquet npm

Développement

pnpm install
pnpm build     # both packages
pnpm ci        # typecheck + build + test

pnpm dev:link fait pointer Beekeeper vers ton checkout et pnpm dev lance l’interface du plugin avec rechargement à chaud. La configuration complète, bases de test comprises, est dans Development.

Licence

MIT