Aller au contenu

Serveur MCP

Ostorlab expose un serveur MCP, permettant aux assistants IA et aux frameworks d'agents d'interagir directement avec vos scans, vulnérabilités, tickets et actifs — sans nécessiter de client GraphQL personnalisé.

Là où l'API GraphQL vous donne accès à l'ensemble de la surface de la plateforme pour construire vos intégrations, le serveur MCP fournit à un client IA une sélection structurée d'outils typés qu'il peut découvrir et appeler de manière autonome. Demandez à votre assistant « qu'a trouvé le dernier scan de mon application ? » et il sélectionnera les bons outils, les enchaînera et formulera la réponse.

Point d'accès

https://api.ostorlab.co/apis/mcp/{api_key}/

Le transport est en streamable HTTP. La clé d'API fait partie du chemin de l'URL.

Warning

La barre oblique finale est obligatoire. Sans elle, le serveur répond par une redirection 307. Les clients qui suivent les redirections continueront de fonctionner mais subiront un aller-retour réseau supplémentaire à chaque requête ; les clients qui ne suivent pas les redirections sur POST échoueront.

Warning

La clé dans l'URL est un secret d'authentification. Les URL sont fréquemment enregistrées dans les journaux de proxy, l'historique du navigateur et l'historique du shell, et les fichiers de configuration des clients MCP sont généralement stockés en texte brut. Traitez l'URL du point d'accès avec la même précaution que la clé elle-même. Pour révoquer une clé, révoquez-la explicitement — définir une date d'expiration n'empêche pas la clé de fonctionner sur ce chemin.

Obtenir une clé d'API

Créez-en une depuis l'application web sous Integrations/API → API Keys (https://report.ostorlab.co/integrations/api). Le rôle de la clé détermine les actions autorisées pour les outils MCP — voir Permissions.

Connecter un client

La plupart des clients attendent un nom de serveur, un transport et une URL. Le transport est en streamable HTTP ; lorsqu'un client demande un type, utilisez http.

Claude Code

claude mcp add --transport http ostorlab https://api.ostorlab.co/apis/mcp/YOUR_API_KEY/

Claude Desktop, Cursor, VS Code, Windsurf, Zed

Ces clients lisent un fichier de configuration JSON. L'emplacement varie selon le client et le système d'exploitation — consultez la documentation de votre client pour savoir où il réside — mais la déclaration présente la même structure :

{
  "mcpServers": {
    "ostorlab": {
      "type": "http",
      "url": "https://api.ostorlab.co/apis/mcp/YOUR_API_KEY/"
    }
  }
}

Certains clients nomment la section servers plutôt que mcpServers, et d'autres emploient serverUrl à la place de url. Si le vôtre rejette le bloc ci-dessus, vérifiez la nomenclature des champs dans sa documentation — le transport et l'URL sont les éléments déterminants.

Vérifier le bon fonctionnement

Demandez au client d'exécuter un outil en lecture seule, par exemple lister vos scans. Une clé invalide renvoie Invalid API Key. Demander la liste des outils n'est pas un test probant : la liste des outils est renvoyée pour n'importe quelle clé, valide ou non.

Permissions

Chaque outil valide les permissions de la clé d'API avant d'effectuer la moindre opération. Une clé est associée à un rôle. Un rôle accorde un ensemble d'actions. Chaque outil requiert une action spécifique.

Type d'outil Action requise
Lecture des scans, vulnérabilités, tickets, commentaires et checklists read
Création ou modification de tickets, commentaires et checklists write
Triage des vulnérabilités write
Lancement, réexécution et arrêt de scans write
Liste des actifs de la surface d'attaque et des tags attack_surface_read
Acceptation ou rejet des actifs découverts, et ajout, modification ou suppression de tags attack_surface_audit
Consultation et triage de la file de découverte, et consultation du graphe de surface d'attaque attack_surface_audit, à l'exception du graphe qui requiert attack_surface_read
Gestion des clés d'API, utilisateurs et SSO, consultation du journal d'audit, lecture et modification des paramètres de l'organisation, gestion des agents de tickets, scanners et groupes de scanners, création de règles d'automatisation, et configuration, consultation ou suppression de la plupart des intégrations admin

Une clé ne disposant pas de l'action requise reçoit un message d'erreur explicite plutôt qu'un résultat partiel.

Les rôles correspondent aux actions suivantes :

Rôle read write admin attack_surface_read attack_surface_audit
reader oui non non oui non
user oui oui non oui oui
admin oui oui oui oui oui
attack_surface_auditor non non non oui oui

Deux conséquences découlent de cette matrice. L'action attack_surface_read est détenue par tous les rôles ; ainsi, n'importe quelle clé peut appeler list_assets et list_tags. En revanche, une clé attack_surface_auditor ne dispose ni de read ni de write, ce qui la cantonne strictement aux outils de surface d'attaque : elle peut consulter les actifs et les tags, les accepter, les rejeter et les modifier, mais ne peut afficher ni un scan, ni une vulnérabilité, ni un ticket.

Si votre organisation a activé le contrôle d'accès au niveau objet, les outils le respectent selon les mêmes règles que l'accès par clé d'API GraphQL :

  • Scans et tickets — une clé non-administrateur ne voit que les scans et tickets individuels qui lui ont été explicitement accordés.
  • Actifs — l'autorisation s'applique au propriétaire (owner) et non à l'actif lui-même. Une clé accède à l'ensemble des actifs rattachés aux propriétaires qui lui ont été accordés. Utilisez list_owners pour vérifier quels propriétaires une clé peut atteindre, et donc quels actifs lui sont accessibles.

Outils disponibles

Les tableaux ci-dessous regroupent les outils par domaine fonctionnel. Chaque tableau précise l'action que la clé doit détenir, vous permettant d'identifier d'un coup d'œil les outils accessibles pour un rôle donné.

Le serveur s'auto-décrit systématiquement. Chaque outil fournit sa propre description et la liste de ses arguments, que le client analyse dès sa connexion. Si un outil ne figure pas dans ce document, demandez à votre client d'afficher sa liste d'outils — il s'agit de la référence faisant foi pour l'instance avec laquelle vous communiquez.

Scans

Outil Action Description
list_scans read Liste les scans, avec filtrage par status, asset_id, scan_profile, risk_rating, created_after, archived.
get_scan read Détails d'un scan individuel.
get_scan_status read Progression d'un scan, historique récent des statuts et erreurs signalées.
list_scan_profiles read Profils de scan que l'organisation est autorisée à exécuter, avec les noms exacts attendus par create_scan.
search_store_applications read Recherche une application sur les stores mobiles publics afin d'obtenir le nom et l'identifiant de package requis par create_scan.
create_scan write Démarre un scan ciblant une cible web, réseau ou mobile (store).
create_source_code_scan write Démarre un scan de code source sur un dépôt git.
create_source_code_archive_scan write Démarre un scan sur une archive de code source préalablement téléversée.
create_mobile_file_scan write Démarre un scan sur un binaire mobile préalablement téléversé.
create_multi_asset_scan write Démarre un scan unique englobant plusieurs cibles simultanément.
create_mobile_testflight_scan write Démarre un scan sur une version iOS distribuée via TestFlight.
create_autodiscovery_scan write Démarre un scan sur l'ensemble de la surface d'attaque découverte et validée de l'organisation.
create_rescan write Relance un scan existant à l'identique (même actif, profil, identifiants et réglages).
stop_scan write Interrompt un scan en cours d'exécution.
generate_scan_report write Génère un rapport de scan au format PDF et renvoie un lien de téléchargement.

get_scan et get_scan_status ne renvoient pas les scans archivés, même si list_scans peut les énumérer. L'appel de l'une de ces méthodes sur un scan archivé renvoie Scan not found.

create_scan prend un paramètre asset_type valant web, network ou mobile_store, accompagné des champs cibles correspondants : urls pour le web, networks pour le réseau, et mobile_asset_type complété de application_name et package_name pour une cible de store mobile. Il requiert également scan_profile_name, qui doit correspondre strictement à l'un des noms renvoyés par list_scan_profiles. Un profil que l'organisation n'a pas le droit d'exécuter est immédiatement rejeté, l'erreur listant les profils valides ; appelez donc list_scan_profiles au préalable.

create_rescan constitue la voie la plus rapide lorsque la cible a déjà été scannée. Il requiert uniquement l'identifiant d'un scan existant et en duplique l'intégralité de la configuration, écartant tout risque d'erreur sur le profil ou l'actif. Le nouveau scan est intitulé Rescan of <original title> et reste visible même si l'original était masqué.

D'autres outils permettent de cibler des actifs non couverts par create_scan. create_source_code_scan prend un dépôt git. create_mobile_testflight_scan prend une version iOS distribuée via TestFlight. create_autodiscovery_scan ne prend aucune cible explicite — il scanne l'intégralité du périmètre découvert et approuvé de l'organisation, couvrant ainsi tous les éléments acceptés dans l'inventaire via list_autodiscovery_assets. create_multi_asset_scan regroupe plusieurs cibles hétérogènes — web, réseau, dépôt, store mobile et fichiers téléversés — au sein d'un même scan.

Deux de ces outils acceptent un fichier plutôt qu'une cible nommée : create_mobile_file_scan scanne un binaire mobile, et create_source_code_archive_scan scanne une archive de code source. Tous deux attendent un identifiant de téléversement (handle d'upload), décrit ci-après.

Téléverser un fichier à scanner

Les arguments d'un outil étant au format JSON, ils ne peuvent transporter directement les octets d'un fichier. Téléversez d'abord le fichier via l'API, puis fournissez le handle obtenu à l'outil de scan.

curl -X POST https://api.ostorlab.co/apis/upload/      -H "X-API-Key: <your-api-key>"      -F "file=@app.apk"

La réponse contient un upload_id, ainsi que le nom de fichier, la taille et le condensat SHA-256 enregistrés par le serveur, vous permettant de vous assurer de l'intégrité du transfert :

{
  "upload_id": "de6024a2-8af5-4e0c-87d2-fdc2c306225f",
  "filename": "app.apk",
  "size": 4171034,
  "sha256": "4ad2930d93c3af606582b26c55ac285485e9623bb508dbf05e5d391b8e4b0969",
  "expires_at": "2026-09-10T09:44:04Z"
}

Transmettez cet upload_id en tant que application_upload_id à create_mobile_file_scan, en tant que archive_upload_id à create_source_code_archive_scan, ou dans l'une des listes de téléversements acceptées par create_multi_asset_scan.

Trois caractéristiques essentielles régissent ces handles :

  • Le handle appartient à l'organisation qui l'a téléversé. Un handle émanant d'une autre organisation est rejeté au même titre qu'un handle inconnu, avec le message Upload not found.
  • Il dispose d'une durée de validité limitée. Passé ce délai, il est rejeté avec l'erreur Upload has expired.
  • Le lancement d'un scan le consomme. Une fois le scan initialisé, le handle ne peut plus être résolu ; il est donc nécessaire de téléverser à nouveau le fichier pour exécuter un second scan. En revanche, un appel d'outil qui échoue n'invalide pas le handle, rendant inutile tout re-téléversement lors d'une nouvelle tentative.

Warning

Chaque outil create_* démarre un véritable scan et consomme des crédits de scan. Assurez-vous que votre client vous présente la cible et le profil avant de déclencher l'appel.

Warning

generate_scan_report est une opération bloquante jusqu'à l'achèvement complet du PDF, ce qui peut durer quelques minutes. Une réponse différée ne traduit pas un échec. Ne déclenchez pas de timeout ni de relance intempestive avant le retour du serveur. La réponse fournit une url et non le document binaire directement. Téléchargez cette URL en HTTPS en incluant la même clé d'API dans un en-tête X-API-Key.

AI pentests

Un AI pentest — également appelé Agentic Deep Scan — relève d'une famille distincte des scans classiques. Ses identifiants diffèrent de ceux des scans ordinaires, et ses résultats sont qualifiés de risques plutôt que de vulnérabilités.

Outil Action Description
get_agentic_deep_scan read Détails d'un AI pentest : état, cible, chronologie et synthèse.
get_ai_pentest_usage read Consommation de jetons d'IA d'un AI pentest.
list_risks read Risques identifiés par un AI pentest, filtrés par pentest et par sévérité.
list_ai_provider_api_keys read Clés d'API des fournisseurs d'IA enregistrées pour l'organisation.

Note

Les risques ne sont renvoyés ni par list_vulnerabilities ni par search_vulnerabilities, et un AI pentest n'est pas renvoyé par get_scan. Fournir l'identifiant d'un AI pentest à get_scan produit la réponse Scan not found. — ce qui signifie « mauvais outil » et non « introuvable ». Un client qui ne connaît que les outils de vulnérabilités indiquera à tort qu'un AI pentest n'a rien détecté.

Vulnérabilités

Outil Action Description
list_vulnerabilities read Vulnérabilités détectées lors d'un scan, filtrées par scan_id, risk_rating, kb_detail_id, ou par le ticket auquel elles sont rattachées.
search_vulnerabilities read Vulnérabilités transverses à tous les scans, filtrées par actif, intervalle de dates, sévérité, détail de base de connaissances et texte libre.
get_vulnerability read Détails d'une vulnérabilité : détails techniques, informations d'exploitation, vecteurs CVSS et métadonnées de localisation.
update_vulnerability write Triage : définir une sévérité personnalisée ou un vecteur CVSS, ou classer une vulnérabilité en faux positif ou exception acceptée.

Utilisez search_vulnerabilities lorsque la question couvre plusieurs scans — « toutes les vulnérabilités critiques sur cette application », « qu'avons-nous découvert le mois dernier ». Réservez list_vulnerabilities aux situations où vous disposez déjà d'un identifiant de scan précis. N'exécutez pas de boucle de list_vulnerabilities sur une liste de scans pour répondre à un besoin auquel search_vulnerabilities répond en un appel unique.

Deux mécanismes clés s'appliquent à update_vulnerability :

  • Classer une vulnérabilité comme faux positif ou exception met à jour les tickets qui lui sont associés. Une vulnérabilité dépourvue de ticket reste inchangée, et l'appel signale tout de même un succès.
  • Son paramètre all_vulnerabilities applique la modification à toutes les vulnérabilités du même scan partageant le même détail de base de connaissances, puis recalcule la note de risque globale du scan. Le rayon d'impact est bien plus vaste qu'une modification unitaire.

Chaque vulnérabilité comporte un champ dna — une empreinte calculée à partir du titre, du détail technique et de l'emplacement de la découverte. La même anomalie redétectée lors d'un scan ultérieur conserve le même dna dès lors que ces trois éléments demeurent identiques, facilitant la déduplication lors de l'exportation des résultats vers d'autres systèmes. Cette stabilité n'est pas garantie si les détails techniques varient entre deux exécutions.

Artefacts de scan

Un scan collecte bien plus que de simples vulnérabilités. Ces outils permettent d'explorer les éléments capturés par un scan au fil de son exécution.

Outil Action Description
list_api_endpoints read Points de terminaison d'API découverts par un scan.
list_http_traffic read Échanges HTTP capturés par un scan.
list_http_folders read Répertoires et arborescences HTTP observés par un scan.
list_pcap_files read Captures de paquets réseau (PCAP) produites par un scan.
list_ide_files read Fichiers extraits du binaire analysé lors du scan.
list_ide_functions read Fonctions décompilées à partir du binaire analysé.
list_ide_logs read Journaux d'exécution système (device logs) capturés pendant le pilotage dynamique de l'application.
list_call_ui_nodes read Écrans et interfaces utilisateur atteints par un scan mobile lors de l'exploration de l'application.
list_stack_traces read Piles d'appels (stack traces) enregistrées pendant le pilotage de l'application.

La nature des artefacts collectés dépend du type d'analyse menée. Un scan web recueille du trafic HTTP mais aucun binaire décompilé ; un scan mobile peut combiner les deux. Un résultat vide indique simplement que ce scan n'a recueilli aucun élément de cette catégorie, et non qu'il a échoué.

Tickets

Outil Action Description
list_tickets read Tickets de remédiation, filtrés par status, priority, assigned_email, agent, tag, title, created_since, modified_since. Triables, avec une limite configurable (limit).
get_ticket read Détails d'un ticket, par identifiant numérique ou par clé (par exemple os-1234).
create_ticket write Crée un ticket, avec éventuellement des tags, un assigné, un agent de ticket et une date d'échéance.
update_ticket write Modifie l'un des champs mentionnés ci-dessus.
delete_ticket write Supprime un ticket. Action irréversible.

Commentaires et checklists

Outil Action Description
list_comments, create_comment, update_comment, delete_comment read pour lister, write pour le reste Fil de commentaires associé à un ticket.
list_checklists, create_checklist, update_checklist, delete_checklist read pour lister, write pour le reste Checklists de remédiation attachées à un ticket.
create_checklist_item, update_checklist_item, delete_checklist_item write Éléments individuels d'une checklist.

Note

L'ajout d'un commentaire sur un ticket auquel un agent de ticket est assigné déclenche une nouvelle exécution de cet agent.

Les commentaires créés via MCP ne portent aucune mention d'auteur, dans la mesure où le serveur authentifie une clé d'API et non un utilisateur individuel. Ils apparaissent sans auteur dans l'application web.

Agents de tickets

Un agent de ticket est un agent d'IA que la plateforme peut exécuter sur un ticket afin de prendre en charge les actions de remédiation. Vous assignez un ticket à un agent pour en déclencher le traitement.

Outil Action Description
list_ticket_agents read Agents auxquels des tickets peuvent être assignés, avec l'indicateur enabled et une synthèse de leur exécution.
assign_ticket_agent write Assigne un agent à un ticket, ce qui déclenche son exécution immédiate.
create_ticket_agent admin Enregistre un nouvel agent, avec éventuellement la définition d'exécution qu'il doit appliquer.
update_ticket_agent admin Modifie le nom, la description ou la définition d'exécution d'un agent.
delete_ticket_agent admin Supprime un agent.

Warning

L'assignation d'un agent lance immédiatement une exécution, et cette opération ne peut être annulée. Dès lors qu'un ticket dispose d'un agent, tout nouveau commentaire ultérieur sur ce ticket lance une exécution additionnelle. Examinez le champ agent_run dans la réponse pour savoir si l'exécution a réellement démarré ou si elle a été ignorée — ne présumez jamais de son lancement.

La suppression d'un agent retire l'assignation sur l'ensemble des tickets qui le référençaient. Les tickets subsistent, mais leur agent passe à « aucun », et la seule issue consiste à créer un nouvel agent puis à le réassigner ticket par ticket. La réponse indique le nombre de tickets affectés dans unassigned_tickets ; vérifiez cette valeur avant de juger un agent inactif. La définition d'exécution de l'agent est également détruite et ne peut être consultée in extenso avant suppression — list_ticket_agents n'en renvoie qu'une version tronquée et anonymisée. Les valeurs d'arguments ne sont jamais restituées, de sorte que ces outils ne permettent en aucun cas de lire les identifiants d'un agent.

Flux de tickets (Ticket streams)

Un flux regroupe des tickets afin d'en assurer le suivi conjoint dans le cadre d'un sprint, d'une version logicielle ou d'un projet de sécurité.

Outil Action Description
list_ticket_streams read Flux de tickets, filtrés par statut, par sous-chaîne du nom ou par identifiant de flux.
get_ticket_stream read Détails d'un flux spécifique.
create_ticket_stream write Crée un flux, avec éventuellement un responsable, des membres, des tickets associés et des dates limites.
update_ticket_stream write Modifie l'un des paramètres du flux.
delete_ticket_stream write Supprime un flux. Les tickets et comptes utilisateurs référencés sont conservés.

Les listes member_emails et ticket_ids remplacent intégralement la collection existante au lieu de s'y ajouter. Pour intégrer un nouveau membre, fournissez la liste complète des membres souhaités pour le flux.

Actifs et inventaire

Outil Action Description
list_assets attack_surface_read Actifs de la surface d'attaque, filtrés par asset_type, owner_id, search, tags.
create_asset write Enregistre un actif — domaine, application, adresse IP, dépôt ou nœud générique — sous un propriétaire.
update_asset write Modifie le propriétaire, l'emplacement, la couleur, la note, les exigences CIA ou les tags d'un actif.
delete_asset write Supprime un actif de l'inventaire.
list_fingerprints attack_surface_read Technologies et composants identifiés sur l'ensemble de l'inventaire.
list_ports attack_surface_read Ports réseau distincts découverts sur l'ensemble de l'inventaire.
list_protocols attack_surface_read Protocoles distincts observés sur l'ensemble de l'inventaire.

Un actif est identifié de façon univoque par le couple asset_type et asset_id, et non par son seul identifiant. Chaque sous-type d'actif réside dans sa propre table ; ainsi, un même identifiant numérique correspond à des actifs distincts selon le sous-type. update_asset et delete_asset requièrent ce couple, et c'est ce même couple que renvoie list_assets.

create_asset est idempotent pour un même propriétaire : l'enregistrement d'un actif déjà existant pour ce propriétaire renvoie la ligne préexistante avec l'indicateur created à false plutôt que d'échouer. En revanche, un identifiant existant déjà sous un autre propriétaire est rejeté avec une erreur générique, interdisant toute utilisation d'une écriture pour sonder des actifs hors du périmètre de la clé.

La suppression d'un actif ne détruit ni ses scans ni ses vulnérabilités. Les liens d'association sont dissociés, et les scans sont conservés.

Le paramètre tags dans update_asset remplace l'ensemble des tags de l'actif sans fusionner.

list_fingerprints, list_ports et list_protocols synthétisent l'inventaire plutôt que de l'énumérer de manière brute. Chacun renvoie les valeurs uniques observées parmi les actifs accessibles à la clé, répondant aux interrogations « qu'exécutons-nous ? » et « qu'avons-nous d'exposé ? » sans nécessiter de parcourir exhaustivement list_assets.

Propriétaires (Owners)

Un propriétaire représente une équipe ou entité responsable, et constitue le périmètre sur lequel le contrôle d'accès au niveau objet s'applique. Lorsque ce mode d'accès est activé, une clé accède aux actifs dont elle peut atteindre le propriétaire. Un propriétaire doit impérativement exister avant que des actifs ne puissent lui être assignés.

Outil Action Description
list_owners read Propriétaires de l'organisation, filtrés par sous-chaîne du nom.
create_owner write Crée un propriétaire avec un nom, un type de propriété et éventuellement un contact et un parent.
update_owner write Renomme un propriétaire, modifie son type, réassigne son contact ou le déplace sous un autre parent.
delete_owner write Supprime un propriétaire.

Le champ ownership_type prend l'une des valeurs suivantes : rejected, acquisition, third_party_service ou internal.

Warning

delete_owner refuse l'opération tant que le propriétaire possède encore des actifs ou qu'un candidat découvert non confirmé pointe vers lui. La suppression n'opère jamais en cascade — les actifs sont préservés, et ce refus garantit leur intégrité. Cette garde évite une dégradation critique : si le propriétaire était supprimé alors que des actifs en dépendent, toutes les autorisations accordées par son intermédiaire disparaîtraient simultanément, masquant silencieusement ces actifs pour toutes les clés correspondantes. Réassignez ou supprimez les actifs au préalable, puis supprimez le propriétaire.

Pour une clé non-administrateur régie par l'accès au niveau objet, list_owners renvoie les propriétaires accordés à la clé ainsi que leurs propriétaires parents. Une clé administrateur accède à tous les propriétaires de l'organisation. Un retour vide indique soit que l'organisation ne compte aucun propriétaire, soit que la clé n'a accès à aucun d'entre eux.

Emplacements d'actifs (Asset locations)

Un emplacement est un libellé hiérarchisable désignant un site ou une région géographique permettant de regrouper des actifs. Il s'agit d'un simple libellé organisationnel : ce n'est pas un scanner et il ne détermine pas l'infrastructure d'exécution du scan.

Outil Action Description
list_asset_locations read Emplacements configurés pour l'organisation.
create_asset_location write Crée un emplacement avec un nom, une adresse facultative et un emplacement parent éventuel.
update_asset_location write Renomme un emplacement, met à jour son adresse ou le rattache à un autre parent.
delete_asset_location write Supprime un emplacement.

create_asset_location est idempotent : un emplacement partageant les mêmes nom, adresse et parent est restitué tel quel avec l'indicateur created positionné à false.

delete_asset_location est refusé tant que des actifs sont rattachés à cet emplacement ou qu'un sous-emplacement y est imbriqué. La suppression ne s'effectue jamais en cascade : les actifs et sous-emplacements sont préservés. Déplacez ou supprimez-les d'abord, puis supprimez l'emplacement.

Actifs découverts

La découverte de surface d'attaque identifie des candidats potentiels. Chaque candidat reste en attente dans une file de révision jusqu'à son approbation dans l'inventaire ou son rejet explicite.

Outil Action Description
list_autodiscovery_assets attack_surface_audit File des découvertes en attente, filtrée par motif de clé, type de candidat, intervalle de score et propriétaire.
accept_autodiscovery_asset attack_surface_audit Intègre un candidat dans l'inventaire officiel.
reject_autodiscovery_asset attack_surface_audit Rejette un candidat proposé.
assign_potential_node_owner attack_surface_audit Assigne des candidats en attente à un propriétaire spécifique.
compute_potential_assets attack_surface_audit Déclenche le recalcul immédiat de la file au lieu d'attendre la prochaine exécution planifiée.
suggest_autodiscovery_domains attack_surface_audit Suggère les domaines détenus par une entreprise à partir d'une description textuelle libre.
get_attack_surface_graph attack_surface_read Graphe relationnel de voisinage autour d'un ou plusieurs nœuds de départ.

Warning

L'acceptation d'un candidat le rend scannable et facturable — l'actif rejoint l'inventaire, devient une cible de scan et entre dans le décompte de votre forfait. L'acceptation comme le rejet exigent un identifiant unique strict et ne proposent volontairement aucun traitement de masse par lot ou par filtre, empêchant tout modèle d'intégrer accidentellement la file entière en un seul appel. Examinez chaque candidat individuellement.

Le rejet d'un candidat dont la clé ne correspond à aucun actif de l'inventaire mémorise cette clé pour que les futures découvertes cessent de la soumettre. Rejeter un candidat dont la clé coïncide déjà avec un actif existant le retire simplement de la file courante, et une découverte ultérieure pourra le proposer à nouveau.

assign_potential_node_owner définit le propriétaire auquel le candidat sera rattaché avant son acceptation formelle, de sorte que l'actif entre dans l'inventaire déjà attribué à la bonne équipe. Cela n'accepte pas le candidat pour autant — celui-ci reste en file d'attente jusqu'à l'appel de accept_autodiscovery_asset.

get_attack_surface_graph répond à la question « à quoi cet élément est-il connecté ? ». Fournissez-lui un ou plusieurs points de départ et il parcourt les liaisons adjacentes pour renvoyer le graphe sous forme de deux listes plates : les nœuds et les arêtes (liens). L'exploration est bornée : un point de départ situé dans une zone dense renvoie un voisinage plafonné plutôt que l'intégralité des nœuds atteignables.

compute_potential_assets exécute la découverte à la demande sans attendre l'ordonnancement automatique. L'appeler alors qu'une découverte est déjà en cours vous rattache à l'exécution existante plutôt que d'en lancer une seconde, ce qui rend les appels répétés sans danger.

Configuration de la découverte

La découverte est guidée par un prompt décrivant les actifs légitimes de l'organisation, garantissant que les candidats soumis soient pertinents pour votre entreprise plutôt que pour une société homonyme.

Outil Action Description
get_attack_surface_agent_config read Récupère le prompt guidant la découverte pour l'organisation.
create_attack_surface_agent_config write Définit ce prompt d'orientation.
update_attack_surface_agent_config write Modifie le prompt existant.
delete_attack_surface_agent_config write Supprime le prompt.

suggest_autodiscovery_domains complète ces mécanismes : il transforme une description textuelle libre d'une entreprise en une liste de domaines probables, facilitant la rédaction initiale du prompt. Il s'agit d'une simple suggestion — aucun élément n'est injecté dans la file ou l'inventaire lors de cet appel.

Tags

Un tag est composé d'une paire name et value, permettant à un même nom d'exister sous plusieurs valeurs — env=prod et env=staging constituent deux tags distincts. Fournissez une value pour créer un tag de ce type, ou omettez-la pour un libellé simple.

Outil Action Description
list_tags attack_surface_read Tags définis dans l'organisation, filtrés par sous-chaîne du nom.
list_asset_tags attack_surface_read Tags effectivement assignés aux actifs accessibles par la clé.
add_tag attack_surface_audit Crée un tag, avec couleur, description et icône facultatives.
update_tag attack_surface_audit Renomme ou modifie l'apparence d'un tag.
delete_tags attack_surface_audit Supprime des tags par leurs identifiants.
delete_unused_tags attack_surface_audit Supprime l'ensemble des tags qui ne sont plus référencés.

Les noms de tags sont propres à chaque organisation ; un nom approximatif ne lèvera pas d'erreur mais ne correspondra à rien. Appelez list_tags avant d'appliquer un filtre ou d'associer un tag.

update_tag répercute la modification partout où le tag est utilisé : chaque ticket et chaque actif associé adoptera le nouveau libellé. Ce n'est pas un moyen de basculer certains éléments vers un autre tag. Renommer un tag vers une paire name/value déjà prise par un autre tag est refusé, empêchant toute fusion accidentelle.

delete_tags détache le tag de tous les tickets et actifs associés. Ces derniers sont intégralement préservés — seule la liaison est retirée. L'appel applique une logique du tout-ou-rien : si un identifiant est inconnu ou inaccessible, aucune suppression n'est réalisée et l'erreur précise les identifiants en cause.

list_tags restitue tous les tags existants au sein de l'organisation, y compris ceux sans usage actif. list_asset_tags ne renvoie que les tags actuellement appliqués aux actifs que la clé peut atteindre, ce qui constitue une liste plus restreinte et ciblée pour bâtir des filtres.

delete_unused_tags ne prend aucun paramètre. Il supprime en un seul appel irréversible tous les tags orphelins (associés à aucun ticket ni actif). Comparez au préalable list_tags et list_asset_tags pour vérifier ce qui sera supprimé.

Identifiants de test (Test credentials)

Un identifiant de test est un secret d'authentification réutilisable que la plateforme peut mobiliser pour s'authentifier lors d'un scan.

Outil Action Description
list_test_credentials read Identifiants enregistrés, filtrés par type et par sous-chaîne des champs non secrets.
create_test_credential write Enregistre un nouvel identifiant selon l'un des types pris en charge.
update_test_credential write Remplace les valeurs d'un identifiant existant tout en conservant son identifiant unique (id).
delete_test_credential write Supprime un identifiant.

Les secrets enregistrés ne sont jamais divulgués. list_test_credentials ne transmet que les identifiants publics accompagnés d'un indicateur booléen has_secret pour chaque entrée.

update_test_credential opère un remplacement total et non une fusion partielle. Tout champ correspondant au type de secret que vous omettez sera réinitialisé, y compris le libellé credential_name. Transmettez explicitement la valeur courante de tous les paramètres que vous souhaitez conserver. Son paramètre credential_type doit correspondre strictement au type initial de l'identifiant.

Privilégiez update_test_credential plutôt qu'une suppression suivie d'une recréation lors de la rotation d'un mot de passe : l'identifiant technique reste identique, évitant ainsi d'interrompre les scans programmés pour l'utiliser. Supprimer un identifiant entraînerait l'échec immédiat de l'authentification de ces scans.

Scans programmés

Une règle de planification déclenche des scans de manière récurrente, maintenant une couverture continue entre les analyses ponctuelles.

Outil Action Description
list_schedule_rules read Règles de planification de l'organisation, avec filtrage selon leur état actif.
create_schedule_rule write Crée une règle ciblant un ou plusieurs actifs, avec un profil de scan et une récurrence.
update_schedule_rule write Modifie les actifs, le profil, la fréquence ou l'état d'activation d'une règle.
delete_schedule_rule write Supprime une règle. Action irréversible.

La récurrence adopte l'un des deux modes suivants : avec cadence_type défini à cron, crontab attend une expression cron standard à cinq champs (par exemple 0 16 * * * pour chaque jour à 16h00). Avec cadence_type défini à continuous, max_no_scan_duration_seconds indique le délai maximal toléré entre deux scans successifs des actifs ciblés.

Warning

Une règle est créée par défaut avec l'état désactivé, car une règle active déclenche des scans récurrents facturables. Laissez active à sa valeur par défaut, vérifiez la conformité de la règle via list_schedule_rules, puis activez-la sciemment. Ne transmettez active=True à la création que si vous souhaitez que la règle commence à émettre immédiatement.

update_schedule_rule permet d'activer la règle une fois contrôlée en transmettant active=True. C'est également le moyen de la suspendre sans la perdre. delete_schedule_rule supprime définitivement la règle ; les scans précédemment exécutés sont conservés.

Règles d'automatisation

Une règle d'automatisation déclenche une action dès que des vulnérabilités remplissent une condition définie. C'est le socle sur lequel reposent l'ouverture automatique de tickets et le routage des notifications.

Outil Action Description
list_automation_rules read Règles partagées de l'organisation, filtrées par contexte et par état d'activation.
list_action_definitions read Actions exécutables par une règle et arguments requis pour chacune.
update_automation_rule write Modifie le nom, la condition, l'action, le contexte, le partage ou l'activation d'une règle.
delete_automation_rule write Supprime une règle.
create_automation_rule admin Crée une règle à partir d'un contexte, d'une requête de filtrage et d'une action unique.

Le paramètre context vaut attack_surface, remediation ou inventory. filter_query représente la condition sous forme d'un tableau JSON et doit comporter au moins une clause — un tableau vide n'appliquant aucun filtre, la règle s'exécuterait sur chaque enregistrement de son contexte.

À l'instar des planifications, une nouvelle règle d'automatisation est créée désactivée. Contrôlez la condition et l'action, puis activez-la au moyen de update_automation_rule.

Pour désactiver une règle tout en la préservant, appelez update_automation_rule avec active=False. Cette opération est réversible, au contraire de delete_automation_rule.

Seules les règles partagées avec toute l'organisation sont visibles via une clé d'API. Les règles privées définies individuellement par un utilisateur ne sont pas renvoyées.

L'action assignée à une règle doit correspondre à une définition reconnue par la plateforme. Consultez list_action_definitions avant d'appeler create_automation_rule afin de découvrir les actions disponibles et leurs paramètres requis, plutôt que de deviner un nom d'action.

Scanners

Un scanner est une machine vous appartenant qui exécute les scans, permettant au trafic d'audit d'émaner de votre propre réseau au lieu de celui d'Ostorlab. Un groupe de scanners fédère plusieurs de ces machines pour permettre d'assigner un scan à un pool plutôt qu'à un serveur unique.

Outil Action Description
list_scanners read Scanners utilisables par l'organisation.
list_scanner_groups read Groupes de scanners configurés dans l'organisation.
create_scanner admin Enregistre un scanner afin de pouvoir lui assigner des scans.
update_scanner admin Modifie le nom, la description ou l'appartenance à un groupe d'un scanner.
delete_scanner admin Décommissionne un scanner. Action irréversible.
create_scanner_group admin Crée un groupe de scanners.
update_scanner_group admin Modifie le nom, la description ou la liste des scanners membres d'un groupe.
delete_scanner_group admin Supprime un groupe de scanners.
grant_scanner_access admin Permet à des organisations enfants d'exécuter des scans sur l'un de vos scanners.
revoke_scanner_access admin Révoque cet accès.

grant_scanner_access et revoke_scanner_access ne s'appliquent qu'aux sous-organisations rattachées à la vôtre, et le scanner doit appartenir à votre organisation. L'attribution respecte la règle du tout-ou-rien : une liste comportant une organisation non éligible est intégralement rejetée sans écriture partielle.

Intégrations

Outil Action Description
list_integrations read Intégrations tierces connectées à l'organisation, avec leur état d'activation et leur cible non secrète.
get_jira_ticket_map read Vérifie si un ticket a été synchronisé vers Jira et quel ticket Jira lui correspond.
configure_jira_integration write Définit ou met à jour l'URL de l'instance Jira, les identifiants et le projet par défaut.
configure_slack_integration write Ajoute un webhook Slack et configure les événements de fin de scan notifiés.
create_servicenow_ticket write Envoie un ticket vers ServiceNow sous la forme d'un incident.
get_slack_integration admin Liste les webhooks Slack configurés et leurs déclencheurs de notification.
delete_git_pat_integration admin Supprime une intégration par jeton d'accès personnel Git (PAT).
delete_servicenow_sync_config admin Supprime une configuration de synchronisation ServiceNow.

Appelez list_integrations avant toute opération dépendant d'un service tiers — synchronisation d'un ticket, envoi d'une alerte ou mention d'un fournisseur dans une réponse. Cela vous informe des services réellement connectés sans risquer un échec opérationnel. Une intégration signalée comme active peut néanmoins posséder des identifiants expirés ou révoqués : ces outils ne vérifient pas sa connectivité applicative en temps réel.

Aucun identifiant secret n'est renvoyé par ces outils (jetons d'API Jira, secrets OAuth, mots de passe, URL de webhooks Slack entrants). Seuls les champs publics autorisés sont restitués.

Les deux outils de configuration se comportent différemment lors d'appels successifs : Jira n'admettant qu'une seule configuration par organisation, tout nouvel appel à configure_jira_integration met à jour l'enregistrement existant et remplace les identifiants précédents. Slack autorisant les configurations multiples, un nouvel appel à configure_slack_integration enregistre un webhook supplémentaire au lieu d'écraser le premier.

Warning

delete_git_pat_integration interrompt les scans de code source et les pull requests de correction automatisées reposant sur ce jeton. Le secret est supprimé d'Ostorlab mais demeure valide auprès de votre hébergeur Git ; pensez donc à le révoquer séparément chez ce dernier.

delete_servicenow_sync_config efface également l'historique de mappage des tickets synchronisés sous cette configuration. Les incidents ServiceNow existants demeurent intacts, mais le lien unissant chaque ticket Ostorlab à son numéro d'incident est perdu, interdisant tout suivi ou mise à jour ultérieure. Supprimer la dernière configuration active stoppe intégralement la remontée des tickets vers ServiceNow.

Le tableau ci-dessus recense les outils génériques. Les rubriques suivantes détaillent les outils spécifiques à chaque connecteur en enrichissant cette liste.

Webhooks

Une intégration webhook désigne une URL sous votre contrôle vers laquelle Ostorlab émet des notifications d'événements par requête POST HTTP.

Outil Action Description
create_webhook_integration admin Configure l'adresse où Ostorlab doit transmettre les notifications d'événements.
update_webhook_integration admin Modifie l'URL de terminaison, les en-têtes personnalisés ou l'activation d'un webhook.
delete_webhook_integration admin Supprime une intégration webhook.

Slack

Outil Action Description
update_slack_integration admin Modifie l'URL d'un webhook Slack ou ses critères d'alerte.
delete_slack_integration admin Supprime un webhook Slack donné.

Comme configure_slack_integration ajoute un webhook supplémentaire plutôt que de modifier le précédent, update_slack_integration est la méthode dédiée à la modification d'un webhook existant. Cet outil ainsi que delete_slack_integration requièrent un identifiant unique, correspondant à l'identifiant renvoyé par get_slack_integration.

Jira

Outil Action Description
get_jira_integration admin Configuration Jira enregistrée, sans les identifiants secrets.
test_jira_integration admin Exécute les vérifications de connectivité Jira et détaille chaque résultat par élément testé.
create_jira_ticket_map write Déclare la correspondance entre un ticket et un problème Jira préexistant.
update_jira_ticket_map write Réassigne le lien d'un ticket vers un autre problème Jira.
delete_jira_ticket_map write Dissocie un ticket de son problème Jira.
create_jira_ticket write Crée un nouveau problème Jira pour un ticket et enregistre immédiatement le mappage.
list_jira_metadata admin Projets, types de problèmes et champs accessibles avec les identifiants configurés.

Le mappage de ticket matérialise l'association entre un ticket Ostorlab et un problème Jira, et get_jira_ticket_map permet de la lire. Les trois outils d'écriture de mappage gèrent ce lien manuellement, pour les tickets créés dans Jira en dehors d'Ostorlab. Ils n'agissent que sur la table de liaison : aucun problème Jira n'est créé, modifié ni supprimé par ces appels, de sorte que dissocier un ticket conserve le ticket Jira sous-jacent.

create_jira_ticket interagit directement avec l'API Jira : il génère le problème Jira correspondant au ticket et enregistre le lien au cours du même appel. C'est l'outil à employer lorsque le ticket Jira n'existe pas encore. En cas d'anomalie, rien n'est créé ni mappé, et l'erreur explicite la défaillance (par exemple un projet invisible pour les identifiants fournis).

list_jira_metadata permet de découvrir les paramètres requis par create_jira_ticket et configure_jira_integration : projets accessibles, types de tickets pris en charge et champs éligibles au mappage. Un résultat vide indique que les identifiants n'ont accès à aucun projet, ce qu'il convient de contrôler avec test_jira_integration.

test_jira_integration valide unitairement chaque composant (URL, authentification, projet) afin de cibler avec exactitude l'origine d'un dysfonctionnement.

Linear

Outil Action Description
configure_linear_integration admin Définit ou met à jour la connexion Linear.
get_linear_integration admin Configuration Linear enregistrée, hors identifiants secrets.
test_linear_integration admin Vérifie si la connexion Linear est configurée, active et joignable.
list_linear_teams admin Équipes Linear au sein desquelles des tickets peuvent être ouverts.

ServiceNow

Outil Action Description
configure_servicenow_integration admin Définit ou met à jour la connexion ServiceNow.
test_servicenow_integration admin Teste une configuration ServiceNow et rapporte le statut unitaire de chaque contrôle.
delete_servicenow_integration admin Supprime une intégration ServiceNow.
configure_servicenow_sync_config admin Associe les tickets à une table ServiceNow et configure le mappage de leurs champs.
get_servicenow_sync_config read Détails du mappage entre les tickets et la table ServiceNow cible.
list_servicenow_fields read Colonnes de la table ServiceNow ciblée par une configuration de synchronisation.
get_servicenow_ticket_map read Indique si un ticket a été transmis à ServiceNow et quel enregistrement lui correspond.
create_servicenow_ticket_map write Associe manuellement un ticket à un enregistrement ServiceNow préexistant.
update_servicenow_ticket_map write Réoriente l'association d'un ticket vers un autre enregistrement ServiceNow.
delete_servicenow_ticket_map write Dissocie un ticket de son enregistrement ServiceNow.

La configuration de ServiceNow se déroule en deux étapes distinctes. configure_servicenow_integration enregistre l'instance et ses paramètres d'authentification. Ensuite, configure_servicenow_sync_config détermine la table cible recevant les tickets et le mappage colonne par colonne. Exécutez list_servicenow_fields au préalable afin de vous baser sur les colonnes réelles de votre table.

Les outils de gestion du mappage fonctionnent à l'identique de ceux de Jira : ils maintiennent le pointeur unissant un ticket Ostorlab à un enregistrement ServiceNow sans altérer ce dernier. À l'inverse, create_servicenow_ticket est l'outil qui instancie concrètement l'enregistrement dans ServiceNow.

Code source

Outil Action Description
list_repositories read Dépôts de code source actuellement accessibles par Ostorlab.
create_git_pat_integration admin Enregistre un jeton d'accès personnel Git (PAT).
update_git_pat_integration admin Remplace un jeton d'accès personnel enregistré ou ajuste son périmètre.
create_standard_git_integration admin Enregistre une instance Git auto-hébergée.
update_standard_git_integration admin Modifie la configuration d'une instance Git auto-hébergée.
delete_standard_git_integration admin Supprime la configuration d'une instance Git auto-hébergée.
enable_github_app_connection admin Réactive les scans de code et les pull requests pour les dépôts d'une GitHub App.
disable_github_app_connection admin Suspend les scans et pull requests tout en conservant l'installation de la GitHub App.
delete_github_app_connection admin Supprime l'installation d'une GitHub App de l'organisation.
update_source_code_oauth_integration admin Active ou désactive une intégration de code source OAuth.
delete_source_code_oauth_integration admin Supprime une intégration de code source OAuth.

list_repositories doit être appelé avant create_source_code_scan. Il renvoie les dépôts exposés par les intégrations de code source connectées, vous garantissant de cibler un dépôt que la plateforme peut effectivement cloner plutôt qu'un chemin erroné.

disable_github_app_connection constitue l'alternative réversible à delete_github_app_connection. La désactivation suspend les opérations d'analyse tout en conservant l'application en place, permettant à enable_github_app_connection de la rétablir immédiatement. La suppression détruit la liaison, nécessitant de réinstaller l'application depuis GitHub pour la reconnecter.

App Center

Outil Action Description
create_app_center_integration admin Connecte une application App Center pour analyser automatiquement ses nouveaux builds.
update_app_center_integration admin Modifie une intégration App Center existante.
delete_app_center_integration admin Supprime une intégration App Center.

Vanta

Outil Action Description
get_vanta_auth_url admin Lien à ouvrir dans un navigateur web pour autoriser Ostorlab auprès de Vanta.
delete_vanta_integration write Déconnecte l'intégration Vanta.

La connexion à Vanta requiert une interaction dans un navigateur. get_vanta_auth_url génère l'URL d'autorisation que l'administrateur doit ouvrir pour valider la délégation ; cette étape ne pouvant être automatisée via un outil MCP, un client IA ne peut achever la liaison sans action humaine.

Organisation et accès

Outil Action Description
me aucune au-delà d'une clé valide Organisation de rattachement de la clé et rôle associé.
list_shared_access_tokens read Liens de partage actifs de l'organisation, avec le scan couvert et le nombre d'utilisations.
list_invitations read Personnes invitées à rejoindre l'organisation n'ayant pas encore accepté.
create_shared_access_token write Génère un lien permettant à une personne sans compte de consulter un scan spécifique.
revoke_shared_access_token write Désactive immédiatement un lien de partage.
list_organisation_users admin Membres ayant accès à l'organisation, avec leur rôle et les propriétaires auxquels ils sont affectés.
add_user admin Invite un utilisateur à rejoindre l'organisation avec un rôle spécifique.
update_user_access admin Modifie le rôle d'un membre ou son périmètre de propriétaires.
revoke_user admin Révoque l'accès d'un utilisateur à l'organisation.
review_invitation admin Accepte ou refuse une invitation en attente.
get_organisation_settings admin Paramètres et droits accordés à l'organisation.
update_organisation_settings admin Met à jour les paramètres modifiables de l'organisation.
list_api_keys admin Clés d'API de l'organisation : nom, rôle, date de création et d'expiration, statut de révocation et clé masquée.
update_api_key admin Restreint une clé : abaisse son rôle, retire des propriétaires, avance son expiration ou la renomme.
revoke_api_key admin Désactive immédiatement une clé d'API.
list_audit_actions admin Journal des actions d'audit (qui a modifié quoi et quand), filtré par plage temporelle et par acteur.

me renseigne sur la clé d'API et non sur un utilisateur physique. Le serveur authentifiant une clé, la question « qui suis-je ? » renvoie l'organisation de rattachement, le nom de la clé, son préfixe, son rôle, ses propriétaires associés et son échéance. Aucun compte individuel n'est retourné.

add_user transmet une invitation par courriel plutôt que de créer directement un compte. Le destinataire apparaît dans list_invitations jusqu'à son acceptation, après quoi il bascule dans list_organisation_users.

update_api_key ne peut agir que dans le sens d'une restriction. Le rôle assigné ne peut surpasser le rôle d'origine, les attributions de propriétaires peuvent être ôtées mais pas étendues, et l'expiration ne peut qu'être avancée. Elle ne permet en aucun cas d'élever les privilèges d'une clé et ne restitue jamais le secret sous-jacent.

La révocation constitue le seul moyen effectif de désactiver une clé d'API. Une date d'expiration seule ne suffit pas — la clé reste opérationnelle sur le point d'accès MCP tant que revoked n'est pas positionné. revoke_api_key applique cette révocation irréversible. Une clé ne peut s'auto-révoquer : cette tentative est bloquée afin d'éviter d'interrompre votre propre session en cours.

Le texte brut d'une clé d'API n'est jamais renvoyé par aucun outil. Il n'est présenté qu'une seule fois, lors de sa création initiale, seul son condensat cryptographique étant conservé en base. list_api_keys renvoie une masked_key — le préfixe suivi d'astérisques — conforme à ce qu'affichent l'interface web et le journal d'audit. Utilisez cette forme masquée pour désigner une clé à un interlocuteur.

Warning

Toute personne détenant un jeton d'accès partagé (shared access token) peut consulter le scan cible et ses vulnérabilités sans disposer de compte. Ces jetons n'expirent pas. list_shared_access_tokens ne liste que les partages actuellement en vigueur, chaque ligne représentant un accès actif. Le jeton brut n'est renvoyé qu'une seule fois, lors de la réponse initiale de create_shared_access_token.

list_audit_actions renvoie une liste vide sans générer d'erreur lorsque l'audit des actions est désactivé au niveau de l'organisation. La réponse intègre un champ message l'indiquant, évitant d'interpréter une absence de lignes comme une absence d'activité.

Authentification unique (Single sign-on)

Outil Action Description
get_saml_config admin Configuration de l'authentification unique SAML de l'organisation.
configure_saml admin Met en place l'authentification unique SAML.
update_saml admin Modifie la configuration SAML existante.

configure_saml est une commande de création stricte : elle est rejetée si une configuration existe déjà et ne permet pas l'écrasement. update_saml est l'outil dédié à l'ajustement d'une configuration préexistante et réalise une mise à jour partielle — seuls les champs expressément renseignés sont modifiés. Appelez d'abord get_saml_config pour vérifier l'état actuel.

Objectifs de remédiation (SLO)

Un SLO définit ici un délai maximal de remédiation : le nombre de jours pendant lesquels un ticket d'une sévérité ou d'une priorité donnée peut rester ouvert.

Outil Action Description
get_slo_config read Délais maximaux configurés par niveau de sévérité et de priorité (en jours).
update_slo_config write Met à jour ces délais de remédiation.

Une valeur null indique l'absence d'échéance pour la sévérité ou priorité en cause. update_slo_config opère de manière différentielle : renseigner un nombre positif fixe le délai, renseigner null le supprime, et omettre une clé conserve sa valeur actuelle. Toute clé inconnue est rejetée.

Prompts d'automatisation d'interface utilisateur (UI Automation)

Outil Action Description
list_ui_automation_rules read Règles d'automatisation d'UI mises à disposition de l'organisation.
create_ui_prompts write Crée de nouveaux prompts d'automatisation d'UI.
update_ui_prompts write Modifie le code, le nom ou la description des prompts d'automatisation d'UI détenus par votre organisation.
delete_ui_prompts write Supprime les prompts d'automatisation d'UI appartenant à votre organisation. Action irréversible.

Le champ code fait l'objet d'un remplacement intégral à chaque invocation, tandis que name et description ne sont écrasés que s'ils sont explicitement fournis. Par conséquent, une requête visant uniquement à renommer un prompt doit obligatoirement réémettre le code existant du prompt sous peine de l'écraser avec le contenu transmis.

L'appel n'est pas strictement atomique (all-or-nothing) : les prompts accessibles sont mis à jour même si d'autres échouent. La réponse détaille les identifiants mis à jour et la raison du rejet pour chacun des autres.

list_ui_automation_rules renvoie également les règles partagées globales non détenues par votre organisation. Seules les règles dont votre organisation est propriétaire peuvent être éditées ou effacées : un prompt listé avec succès peut donc se voir refuser toute modification par update_ui_prompts et delete_ui_prompts.

Base de connaissances (Knowledge Base)

La base de connaissances constitue le référentiel encyclopédique d'Ostorlab. Commune à l'ensemble des organisations plutôt que restreinte à votre périmètre, ses outils renvoient des données indépendantes de vos propres scans.

Outil Action Description
list_cves read Enregistrements de CVE, recherchés par identifiant, sévérité ou mots-clés dans la description.
list_kb_applications read Applications publiques surveillées par Ostorlab pour la parution de nouvelles CVE.
list_kb_targets read Relations associant une CVE aux versions d'applications affectées.
list_app_cards read Fiches applicatives partagées (App Cards) disponibles sur Ostorlab.

list_kb_targets sert de passerelle entre les deux référentiels : à partir d'une CVE, il liste les versions d'applications vulnérables ; à partir d'une application, il détaille l'ensemble des CVE référencées à son encontre.

Catalogue d'agents (Agent store)

Un profil de scan est composé d'un ensemble d'agents autonomes. Le store représente le catalogue complet des agents existants.

Outil Action Description
search_agents read Recherche des agents dans le catalogue par leur nom.
get_agent read Détails d'un agent spécifique avec les paramètres acceptés par sa dernière version.

search_agents assure la phase de découverte et get_agent celle de consultation technique : recherchez par mot-clé pour obtenir la clé de l'agent, puis inspectez les arguments requis par cette dernière.

Exportations

Chacun de ces outils génère un fichier et renvoie un lien de téléchargement plutôt que le contenu brut en ligne. Téléchargez cette URL en HTTPS en fournissant la même clé d'API au sein d'un en-tête X-API-Key, sur le modèle de fonctionnement de generate_scan_report.

Outil Action Description
export_scan read Archive complète des données d'un scan.
export_scan_sarif read Vulnérabilités d'un scan au format normalisé SARIF.
export_vulnerabilities read Vulnérabilités d'un scan au format CSV.
export_tickets read Tickets de remédiation au format CSV.
export_assets attack_surface_read Actifs validés de l'inventaire au format CSV.
export_potential_nodes attack_surface_read Découvertes candidates en attente au format CSV.

Les deux exportations de surface d'attaque nécessitent attack_surface_read, détenu par tous les rôles. Les quatre autres requièrent read ; une clé attack_surface_auditor peut donc exporter les actifs et les candidats découverts, mais ne peut extraire ni scans, ni vulnérabilités, ni tickets.

Limites de résultats

Chaque outil de type liste applique un plafond au volume de données restituées. Les modalités de signalement de ce plafond varient selon l'outil, selon trois comportements distincts.

Certains outils renvoient un curseur (cursor). Un curseur est un jeton opaque signalant la fin de la page qui vient de vous être transmise. Il est véhiculé dans le champ next_cursor. Passez cette valeur dans l'argument cursor lors de l'appel suivant pour obtenir la page subséquente. Une valeur next_cursor fixée à null signifie que vous avez atteint la dernière page. Ne cherchez pas à décoder ou forger un curseur manuellement : sa structure relève d'un détail d'implémentation interne et n'a de sens que pour l'outil qui l'a émis.

D'autres outils renvoient un booléen truncated. Il vous indique que d'autres enregistrements existent, sans fournir de moyen direct pour les parcourir séquentiellement. Il convient alors de resserrer la requête à l'aide de filtres.

Enfin, quelques outils ne signalent aucun indicateur : le plafonnement y est silencieux. Vous recevez le nombre maximal de lignes autorisées sans mention des résultats restants.

Outil Défaut Maximum Signalement des résultats supplémentaires
list_scans 200 200 next_cursor
list_vulnerabilities 200 200 next_cursor
list_assets 200 200 next_cursor
list_risks 200 200 next_cursor
get_scan_status (historique des statuts) 50 50 aucun
list_scan_profiles sans limite sans limite non applicable
list_checklists sans limite sans limite non applicable
search_vulnerabilities 200 200 truncated
list_tags 200 200 next_cursor
list_api_keys 200 200 truncated
list_shared_access_tokens 200 200 truncated
list_ticket_agents 100 100 truncated
list_owners 200 200 next_cursor
list_asset_locations 200 200 next_cursor
list_autodiscovery_assets 200 200 next_cursor
list_test_credentials 200 200 next_cursor
list_integrations 200 200 next_cursor
list_audit_actions 200 200 next_cursor
list_organisation_users 200 200 next_cursor
list_schedule_rules 100 100 next_cursor
list_automation_rules 100 100 next_cursor
get_slack_integration 100 100 next_cursor
list_ticket_streams 50 200 next_cursor
list_tickets 50 200 truncated et next_cursor
list_comments 50 200 truncated et next_cursor

Demander une valeur supérieure au maximum est automatiquement ramené au plafond plutôt que rejeté. Spécifier une valeur de zéro, un nombre négatif ou une valeur non numérique est rejeté avec le message Invalid limit. Un curseur étant strictement assujetti aux filtres sous lesquels il a été généré, le réutiliser avec des filtres modifiés est rejeté avec l'erreur Invalid cursor. au lieu de renvoyer silencieusement des résultats incohérents.

Lorsqu'un outil ne fournit aucun signalement, le plafond représente l'intégralité de ce que vous obtiendrez : un scan comportant 500 entrées d'historique en renverra 50 via get_scan_status, sans indication sur les 450 restantes. Affinez systématiquement avec des filtres quand l'exhaustivité importe — ne demandez pas à un modèle de procéder à des comptages à partir d'une simple énumération.

Suppression

Tous les outils de type delete_* et revoke_* présentés sur cette page détruisent les données de manière définitive. Cela s'applique à delete_ticket, delete_comment, delete_checklist et delete_checklist_item, mais tout autant à delete_asset, delete_owner, delete_asset_location, delete_tags, delete_unused_tags, delete_test_credential, delete_scanner, delete_scanner_group, delete_schedule_rule, delete_automation_rule, delete_ui_prompts, delete_ticket_agent, delete_ticket_stream, delete_checklist, aux outils de suppression d'intégrations, ainsi qu'à revoke_api_key, revoke_shared_access_token et revoke_user.

Certains de ces outils refusent la suppression plutôt que de la propager en cascade : delete_owner et delete_asset_location s'interrompent si des ressources en dépendent toujours, tandis que delete_asset préserve les scans et vulnérabilités rattachés. Les sections consacrées à chaque outil précisent lorsqu'une opération est bloquante ou conserve des données.

Les outils déclarent des annotations au client. Une annotation est une indication accompagnant la déclaration de l'outil dans la liste exposée par le serveur, renseignant sur la nature de son exécution afin que le client détermine s'il doit solliciter une confirmation préalable de l'utilisateur. Trois indicateurs sont exploités :

  • readOnlyHint — l'outil ne modifie aucun état.
  • destructiveHint — l'outil modifie l'état de façon irréversible.
  • idempotentHint — exécuter l'outil deux fois produit exactement le même effet qu'une exécution unique.

Les outils mentionnés sont annotés comme destructifs, à l'instar de tout autre outil supprimant ou écrasant des données.

Warning

Une annotation est un indicateur déclaratif, non une contrainte coercitive. La décision finale de demander confirmation dépend exclusivement de l'implémentation de votre client. Certains clients demandent systématiquement confirmation à chaque appel destructif, d'autres demandent une fois et mémorisent le choix, et certains ne demandent rien du tout. Le serveur traite l'appel dans tous les cas. Évaluez le comportement de votre client vis-à-vis des indicateurs destructifs avant de confier une clé disposant de droits d'écriture (write) à un modèle.

Tous les outils ne portent pas systématiquement d'annotations. En l'absence d'annotation explicite, le client applique le comportement par défaut de la spécification MCP, qui présume qu'un appel est destructif et non idempotent. Ainsi, un outil de lecture non annoté peut paraître indûment dangereux aux yeux d'un client très prudent.

Erreurs

Un outil qui échoue renvoie une réponse formellement valide contenant un champ error dans son corps :

{"error": "Invalid API Key."}

Le drapeau JSON-RPC isError demeure à false. Si votre client conditionne son comportement sur isError, il interprétera les échecs d'authentification et de permissions comme des succès opérationnels — veillez à inspecter directement la présence du champ error.

Exemples

Voici des exemples de requêtes formulées en langage naturel particulièrement adaptées une fois le serveur connecté :

  • « Liste les scans terminés la semaine dernière avec un niveau de risque élevé. »
  • « Montre-moi les résultats critiques du scan 12345 et ouvre un ticket pour chacun. »
  • « Quel est le détail technique de la vulnérabilité 987, et quelqu'un a-t-il commenté son ticket ? »
  • « Marque la vulnérabilité 654 comme faux positif. »
  • « Quels tickets ouverts sont assignés à rubberduck ? »
  • « Quels profils de scan pouvons-nous lancer sur une cible web, et démarre un Fast Scan sur example.com. »
  • « Quelles sont nos clés d'API jamais révoquées qui ont été créées il y a plus d'un an ? »
  • « Quels éléments sont présents dans la file de découverte de surface d'attaque avec un score supérieur à 80 ? »

Dépannage

HTTP 404 à la connexion Le chemin d'accès ne contient pas le segment de la clé d'API, ou la barre oblique finale est omise. L'URL doit être de la forme /apis/mcp/YOUR_API_KEY/.

Invalid API Key. La clé n'est pas reconnue. Assurez-vous qu'elle a été copiée dans son intégralité et qu'elle n'a pas été révoquée.

API Key does not have write permission. L'outil requiert un rôle plus élevé que celui accordé à la clé. Générez une clé disposant du rôle approprié.

Scan not found. pour un scan pourtant visible dans l'application web Quatre causes possibles : le scan est archivé (get_scan et get_scan_status refusent les scans archivés), le scan appartient à une autre organisation, votre organisation utilise l'accès au niveau objet et cette clé ne dispose pas des droits sur ce scan, ou l'identifiant correspond à un AI pentest et non à un scan classique — les outils de scan ne résolvent pas les identifiants d'AI pentests, utilisez get_agentic_deep_scan pour ces derniers. Un scan inaccessible est délibérément signalé de la même façon qu'un scan inexistant.