외부 egress 호스트 allowlist QA 가이드
이 문서는 Pipeline Studio의 외부 egress 호스트 allowlist(ws-admin 전용)를 QA가 화면에서 직접 따라 검증할 수 있도록 단계별 스크린샷과 함께 정리한 것입니다. 모든 화면은 실제 prod(gend.genon.ai)의 finance-invest 워크스페이스에서 ws-admin 계정으로 캡처했습니다.
개요
수집 소스(예: REST Source)가 외부 API를 호출할 때 secret(API 키) 을 써야 하는 경우, 그 키가 임의의 호스트로 새지 않도록 GenD는 egress-proxy(공유 인프라 #2290)를 단일 통로로 둡니다. 이 프록시는:
- 모든 외부 호출에 대해 SSRF 검증(사설·루프백·클라우드 메타데이터·CGNAT IP 차단, DNS rebind 방어, https-only)을 수행하고,
- secret을 참조하는 요청은 대상 호스트가 해당 워크스페이스의 allowlist에 등록돼 있을 때만 통과시킵니다(없으면 차단).
이 화면은 그 워크스페이스별 호스트 allowlist를 ws-admin이 관리하는 곳입니다.
권한: 이 탭은 워크스페이스 admin(
/tenants/<slug>/admins) 또는 글로벌 admin에게만 보입니다. 일반 멤버에게는 탭이 노출되지 않으며, API 레벨에서도 list/create/delete 모두 403입니다.주의 — 워크스페이스 없는 계정: 글로벌 admin 이라도 어떤 워크스페이스에도 속하지 않으면(상단바 "워크스페이스 없음") 호스트 등록이 에러 없이 무시됩니다 — 추가 버튼을 눌러도 목록이 계속 비어 있습니다. 등록 대상 워크스페이스에 소속된 계정으로 로그인한 뒤 진행하세요(그룹 변경 후에는 재로그인 필요). 2026-07-21 E2E 에서 실제로 겪은 함정입니다.
현재 상태: egress 호스트 등록과 이를 소비하는
rest_source노드 모두 prod 라이브입니다 (Epic #2286 전체 활성화, 2026-06-25). 여기 등록한 호스트로 rest_source 가 secret 참조 호출을 바로 수행할 수 있습니다.
1. egress 호스트 탭 열기
Pipeline Studio(/pipeline-studio) 상단 탭에서 외부 egress 호스트 탭을 엽니다. (ws-admin에게만 보입니다.)
확인 포인트(QA): 일반 멤버 계정으로 로그인하면 이 탭 자체가 보이지 않아야 합니다(권한 게이트).
2. 호스트 추가
호스트 추가 버튼을 누르면 다이얼로그가 열립니다. 호스트(FQDN) 에 정확한 도메인(예: opendart.fss.or.kr)을 입력합니다. 메모는 선택입니다.
저장하면 목록에 추가되고 성공 알림이 표시됩니다.
확인 포인트(QA): 입력한 호스트가 정규화(소문자, 끝점 제거)되어 저장됩니다. 예:
OpenDART.FSS.or.KR.→opendart.fss.or.kr.
3. 중복 추가는 거부
같은 호스트를 다시 추가하면 (workspace_id, host) 유일 제약으로 409가 반환되고 에러 알림이 뜹니다. 목록의 행 수는 그대로 1개입니다(중복 생성 안 됨).
4. 호스트 삭제
각 행의 휴지통 아이콘(스크린리더 라벨 "Delete <host>")을 누르면 해당 호스트가 allowlist에서 제거됩니다.
확인 포인트(QA): 삭제 후 그 호스트로 향하는 secret-참조 수집 요청은 egress-proxy에서 다시 차단됩니다(403
HOST_NOT_ALLOWLISTED).
보안 동작 요약 (참고)
| 상황 | egress-proxy 동작 |
|---|---|
| secret 미사용(공개 RSS 등) | allowlist 불필요 — SSRF 필터만 통과하면 호출 가능 |
| secret 사용 + 호스트 allowlist에 있음 | 통과(서버사이드에서 Vault 해석·헤더 주입, caller는 평문 미수신) |
| secret 사용 + 호스트 allowlist에 없음 | 차단(403) — 임의 호스트로 secret 유출 방지 |
| 사설/메타데이터/CGNAT IP, http, rebind | 차단(SSRF) — allowlist 여부와 무관 |
자동 검증
이 가이드의 모든 단계는 ui/tests/egress-hosts-e2e.spec.ts(Playwright)로 자동 검증되며, QA_CAPTURE=1로 실행하면 위 스크린샷이 재생성됩니다.
E2E_BASE_URL=https://gend.genon.ai E2E_USERNAME=... E2E_PASSWORD=... \
QA_CAPTURE=1 pnpm exec playwright test egress-hosts