Guardrails

Guardrails は、Browser Run セッションの HTTP と HTTPS リクエストを、許可したホスト名に制限します。

次のことができます。

• 自動化の対象を絞る — 各セッションを、その作業に必要なホスト名に限定します。
• ページの依存関係に対応する — 必要なサードパーティ API、スクリプト、画像、フォントを含めます。
• 自己完結ページを動かす — 外部の HTTP と HTTPS リクエストを防ぎます。

セッションの Guardrails は、Puppeteer、Playwright、Chrome DevTools Protocol (CDP) で作成したブラウザーセッションに適用されます。Quick Actions では使えません。

ブラウザーが訪問するホスト名と、リダイレクト、API、スクリプト、画像、フォントに必要なホスト名を追加します。よく使うホスト名や共有ホスト名は、1 件ずつ列挙せずドメインセットを使います。

新しいセッション開始時に Guardrails を設定します。ポリシーはそのセッションの生存期間中は固定です。

許可リストの管理方法に応じてプロパティを選びます。

両方のプロパティは任意で、合わせて 1 つの許可リストになります。両方を省略すると、HTTP と HTTPS リクエストは制限されません。

セッション開始前に、Guardrail ポリシーが次の要件を満たすことを確認します。

• allowedDomains は 50 件までです。
• allowedDomainSets は 4 件までです。
• ホスト名パターンにはスキーム、ポート、パスを含めません。
• 各ホスト名パターンのワイルドカードは 1 つまでです。

ポリシーがこれらの要件を満たさない場合、Browser Run はセッションリクエストを 400 レスポンスで拒否します。

この関数は、example.com、そのサブドメイン、common-cdns ドメインセットのホスト名を許可するセッションを開始します。

例では、ブラウザーバインディング名を MYBROWSER と想定します。

import puppeteer from "@cloudflare/puppeteer";

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

	return browser;
}

import puppeteer from "@cloudflare/puppeteer";

interface Env {
	MYBROWSER: Fetcher;
}

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

	return browser;
}

Playwright は、launch() オプションで同じ guardrails オブジェクトを受け付けます。

Workers の外でガード付きセッションを取得するには REST API を使います。このリクエストは $ACCOUNT_ID が設定済みで、$CLOUDFLARE_API_TOKEN に Browser Rendering Write 権限があることを想定します。

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-rendering/devtools/browser" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"guardrails": {
				"allowedDomains": [
						"example.com",
						"*.example.com"
				],
				"allowedDomainSets": [
						"common-cdns"
				]
		}
	}'

allowedDomains で、ブラウザーがリクエストできるホスト名を指定します。

各エントリはホスト名のみです。https:// などのプロトコル、:443 などのポート、/api などのパスは含めません。

• example.com は example.com だけを許可します。
• *.example.com は www.example.com や api.example.com などのサブドメインを許可しますが、example.com は許可しません。

各エントリで * ワイルドカードを 1 つ使い、ホスト名のバリエーションに一致できます。

ドメインセットは、セッション間で共有ホスト名一覧を再利用するのに役立ちます。allowedDomainSets プロパティは、common-cdns セット名と HTTPS URL を受け付けます。

ページが一般的なコンテンツ配信ネットワーク（CDN）ホスト名のアセットに依存する場合は、Cloudflare 管理の common-cdns セットを使います。

{
	"allowedDomains": ["example.com"],
	"allowedDomainSets": ["common-cdns"]
}

Cloudflare は common-cdns セットを管理し、内容は変わることがあります。許可ホスト名を固定したい場合は、allowedDomains またはホストしたホスト名一覧を使います。

ページと依存関係に固有のホスト名パターンには、HTTPS URL を使います。

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

たとえば browser-run-hostnames.txt は次のようにできます。

example.com
*.example.com

# Third-party API
api.example.net

ホストした一覧は次の要件を満たす必要があります。

Cloudflare はホストした一覧を最大 1 時間キャッシュします。キャッシュ更新後の変更は、新しく開始したセッションにだけ影響し、既存セッションには影響しません。

空の allowedDomains 配列は、すべての HTTP と HTTPS リクエストをブロックします。インライン HTML をスクリーンショットや PDF にするなど、自己完結ページに使います。

インラインコンテンツは描画できますが、ブラウザーは外部 API やアセットをリクエストできません。このポリシーにドメインセットを含めないでください。

対応する連携では、このポリシーオブジェクトを guardrails の値として使います。

{
	"allowedDomains": []
}

Puppeteer で許可リスト外のホスト名をリクエストします。この例はレスポンスステータスと Guardrail ヘッダーを確認します。

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

import puppeteer from "@cloudflare/puppeteer";

interface Env {
	MYBROWSER: Fetcher;
}

export async function verifyGuardrails(env: 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();
	}
}

ブロックされたリクエストは、次のヘッダー付きの 403 レスポンスを返します。

Live View を使う場合も、セッションの Guardrails は有効なままです。Live View の { mode: "readonly" } 設定は閲覧者の操作を制御し、セッションのホスト名許可リストは変えません。