Cloudflare Browser Run får guardrails – lås webbagentens värdnamn och prova att blockeringen syns

Vad Cloudflare släppte den 14 september 2026

I changeloggen Control which hostnames Browser Run sessions can access beskriver Cloudflare guardrails som begränsar en sessions HTTP- och HTTPS-anrop till tillåtna värdnamn. Cloudflare nämner tre användningsfall: hålla ett flöde inom en sajt och dess subdomäner, begränsa laddning till kända tredjeparts-API:er, skript, bilder och typsnitt, samt rendera egen HTML till skärmdump eller PDF utan externt innehåll.

Enligt dokumentationen gäller policyn sessioner som skapas med Puppeteer, Playwright eller Chrome DevTools Protocol, men inte Quick Actions, och den stöds inte med Kitesurf. Du sätter den när sessionen startar, via launch() i Puppeteer eller Playwright eller via REST-anropet POST /client/v4/accounts/$ACCOUNT_ID/browser-rendering/devtools/browser med en token som har behörigheten Browser Rendering Write. Två saker avgör hur du bygger provet: policyn ligger fast under hela sessionen, och om du utelämnar både allowedDomains och allowedDomainSets förblir anropen obegränsade. En saknad policy är alltså ingen spärr.

import puppeteer from "@cloudflare/puppeteer";

export async function startGuardedSession(env) {
  return puppeteer.launch(env.MYBROWSER, {
    guardrails: {
      allowedDomains: ["example.com", "*.example.com"],
      allowedDomainSets: ["common-cdns"]
    }
  });
}

Kompatibilitetskravet är @cloudflare/puppeteer 1.4.0 eller senare respektive @cloudflare/playwright 1.3.6 eller senare. Playwright tar emot samma guardrails-objekt i sina launch()-alternativ. Spara den faktiskt installerade versionen ur låsfilen i provets metadata, så att ett ändrat beteende går att knyta till en uppgradering.

Skriv en allowlist som håller

Varje post i allowedDomains är ett värdnamn: inget https://, ingen port som :443, ingen sökväg som /api. Ett mönster får innehålla högst en *. Gränserna är 50 poster i allowedDomains och fyra poster i allowedDomainSets. Bryter policyn mot något av kraven avvisar Browser Run sessionsbegäran med 400. Cloudflares egen instruktion är att ta med värdnamnet webbläsaren besöker plus de värdnamn som krävs för omdirigeringar, API:er, skript, bilder och typsnitt.

Domänset: bekvämt eller fast

allowedDomainSets tar setnamnet common-cdns och HTTPS-URL:er till egna hostade listor. Cloudflare underhåller common-cdns och kan ändra det över tid. Det passar en skärmdumpstjänst där sidan bara ska ladda sina typsnitt, men det är fel verktyg om du behöver dokumentera exakt vilka värdnamn agenten fick nå. För det fallet hänvisar Cloudflare till allowedDomains eller en hostad lista.

En hostad lista är en textfil som du pekar på med URL:

{
  "allowedDomainSets": ["https://example.com/browser-run-hostnames.txt"]
}

Två fallgropar följer av kravtabellen. Den första är att redan en felskriven rad, till exempel ett mönster med https://, underkänner hela listan. Den andra är att Cloudflare cachar listan i upp till en timme och att en ändring efter cacheuppdateringen bara påverkar nya sessioner. En redigering i listan är därför inte verifierad förrän provet körts i en ny session. Lägg listan på ett värdnamn du själv kontrollerar; en allowlist som någon annan kan redigera är i praktiken deras policy, inte din.

För självständiga sidor finns det strängaste läget. En tom array blockerar alla HTTP- och HTTPS-anrop: inline-HTML renderas till skärmdump eller PDF, men webbläsaren kan inte hämta externa API:er eller tillgångar. Cloudflare säger att inga domänset ska ingå i den policyn.

{
  "allowedDomains": []
}

Prova att blockeringen syns i svaret

Cloudflare visar hur ett blockerat anrop ser ut från insidan av sessionen: svaret har status 403, headern cf-mitigated har värdet guardrails och cf-brapi-guardrails-reason har värdet not-in-allowlist. Det är tre kontrollerbara villkor, och dokumentationens exempel kräver alla tre:

import puppeteer from "@cloudflare/puppeteer";

export async function verifyGuardrails(env) {
  const browser = await puppeteer.launch(env.MYBROWSER, {
    guardrails: {
      allowedDomains: ["example.com"]
    }
  });

  try {
    const page = await browser.newPage();
    const response = await page.goto("https://example.org");
    const status = response?.status();
    const headers = response?.headers() ?? {};

    if (
      status !== 403 ||
      headers["cf-mitigated"] !== "guardrails" ||
      headers["cf-brapi-guardrails-reason"] !== "not-in-allowlist"
    ) {
      throw new Error("Expected Browser Run guardrails to block the request");
    }
  } finally {
    await browser.close();
  }
}

Ett prov som bara visar att en otillåten värd stoppas räcker inte, eftersom det inte skiljer en fungerande policy från en refaktorering som råkat tappa guardrails-objektet på vägen. Kör därför fyra fall med samma binding, samma paketversion och en ändring i taget. Metoden följer AI-kreatörs guide om testning av AI-genererad kod: kriteriet måste mäta det provet beställer.

Spara status, de två headervärdena, det begärda värdnamnet och den installerade versionen per fall. Spara inte sidinnehållet; provet handlar om var webbläsaren fick gå, inte om vad den såg.

Stoppregeln när agenten möter 403

Policyn kan inte utökas mitt i en session. En agent som får 403 med cf-brapi-guardrails-reason: not-in-allowlist har därför två vägar: avbryta uppgiften och logga värdnamnet, eller starta en ny session med bredare lista. Den andra vägen ska inte vara agentens att välja. Om modellen får lägga till värdnamn i sin egen allowlist har listan slutat vara en avgränsning och blivit ett förslag. Låt den blockerade begäran bli ett ärende: värdnamn, orsak och vilken sida som innehöll länken. En människa avgör om posten ska in, och ändringen provas i en ny session innan agenten körs igen.

Guardrails styr var webbläsaren får hämta, inte vad den läser. En tillåten sida kan innehålla text som ser ut som instruktioner till agenten, och allowlisten gör ingenting åt det. Principen i AI-kreatörs guide om agenter och automatisering gäller oförändrad: avgränsningen är säkerheten, och innehåll från sidor du inte kontrollerar är data, inte order. Behandla en instruktion i sidinnehållet som du behandlar ett blockerat värdnamn – logga och stoppa, kör inte vidare. Samma linje gäller vad som får lämna sessionen; guiden om känsliga data beskriver hur du bestämmer den listan i förväg.

Live View påverkar inte ovanstående. Cloudflare införde samtidigt ett readonly-läge med { mode: "readonly" } som låter en tittare följa sessionen utan att klicka, skriva eller navigera. Enligt dokumentationen ändrar det läget bara tittarens interaktion, inte sessionens allowlist.

Godkänn först när fyra fall är gröna

Stoppregeln är enkel att formulera: ge inte en agent fler värdnamn än provet täcker. Den dag en uppgift kräver en ny domän är det provet som ska växa först, inte listan.