Hoe Unknown-verkeer in je app te verwerken

Is Unknown een fout of een resultaat?

Wanneer je interacties begint te classificeren als Human, Human + AI, Agent of Unknown, is de Unknown-bucket vaak groter dan mensen verwachten. Het is verleidelijk om dat als een gat te zien dat je moet verbergen, door Unknown samen te voegen met Human of door het als verdacht te behandelen. Beide keuzes zorgen voor problemen.

Unknown betekent dat het beschikbare bewijs geen betrouwbare vaststelling ondersteunt. Een request van een client die geen JavaScript draait, een call naar een endpoint waar je geen signalen verzamelt, een sessie die eindigde na één pagina: dit kan allemaal volstrekt legitiem zijn, en geen ervan geeft je genoeg om te zeggen wie of wat er handelde.

Unknown eerlijk rapporteren is wat de andere klassen betrouwbaar houdt. Als je systeem nooit Unknown zegt, is elk Human-resultaat gedeeltelijk een gok, en kun je niet zien welk deel. Ons stuk over waarom Unknown een geldig resultaat is bij het classificeren van AI-verkeer licht de redenering uitgebreider toe.

Deze gids behandelt hoe je Unknown in de praktijk verwerkt: expliciete per-route fallbacks, de regels die voorkomen dat het in andere klassen lekt, hoe je het bewaakt en hoe je het vermindert waar dat telt.

Stap 1: Val nooit standaard terug op Human

De meest voorkomende fout is een classificatiefunctie die Human teruggeeft zodra er geen automatiseringssignaal wordt gevonden. Het lijkt redelijk en het is onjuist. Afwezigheid van een botsignaal is niet hetzelfde als aanwezigheid van een menselijk signaal.

// 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" };
}

Pas dezelfde regel overal toe waar resultaten worden geproduceerd: time-outs, fouten, verouderde cache-items en ontbrekende telemetry leveren allemaal Unknown op. Schrijf voor elk van deze paden een test, zodat het gedrag niet stilletjes kan terugvallen. Het voorbeeld hieronder gebruikt de ingebouwde Node.js test runner.

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");
});

Stap 2: Geef elke route een expliciete fallback

Unknown heeft gedefinieerd gedrag nodig, en het juiste gedrag hangt af van de route. Bepaal het per route, leg het vast en bewaar het in configuratie. Voor hoe deze fallbacks passen in een breder beleidsmodel, zie beleidsregels op app-niveau ontwerpen voor mensen en AI-agenten.

Het patroon is eenvoudig. Voor routes met laag risico gedraagt Unknown zich als normaal verkeer. Voor routes met hoog risico krijgt Unknown dezelfde bescherming die de route al heeft. In geen van beide gevallen maakt het actorresultaat het erger voor een niet-geclassificeerde maar legitieme gebruiker.

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",
};

Stap 3: Behandel time-outs en fouten op dezelfde manier

Actor-evaluatie zit in het request-pad, dus die moet een strikte tijdslimiet hebben. Wanneer die limiet wordt overschreden, produceer Unknown en pas de route-fallback toe. Blokkeer nooit een request omdat evaluatie traag was.

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" });

Leg vast waarom een resultaat Unknown is: geen bewijs, time-out, evaluatiefout of verouderd bewijs. Die redenen laten zien wat je moet oplossen.

Stap 4: Behandel Unknown niet als verdacht

Unknown is geen risicoscore. Veel legitieme clients zullen op sommige routes altijd Unknown zijn: command-line tools, server-side integraties zonder handtekeningen, toegankelijkheidstools, privacygerichte browsers en eenvoudige feed-readers. Zelfs grote AI-operators identificeren hun fetchers vandaag vooral via user agent en gepubliceerde IP-bereiken. De crawlerdocumentatie van OpenAI vermeldt bijvoorbeeld vanaf november 2026 voor elk van zijn bots een user agent string en een gepubliceerd IP-adresbestand.

Als je op verdacht gedrag wilt reageren, baseer dat dan op gedrag dat je kunt beschrijven, zoals request rates, mislukte inlogpatronen of misbruikmeldingen, met eigen bewijs. Houd die logica gescheiden van de actor class, zodat geen van beide de andere vertekt.

Stap 5: Hoe bewaak je je Unknown-percentage?

Het Unknown-percentage is het aandeel interacties dat als Unknown is geclassificeerd. Volg het per route, per integratiecontext en in de tijd. Het is een van de nuttigste gezondheidsmetriek die je hebt.

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 }));
}

Wat de cijfers je vertellen:

• Een hoog, stabiel percentage op een route betekent meestal dat je daar een signaal mist. Een pagina die nooit je browserintegratie laadt, of een API die nooit signed requests ziet, blijft grotendeels Unknown.
• Een plotselinge stijging betekent vaak dat er iets in je stack is veranderd, bijvoorbeeld een release die een header heeft verwijderd, een CDN-regel die signature headers wegstrepen, of een frontendwijziging die niet meer de declaraties van je app verstuurt.
• Een plotselinge daling is ook het controleren waard. Als Unknown daalt terwijl Human stijgt, bevestig dan dat er nieuw bewijs is binnengekomen in plaats van dat een fallback stilletjes is veranderd.

Stel alerts in op scherpe veranderingen, niet op absolute niveaus. Elke applicatie heeft zijn eigen normaal.

Stap 6: Hoe verlaag je Unknown waar dat telt?

Je hoeft Unknown niet tot nul terug te brengen. Je hebt genoeg bewijs nodig op de routes waar beslissingen ertoe doen. Werk ze af in volgorde van impact:

1. Voeg eerst bewijs toe op routes met grote impact. Als accountwijzigingen meestal Unknown zijn, dan is dat de plek waar een browserintegratie of server-side check zich terugverdient.
2. Nodig geautomatiseerde clients uit om zichzelf te identificeren. Publiceer documentatie voor je API waarin je uitlegt hoe agents requests kunnen ondertekenen met HTTP Message Signatures en de IETF Web Bot Auth conventies, en geef geverifieerde clients een betere ervaring, zoals hogere limieten of gestructureerde responses. Clients die kunnen verifiëren, zullen dat dan ook gaan doen.
3. Gebruik je eigen applicatiekennis. Als gebruikers met je ingebouwde assistent werken, leg dat vast als een declaratie. Je app weet vaak meer dan het netwerk.
4. Los de plumbing op. Zorg ervoor dat proxies de headers doorsturen waarop je vertrouwt en dat evaluatie genoeg tijdslimiet heeft om te voltooien.

Voor een praktische kijk op de signalen die verkeer uit Unknown halen, lees hoe je kunt zien of websiteverkeer van AI-agenten komt.

Stap 7: Toon Unknown eerlijk in dashboards

Toon Unknown als een eigen reeks met hetzelfde visuele gewicht als de andere klassen. Verstop het niet in een "other"-bucket, en kleur het niet als een alert. Wanneer stakeholders een groot Unknown-aandeel zien, is de juiste reactie "waar hebben we meer bewijs nodig", niet "waar zitten de bots".

Stap 8: Beoordeel Unknown op uitkomsten, niet op aannames

Neem om de paar weken een steekproef van Unknown-interacties uit je belangrijkste routes en kijk naar wat er echt gebeurde. Voltooide de sessie een aankoop, maakte die een project aan, las die drie artikelen, of faalde die herhaaldelijk bij het inloggen? Uitkomsten laten zien wat voor soort verkeer in de bucket zit zonder er te vroeg een label op te plakken.

Verdeel wat je vindt in drie praktische categorieën:

1. Legitiem en laag risico. Feed-readers, link previews, monitoringtools en mensen met privacy-instellingen. Laat de route-fallback zoals die is.
2. Legitieme automatisering die zichzelf zou kunnen identificeren. Integraties en agents die graag een gestructureerd pad zouden gebruiken of requests zouden ondertekenen als je zo'n optie bood. Publiceer richtlijnen en neem waar mogelijk contact op.
3. Gedrag dat een eigen controle nodig heeft. Credential stuffing of scrapingpatronen, beide gecatalogiseerd in het project OWASP Automated Threats to Web Applications. Pak deze aan met op gedrag gebaseerde controles die eigen bewijs hebben, zoals percentages mislukte logins, en houd ze gescheiden van de actor class.

Deze review houdt je fallbacks verankerd in je echte verkeer en geeft je een duidelijke lijst van waar je het volgende bewijs moet toevoegen.

Veelgestelde vragen

Moet Unknown meetellen voor rate limits? Gebruik je standaardlimieten. Rate limiting per class is prima voor geverifieerde agents, die hogere limieten kunnen verdienen, maar Unknown moet de normale limiet krijgen, niet een straflimiet.

Kunnen we Unknown-gebruikers uitdagen? Alleen waar de route iedereen in die situatie al uitdaagt. Een challenge toevoegen puur omdat een resultaat Unknown is, straft legitieme gebruikers wiens clients minder signalen sturen.

Wordt Unknown kleiner naarmate standaarden volwassen worden? Naarmate meer geautomatiseerde clients requests ondertekenen, verschuift meer agentverkeer van Unknown of declared naar verified. Je monitoring laat die verschuiving route voor route zien.

Waar Proof of Actor past

Proof of Actor rapporteert Unknown als een eersteklas resultaat, met de reden erbij, en zet het nooit om naar Human. Je applicatie kiest de fallback voor elke route, en de analytics laten zien waar de dekking eindigt zodat je bewijs kunt toevoegen waar dat telt.

Om dit samen met ons team op een productieapplicatie in te richten, vraag vroege toegang aan. Om precies te begrijpen wat het bewijs kan vaststellen, lees Detection & Limitations.

Bronnen

• RFC 9421: HTTP Message Signatures: de standaard die geautomatiseerde clients kunnen gebruiken om requests te ondertekenen
• draft-ietf-webbotauth-httpsig-protocol: IETF Web Bot Auth-concept voor ondertekend geautomatiseerd verkeer (work in progress vanaf november 2026)
• OpenAI: Overview of OpenAI Crawlers: user agent strings en gepubliceerde IP-adresbestanden voor de bots van OpenAI
• OWASP Automated Threats to Web Applications: taxonomie van geautomatiseerde dreigingen zoals credential stuffing en scraping
• Node.js test runner: de module node:test die in het voorbeeld wordt gebruikt