Détection d'agents IA

Les agents IA et navigateurs autonomes représentent une part croissante du trafic web. OpenAI Operator, Claude for Chrome, Perplexity Comet, Browserbase et d’autres frameworks d’agents pilotent de vraies sessions dans de vrais navigateurs, si bien que les seuls contrôles User-Agent ne suffisent pas. cside Device Intelligence expose ces visiteurs via l’objet bot renvoyé par /token/v2/verify dans l’Events API.

Ce que cside détecte

Le verdict bot combine deux modèles et des contrôles déterministes :

• Le modèle 1 note le fingerprint de l’appareil et les signaux réseau : marqueurs headless et d’automatisation (navigator.webdriver, utilisation de CDP, variables globales d’automatisation injectées), anomalies de rendu et de polices, caractéristiques TCP et TLS, et IP de datacenter ou d’hébergeur
• Le modèle 2 note le comportement dans la page : mouvement du curseur, timing des événements, événements non fiables (déclenchés par un script) et hooks d’API JavaScript
• Les agents connus sont associés à un bot_agent_id, comme google-googleother, lorsque le trafic correspond à la signature d’un crawler ou d’un agent connu

Ensemble, ils identifient les agents navigateur autonomes, les navigateurs headless (Puppeteer, Playwright, Selenium), les runtimes instrumentés pilotés via WebDriver ou CDP, ainsi que les crawlers et scrapers classiques. La détection s’exécute server-side après l’envoi de la télémétrie par le navigateur, modifier les headers ne suffit donc pas à la contourner.

Lire le verdict bot

Échangez le token de session sur /token/v2/verify avec votre clé API backend. La réponse contient un objet bot :

{
  "status": "completed",
  "bot": {
    "is_bot": true,
    "bot_probability": 0.94,
    "bot_confidence": 0.88,
    "bot_agent_id": "",
    "reasons": [
      "navigator.webdriver is set",
      "cursor movement scored as automated"
    ],
    "model_1_score": 0.91,
    "model_1_threshold": 0.7,
    "model_2_score": 0.86,
    "model_2_threshold": 0.6,
    "session_event_count": 42
  }
}

Champ	Type	Signification
is_bot	boolean	Le verdict. true lorsque la probabilité dépasse le seuil de décision ou qu’un contrôle déterministe se déclenche.
bot_probability	number	Probabilité que le visiteur soit un bot, de 0 à 1.
bot_confidence	number	Degré de certitude du modèle dans cette probabilité, de 0 à 1. Une confiance faible signifie généralement que peu de données comportementales étaient disponibles.
bot_agent_id	string	Bot ou agent identifié lorsque le trafic correspond à une signature connue. Vide en l’absence de correspondance.
reasons	string[]	Explications lisibles derrière le verdict.
model_1_score, model_1_threshold	number	Score du modèle fingerprint et réseau, et seuil qui lui est appliqué.
model_2_score, model_2_threshold	number	Score du modèle comportemental et son seuil. Absents lorsqu’aucune donnée comportementale n’a été collectée.
session_event_count	number	Nombre d’événements comportementaux produits par la session.

Basez votre décision sur is_bot. Utilisez bot_probability et bot_confidence lorsque vous voulez des réponses graduées, par exemple un challenge entre 0,5 et le seuil, et un blocage au-dessus.

const { status, bot } = data;

if (status !== "completed" || !bot) {
  // L'évaluation est en attente ou a échoué : fail open
  return allow();
}

if (bot.is_bot) {
  return respondWithChallenge(bot.reasons);
}

Combinez le verdict avec d’autres signaux de la même réponse pour plus de confiance :

• Les champs d’automatisation de fingerprint (web_driver, cdp, tamper_injected_global_ids, tamper_probe_blocked) montrent directement les preuves d’automatisation
• fingerprint.developer_tools_detected est courant chez les agents exécutés localement
• fingerprint.virtual_machine_detected signale les sessions exécutées dans une VM ou une sandbox
• ip_enrichment.hosting et ip_enrichment.is_datacenter_ip signalent le trafic provenant de fournisseurs cloud

Exemple d’intégration

Dans votre JavaScript côté client, demandez le token de session de fingerprint :

const result = await sendClientTelemetry({
  userId: "1234567890",
});

if (result.errors) {
  console.error(result.errors);
  throw new Error("La requête de télémétrie a échoué.");
}

const { token: sessionToken } = result;

Dans votre backend, échangez le token de session avec https://api.cside.com/token/v2/verify, puis évaluez bot.is_bot :

const response = await fetch("https://api.cside.com/token/v2/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CSIDE_FINGERPRINT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ token: sessionToken }),
});

const data = await response.json();

if (!response.ok) {
  throw new Error(data.error || "L'échange de fingerprint a échoué.");
}

if (data.status !== "completed") {
  // 202 pending ou évaluation échouée : réessayez plus tard ou fail open
  return allow();
}

if (data.bot?.is_bot) {
  // Bloquez, challengez ou journalisez la requête
  return respondWithChallenge();
}

/token/v2/verify renvoie 202 Accepted avec { "status": "pending" } tant que l’évaluation est en cours de traitement. Réinterrogez après un court délai ou fail open.

Dans le tableau de bord

La ligne Bot / Agents de l’onglet Overview d’une session affiche le même verdict avec les scores de modèle qui le sous-tendent. L’onglet Captured metadata liste les caractéristiques du modèle de bot lorsqu’un vecteur de caractéristiques a été capturé.

Cas d’usage courants

• Protéger les formulaires et les tunnels de paiement - rejetez le trafic des agents avant qu’il n’atteigne le paiement ou la création de compte
• Restreindre le scraping IA du contenu payant - appliquez des limites de débit ou des niveaux d’accès différents lorsque des agents IA sont détectés
• Mesurer la part des agents dans votre trafic - enregistrez bot.is_bot, bot_probability, bot_agent_id et la chaîne user_agent pour rendre compte de la part automatisée de votre trafic
• Preuves de rétrofacturation et de fraude - associez l’objet bot à fingerprint.device_id pour constituer une piste d’audit des sessions automatisées

Étapes suivantes

• Lisez la référence Events API complète pour la forme exacte de la réponse
• Consultez l’objet bot_evaluation de l’export S3 pour les mêmes champs dans les exports batch
• Contactez l’équipe commerciale pour activer Device Intelligence sur votre compte