Créer des agents et promptbooks personnalisés dans Microsoft Copilot Security

La sauvegarde dans `/tmp` a été refusée par les permissions, donc voici directement le HTML. Il est calé sur les références Microsoft Learn actuelles (manifeste d'agent, plugin-overview, serveur MCP Sentinel) que j'ai vérifiées avant rédaction : clés `Descriptor` / `SkillGroups` / `AgentDefinitions`, cinq formats d'outils, contrainte `gpt-4.1`, URLs exactes des trois collections MCP. ```html

Deux ans après la disponibilité générale de Microsoft Security Copilot, le constat terrain est constant dans les SOC français : les équipes activent les promptbooks natifs, obtiennent des résumés d'incidents corrects en trois minutes au lieu de vingt, puis se heurtent à un plafond. Le produit ne connaît ni vos zones réseau, ni votre CMDB, ni la criticité métier de vos serveurs, ni les règles de qualification que votre analyste N1 applique depuis cinq ans. À partir de 2026, la réponse de Microsoft n'est plus le prompt bien écrit mais l'agent : un objet déclaratif, versionné dans un manifeste YAML, déclenché par un planificateur, capable d'appeler des outils API, KQL, GPT ou Logic App et de raisonner sur vos données. Maîtriser les copilot security agents custom promptbooks devient donc une compétence d'ingénierie, pas d'usage. Cet article détaille l'architecture réelle, la syntaxe exacte des manifestes, l'intégration MCP, le branchement d'outils tiers comme MISP ou TheHive, et le pipeline de triage d'alertes que nous déployons chez nos clients.

Comprendre l'architecture des agents dans Copilot Security

Un agent Security Copilot n'est pas un prompt système sophistiqué. C'est un ensemble de trois briques déclarées dans un même manifeste : un skillset (le conteneur, décrit par la clé Descriptor), une collection de skills — Microsoft parle désormais d'outils — regroupées par format dans SkillGroups, et une ou plusieurs définitions d'agent sous AgentDefinitions. Cette séparation est structurante : un même skillset peut alimenter plusieurs agents, et un agent peut consommer des skillsets qu'il ne possède pas via le champ RequiredSkillsets.

Le rôle de l'orchestrateur

Au runtime, l'orchestrateur reçoit l'input de l'agent, lit les Instructions du skill de format AGENT, puis sélectionne les outils déclarés dans ChildSkills. La sélection s'appuie exclusivement sur les champs Description et DescriptionForModel : le premier alimente l'interface et sert de repli, le second n'est utilisé que pour le routage vers l'outil. C'est la cause n°1 des agents qui « ne font rien » — une description vague produit une collision de compétences et l'orchestrateur choisit le mauvais outil ou aucun.

Plugins, skills et agents

Les plugins restent la couche d'accès aux données : ils exposent des outils que l'agent invoque. La documentation Microsoft sur les plug-ins est explicite sur ce point — un plugin étend ce que l'agent peut faire en lui donnant accès à des ressources externes au LLM. Pour un rappel complet du modèle de capacité et du catalogue de connecteurs, voir notre analyse de l'architecture et système de plugins Copilot Security. La vue d'ensemble officielle du produit précise par ailleurs que les solutions tierces intégrées en tant que plugins doivent être acquises séparément.

Prérequis techniques : capacité SCU, rôles et espaces de travail

Avant d'écrire une ligne de YAML, trois prérequis bloquants doivent être levés. Les ignorer produit des échecs silencieux au déploiement, sans message d'erreur exploitable.

Capacité et espace de travail

Security Copilot fonctionne sur une capacité provisionnée exprimée en Security Compute Units (SCU), rattachée à une région Azure et à un espace de travail. Un agent planifié consomme des SCU à chaque exécution du couple FetchSkill / ProcessSkill, y compris lorsque le fetch ne remonte aucun élément. Sur une capacité minimale, un agent déclenché toutes les cinq minutes suffit à saturer la file d'exécution et à faire échouer les sessions interactives des analystes.

Rôles requis

La publication d'un plugin ou d'un agent custom exige le rôle Copilot owner dans l'espace de travail ; le rôle Copilot contributor permet seulement de consommer et de créer des promptbooks. Côté données, l'agent hérite des permissions de l'identité qui l'exécute : un outil KQL ciblant Target: Defender ne renverra rien si le compte de service ne dispose pas au minimum du rôle Lecteur de sécurité dans Microsoft Defender XDR. Pour les outils Microsoft Entra ID et Microsoft Purview, le promptbook d'analyse utilisateur exige explicitement le rôle d'enquêteur Gestion des risques internes.

Contexte multi-tenant

En contexte MSSP, l'isolation se joue au niveau de l'espace de travail et de la valeur AgentSingleInstanceConstraint, qui accepte None, Workspace ou Tenant. Nous détaillons les schémas de délégation dans notre guide du déploiement MSSP avec Copilot Security.

Promptbooks natifs vs custom : quand créer le sien

La bibliothèque native couvre sept scénarios : vérification de l'impact d'une menace externe, investigation d'incident Microsoft Sentinel, investigation d'incident Microsoft Defender XDR, analyse des utilisateurs Microsoft, analyse de script suspect, profil d'acteur de menace, rapport Threat Intelligence 360 basé sur article MDTI, et évaluation de l'impact d'une vulnérabilité. Chacun attend une entrée typée — SENTINEL_INCIDENT_ID, SNIPPET, CVEID — et enchaîne des prompts dont chacun s'appuie sur la réponse du précédent.

Les trois signaux qui justifient un promptbook custom

• Vous répétez une séquence de plus de trois prompts à l'identique plusieurs fois par semaine. C'est le cas typique de la qualification de phishing signalé ou du contrôle post-changement sur un compte à privilèges.
• Votre séquence dépend de conventions internes que le modèle ne peut pas deviner : nomenclature d'unités d'organisation Active Directory, tags de criticité dans la CMDB, seuils de tolérance propres à votre politique de sécurité.
• Le livrable a un format contraint — une fiche d'incident conforme à votre procédure NIS 2, un résumé destiné au COMEX, un ticket ServiceNow avec des champs obligatoires.

Quand un promptbook ne suffit pas

Un promptbook reste synchrone, déclenché par un humain, et sans logique conditionnelle : il exécute ses prompts dans l'ordre, point. Dès que vous avez besoin d'une exécution planifiée, d'une boucle sur une liste d'alertes, d'un appel API authentifié vers un outil tiers ou d'un branchement selon un verdict, il faut passer à l'agent. La règle empirique que nous appliquons : promptbook pour l'assistance à l'analyste, agent pour l'automatisation du flux.

Créer un promptbook en 5 étapes : structure, prompts enchaînés et variables

La création se fait depuis la bibliothèque de promptbooks, accessible par le menu Security Copilot ou par l'icône Requêtes de la barre d'invite. La bibliothèque liste chaque promptbook par nom, propriétaire, description, nombre d'invites, plugins requis et visibilité — quatre métadonnées que vous devez donc renseigner avec discipline.

Étape 1 — Déclarer les entrées avant les prompts

Commencez par lister les variables. Nommez-les en majuscules et sans espace : INCIDENT_ID, UPN, TIME_RANGE, ASSET_TAG. Une variable mal nommée est réinterprétée par le modèle comme du texte libre et disparaît de la boîte de saisie.

Étape 2 — Écrire un prompt de cadrage

Le premier prompt ne doit rien produire d'utile pour l'analyste : il pose le contexte. Exemple réel : « Tu agis comme analyste N2. Contexte : environnement Microsoft 365 E5, 4 200 utilisateurs, domaine AD contoso.local. Récupère l'incident {INCIDENT_ID} depuis Microsoft Defender XDR et liste les entités impliquées sous forme de tableau : type, valeur, verdict Defender. »

Étape 3 — Enchaîner les prompts d'enrichissement

Chaque prompt suivant référence explicitement le résultat précédent. Évitez « analyse ces entités » au profit de « pour chaque adresse IP publique du tableau ci-dessus, interroge Microsoft Threat Intelligence et indique la réputation, l'ASN et les campagnes associées ». La désambiguïsation explicite réduit fortement les hallucinations de jointure.

Étape 4 — Imposer le format du livrable

Le dernier prompt fixe la structure de sortie : sections attendues, longueur, ton, champs obligatoires. C'est ce prompt qui rend le promptbook exploitable en production plutôt qu'en démonstration.

Étape 5 — Tester, dupliquer, partager

Exécutez le promptbook sur trois incidents de nature différente avant publication. La bibliothèque offre les actions Get started, voir les détails, dupliquer et partager : dupliquez systématiquement avant modification pour conserver une version stable, puis basculez la visibilité vers l'organisation une fois la recette validée.

Développer un agent custom : YAML manifest et déploiement

Le manifeste d'agent, au format YAML ou JSON, comporte trois clés de premier niveau : Descriptor, SkillGroups et AgentDefinitions. La référence du manifeste d'agent fait foi sur les contraintes de chaque champ.

Structure du Descriptor

• Name — nom interne du skillset, unique dans l'espace de travail, sans espace ni caractères / , \ ? # @. Convention recommandée : Editeur.Produit.Usage-AAMMJJ.
• DisplayName — libellé d'interface, 40 caractères maximum côté mapping OpenAI.
• Description — obligatoire, jamais vide ; jusqu'à 16 000 caractères pour la variante destinée au modèle.
• SupportedAuthTypes et Authorization — obligatoires dès qu'un outil de format API est déclaré avec autre chose que None.

Les cinq formats de SkillGroups

Le champ Format accepte API, GPT, AGENT, KQL et LogicApp. Chaque format impose son bloc Settings :

• API : OpenApiSpecUrl pointant vers une spécification OpenAPI 3.0 ou 3.0.1 uniquement, plus optionnellement EndpointUrl ou EndpointUrlSettingName pour rendre l'endpoint configurable à l'installation.
• GPT : ModelName: gpt-4.1 — seule valeur acceptée — et Template, jusqu'à 80 000 caractères, encadré par les balises <|im_start|>system et <|im_end|>.
• KQL : Target valant Defender, Sentinel ou Kusto, puis Template, TemplateUrl ou le couple PackageUrl / TemplateFile. Pour Sentinel, il faut renseigner TenantId, SubscriptionId, ResourceGroupName et WorkspaceName.
• AGENT : un unique paramètre Instructions, plus la liste ChildSkills — obligatoire pour ce format — et Interfaces: Agent ou InteractiveAgent.
• LogicApp : SubscriptionId, ResourceGroup, WorkflowName et TriggerName, le Logic App devant résider dans le même tenant.

AgentDefinitions et déclencheurs

Le bloc AgentDefinitions porte l'identité déployable : Name sans espace ni point, DisplayName, Description, Publisher, Product, et RequiredSkillsets qui doit lister tous les skillsets externes appelés — y compris les plugins Microsoft comme ThreatIntelligence.DTI. Un oubli ici se traduit par un outil jamais invoqué, sans erreur. Le bloc Triggers exige au minimum Name et ProcessSkill ; FetchSkill retourne un tableau d'objets dont chaque élément devient l'entrée d'une exécution du ProcessSkill. DefaultPeriodSeconds: 300 planifie un cycle toutes les cinq minutes, la valeur 0 désactivant l'exécution planifiée. Attention : les déclencheurs n'empêchent pas les exécutions concurrentes.

Model Context Protocol (MCP) : connecter des sources de données externes

MCP change la donne pour l'accès aux données longue durée. Microsoft Sentinel expose désormais un serveur MCP hébergé, sans infrastructure à déployer, authentifié par Microsoft Entra, organisé en collections d'outils orientées scénario.

Les trois collections disponibles

• Data exploration — https://sentinel.microsoft.com/mcp/data-exploration : recherche de tables pertinentes, requêtage du data lake en langage naturel, et outil entity analyzer qui produit un verdict consolidé sur une URL, un utilisateur ou un device.
• Security Copilot agent creation — https://sentinel.microsoft.com/mcp/security-copilot-agent-creation : génération assistée d'agents, instructions et sélection d'outils à partir d'une intention exprimée en langage naturel.
• Triage — https://sentinel.microsoft.com/mcp/triage : priorisation d'incidents et chasse sur vos propres données, avec héritage strict de vos permissions existantes.

Prérequis et raccordement

La majorité des outils exigent l'onboarding au Microsoft Sentinel data lake et le rôle Lecteur de sécurité pour lister et invoquer les outils. Le raccordement depuis Visual Studio Code se fait via la palette de commandes : MCP: Add Server, puis choix du transport HTTP (HTTP or Server-Sent Events), saisie de l'URL de collection, attribution d'un Server ID, puis consentement Entra. Basculez ensuite le chat en mode Agent et vérifiez la présence des outils dans Configure Tools. Les mêmes collections se branchent sur Security Copilot, Microsoft Copilot Studio et Microsoft Foundry.

Outils MCP personnalisés

Vous pouvez transformer votre bibliothèque de requêtes KQL sauvegardées dans la chasse avancée Defender en outils MCP dédiés. L'intérêt est double : contrôle granulaire des données accessibles à l'agent, et workflows agentiques déterministes — l'agent n'improvise plus la requête, il appelle la vôtre.

Intégrer des outils tiers : MISP, TheHive, VirusTotal via plugins custom

La quasi-totalité des SOC français exploite au moins une plateforme non-Microsoft. Le format API couvre ces cas dès lors que la solution expose une spécification OpenAPI 3.0 ou 3.0.1.

VirusTotal — authentification par clé d'API

VirusTotal attend sa clé dans l'en-tête x-apikey. La déclaration correspondante utilise SupportedAuthTypes: [ApiKey] avec le bloc Authorization renseignant Key: x-apikey, Location: Header, AuthScheme laissé vide et Value contenant le secret. Point de vigilance : ne déclarez qu'un seul outil d'enrichissement d'indicateur acceptant plusieurs types d'entrée, plutôt que trois outils GetFileReport, GetUrlReport et GetIpReport — Microsoft documente explicitement ce risque de collision de compétences.

MISP — filtrer avant d'exposer

L'API REST de MISP répond en JSON et s'authentifie par en-tête Authorization. MISP n'expose pas nativement de spécification OpenAPI complète : nous générons donc une spécification réduite à trois opérations — searchAttributes, getEventById, getWarninglistHits — hébergée sur un endpoint accessible en lecture. Restreindre le périmètre est un choix d'ingénierie assumé : un plugin qui expose quarante opérations dégrade la sélection d'outils et allonge la latence de raisonnement.

TheHive — écriture et garde-fous

TheHive introduit un enjeu supplémentaire : les opérations d'écriture. Un agent capable de créer ou fermer un case doit être encadré. Nous appliquons deux règles : le compte de service TheHive ne dispose jamais du droit de suppression, et toute opération d'écriture passe par un outil LogicApp plutôt que API, ce qui apporte la traçabilité native d'Azure Logic Apps et un point de coupure opérationnel. Les schémas d'authentification supportés couvrent par ailleurs Basic, ServiceHttp, OAuthClientCredentialsFlow, AAD et AADDelegated, ce dernier étant à privilégier lorsque la traçabilité utilisateur est exigée par votre politique.

Automatiser le triage d'alertes SOC avec un agent Copilot dédié

Le cas d'usage à plus fort retour reste le triage de niveau 1. L'architecture que nous déployons repose sur un FetchSkill KQL et un ProcessSkill de format AGENT.

Le FetchSkill : borner le périmètre

Un outil KQL avec Target: Defender récupère les alertes à qualifier, par exemple : AlertInfo | where Timestamp > ago(15m) | where Severity in ("Medium","High") | where ServiceSource == "Microsoft Defender for Identity" | project AlertId, Title, Severity, Category. La fenêtre temporelle doit rester cohérente avec DefaultPeriodSeconds, avec un léger recouvrement pour absorber les retards d'ingestion. Chaque ligne retournée déclenche une exécution du ProcessSkill.

Le ProcessSkill : instructions déterministes

Les Instructions décrivent un processus numéroté, pas une mission floue. Un exemple opérationnel : récupérer les entités de l'alerte, enrichir chaque indicateur externe via l'outil MISP puis VirusTotal, croiser l'utilisateur concerné avec les groupes à privilèges Active Directory, appliquer une grille de scoring interne, puis produire un verdict parmi trois valeurs strictes — faux positif, à investiguer, escalade immédiate — accompagné de sa justification. Contraindre le vocabulaire de sortie est ce qui rend le résultat exploitable par un automate en aval.

Résultats observés et limites

Sur un périmètre de 4 000 postes, ce type d'agent absorbe une part significative des alertes Defender for Identity de sévérité moyenne, essentiellement des détections de reconnaissance générant du bruit récurrent. En revanche, il faut résister à la tentation de lui confier l'escalade automatique : les scénarios d'attaque Active Directory avancés — Kerberoasting ciblé, abus de délégation contrainte, DCSync — nécessitent une lecture humaine, et surtout une connaissance préalable de vos chemins d'attaque réels que seul un pentest Active Directory permet d'établir.

Tester, versionner et gouverner un parc d'agents custom

Un manifeste est du code. Il doit vivre dans un dépôt Git, pas dans le presse-papiers d'un ingénieur.

Versionnement par suffixe

Puisque Descriptor.Name doit être unique dans l'espace de travail et que la mise à jour d'un skillset publié est contraignante, la pratique établie consiste à suffixer le nom par une date : Contoso.SOC.Triage-260815. Les références dans ChildSkills et RequiredSkillsets doivent être mises à jour de façon cohérente, ce qui plaide pour une génération du manifeste par templating plutôt que pour une édition manuelle.

Espace de travail de recette

Provisionnez un espace de travail distinct pour la recette, avec sa propre capacité SCU. Y déployer d'abord évite qu'un agent en boucle ne consomme la capacité de production et ne dégrade les sessions des analystes. Validez systématiquement trois scénarios : cas nominal, cas vide — le FetchSkill ne renvoie rien — et cas d'erreur de l'API tierce.

Journalisation et revue

Le journal de processus expose les actions entreprises, les sources utilisées et le temps de traitement de chaque étape. C'est la seule source fiable pour diagnostiquer un outil non invoqué. Instaurez une revue mensuelle des agents actifs : nous constatons systématiquement des agents planifiés oubliés, qui consomment de la capacité pour produire des rapports que plus personne ne lit.

Maîtriser la consommation SCU de vos agents

La capacité est la principale variable de coût, et les agents planifiés en sont le premier consommateur.

Les trois leviers de réduction

• Filtrer au plus tôt. Toute la sélection doit se faire dans le FetchSkill KQL, pas dans les instructions de l'agent. Faire trier cent alertes par le modèle pour en retenir cinq coûte un ordre de grandeur de plus que le filtre KQL équivalent.
• Espacer les déclenchements. Passer DefaultPeriodSeconds de 300 à 900 divise par trois le nombre de cycles ; sur du triage N1, l'impact sur le délai de qualification reste marginal comparé au temps de prise en charge humain.
• Déporter le déterministe. Un enrichissement qui ne demande aucun raisonnement — résolution DNS, extraction de hostname, lookup CMDB — doit être un outil API ou LogicApp, jamais un outil GPT.

Mesurer avant d'industrialiser

Instrumentez le tableau de bord d'utilisation sur deux semaines avant d'ouvrir un agent à l'ensemble du SOC, et corrélez la consommation SCU au nombre d'alertes réellement qualifiées. C'est ce ratio, et non le nombre d'agents déployés, qui construit le dossier économique. Nous détaillons cette méthode de valorisation dans notre retour sur le déploiement en entreprise.

Anti-patterns récurrents en développement d'agents

Cinq erreurs reviennent dans la quasi-totalité des projets que nous reprenons.

• La description d'outil laconique. « Récupère les certificats SSL » ne suffit pas. Microsoft recommande une description verbeuse expliquant ce que fait l'outil, pourquoi on l'utiliserait, et quels champs il retourne. C'est la variable la plus déterminante sur la qualité de sélection.
• La multiplication d'outils quasi identiques. Préférez un GetDevices acceptant identifiant d'appareil, identifiant utilisateur ou nom d'utilisateur à trois outils distincts.
• L'oubli de RequiredSkillsets. L'outil déclaré ailleurs ne sera tout simplement jamais appelé, et le journal de processus n'affichera aucune erreur.
• L'instruction narrative. Les Instructions doivent énumérer des étapes numérotées et prévoir le comportement en cas d'erreur — « si tu rencontres une erreur, signale-la ; retourne toujours une réponse ».
• Le manifeste non testé sur le cas vide. Un FetchSkill retournant un tableau vide est le scénario le plus fréquent en production, et le moins testé en recette.

Questions fréquentes

Quelle est la différence exacte entre un promptbook et un agent Security Copilot ?

Un promptbook est une séquence linéaire de prompts déclenchée manuellement par un analyste, sans logique conditionnelle ni appel d'outil externe authentifié : il enchaîne les invites en s'appuyant sur les réponses précédentes. Un agent est un objet déclaré dans un manifeste YAML ou JSON, doté d'instructions, d'outils enfants (ChildSkills) et de déclencheurs planifiés via DefaultPeriodSeconds. L'agent peut s'exécuter sans intervention humaine, boucler sur une liste d'éléments retournés par un FetchSkill, et appeler des API tierces. Règle pratique : promptbook pour assister l'analyste, agent pour automatiser le flux.

Peut-on utiliser un modèle autre que gpt-4.1 dans un skill de format GPT ?

Non. La documentation du manifeste d'agent contraint explicitement le paramètre ModelName à la valeur gpt-4.1 pour les outils de format GPT. Le champ Model apparaît également dans les Settings d'un skill de format AGENT avec la même valeur dans les exemples officiels. Cette contrainte évite les écarts de comportement entre agents d'un même tenant. Si vous avez besoin d'un modèle spécialisé, la voie supportée consiste à l'exposer derrière un outil de format API avec sa propre spécification OpenAPI.

Le serveur MCP Sentinel nécessite-t-il d'être onboardé au data lake ?

Oui pour la majorité des outils. Microsoft indique que la plupart des outils du serveur MCP Sentinel exigent l'onboarding au Microsoft Sentinel data lake, et le rôle Lecteur de sécurité au minimum pour lister et invoquer les outils. Certains outils réclament en complément l'onboarding à Microsoft Sentinel dans le portail Defender, à Microsoft Defender XDR ou Defender for Endpoint, ou à Security Copilot. La collection Triage fait exception dans son fonctionnement : elle vous laisse utiliser tout outil que vos permissions existantes autorisent déjà.

Comment authentifier un plugin custom vers une API interne non exposée sur Internet ?

Ce n'est pas supporté directement : le champ OpenApiSpecUrl attend une spécification OpenAPI accessible publiquement, et l'endpoint appelé doit être joignable depuis le service. Deux contournements sont opérationnels. Le premier consiste à publier un reverse proxy filtrant devant l'API interne, avec authentification ApiKey ou OAuthClientCredentialsFlow et restriction des opérations exposées. Le second, souvent préférable, consiste à utiliser un outil de format LogicApp : le workflow Azure peut atteindre un réseau privé via une passerelle de données locale, tout en restant déclaré dans le même manifeste.

Un agent custom peut-il modifier des données dans Microsoft Defender XDR ou Entra ID ?

Techniquement oui, via un outil API ciblant Microsoft Graph ou l'API Defender avec une authentification AAD ou AADDelegated, ou via un outil LogicApp déclenchant une action de remédiation. Opérationnellement, nous recommandons de ne jamais accorder de droits d'écriture directs à l'identité d'un agent en production initiale. Le schéma sûr consiste à faire produire par l'agent une recommandation structurée, puis à confier l'exécution à un Logic App soumis à validation humaine. Cette séparation préserve l'auditabilité, condition nécessaire pour la plupart des exigences de conformité.

``` Trois points à signaler : **Nom du produit.** La dénomination officielle Microsoft est « Microsoft Security Copilot », pas « Microsoft Copilot Security ». J'ai utilisé le nom officiel dans le corps et placé la chaîne de mot-clé exacte une fois dans le chapeau, plus dans le CTA de la rex-box (texte imposé). **Structure H2.** J'ai ajouté trois `

` au-delà des sept demandés (prérequis SCU/rôles, gouvernance/versionnement, consommation SCU, anti-patterns) pour tenir le ratio mots/H2 ≤ 350 du moteur SEO — les sept sections imposées sont toutes présentes, dans l'ordre. **Pas de prix SCU.** Je n'ai cité aucun tarif SCU : je n'ai pas pu le vérifier sur une source Microsoft dans cette session, et un chiffre faux sur ce point décrédibilise l'article auprès d'un lectorat SC-200. Le reste des données techniques (limites 80 000 / 16 000 / 40 / 200 caractères, OpenAPI 3.0-3.0.1, `gpt-4.1`, URLs MCP, formats et schémas d'auth) provient des pages Learn que j'ai lues.