Cursor Agent Hooks avec AI-FW

Inspecter prompts, commandes shell, fichiers, appels MCP et effets d’agents Cursor via la passerelle AI-FW.

Cursor Agent Hooks permet à AI-FW de gouverner l’activité sur les postes développeurs. Un shim local reçoit les payloads Cursor sur stdin, les transmet à AI-FW et retourne une décision adaptée à l’événement.

Model routing et hooks#

Mécanisme	Couverture
Model routing	Prompts, réponses, streaming, tool calls et trafic de modèles relayé par le gateway compatible OpenAI.
Cursor Agent Hooks	Commandes shell, lectures/écritures de fichiers, appels MCP, démarrage de sous-agents, prompts, événements d’onglet et effets locaux.

Utilisez les deux pour couvrir le trafic modèle et les opérations du poste.

Événements observés#

Événement Cursor	Comportement AI-FW	Blocage possible
beforeSubmitPrompt	Règles de prompt, PII et analyse sémantique.	Oui
preToolUse	Vérifie l’outil avec l’allow-list et inspecte l’entrée.	Oui
beforeShellExecution	Inspecte la commande avant exécution.	Oui
beforeMCPExecution	Gouverne l’identité server/tool et le payload MCP.	Oui
beforeReadFile	Inspecte chemin et contenu avant le modèle.	Oui
subagentStart	Traite le type de sous-agent comme capacité déclarée.	Oui
afterFileEdit	Consigne l’effet fichier et inspecte son contenu.	Non, notification
afterShellExecution	Consigne métadonnées et digests de sortie.	Non
afterAgentResponse	Inspecte la réponse de l’assistant.	Non
sessionStart / sessionEnd	Consigne cycle de vie et durée.	Non
beforeTabFileRead / afterTabFileEdit	Gouverne les lectures et consigne les éditions autonomes.	Lectures seulement

La capture est observe-first : elle journalise sans refuser. L’application nécessite une allow-list et l’activation explicite du blocage.

Configurer l’intégration#

Ouvrez AI Firewall -> Agent Config -> Integrations -> Cursor Agent Hooks.

Paramètre	Défaut	Signification
Enable Cursor Hooks	Off	Active POST /hooks/cursor ; désactivé, renvoie 404.
Credential	AI-FW API key	Préféré pour attribution et révocation ; authentification par signature également disponible.
Mask Rules	Allow	Autorise et journalise une correspondance mask ; choisir Deny pour refuser.
Ask Permission	On	Permet de demander confirmation humaine pour shell et MCP. Off rend ces décisions binaires.
Decide Within	5000 ms	Budget de décision ; dépassé, la requête est refusée.
Repeat Window	2000 ms	Une livraison répétée met à jour la ligne existante ; 0 journalise chacune.
Events	All	Événements Cursor transmis par le shim.
Deny Message	Intégré	Message de refus affiché au développeur.

Les changements de paramètres sont audités.

Installer le shim#

Le shim est publié dans le package public tools/securetron-aifw. C’est un processus local à distribuer selon la procédure entreprise ou à configurer par projet.

Placez le shim à un emplacement stable.
Créez hooks.json depuis le modèle fourni.
Configurez la commande avec un chemin absolu au niveau entreprise ou utilisateur.
Renseignez endpoint et credential AI-FW.
Commencez en capture et observe-first, examinez l’activité avant d’activer le blocage.

L’API key permet une attribution par clé, étiquette agent et owner. Une signature partagée n’offre pas le même périmètre par développeur.

Utilisez capture mode pour inspecter les payloads avant connexion au gateway ; retirez-le avant l’application des règles.

IDE Artifacts#

Lorsque IDE Artifacts est activé dans AI Firewall -> Agent Config -> Integrations, AI-FW consigne écritures/suppressions de fichiers, lectures, métadonnées de commandes et réponses. La fonction est désactivée par défaut.

Les paramètres permettent de choisir kinds, contenu digest-first, plafond et rétention. La sortie des commandes n’est jamais stockée ; règles no-log et politique sensible peuvent aussi supprimer le contenu. Exports : métadonnées et digests seulement.

Lire les résultats#

Question	Où regarder
Que fait la session ?	Audit Logs -> Activity, filtré par conversation.
Fichiers, commandes et effets consignés ?	Artifacts, filtré par type, source, agent, session ou chemin.
Quels outils appelés ?	Skills & Tools, filtré par source ou état.
Début et fin de session ?	Audit Logs -> Events, source cursor.
Contrôles avec télémétrie ?	Compliance, lorsque les contrôles citent des sources observées.

Conversation ID relie prompts, outils et artifacts. Un outil déclaré mais jamais invoqué n’est pas compté comme usage.

Pannes et confidentialité#

L’endpoint exige un credential. Si le gateway est inaccessible, utilisez la posture par événement dans hooks.json et l’option fail-open/fail-closed du shim. Les événements de permission devraient échouer fermé lorsqu’une panne ne doit pas autoriser une commande.

Arguments et contenu privilégient les digests. Ne stockez le contenu que si nécessaire, après examen de la rétention et des règles no-log. La distribution entreprise et la confiance du workspace font partie de la frontière de sécurité.