From 7e50f16b7757a64555c967c83c7fbce8ec6928fb Mon Sep 17 00:00:00 2001 From: Jeongwoo Choi Date: Tue, 11 Aug 2026 12:50:50 +0900 Subject: [PATCH] docs: add firewall & proxy checklist page Add docs/firewall.html, a standalone bilingual (KO/EN) guide listing every outbound endpoint CopilotWatchTower contacts, so admins can pre-clear firewall/proxy rules before installing. - Required domains (Entra ID auth, Microsoft Graph, auth CDNs, blob storage) and optional ones (Purview eDiscovery, Power Platform/Copilot Studio, GitHub release download), each with port and requesting component (Node vs Chromium vs OS browser). - Copy-to-clipboard allowlist block. - Warns that the Node collection path uses global fetch and ignores system proxy/PAC settings while the embedded Chromium windows honour them, so interactive sign-in can succeed while background collection silently fails. - Warns that TLS-inspection appliances break the Node path since it trusts only bundled root CAs; suggests bypass or NODE_EXTRA_CA_CERTS. - Loopback note for the admin-consent callback, PowerShell connectivity test snippets, and a symptom/cause troubleshooting table. Link it from index.html via the nav, a banner in the download section, and the footer, and fix a pre-existing horizontal overflow of the header on narrow viewports. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/firewall.html | 1124 ++++++++++++++++++++++++++++++++++++++++++++ docs/index.html | 56 ++- 2 files changed, 1178 insertions(+), 2 deletions(-) create mode 100644 docs/firewall.html diff --git a/docs/firewall.html b/docs/firewall.html new file mode 100644 index 0000000..9baf55f --- /dev/null +++ b/docs/firewall.html @@ -0,0 +1,1124 @@ + + + + + +방화벽 · 프록시 점검 가이드 · CopilotWatchTower + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + CopilotWatchTower + + +
+
+ + +
+
+

홈 › 방화벽 · 프록시 가이드

+

설치 전 점검할 방화벽 · 프록시 허용 목록

+

+ CopilotWatchTower는 관리자 PC 한 대에서 실행되는 데스크톱 앱이며, 수집한 데이터를 외부로 전송하지 않습니다. + 다만 Microsoft 365·Power Platform API를 직접 호출하므로 아래 도메인에 대한 아웃바운드 HTTPS(443) 통신이 필요합니다. + 폐쇄망·프록시·TLS 검사 환경에서는 설치 전에 이 목록을 네트워크 담당자와 함께 점검하세요. +

+

대상 버전 v2.0.0 · 상용(Commercial) 클라우드 기준 · 모든 통신은 아웃바운드 TCP 443

+
+
+ + +
+
+ 3줄 요약 +

바쁘다면 이것만

+
+
+
🔓
+

필수는 2개 도메인

+

login.microsoftonline.com과 graph.microsoft.com만 열려 있으면 온보딩·대화 수집·사용량 리포트 등 핵심 기능이 동작합니다. 나머지는 사용하는 기능에 따라 추가하세요.

+
+
+
🧩
+

네트워크 스택이 두 개

+

앱 내부 HTTPS 클라이언트(Node)와 내장 브라우저 창(Chromium)이 서로 다른 경로로 나갑니다. Chromium만 Windows 시스템 프록시를 따르므로, 프록시 설정 하나만으로는 부족할 수 있습니다.

+
+
+
🛡️
+

TLS 검사는 예외 처리

+

인증·Graph 트래픽에 SSL 가로채기를 적용하면 인증서 검증 실패로 수집이 통째로 멈춥니다. 해당 도메인은 검사 예외(bypass)로 두는 것을 권장합니다.

+
+
+
+
+ + +
+
+ 허용 목록 +

기능별 아웃바운드 도메인

+

+ 모든 통신은 아웃바운드 TCP 443(HTTPS)입니다. 인바운드 개방은 필요하지 않습니다. + 「요청 주체」는 그 도메인을 누가 호출하는지를 뜻하며, 프록시·TLS 검사 정책을 세울 때 중요합니다. +

+
+
Node 앱 내부 HTTPS 클라이언트 (백그라운드 수집)
+
Chromium 앱이 띄우는 내장 브라우저 창 (대화형 로그인)
+
OS 기본 웹 브라우저로 전달 (외부 링크)
+
+ + +
+
🔑
+

인증 & Microsoft Graph

+ 필수 +
+

온보딩(앱 자동 등록·관리자 동의), Copilot 대화 수집(API), 사용량 리포트, 감사 로그 등 앱의 모든 기본 동작에 필요합니다.

+
+ + + + + +
도메인포트요청 주체용도
+
+ + +
+
🔎
+

Purview eDiscovery 수집

+ 선택 +
+

라이선스가 없는 사용자의 Copilot 대화까지 eDiscovery로 복원하는 기능을 사용할 때만 필요합니다. 내보내기 결과 ZIP은 Microsoft가 반환하는 동적 URL에서 내려받습니다.

+
+ + + + + +
도메인포트요청 주체용도
+
+ + +
+
⚡
+

Power Platform & Copilot Studio

+ 선택 +
+

Copilot Studio 대화(Dataverse conversationtranscripts) 수집과 Copilot 메시지 크레딧 소비량 조회를 사용할 때만 필요합니다. Dataverse 호스트는 테넌트 환경마다 지역 접미사가 달라지므로 와일드카드 허용을 권장합니다.

+
+ + + + + +
도메인포트요청 주체용도
+
+ + +
+
📦
+

배포 & 로컬 통신

+ 선택 +
+

앱에는 자동 업데이트 기능이 없습니다. GitHub 접속은 설치 파일을 내려받는 시점에만 필요하며, 실행 중에는 사용하지 않습니다.

+
+ + + + + +
도메인포트요청 주체용도
+
+ +
+
ℹ️
+
+ 앱이 호출하지 않는 것: 분석·텔레메트리 서비스, 외부 폰트/CDN, 라이선스 서버, 자체 백엔드가 전혀 없습니다. + 위 표에 없는 도메인으로 나가는 트래픽이 보인다면 앱의 동작이 아닙니다. +
+
+
+
+ + +
+
+
+
+ 복사용 +

허용 목록 한 번에 붙여넣기

+
+ +
+

방화벽·프록시 정책에 그대로 넣을 수 있는 도메인 목록입니다. 사용하지 않는 기능의 줄은 지워서 최소 권한으로 운영하세요.

+
+
+
+ + +
+
+ 주의사항 1 +

프록시 환경에서 꼭 확인할 것

+

+ CopilotWatchTower는 하나의 앱 안에서 두 가지 서로 다른 네트워크 스택을 사용합니다. 이 둘은 프록시 설정을 공유하지 않습니다. +

+ +

① 내장 브라우저 창 (Chromium)

+

+ Power Platform 관리 센터·Power Apps 메이커 포털 로그인, eDiscovery 대화형 다운로드에 사용됩니다. + Chromium 스택이므로 Windows 시스템 프록시 설정(WinINET·WPAD·PAC 스크립트)을 자동으로 따릅니다. 별도 설정이 대부분 필요하지 않습니다. +

+ +

② 앱 내부 HTTPS 클라이언트 (Node)

+

+ Graph 대화·리포트 수집, Dataverse 조회, 라이선싱 API 등 실제 데이터 수집의 대부분을 담당합니다. + 런타임 기본 fetch를 그대로 사용하므로 시스템 프록시 설정과 HTTP_PROXY / HTTPS_PROXY 환경 변수, PAC 스크립트를 인식하지 않습니다. + 명시적 프록시를 통해서만 외부로 나갈 수 있는 네트워크라면, 이 경로의 요청은 프록시를 우회하려다 그대로 차단됩니다. +

+ +
+
⚠️
+
+ 권장 구성: 위 표의 도메인을 프록시 예외(bypass) 목록에 넣고 직접 아웃바운드 443을 허용하거나, + 투명 프록시(transparent proxy)를 통해 나가도록 구성하세요. + 「내장 브라우저 로그인은 되는데 수집만 0건」이라면 거의 항상 이 문제입니다. +
+
+
+
+ + +
+
+ 주의사항 2 +

TLS(SSL) 검사 장비가 있다면

+

+ SSL 가로채기 장비는 사내 CA로 인증서를 재발급합니다. 내장 브라우저 창은 Windows 인증서 저장소를 사용하므로 대개 문제가 없지만, + 앱 내부 HTTPS 클라이언트는 런타임에 내장된 루트 CA 목록만 신뢰하므로 사내 CA를 알지 못해 연결이 실패합니다. +

+
    +
  • 가장 권장: login.microsoftonline.com, graph.microsoft.com을 TLS 검사 예외로 지정합니다. Microsoft도 인증·Graph 트래픽에 대한 가로채기를 권장하지 않습니다.
    • +
  • 차선책: 예외를 둘 수 없다면 사내 루트 CA를 PEM으로 내보낸 뒤 시스템 환경 변수 NODE_EXTRA_CA_CERTS에 해당 파일 경로를 지정하고 앱을 재시작합니다.
    • +
  • 증상: 수집 로그에 unable to verify the first certificate, self-signed certificate in certificate chain, UNABLE_TO_GET_ISSUER_CERT_LOCALLY가 보이면 TLS 검사 문제입니다.
    • +
+
+
+ + +
+
+ 주의사항 3 +

로컬 방화벽 · 루프백

+

+ 온보딩 마법사는 Entra ID 관리자 동의 결과를 돌려받기 위해 127.0.0.1에 임시 HTTP 리스너를 잠깐 띄웁니다(포트는 OS가 자동 할당). + 외부에 노출되지 않는 루프백 전용 통신이므로 인바운드 방화벽 규칙을 새로 만들 필요는 없습니다. +

+
    +
  • Windows Defender 방화벽 알림이 뜨면 취소하지 말고 허용하세요. 차단하면 관리자 동의 후 온보딩이 끝나지 않고 계속 대기합니다.
    • +
  • EDR·엔드포인트 보호 솔루션이 루프백 리스닝 소켓이나 브라우저 자동화 동작을 차단하지 않는지 확인하세요.
    • +
  • 앱 데이터는 %LOCALAPPDATA%의 로컬 SQLite에 저장됩니다. 별도의 DB 서버 포트는 사용하지 않습니다.
    • +
+
+
+ + +
+
+ 점검 +

PowerShell로 5분 만에 확인

+

앱을 설치할 관리자 PC에서, 실제로 앱을 실행할 계정으로 아래를 실행하세요. 다른 PC나 다른 계정에서의 결과는 참고가 되지 않습니다.

+ +

1. 도메인별 443 연결 확인

+
# 각 도메인의 TCP 443 도달 여부를 확인합니다. +$targets = @( + 'login.microsoftonline.com', + 'graph.microsoft.com', + 'aadcdn.msftauth.net', + 'globaldisco.crm.dynamics.com', + 'admin.powerplatform.microsoft.com', + 'licensing.powerplatform.microsoft.com', + 'api.bap.microsoft.com', + 'make.powerapps.com' +) + +foreach ($t in $targets) { + $r = Test-NetConnection -ComputerName $t -Port 443 -WarningAction SilentlyContinue + '{0,-40} {1}' -f $t, $(if ($r.TcpTestSucceeded) { 'OK' } else { 'BLOCKED' }) +}
+ +

2. TLS 가로채기 여부 확인

+

응답한 인증서의 발급자(Issuer)가 Microsoft 계열이 아니라 사내 보안 장비 이름이라면 TLS 검사가 적용된 것입니다.

+
# 인증서 발급자를 확인합니다. +$c = [System.Net.Http.HttpClientHandler]::new() +$issuer = $null +$c.ServerCertificateCustomValidationCallback = { param($m,$cert,$ch,$e) $script:issuer = $cert.Issuer; $true } +$h = [System.Net.Http.HttpClient]::new($c) +$null = $h.GetAsync('https://graph.microsoft.com/v1.0/$metadata').Result +"Issuer: $issuer"
+ +

3. 실제 API 응답 확인

+

401 Unauthorized가 돌아오면 정상입니다(인증 없이 호출했으므로). 타임아웃·인증서 오류·프록시 오류가 나면 네트워크 문제입니다.

+
try { + Invoke-WebRequest 'https://graph.microsoft.com/v1.0/me' -UseBasicParsing -TimeoutSec 15 | Out-Null +} catch { + "응답: $($_.Exception.Message)" +}
+
+
+ + +
+
+ 문제 해결 +

증상으로 원인 찾기

+

앱의 「수집 로그」 화면에서 실패한 단계를 확인한 뒤, 아래 표에서 대응되는 도메인을 우선 점검하세요.

+
+ + + + + +
증상확인할 도메인 · 원인
+
+
+
+ + +
+
+ 참고 +

Microsoft 공식 엔드포인트 문서

+

+ 이 페이지는 CopilotWatchTower가 실제로 호출하는 대상만 정리한 것입니다. + 테넌트 전체의 Microsoft 365 통신을 허용해야 한다면 아래 공식 문서를 함께 참고하세요. + 상용(Commercial) 클라우드 기준이며, GCC High·DoD·中國 세종 클라우드는 지원 대상이 아닙니다. +

+ +
+
+ + + + + + + diff --git a/docs/index.html b/docs/index.html index 60df3a6..33545bc 100644 --- a/docs/index.html +++ b/docs/index.html @@ -63,7 +63,8 @@ .nav { display: flex; align-items: center; justify-content: space-between; height: 64px; } .brand { display: flex; align-items: center; gap: 12px; font-weight: 800; font-size: 17px; letter-spacing: -.2px; } .brand .logo { width: 32px; height: 32px; flex: 0 0 auto; border-radius: 8px; } - .nav-links { display: flex; gap: 28px; align-items: center; font-size: 14.5px; color: var(--muted); } + .nav-links { display: flex; gap: 24px; align-items: center; font-size: 14.5px; color: var(--muted); } + @media (min-width: 901px) { .nav-links { white-space: nowrap; } } .nav-links a:hover { color: var(--text); } .nav-cta { background: var(--accent-grad); color: #fff; padding: 9px 18px; border-radius: 10px; @@ -78,7 +79,14 @@ letter-spacing: .2px; transition: color .15s ease, border-color .15s ease, background .15s ease; } .lang-toggle:hover { color: var(--text); border-color: var(--accent); background: var(--card-2); } - @media (max-width: 760px) { .nav-links a:not(.nav-cta) { display: none; } } + @media (max-width: 900px) { .nav-links a:not(.nav-cta) { display: none; } } + @media (max-width: 460px) { + .brand { font-size: 15px; gap: 9px; min-width: 0; } + .brand span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } + .nav-links { gap: 10px; flex: 0 0 auto; } + .lang-toggle { padding: 7px 10px; font-size: 12px; } + .nav-cta { padding: 8px 13px; font-size: 13px; } + } /* ---------- Hero ---------- */ .hero { position: relative; padding: 96px 0 72px; text-align: center; } @@ -231,6 +239,27 @@ .pkg-list { display: inline-flex; flex-wrap: wrap; gap: 8px; justify-content: center; margin-top: 8px; } .pkg { font-size: 12.5px; color: var(--muted); background: var(--bg-soft); border: 1px solid var(--border); padding: 5px 11px; border-radius: 8px; font-family: ui-monospace, monospace; } + /* ---------- Firewall banner ---------- */ + .fw-banner { + margin: 30px auto 0; max-width: 820px; display: flex; gap: 20px; align-items: center; + background: var(--card); border: 1px solid var(--border); border-radius: 18px; + padding: 24px 28px; text-align: left; flex-wrap: wrap; + } + .fw-banner .fw-ic { + width: 52px; height: 52px; flex: 0 0 auto; border-radius: 14px; display: grid; place-items: center; + background: linear-gradient(135deg, rgba(91,140,255,.18), rgba(124,92,255,.18)); + border: 1px solid var(--border); font-size: 25px; + } + .fw-banner .fw-body { flex: 1 1 320px; } + .fw-banner h3 { font-size: 17.5px; font-weight: 800; margin-bottom: 6px; } + .fw-banner p { color: var(--muted); font-size: 14.2px; } + .fw-banner .fw-cta { + flex: 0 0 auto; background: var(--bg-soft); border: 1px solid var(--border); color: var(--text); + padding: 11px 20px; border-radius: 11px; font-weight: 700; font-size: 14.5px; + transition: border-color .15s ease, background .15s ease, transform .15s ease; + } + .fw-banner .fw-cta:hover { border-color: var(--accent); background: var(--card-2); transform: translateY(-2px); } + /* ---------- Dev / code ---------- */ .code { background: #0b1020; border: 1px solid var(--border); border-radius: 14px; padding: 22px 24px; @@ -277,6 +306,7 @@ 데이터 출처 주요 화면 다운로드 + 방화벽 가이드 커뮤니티 GitHub @@ -610,6 +640,15 @@

지금 바로 시 자체 서명 인증서를 사용하므로 설치 전 인증서 신뢰 등록이 필요합니다. 자세한 절차는 압축 안의 INSTALL.txt를 참고하세요.

+ +
+
🧱
+
+

설치 전에 방화벽 · 프록시부터 점검하세요

+

앱은 Microsoft 365·Power Platform API를 직접 호출합니다. 폐쇄망·프록시·TLS 검사 환경이라면 허용해야 할 도메인과 포트, 자주 겪는 오류를 미리 확인하세요.

+
+ 🧱 방화벽 가이드 보기 → +
@@ -656,6 +695,7 @@

커뮤니티 + 방화벽 가이드 GitHub Releases 문서 @@ -681,6 +721,7 @@

INSTALL.txt를 참고하세요.`, + "fw.title": `설치 전에 방화벽 · 프록시부터 점검하세요`, + "fw.lead": `앱은 Microsoft 365·Power Platform API를 직접 호출합니다. 폐쇄망·프록시·TLS 검사 환경이라면 허용해야 할 도메인과 포트, 자주 겪는 오류를 미리 확인하세요.`, + "fw.cta": `🧱 방화벽 가이드 보기 →`, + "dev.eyebrow": `개발자용`, "dev.title": `소스에서 직접 실행`, "dev.lead": `Python 3.11+ 가상환경에서 editable 설치 후 바로 실행할 수 있습니다.`, @@ -833,6 +878,7 @@

INSTALL.txt inside the archive.`, + "fw.title": `Check your firewall and proxy before installing`, + "fw.lead": `The app calls Microsoft 365 and Power Platform APIs directly. On restricted, proxied, or TLS-inspecting networks, review the domains and ports to allow — and the errors you'll hit if you don't — up front.`, + "fw.cta": `🧱 Open the firewall guide →`, + "dev.eyebrow": `For developers`, "dev.title": `Run directly from source`, "dev.lead": `In a Python 3.11+ virtual environment, install in editable mode and run right away.`, @@ -1000,6 +1051,7 @@