Comment gérer le trafic Unknown dans votre app

Unknown est-il une erreur ou un résultat ?

Quand vous commencez à classer les interactions en Human, Human + AI, Agent ou Unknown, le compartiment Unknown est souvent plus grand que prévu. Il peut être tentant de le traiter comme un manque à masquer, soit en l’intégrant à Human, soit en le considérant comme suspect. Ces deux choix posent problème.

Unknown signifie que les éléments de preuve disponibles ne permettent pas une détermination fiable. Une requête provenant d’un client qui n’exécute aucun JavaScript, un appel vers un endpoint où vous ne collectez aucun signal, une session interrompue après une seule page: tout cela peut être parfaitement légitime, et aucun de ces cas ne vous donne assez d’éléments pour dire qui ou quoi agissait.

C’est le fait de rapporter Unknown honnêtement qui rend les autres classes dignes de confiance. Si votre système ne renvoie jamais Unknown, chaque résultat Human est en partie une estimation, et vous ne pouvez pas savoir laquelle. Notre article sur pourquoi Unknown est un résultat valide lors de la classification du trafic IA explique ce raisonnement plus en détail.

Ce guide explique comment gérer Unknown en pratique: solutions de repli explicites par route, règles qui l’empêchent de se propager aux autres classes, suivi, et réduction là où cela compte.

Étape 1: ne vous rabattez jamais sur Human par défaut

L’erreur la plus courante est une fonction de classification qui renvoie Human dès qu’elle ne trouve aucun signal d’automatisation. Cela paraît raisonnable et c’est faux. L’absence de signal de bot n’est pas la présence d’un signal humain.

// Wrong: silence becomes Human
function classifyWrong(e: Evidence) {
  if (e.signatureValid) return { actor: "agent", basis: "verified" };
  if (e.declaredAgent) return { actor: "agent", basis: "declared" };
  return { actor: "human", basis: "inferred" };
}

// Right: Human requires positive evidence, otherwise Unknown
function classify(e: Evidence) {
  if (e.signatureValid) return { actor: "agent", basis: "verified" };
  if (e.declaredAgent) return { actor: "agent", basis: "declared" };
  if (e.interactiveSession) return { actor: "human", basis: "inferred" };
  return { actor: "unknown", basis: "unknown" };
}

Appliquez la même règle partout où des résultats sont produits: les délais d’attente, les erreurs, les entrées de cache obsolètes et les télémétries manquantes doivent tous produire Unknown. Écrivez un test pour chacun de ces chemins afin que le comportement ne puisse pas régresser silencieusement. L’exemple ci-dessous utilise le Node.js test runner intégré.

import { test } from "node:test";
import assert from "node:assert/strict";

test("missing evidence is unknown, not human", () => {
  const r = classify({ signatureValid: false, declaredAgent: false, interactiveSession: false });
  assert.equal(r.actor, "unknown");
});

Étape 2: donnez à chaque route une solution de repli explicite

Unknown a besoin d’un comportement défini, et le bon comportement dépend de la route. Décidez-en route par route, consignez-le et conservez-le dans la configuration. Pour comprendre comment ces solutions de repli s’intègrent dans un modèle de politique plus large, voir concevoir des politiques au niveau de l’app pour les humains et les agents IA.

Le schéma est simple. Pour les routes à faible risque, Unknown se comporte comme le trafic normal. Pour les routes à fort risque, Unknown bénéficie de la même protection que celle déjà appliquée à la route. Dans aucun des deux cas le résultat d’acteur n’aggrave la situation d’un utilisateur non classé mais légitime.

type Fallback = "allow" | "standard_limit" | "existing_checks" | "review";

const unknownFallback: Record<string, Fallback> = {
  "GET /docs/*": "allow",
  "GET /api/catalog": "standard_limit",
  "POST /signup": "existing_checks",
  "POST /account/password": "existing_checks",
  "POST /exports": "review",
};

Étape 3: traitez les délais d’attente et les erreurs de la même manière

L’évaluation de l’acteur se trouve sur le chemin de la requête, elle doit donc disposer d’un budget de temps strict. Quand ce budget est dépassé, produisez Unknown et appliquez la solution de repli de la route. Ne bloquez jamais une requête parce que l’évaluation a été trop lente.

async function withBudget<T>(work: Promise<T>, ms: number, onTimeout: T): Promise<T> {
  let timer: NodeJS.Timeout;
  const timeout = new Promise<T>((resolve) => {
    timer = setTimeout(() => resolve(onTimeout), ms);
  });
  try {
    return await Promise.race([work, timeout]);
  } finally {
    clearTimeout(timer!);
  }
}

const result = await withBudget(evaluateActor(req), 150, { actor: "unknown", basis: "unknown" });

Enregistrez la raison pour laquelle un résultat est Unknown: absence de preuve, délai d’attente, erreur d’évaluation ou preuve obsolète. Ces raisons vous indiquent ce qu’il faut corriger.

Étape 4: ne considérez pas Unknown comme suspect

Unknown n’est pas un score de risque. De nombreux clients légitimes seront toujours Unknown sur certaines routes: outils en ligne de commande, intégrations serveur sans signatures, outils d’accessibilité, navigateurs axés sur la confidentialité et simples lecteurs de flux. Même les grands opérateurs IA identifient encore aujourd’hui la plupart de leurs récupérateurs par user agent et par plages d’IP publiées. La documentation du crawler d’OpenAI, par exemple, indique une chaîne user agent et un fichier d’adresses IP publiées pour chacun de ses bots à partir de novembre 2026.

Si vous voulez agir sur un comportement suspect, fondez-vous sur un comportement que vous pouvez décrire, comme les taux de requêtes, les schémas d’échec de connexion ou les signalements d’abus, avec ses propres éléments de preuve. Gardez cette logique séparée de la classe d’acteur pour que ni l’une ni l’autre ne déforme l’autre.

Étape 5: comment surveiller votre taux d’Unknown ?

Le taux d’Unknown est la part des interactions classées Unknown. Suivez-le par route, par contexte d’intégration et dans le temps. C’est l’un des indicateurs de santé les plus utiles dont vous disposez.

type Row = { route: string; actor: string };

export function unknownRate(rows: Row[]) {
  const byRoute = new Map<string, { total: number; unknown: number }>();
  for (const r of rows) {
    const s = byRoute.get(r.route) ?? { total: 0, unknown: 0 };
    s.total += 1;
    if (r.actor === "unknown") s.unknown += 1;
    byRoute.set(r.route, s);
  }
  return [...byRoute].map(([route, s]) => ({ route, rate: s.unknown / s.total, total: s.total }));
}

Ce que les chiffres indiquent:

• Un taux élevé et stable sur une route signifie généralement qu’il manque un signal à cet endroit. Une page qui ne charge jamais votre intégration navigateur, ou une API qui ne voit jamais de requêtes signées, restera principalement Unknown.
• Une hausse soudaine signifie souvent qu’un élément a changé dans votre stack, par exemple une release qui a supprimé un header, une règle CDN qui retire les headers de signature, ou une modification frontend qui a cessé d’envoyer les déclarations de votre app.
• Une baisse soudaine mérite aussi d’être vérifiée. Si Unknown baisse alors que Human augmente, confirmez qu’un nouvel élément de preuve est bien arrivé plutôt qu’un changement silencieux de fallback.

Déclenchez des alertes sur les changements brutaux, pas sur les niveaux absolus. Chaque application a son propre normal.

Étape 6: comment réduire Unknown là où cela compte ?

Vous n’avez pas besoin de faire tomber Unknown à zéro. Vous avez besoin d’assez d’éléments de preuve sur les routes où les décisions comptent. Procédez dans l’ordre de l’impact:

1. Ajoutez d’abord des éléments de preuve sur les routes à fort impact. Si les changements de compte sont surtout Unknown, c’est là qu’une intégration navigateur ou une vérification côté serveur apporte le plus.
2. Invitez les clients automatisés à s’identifier. Publiez une documentation pour votre API qui explique comment les agents peuvent signer les requêtes avec HTTP Message Signatures et les conventions IETF Web Bot Auth, et offrez aux clients vérifiés une meilleure expérience, par exemple des limites plus élevées ou des réponses structurées. Les clients capables de se vérifier commenceront à le faire.
3. Utilisez la connaissance de votre propre application. Si les utilisateurs interagissent avec votre assistant intégré, enregistrez-le comme une déclaration. Votre app en sait souvent plus que le réseau.
4. Corrigez la plomberie. Vérifiez que les proxys transmettent les headers sur lesquels vous vous appuyez et que l’évaluation dispose d’un budget de temps suffisant pour se terminer.

Pour un aperçu pratique des signaux qui font sortir le trafic de Unknown, lisez comment savoir si le trafic d’un site web provient d’agents IA.

Étape 7: affichez Unknown honnêtement dans les tableaux de bord

Affichez Unknown comme une série à part entière, avec le même poids visuel que les autres classes. Ne le masquez pas dans une catégorie "autre", et ne lui donnez pas la couleur d’une alerte. Quand les parties prenantes voient une part importante d’Unknown, la bonne réaction est "où avons-nous besoin de plus de preuves", pas "où sont les bots".

Étape 8: examinez Unknown à partir des résultats, pas des suppositions

Toutes les quelques semaines, prélevez un échantillon d’interactions Unknown sur vos routes les plus importantes et regardez ce qui s’est réellement passé. La session a-t-elle finalisé un achat, créé un projet, lu trois articles, ou échoué à plusieurs reprises à la connexion ? Les résultats vous indiquent quel type de trafic se trouve dans le compartiment sans lui imposer trop tôt une étiquette.

Regroupez ce que vous trouvez en trois catégories pratiques:

1. Légitime et à faible risque. Lecteurs de flux, aperçus de liens, outils de supervision et personnes ayant des paramètres de confidentialité. Gardez la solution de repli de la route telle quelle.
2. Automatisation légitime qui pourrait s’identifier. Intégrations et agents qui utiliseraient volontiers un chemin structuré ou signeraient les requêtes si vous leur en donniez un. Publiez des consignes et prenez contact lorsque c’est possible.
3. Comportement nécessitant son propre contrôle. Les schémas de credential stuffing ou de scraping, tous deux répertoriés dans le projet OWASP Automated Threats to Web Applications. Traitez-les avec des contrôles fondés sur le comportement et disposant de leurs propres preuves, comme les taux d’échec de connexion, et gardez-les séparés de la classe d’acteur.

Cette revue ancre vos solutions de repli dans votre trafic réel et vous donne une liste claire des endroits où ajouter ensuite des éléments de preuve.

Questions courantes

Unknown doit-il entrer dans les limites de débit ? Utilisez vos limites standard. Le rate limiting par classe convient aux agents vérifiés, qui peuvent obtenir des limites plus élevées, mais Unknown doit recevoir la limite normale, pas une limite punitive.

Peut-on challenger les utilisateurs Unknown ? Uniquement là où la route challenge déjà tout le monde dans cette situation. Ajouter un challenge uniquement parce qu’un résultat est Unknown pénalise des utilisateurs légitimes dont les clients envoient moins de signaux.

Unknown diminuera-t-il à mesure que les standards mûrissent ? À mesure que davantage de clients automatisés signent les requêtes, plus de trafic agentique passe de Unknown ou declared à verified. Votre suivi montrera ce déplacement route par route.

Où Proof of Actor s’insère

Proof of Actor signale Unknown comme un résultat de premier ordre, avec sa raison, et ne le convertit jamais en Human. Votre application choisit la solution de repli pour chaque route, et les analyses indiquent où la couverture s’arrête afin que vous puissiez ajouter des preuves là où cela compte.

Pour mettre cela en place sur une application de production avec notre équipe, demandez un accès anticipé. Pour comprendre précisément ce que les éléments de preuve peuvent établir, lisez Detection & Limitations.

Sources

• RFC 9421: HTTP Message Signatures: le standard que les clients automatisés peuvent utiliser pour signer les requêtes
• draft-ietf-webbotauth-httpsig-protocol: brouillon IETF Web Bot Auth pour le trafic automatisé signé (travail en cours à partir de novembre 2026)
• OpenAI: Overview of OpenAI Crawlers: chaînes user agent et fichiers d’adresses IP publiées pour les bots d’OpenAI
• OWASP Automated Threats to Web Applications: taxonomie des menaces automatisées telles que le credential stuffing et le scraping
• Node.js test runner: le module node:test utilisé dans l’exemple