ISS-PWA) CF WAF 오탐에 따른 manifest.json 403 에러 해결

1. 개요

모바일 브라우저 환경에서 DoEatFit 서비스의 PWA “홈 화면에 앱 추가” 팝업이 먹통이 되는 치명적인 장애가 터져 나왔습니다. 분석 결과, 앱의 메타데이터 명세서 역할을 하는 정적 파일인 /manifest.json 요청을 Cloudflare의 인공지능 기반 봇 탐지(Bot Management) WAF 엔진이 악의적인 크롤러 봇으로 오탐하여 403 (Forbidden) 에러를 강제로 반환하고 있었습니다. 전체 도메인 보안을 훼손하지 않으면서, 오직 매니페스트 경로 단 한 곳에만 한정하여 봇 방화벽 검사를 우회해 주는 극소 영역 우회(Granular Bypass) 커스텀 규칙을 Cloudflare WAF에 수립하여 장애를 깔끔하게 해결했답니다. 이 과정과 구체적인 원인 분석, 해결책을 상세히 정리해 드립니다.

---

2. 핵심 내용

2-1. 🚨 문제 상황과 원인 분석

• 문제 현상:
  • 모바일 웹 기술의 꽃은 단연 브라우저 설치를 통해 바탕화면 아이콘으로 단 1초 만에 네이티브 앱처럼 구동하는 PWA(Progressive Web App) 스펙이지요. DoEatFit을 PWA 규격에 완벽히 맞추어 서비스에 적용하고 론칭했으나, 일부 스마트폰 환경에서 “홈 화면에 앱 추가” 배너 및 팝업 자체가 아예 나타나지 않는 현상이 인입되었습니다.
  • 개발자 도구의 콘솔 패널과 네트워크 트래픽을 열어 조사한 결과, PWA 설치 규격을 검사하기 위해 첫 마운트 시 백그라운드로 로드해야 하는 /manifest.json 정적 자산 경로가 지속적으로 403 Forbidden 상태를 반환하며 차단당하고 있었습니다. 메타데이터 명세서 파일을 읽어 들이는 것부터 실패했기에 브라우저는 PWA 자격 요건 미달로 최종 판정하고, 설치 팝업 전체를 비활성화해 버린 상태였습니다.
• 원인 분석:
  • 도대체 왜 개인 정보도 없는 얌전한 정적 JSON 리소스 파일에 403 차단 딱지가 달라붙었는지 Cloudflare 보안 분석(Security Analytics) 탭과 헤더 정보를 정밀 진단했습니다.

graph TD
    A["브라우저 백그라운드 스레드"] -- "/manifest.json 비동기 요청" --> B{"Cloudflare WAF"}
    B -- "특이한 헤더 패턴 & 익명 CORS 스펙" --> C["Bot Management AI 엔진"]
    C -- "오탐: 악성 크롤러 봇 침입 감지!" --> D["403 Forbidden 차단 발동"]
    D --> E["브라우저: PWA 설치 및 서비스워커 가동 거부"]

1. Web App Manifest 백그라운드 요청의 특수성: 브라우저(특히 WebKit 및 Chromium) 엔진들은 PWA 관련 자산인 manifest.json이나 sw.js를 비동기 백그라운드 스레드에서 가져올 때, 일반 유저가 마우스로 정적 링크를 밟아 웹 서핑을 할 때와는 아주 상이한 헤더 데이터 구조(sec-fetch-mode, sec-fetch-dest: manifest, CORS 익명 요청 등)를 실어 보냅니다.
2. Cloudflare Bot Management (WAF)의 정적 파일 크롤링 오진: 이 도메인의 앞 단을 수호하고 있던 Cloudflare Bot Management WAF 엔진은 이 날것의 기이한 백그라운드 비동기 요청 스트림을 감지하자마자, 사람이 하는 정상 브라우징이 아닌 ‘악의적인 스크래핑 봇이 보안 구역에 직접 침입하여 소스 코드를 빼 가려는 불법 침투 행위’로 과도하게 오탐하여 칼같이 차단을 집행했던 것이었습니다.

2-2. 💡 우아한 해결책 및 구현 명세

• 해결 방안:
  • 보안 초병이 너무 부지런히 일한 나머지 시스템의 인프라 정맥을 끊어놓은 꼴이었습니다. 이를 해결하기 위해 WAF 방화벽 감도를 일괄 낮추는 위험천만한 타협은 배제해야 했습니다.
  • 그 대신, 보안 위협에 노출될 기밀 데이터가 전무한 /manifest.json 파일의 안전한 공용 성격을 착안하여, 오직 해당 단일 파일 경로에만 국한해 봇 탐지를 우회해 주는 ‘극소 영역 우회(Granular Bypass)’ 커스텀 규칙을 수립했습니다.
• Cloudflare WAF Custom Rule 명세:
  1. 규칙 이름: PWA Manifest WAF Granular Bypass Skip
  2. 트래픽 매칭 조건 (Expression):
     • 필드: URI Path
     • 연산자: equals
     • 값: /manifest.json
  3. 취할 작업 (Action): Skip
  4. Skip할 대상 세부 설정:
     • ☑ Bot Management (오탐 차단 바이패스)
     • ☑ WAF Managed Rules (기타 매니지드 규칙 탐지 바이패스)
  • 이렇게 세밀하게 핀포인트로 규칙을 주입하게 되면, /api/auth/login이나 중요 회원 정보 API 같은 진짜 칼끝이 향하는 영역의 봇 차단 보안 장벽은 100% 동일하게 철벽 보존하면서도, 안전한 공용 관문인 매니페스트 통신만 깨끗하게 뚫어낼 수 있게 됩니다.

2-3. ✅ 결과 검증 및 모던 오픈소스 라이브러리 검토

• 결과 검증:
  • 매니페스트 복귀 완료: WAF Skip 정책을 배포하고 브라우저 강력 새로고침을 통해 네트워크 패널을 감시한 결과, /manifest.json 파일의 HTTP 응답 상태가 200 OK로 즉시 정상 복구됨을 입증했습니다.
  • 홈 화면 설치 기능 정상화: 모바일 사파리 및 안드로이드 크롬 기기로 사이트에 진입하자마자, 하단에서 “홈 화면에 이 앱 추가” 안내 배너와 팝업 제스처가 부드럽고 수려하게 점등되는 성과를 거두었습니다.
  • 서비스 워커(sw.js) 연계 가동: 매니페스트 관문이 안전하게 열리자, 브라우저가 비로소 PWA 자격을 인정하여 sw.js (서비스 워커) 백그라운드 프록시를 정상 적재했습니다. 이로써 오프라인 캐싱과 고도화된 백그라운드 데이터 동기화를 향한 차세대 웹앱 고도화의 주춧돌을 안전하게 놓을 수 있었습니다.
• 추천 오픈소스 라이브러리 검토:
  1. Cloudflare WAF Custom Rules
     • 평가: 도메인 전체에 광범위한 침투 방어막을 얹어주면서도, 정규식 매칭을 통해 특정 API나 경로에 한정하여 세련되게 우회(Skip)를 구성해 줄 수 있는 퍼블릭 클라우드 최고의 수문장 인프라 솔루션입니다.
  2. Workbox (by Google Chrome team)
     • 평가: PWA 서비스 워커를 날것으로 코딩하면 수백 줄에 걸친 캐시 제어 루프와 라이프사이클 관리에 버그가 나기 십상입니다. Workbox 라이브러리를 도입하면 ‘NetworkFirst’, ‘CacheFirst’, ‘Stale-While-Revalidate’ 같은 고급 오프라인 캐싱 아키텍처 전략을 단 몇 줄의 설정만으로 무장애 이식할 수 있어 PWA 고도화 단계에서 필수로 검토해 보실 것을 적극 권장합니다.

---