Playwright 자동화에 Cloudflare 승인 호스트와 읽기 전용 검토 적용하기

2026년 9월 14일, Cloudflare Browser Run에 고객용 Playwright 브라우저 자동화를 전달하는 방식을 바꿀 두 가지 제어 기능이 추가됐습니다. 세션을 승인된 호스트명 목록 안에서만 작동하게 만들 수 있고, 검토자는 조작 권한 없이 Live View로 실행 과정을 지켜볼 수 있습니다. 호스트명은 직접 최대 50개까지 지정하거나 공유 도메인 세트를 최대 4개까지 연결할 수 있지만, 중요한 것은 목록의 크기가 아니라 작업 범위를 명확히 구획할 수 있다는 점입니다.

하나가 아닌 두 개의 경계가 생겼습니다

Browser Run 세션은 원격 Chrome 인스턴스입니다. 코드는 Puppeteer, Playwright 또는 흔히 CDP라고 부르는 Chrome DevTools Protocol로 이 인스턴스를 제어합니다.

새로운 세션 가드레일은 브라우저가 HTTP 또는 HTTPS로 요청할 수 있는 목적지 호스트명을 결정합니다. 정책은 세션을 시작할 때 고정되며 해당 세션이 끝날 때까지 유지됩니다.

Live View의 새로운 읽기 전용 설정은 다른 역할을 합니다. 생성된 보기 링크를 사용하는 한 사람이 무엇을 할 수 있는지 정합니다. 읽기 전용 검토자는 세션을 볼 수 있지만 페이지 이동, 입력, 클릭, JavaScript 실행은 할 수 없습니다.

이 차이를 이해해야 합니다. 자동화 코드는 계속 브라우저를 제어하고, 검토자는 그 과정을 관찰하기만 합니다. 동시에 어떤 Live View 연결이 열려 있든 브라우저의 HTTP 및 HTTPS 요청은 세션 허용 목록 안에 머뭅니다.

브라우저 자동화를 고객 검토 워크플로로 바꾸는 방법

에이전시가 고객의 웹 앱 안에서 보고서를 생성하는 상황을 가정해 보겠습니다. 브라우저에는 고객의 기본 호스트명뿐 아니라 인증 호스트명, API, 폰트 호스트, 경우에 따라 이미지 CDN까지 필요합니다. 고객은 결과를 승인하기 전에 실행 과정도 보고 싶어 합니다.

이제 두 가지 판단을 분리해 처리할 수 있습니다.

1. 기술 책임자가 세션에 필요한 목적지를 승인합니다.
2. 고객은 보기 전용 Live View URL을 받아 작업이 실행되는 과정을 확인합니다.

검토자에게 조작 가능한 브라우저를 넘기지 않고, 작업에도 제한 없는 목적지 목록을 허용하지 않습니다. 브라우저 공유 링크 하나를 시연 도구이자 접근 제어 수단으로 함께 쓰는 것보다 훨씬 깔끔한 인계 방식입니다.

물론 이것만으로 완전한 보안 체계가 되지는 않습니다. Cloudflare는 HTTP와 HTTPS 요청에 적용되는 호스트명 제어 기능이라고 설명하므로, 이를 범용 네트워크 샌드박스라고 표현해서는 안 됩니다. Live View URL에는 서명된 JWT도 포함됩니다. 따라서 전체 URL 자체가 자격 증명입니다. 읽기 전용 모드는 조작을 막지만, 화면에 표시되는 내용까지 숨겨주지는 않습니다.

실제 부담은 에셋 목록 관리에 있습니다

눈에 바로 보이는 호스트명만으로 페이지 전체가 작동하는 경우는 드뭅니다.

실서비스 페이지는 로그인 과정에서 리디렉션되고, 별도 API를 호출하며, 스크립트와 이미지, 폰트를 각각 다른 호스트에서 불러올 수 있습니다. Cloudflare는 이 모든 의존성을 목록에 넣으라고 안내합니다. 하나라도 빠뜨리면 해당 요청은 403을 받으며 응답 헤더에는 cf-mitigated: guardrails와 cf-brapi-guardrails-reason: not-in-allowlist가 표시됩니다.

따라서 허용 목록 관리는 실제 납품 비용이 됩니다. 고객 사이트의 디자인 개편, ID 공급자 변경, 분석 도구 교체, CDN 이전이 있을 때마다 정책을 바꾸고 다시 검증해야 할 수 있습니다. 이 작업에 보편적으로 적용할 수 있는 정직한 공수 수치는 없습니다. 실제 프로젝트에서 직접 측정해야 합니다.

Cloudflare는 목록을 전달하는 두 가지 방식을 제공합니다.

• allowedDomains는 세션 시작 호출에 최대 50개의 호스트명 패턴을 직접 넣는 방식입니다.
• allowedDomainSets에는 공유 목록을 최대 4개까지 지정할 수 있습니다. Cloudflare의 common-cdns 세트 또는 호스트명 목록을 일반 텍스트로 반환하는 HTTPS URL을 사용할 수 있습니다.

공유 목록은 여러 고객 작업에서 동일한 승인 서비스를 사용해야 할 때 유용합니다. 다만 반영 시점에 규칙이 있습니다. Cloudflare는 호스팅된 목록을 최대 1시간 캐시하며, 변경 내용은 갱신된 목록을 읽은 뒤 시작한 세션에만 적용됩니다. 실행 중인 세션의 정책은 중간에 바뀌지 않습니다.

common-cdns에도 트레이드오프가 있습니다. Cloudflare가 직접 관리하고 언제든 내용을 바꿀 수 있기 때문입니다. 목록 유지 부담은 줄지만 고정된 허용 목록은 아닙니다. 계약이나 감사에서 목적지 집합이 변하지 않아야 한다면, 호스트명을 명시적으로 지정하거나 직접 호스팅한 목록을 사용해야 합니다.

지금 바로 활용할 수 있는 네 가지 팀

에이전시 기술 책임자: 승인과 제어를 분리합니다

고객 앱과 필요한 의존성만 허용한 뒤 브라우저 작업을 실행하고, 어카운트 담당자나 고객 검토자에게 읽기 전용 Live View 링크를 생성해 전달합니다. 검토자는 앱을 클릭하거나 실행 흐름을 바꾸지 않고 결과가 만들어지는 과정을 지켜볼 수 있습니다. 검토 단계가 어느새 운영 권한 인계로 변하는 일을 막을 수 있다는 것이 핵심입니다.

SaaS 창업자: 독립형 PDF를 외부 요청 없이 유지합니다

신뢰할 수 있는 인라인 HTML로 스크린샷이나 PDF를 만들고 있다면, 도메인 세트 없이 빈 allowedDomains 배열로 세션을 시작합니다. HTML은 그대로 렌더링되지만 HTTP 또는 HTTPS를 통해 외부 API, 스크립트, 이미지, 폰트를 가져올 수 없습니다. 그러면 “이 렌더링은 외부 웹 콘텐츠를 요청하지 않았다”는 단순하고 검증 가능한 기준을 세울 수 있습니다.

스크린샷과 PDF에 흔히 쓰는 단축 엔드포인트를 포함해 Quick Actions에서는 이 제어 기능을 사용할 수 없습니다. Puppeteer, Playwright 또는 CDP를 통한 Browser Session이 필요합니다.

플랫폼 팀: 의존성 정책을 한곳에서 관리합니다

HTTPS로 일반 텍스트 목록을 호스팅하고 한 줄에 호스트명 패턴을 하나씩 적은 뒤, 해당 URL을 allowedDomainSets에서 참조합니다. 여러 세션 실행기가 같은 목록을 사용할 수 있습니다. 관리 지점이 하나로 모인다는 장점이 있지만, 잘못된 줄이 하나라도 있으면 호스팅된 목록 전체가 거부된다는 점을 기억해야 합니다.

보안 검토자: 실패하는 테스트를 요구합니다

설정값을 보여주는 데서 끝내면 안 됩니다. 허용되지 않은 호스트명으로 요청을 한 번 보내고, 403 상태와 두 가드레일 헤더를 검토 기록에 저장합니다. 올바르게 보이는 설정 객체의 스크린샷이 아니라, 차단 경로가 실제로 작동했다는 증거를 남기는 것이 목적입니다.

Playwright로 보호된 검토 세션 구성하기

이 기능은 세션 생성 시점에 적용되므로 기술적인 설정 과정이 필요합니다. 아래 코드는 이 글을 작성할 때 확인한 Cloudflare 문서에서 가져왔습니다.

1. 1

   호환 클라이언트를 설치하고 브라우저를 바인딩합니다

   가드레일을 사용하려면 Cloudflare의 @cloudflare/puppeteer 1.4.0 이상이 필요합니다. Puppeteer 설치 명령은 다음과 같습니다.

   npm i -D @cloudflare/puppeteer

   Worker에는 브라우저 바인딩도 필요합니다. Cloudflare의 Wrangler 예제에서는 이름을 MYBROWSER로 지정합니다.

   {
   	"$schema": "./node_modules/wrangler/config-schema.json",
   	"name": "browser-rendering",
   	"main": "src/index.ts",
   	"workers_dev": true,
   	"compatibility_flags": ["nodejs_compat_v2"],
   	"browser": {
   		"binding": "MYBROWSER"
   	}
   }

   설치된 패키지 버전을 확인해야 합니다. 이전 Puppeteer 개요 문서에는 여전히 1.1.0이 최신 버전으로 표시되지만, 새 가드레일 문서에서는 1.4.0 이상을 요구합니다. 해당 기능의 요구 사항을 기준으로 판단하십시오.

2. 2

   목적지 정책과 함께 세션을 시작합니다

   Cloudflare의 보호된 Puppeteer 예제는 루트 도메인과 그 하위 도메인, 공유 common-cdns 세트를 허용합니다.

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

   페이지의 리디렉션, API, 스크립트, 이미지, 폰트를 모두 조사한 뒤에만 예제 값을 교체해야 합니다. *.example.com에는 example.com이 포함되지 않으므로 두 항목을 모두 넣었다는 점에 주목하십시오.

3. 3

   승인되지 않은 호스트가 차단되는지 증명합니다

   목록에 없는 호스트명으로 요청을 한 번 보냅니다. 예상 결과는 HTTP 403이며, 응답에는 cf-mitigated: guardrails와 cf-brapi-guardrails-reason: not-in-allowlist가 있어야 합니다. 승인한 페이지도 전체 로그인 및 렌더링 경로를 따라 테스트하십시오. 실패 테스트는 경계가 작동함을 증명하고, 성공 테스트는 작업이 여전히 정상임을 증명합니다.

4. 4

   보기 전용 검토 링크를 생성합니다

   세션 ID를 확보한 뒤, Cloudflare의 REST 예제로 검토자가 조작할 수 없는 탭 보기를 생성합니다.

   curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-rendering/devtools/browser/$SESSION_ID/live_view" \
   	--request POST \
   	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
   	--json '{
   		"mode": "tab",
   		"guardrails": {
   			"mode": "readonly"
   		}
   	}'

   이 URL은 신뢰할 수 있는 서버 측 코드에서 생성하고 신뢰할 수 있는 채널로 전달해야 합니다. 기본 연결 시작 제한 시간은 5분입니다. expiresInMs는 최소 60,000밀리초부터 최대 3,600,000밀리초, 즉 1시간까지 설정할 수 있습니다.

여기서 반복되는 guardrails라는 단어가 혼동을 줄 수 있습니다. 세션 시작 설정에서는 allowedDomains를 담아 목적지를 제어합니다. Live View URL 요청에서는 mode: readonly를 담아 해당 검토자의 권한을 제어합니다. 두 경계를 모두 원한다면 두 설정이 모두 필요합니다.

기능 도입으로 요금 항목이 달라질 수 있습니다

현재 Cloudflare의 Browser Run 요금에는 허용 목록 항목별 별도 요금이 없습니다. 비용이 달라지는 지점은 연동 방식입니다.

Quick Actions는 브라우저 사용 시간만 과금되지만 이 가드레일을 사용할 수 없습니다. 가드레일을 지원하는 Browser Sessions에는 브라우저 사용 시간과 동시 실행 브라우저 요금이 함께 부과됩니다. 단축 방식의 PDF 또는 스크린샷 워크플로에 호스트명 제한이 필요해졌다면, Puppeteer, Playwright 또는 CDP로 옮길 때 구현 방식과 비용 모델이 모두 바뀝니다.

Workers Paid에는 매월 브라우저 사용 시간 10시간과 동시 실행 브라우저 10개가 포함됩니다. 추가 브라우저 사용 시간은 시간당 $0.09입니다. 추가 동시 실행은 일별 최대치의 월평균을 기준으로 브라우저당 $2.00입니다.

계획에 활용할 수 있는 계산식은 다음과 같습니다.

extra usage cost = max(0, browser hours - 10) × $0.09 + max(0, average daily peak browsers - 10) × $2.00

Cloudflare의 예시에서는 브라우저 사용 시간 50시간과 평균 동시 실행 브라우저 15개를 사용합니다. 추가 40시간에 $3.60, 추가 브라우저 5개에 $10.00이 발생해 추가 사용료는 총 $13.60입니다. 이는 가드레일 자체의 요금이 아닙니다. 가드레일을 지원하는 Browser Session 경로에 붙는 비용입니다.

Workers Free에는 하루 브라우저 사용 시간 10분과 동시 실행 브라우저 3개가 포함됩니다. 작은 개념 검증에는 충분할 수 있지만, 검토를 반복하는 고객 워크플로를 운영하기에는 여유가 많지 않습니다.

이미 Browser Sessions를 사용 중이라면 과금 항목은 달라지지 않습니다. 새로 생기는 비용은 대부분 운영 측면에 있습니다. 에셋 호스트를 수집하고, 차단 및 허용 경로를 테스트하고, 목록을 최신 상태로 유지하는 작업입니다. 관리형 브라우저 방식을 비교하는 단계라면 AI 에이전트용 브라우저 종합 가이드에서 이러한 사용료 항목을 더 넓은 맥락으로 살펴볼 수 있습니다.

여전히 문제가 생기는 지점

개발 환경에서는 잘 작동하던 페이지가 허용 목록 적용 후 폰트, 이미지, 로그인 리디렉션 또는 API 호출을 잃는 것이 가장 흔한 실패입니다. 넓은 와일드카드를 쓰면 문제는 사라질 수 있지만, 애초에 만들려던 경계도 약해집니다.

Cloudflare는 호스트명 패턴 하나에 와일드카드 1개를 허용합니다. 하위 도메인에는 *.example.com을 사용하고 루트 도메인은 별도로 나열하는 편이 좋습니다. *example.com 같은 접두사 패턴은 evilexample.com처럼 비슷하게 꾸민 주소까지 일치할 수 있으므로, 엄격한 고객 정책에는 적합하지 않은 지름길입니다.

읽기 전용 Live View에도 한계가 있습니다. 검토자 연결 1개만 보호할 뿐 세션 운영자를 제한하지 않으며, 다른 연결이 세션을 제어하는 것도 막지 않습니다. 필요한 명령이 차단되므로 Puppeteer와 Playwright는 읽기 전용 연결을 조작할 수 없습니다. 검토자에게는 유용하지만 자동화 자격 증명으로는 쓸 수 없으며, 바로 그것이 의도한 동작입니다.

Quick Actions와 Kitesurf는 여전히 가드레일 기능의 적용 대상이 아닙니다. 둘 중 하나를 사용하는 팀은 호스트명 경계를 위해 연동 방식을 바꾸기로 결정하기 전까지 영향을 받지 않습니다.

월요일에 바로 실행할 일

목적지 집합이 안정적인 실제 고객 작업 하나를 고르십시오. 가장 복잡한 로그인 흐름부터 시작할 필요는 없습니다.

정상 경로에서 사용하는 모든 호스트명을 리디렉션과 에셋 호스트까지 포함해 조사합니다. 가드레일이 적용된 Browser Session을 시작해 의도한 결과를 확인한 다음, 승인되지 않은 호스트명으로 일부러 요청을 보내 403 증거를 저장합니다. 마지막으로 팀원에게 읽기 전용 Live View 링크를 전달해 화면은 볼 수 있지만 조작할 수 없는지 확인합니다.

이 파일럿에서 네 가지를 기록하십시오. 필요한 호스트명 수, 목록 관리에 쓴 시간, 처음에 잘못 차단한 정상 요청 수, 동시 실행 브라우저의 평균 최대치입니다. 이 네 값으로 해당 워크플로에서 이 기능이 깔끔한 통제 수단인지, 비용이 큰 약속인지 판단할 수 있습니다.

고객에게 브라우저 작업을 납품하고, 필요한 호스트를 파악할 수 있으며, 제어 권한 없는 관찰이 실제 승인 문제를 해결한다면 이번 주에 실행하십시오. 의존성이 계속 바뀌거나 아직 Quick Actions를 사용하면서 Browser Session 전환 비용을 계산하지 않았다면 기다리는 편이 낫습니다. Browser Sessions를 실행하지도, 실시간 브라우저 작업을 공유하지도 않는다면 이번 변경은 다음 월요일의 업무를 바꾸지 않습니다.

플랫폼 변화를 실제 운영 관점에서 해설한 글을 더 받아보고 싶다면 뉴스레터를 구독하십시오.