playwright-stealth 개발 중단에 따른 Python 버전 자체 제작 및 PyPI 공개 과정

2025년, Python으로 스크레이핑이나 브라우저 자동화를 하는 엔지니어들에게 골치 아픈 문제가 발생했습니다. playwright-stealth—WebDriver 감지를 회피하는 데 필수적인 라이브러리—의 개발이 중단된 것입니다.

본인 스스로도 Python×Playwright를 이용한 브라우저 자동화 프로젝트를 여러 건 담당해 왔지만, playwright-stealth가 멈추면서 봇 감지에 걸리기 시작하는 사이트들이 속출했습니다. 특히 EC 사이트 관리 화면이나 구인 사이트 등 정교한 봇 감지를 채택하는 서비스에서 두드러졌습니다.

'직접 만들자'는 결론에 이르러 pw-stealth-enhanced를 개발하고 PyPI에 공개했습니다. 본 기사에서는 그 배경과 사용법을 소개합니다.

🔧

개발 환경 이야기: 이 라이브러리는 여러 LLM(거대 언어 모델)을 용도별로 전환하며 개발되었습니다. Claude Code CLI를 GLM/MiniMax로 대체한 사례이며, 해당 AI 구동 개발 환경 구축 방법을 해설하고 있습니다.

playwright-stealth는 Node.js용 puppeteer-extra-plugin-stealth의 Python 포팅 버전입니다. 주로 다음과 같은 감지 항목에 대응해 왔습니다:

• navigator.webdriver
  속성 감지 - Chrome 확장 기능에 의한 자동화 감지
• 헤드리스 브라우저 고유 속성 덮어쓰기

하지만, 2024년 하반기경부터 유지보수가 지연되기 시작하여, 2025년에는 issue나 PR이 완전히 방치된 상태입니다.

치명적인 것은 Canvas 지문(Fingerprint), WebGL 정보, AudioContext 지문과 같이 최근 주류가 된 감지 기법에 전혀 대응하고 있지 않다는 점입니다. 봇 감지 서비스 측에서는 이미 이러한 고도화된 기법을 활용하고 있음에도 불구하고, 라이브러리 측의 접근 방식이 완전히 시대에 뒤떨어져 있었습니다.

기존 playwright-stealth의 기본 기능은 계승하면서, 현대적인 봇 감지에 폭넓게 대응한 스텔스 라이브러리로 개발했습니다.

기본 중의 기본. navigator.webdriver 속성을 undefined로 만들어 자동화 도구의 존재를 숨깁니다. 컨텍스트 생성 시 확실하게 적용되도록 보장합니다.

가장 큰 개선점입니다. Canvas 지문은 현대 봇 감지에서 가장 일반적인 기법 중 하나로, 그리기 과정에서의 미세한 부동소수점 연산 차이를 감지합니다.

getImageData 호출 시 실시간으로 노이즈를 주입하여, 접근마다 다른 Canvas 지문이 생성되도록 합니다.

WebGL 지문도 중요한 감지 포인트입니다. GPU의 벤더명과 렌더러 정보를 실제 브라우저 환경에 준거한 값으로 대체합니다.

AudioContext 지문에도 대응했습니다. OscillatorNode 등의 출력에 미세한 노이즈를 더하여, 일관된 지문 생성을 방지합니다.

사용 가능한 폰트 목록 역시 봇 감지의 재료가 됩니다. 정상적인 브라우저 환경과 유사한 폰트 패밀리 목록을 주입하여 의심스러운 일치를 회피합니다.

Notification.permission이나 permissions.query 등도 자동화 감지의 단서가 됩니다. 정상적인 사용자 행동 패턴에 준거한 값을 반환하도록 패치했습니다.

사용자 에이전트(User Agent)와 뷰포트의 로테이션 기능을 구현했습니다. 요청마다 다른 프로필을 사용할 수 있어, 트래킹이나 개별 감지를 회피하기 쉽습니다.

config = StealthConfig(
rotate_ua=True, # UA 로테이션 활성화
rotate_viewport=True, # 뷰포트 로테이션 활성화
...

navigator.language, 시간대 정보도 명시적으로 지정 가능합니다. 지역 한정 콘텐츠 스크레이핑이나 로컬 서비스가 관련된 자동화에 필수적인 기능입니다.

pip install pw-stealth-enhanced

의존성은 playwright>=1.40.0 뿐입니다. 다른 필요한 패키지는 없습니다.

import asyncio
from playwright.async_api import async_playwright
from pw_stealth_enhanced import apply_stealth
...
더 세밀한 제어가 필요할 경우, StealthConfig
객체를 전달합니다.

import asyncio
from playwright.async_api import async_playwright
from pw_stealth_enhanced import apply_stealth, StealthConfig
...

from pw_stealth_enhanced import create_context_with_stealth
# 컨텍스트 생성과 스텔스 적용을 동시에
context = await create_context_with_stealth(...)
...

가장 유명한 자동화 감지 테스트 사이트입니다. 적용 전에는 'WebDriver detected', 'Automation detected'와 같은 빨간색 경고가 나타나지만, 적용 후에는 초록색 체크 표시가 다수를 차지합니다.

await page.goto("https://bot.sannysoft.com/")
await page.screenshot(path="sannysoft_result.png")

더 고도한 감지를 수행하는 사이트입니다. Canvas, WebGL, Font 등 다각적인 지표를 체크합니다. Canvas 핑거프린팅의 노이즈 주입 효과가 현저하게 나타납니다.

await page.goto("https://abrahamjuliot.github.io/creepjs/")

Canvas, Audio 등 전방위적인 테스트를 제공합니다.

await page.goto("https://browserleaks.com/canvas")

주의: 봇 감지 기술은 매일 진화하고 있습니다. 모든 감지를 우회할 수는 없지만, 현 단계의 주요 감지 기법에는 광범위하게 대응합니다.

📝

개발 지식 기록 방법: 이 라이브러리 개발 과정에서 '왜 이 구현을 했는지'를 개인에게 종속시키지 않고 기록하는 시스템으로 SSOT(Single Source of Truth)를 활용하고 있습니다. Claude Code의 기억을 Obsidian에서 SSOT화하는 설계로 그 설계 사상을 설명합니다.

• 📖 Claude Code CLI를 GLM/MiniMax로 대체한 이야기 — 이 라이브러리가 탄생한 AI 구동 개발 환경 구축 방법을, 비용 관리 관점까지 포함하여 설명합니다.
• 📖 Claude Code의 기억을 Obsidian에서 SSOT화하는 설계 — AI 개발에서 '왜 이렇게 구현했는지'를 개인 종속성을 갖지 않고 지식으로 축적하는 설계

pw-stealth-enhanced는 MIT 라이선스로 공개하고 있습니다.

PyPI: https://pypi.org/project/pw-stealth-enhanced/

• GitHub: https://github.com/fukukei23/pw-stealth-enhanced

'이 감지에 걸린다', '이 기능도 추가해줬으면 좋겠다'와 같은 요청 사항이 있다면, issue 보고 또는 직접 PR을 부탁드립니다. 브라우저 자동화와 봇 감지의 치열한 싸움은 앞으로도 계속될 것입니다. 커뮤니티의 손으로 유지보수되는 OSS로서, 함께 키워나가요.

본 기사는 개인 Zenn에서도 공개하고 있습니다.