SHIELD Gate 사용자 로그 오류 대응 가이드
SHIELD Gate 통합 로그 중 사용자 로그 이벤트가 WARN 또는 ERROR 레벨로 기록됐을 때의 의미와 대응 절차를 정리한 고객용 운영 가이드입니다.
목차
1. 개요
1.1 로그 레벨 구분
| 레벨 | 의미 |
|---|---|
INFO | 정상 동작 또는 일반 이벤트 기록. 별도 조치 불필요. |
WARN | 서비스 이용에 직접적인 영향은 없으나 점검 가치가 있는 상황. |
ERROR | 기능 수행 실패. 원인 확인 및 대응 필요. |
1.2 본 가이드의 범위
- 본 가이드는 사용자 로그 중
ERROR레벨이 발생할 수 있는 이벤트 에 한정해 상세 대응을 설명합니다. - 항상
INFO로만 기록되는 이벤트 목록은 5.1 부록 참조.
2. 사용자 로그 이벤트 요약
아래 표는 SHIELD Gate 사용자 로그의 전체 이벤트와 ERROR 레벨 발생 가능 여부를 정리한 것입니다.
| 분류 | 이벤트 코드 | 이벤트명 | ERROR 발생 | 대응 섹션 |
|---|---|---|---|---|
| 인증 | CALLBACK_SECURITY365_CODE | 로그인 | ⚠️ (※1) | — |
POST_SIGN_OUT | 로그아웃 | ✅ | 3.1 | |
POST_RELAY_TOKEN | 서비스 이동 | ✅ | 3.1 | |
NAVIGATE_TO_ADMIN_PAGE | 관리자페이지로 이동 | ❌ | — | |
| 격리 브라우저 | POST_INQUIRY_WORK_ITEM_ACCESS_URL | 브라우저 접속 | ❌ | — |
RBI_URL_CHANGED | 브라우저 접속 후 이동 | ❌ | — | |
RBI_CHECK_INPUT_TEXT | 사용자 입력 민감정보 검사 | ❌ | — | |
RBI_CLIPBOARD_ACCESS_RB2PC | 격리 브라우저에서 복사 | ❌ | — | |
RBI_CLIPBOARD_ACCESS_PC2RB | 격리 브라우저로 붙여넣기 | ❌ | — | |
RBI_USAGE_ERROR | 격리 브라우저 오류 | ✅ | 3.6 / 4 | |
RBI_SESSION_TIMEOUT | 격리 브라우저 세션 타임아웃 | ❌ | — | |
RBI_KEYBOARD_INPUT | 키보드 입력 차단 | ❌ | — | |
| 개인화 | POST_FAVORITE_ITEM | 즐겨찾기 등록 | ✅ | 3.2 |
DELETE_FAVORITE_ITEM | 즐겨찾기 삭제 | ✅ | 3.2 | |
| 파일 | RBI_FILE_UPLOAD | 파일 업로드 | ✅ | 3.4 |
RBI_FILE_DOWNLOAD | 파일 다운로드 | ✅ | 3.5 | |
RBI_FILE_VIEWER_REQUEST | SHIELD Viewer 요청 | ❌ | — | |
| 상단바 | GET_EXTERNAL_INTERFACE_ACCESS_URL | 상단바 외부 링크 접속 | ✅ | 3.3 |
※1
CALLBACK_SECURITY365_CODE안내 로그인 이벤트는 로그인에 성공한 경우에만 기록됩니다. 로그인 실패 자체는 사용자 정보를 확정할 수 없어 별도의ERROR로그로 남지 않습니다. 로그인 실패가 반복될 경우 소프트캠프에 문의 바랍니다.
3. ERROR 발생 이벤트별 대응 가이드
표 안의 "담당" 표기 규약
사용자— 재로그인·재시도·환경 확인 등으로 본인이 해결 가능한 범위고객사 관리자— 정책·권한·방화벽·DNS·인증서 등 고객사 운영 영역에서 점검·설정으로 해결 가능한 범위대상 사이트 측— 격리 브라우저로 접속하는 외부 웹사이트 측 책임 범위소프트캠프— 서비스 내부 이슈로 판단되어 문의가 필요한 범위
3.1 POST_SIGN_OUT / POST_RELAY_TOKEN (로그아웃 / 서비스 이동)
🔧 책임 구분 요약 —
소프트캠프 영역이 이벤트의ERROR는 전적으로 서비스 내부 이슈로만 발생 합니다. 고객사 설정으로 유발되는 케이스는 없으며, 고객사 측 조치 항목 없이 바로 소프트캠프 문의 대상입니다.
| 항목 | 내용 |
|---|---|
| 이벤트 | POST_SIGN_OUT — SHIELD Gate 로그아웃POST_RELAY_TOKEN — Security365 관리센터에서 SHIELD Gate 관리자 페이지로 이동 |
| 일반적 성격 | 서비스 내부 이슈로만 발생. 사용자/고객사 설정에서 유발되는 케이스는 없음. |
3.1.1 발생 가능 원인
| # | 원인 | 담당 |
|---|---|---|
| 1 | 내부 데이터 저장소 일시 장애 | 소프트캠프 |
| 2 | 인증 서비스 연동 오류 | 소프트캠프 |
3.1.2 권장 조치
- [사용자] 재로그인 후 동일 작업 재시도
- [고객사 관리자] 동일 시간대 다른 사용자에게도 같은 에러가 발생했는지 확인 (인프라성 이슈 판단)
- 동일 증상이 지속되면 소프트캠프 문의
3.2 POST_FAVORITE_ITEM / DELETE_FAVORITE_ITEM (즐겨찾기 등록 / 삭제)
🔧 책임 구분 요약 —
소프트캠프 영역이 이벤트의ERROR는 서비스 내부 데이터 저장소 이슈로만 발생 합니다. 고객사 측 조치 항목 없이 소프트캠프 문의 대상입니다.
| 항목 | 내용 |
|---|---|
| 이벤트 | POST_FAVORITE_ITEM — 즐겨찾기 등록DELETE_FAVORITE_ITEM — 즐겨찾기 삭제 |
| 일반적 성격 | 서비스 내부 데이터 저장소 이슈로 주로 발생. |
3.2.1 발생 가능 원인
| # | 원인 | 담당 |
|---|---|---|
| 1 | 내부 데이터 저장소 연결 오류 | 소프트캠프 |
| 2 | 기타 서비스 내부 예외 | 소프트캠프 |
3.2.2 권장 조치
- [사용자] 잠시 후 재시도
- 반복 발생 시 소프트캠프 문의
3.3 GET_EXTERNAL_INTERFACE_ACCESS_URL (상단바 외부 링크 접속)
🔧 책임 구분 요약 —
고객사 관리자 1차 점검1차로 고객사 관리자의 상단바 외부 링크 설정 을 확인. 설정이 정상임에도 발생하면 소프트캠프 문의.
| 항목 | 내용 |
|---|---|
| 이벤트 | 관리자가 사용자 페이지 상단바에 설정한 커스텀 버튼을 사용자가 클릭해 외부 URL로 접속하는 동작 |
3.3.1 발생 가능 원인
| # | 원인 | 담당 | 비고 |
|---|---|---|---|
| 1 | 상단바 외부 링크가 설정되지 않은 상태에서 호출 | 고객사 관리자 | 관리자 페이지 UI에서 사전 차단되므로 통상 발생하지 않음 |
| 2 | 내부 데이터 저장소 조회 오류 | 소프트캠프 | — |
3.3.2 권장 조치
- [고객사 관리자] 관 리자 페이지 > 상단바 설정에서 해당 커스텀 버튼이 정상 등록돼 있는지 확인
- 설정이 정상임에도 반복 발생 시 소프트캠프 문의
3.4 RBI_FILE_UPLOAD (파일 업로드)
🔧 책임 구분 요약 —
외부 사이트 / 사용자 환경 1차 점검대부분의 케이스는 업로드 대상 사이트 측 이슈 또는 사용자 PC의 네트워크 환경 이슈 가 1순위 원인. SHIELD Drive 관련 실패만 권한·인증 확인 후 소프트캠프 문의 대상.
격리 브라우저를 통한 파일 업로드 과정에서 발생하는 ERROR 로그입니다. 업로드 경로에 따라 원인이 달라지므로 아래 4개 케이스로 구분해 설명합니다.
3.4.1 [케이스 A] 로컬 PC → 격리 브라우저로 접속한 사이트 업로드
사용자가 격리 브라우저에서 열린 사이트에 로컬 파일을 첨부해 업로드할 때 발생.
| # | 발생 원인 | 담당 | 확인 방법 |
|---|---|---|---|
| 1 | 업로드 대상 사이트 서버의 비정상 응답 (사이트 일시 장애, 인증 만료, 파일 크기/형식 정책 위반 등) | 대상 사이트 측 | 사용자가 대상 사이트에 직접 접속해서 동일 파일 업로드 시에도 동일 증상인지 비교 |
| 2 | 네트워크 단절 / CORS / DNS 실패로 요청 자체가 실패 | 사용자 / 고객사 관리자 | 사용자 PC 네트워크 상태, VPN 연결, 방화벽 정책 확인 |
| 3 | 대상 사이트가 JSON이 아닌 형식으로 응답 (HTML 에러 페이지 등) | 대상 사이트 측 | 대상 사이트 측 이슈 가능성이 높음 |
권장 조치
- 사용자 PC에서 대상 사이트에 직접 접속해 동일 파일 업로드가 정상인지 비교
- 직접 접속도 실패한다면 → 대상 사이트 측 이슈로 판단
- 직접 접속은 정상이지만 격리 브라우저에서만 실패한다면 → 소프트캠프 문의
3.4.2 [케이스 B] SHIELD Drive 파일 → 격리 브라우저 사이트 (SHIELD Drive 파일 가져오기 단계 실패)
사용자가 SHIELD Drive 다이얼로그에서 파일을 선택해 격리 브라우저 사이트에 업로드할 때, SHIELD Drive에서 원본 파일을 가져오는 단계 에서 실패.
| # | 발생 원인 | 담당 | 조치 |
|---|---|---|---|
| 1 | SHIELD Drive 인증이 만료되었거나 토큰이 유효하지 않음 | 사용자 | 로그아웃 후 재로그인 |
| 2 | 사용자에게 해당 파일 접근 권한이 없음 | 고객사 관리자 | 파일/폴더 접근 권한 부여 |
| 3 | 파일이 SHIELD Drive에서 이미 삭제되었거나 이동됨 | 사용자 | SHIELD Drive에서 파일 존재 여부 확인 후 재시도 |
| 4 | SHIELD Drive 서비스 내부 오류 | 소프트캠프 | 소프트캠프 문의 |
3.4.3 [케이스 C] SHIELD Drive 파일 → 격리 브라우저 사이트 (대상 사이트 업로드 단계 실패)
케이스 B와 동일한 흐름이지만, SHIELD Drive에서 파일을 정상적으로 가져온 뒤 격리 브라우저로 접속한 사이트에 업로드하는 단계에서 실패.
| # | 발생 원인 | 담당 | 확인 방법 |
|---|---|---|---|
| 1 | 대상 사이트 서버의 비정상 응답 | 대상 사이트 측 | 사용자가 대상 사이트에 직접 접속해 동일 증상인지 비교 |
| 2 | 네트워크 단절 또는 CORS 오류 | 고객사 관리자 | 네트워크 / 방화벽 정책 확인 |
3.4.4 [케이스 D] 다중 파일 업로드 (비동기 실패)
로컬 파일 또는 SHIELD Drive 파일을 한 번에 여러 개 업로드할 때, 일부 파일의 업로드 응답 처리 단계에서 실패.
- 원인·조치 기준은 케이스 A 와 동일
- 특정 파일만 반복 실패하는지, 전체 다발적으로 실패하는지 구분해 확인
3.5 RBI_FILE_DOWNLOAD (파일 다운로드)
🔧 책임 구분 요약 —
혼합 (SHIELD Drive 저장은 관리자 영역 비중 큼)다운로드 정책 트리거 실패(케이스 A)와 SHIELD Drive 업로드 네트워크 실패(케이스 B)는 소프트캠프 처리 영역. SHIELD Drive 저장 중 응답 오류(케이스 C)는 대부분 고객사 관리자의 스토리지 / 권한 / 확장자 정책 설정 영역.
격리 브라우저를 통한 파일 다운로드 과정에서 발생하는 ERROR 로그입니다. 다운로드 저장 위치(로컬 PC / SHIELD Drive)와 실패 지점에 따라 아래 3개 케이스로 구분합니다.
3.5.1 [케이스 A] 다운로드 정책 트리거 실패
사용자가 격리 브라우저 사이트에서 파일 다운로드 버튼을 클릭할 때, SHIELD Gate 백엔드의 다운로드 정책 처리 단계 에서 실패.
| # | 발생 원인 | 담당 |
|---|---|---|
| 1 | SHIELD Gate 서버 내부 오류 (임시 파일 생성 실패, 데이터 저장소 오류 등) | 소프트캠프 |
| 2 | 격리 브라우저 컨테이너에서 파일을 받아오는 단계의 오류 | 소프트캠프 |
| 3 | 분류되지 않은 예외 | 소프트캠프 |
권장 조치
- [사용자] 동일 파일 재다운로드 시도
- 다른 파일은 정상 다운로드되는데 특정 파일만 반복 실패한다면 해당 파일 정보와 함께 소프트캠프 문의
3.5.2 [케이스 B] SHIELD Drive 저장소로 다운로드 — 네트워크 / HTTP 예외
SHIELD Drive를 사용하는 환경에서, 격리 브라우저 사이트의 다운로드 파일을 SHIELD Drive로 보관하는 흐름 중 SHIELD Drive 업로드 API 호출 자체가 실패 한 경우.
| # | 발생 원인 | 담당 |
|---|---|---|
| 1 | SHIELD Gate 서버 / 격리 브라우저 컨테이너 파일 처리 오류 | 소프트캠프 |
| 2 | 서버 다운, 타임아웃 등 일시적 네트워크 예외 | 소프트캠프 |
권장 조치
- [사용자] 잠시 후 재시도
- 동일 시간대에 다수 사용자가 동일 증상을 겪는다면 → 인프라성 이슈 가능성
- 반복 발생 시 소프트캠프 문의
3.5.3 [케이스 C] SHIELD Drive 저장소로 다운로드 — 응답 비즈니스 코드 실패
케이스 B와 동일한 흐름이나 API 호출은 성공했고 SHIELD Drive 측 응답이 비정상 인 경우.
| # | 발생 원인 | 담당 | 조치 |
|---|---|---|---|
| 1 | SHIELD Drive 스토리지가 생성되어 있지 않음 | 고객사 관리자 | SHIELD Drive 스토리지 생성 |
| 2 | SHIELD Gate가 해당 스토리지에 접근 권한 없음 | 고객사 관리자 | 스토리지 접근 권한 설정 |
| 3 | 파일명이 SHIELD Drive 명명 규칙에 위배 | 사용자 | 파일명 변경 후 재시도 |
| 4 | 사용자 스토리지 용량 초과 | 고객사 관리자 | 파일 정리 또는 용량 증설 |
| 5 | SHIELD Drive가 해당 확장자를 미지원 / 차단 | 고객사 관리자 | SHIELD Drive 확장자 정책 확인 |
| 6 | 파일 저장소 연동 서비스의 업로드 실패 | 소프트캠프 | 소프트캠프 문의 |
| 7 | SHIELD Drive 내부 업로드 처리 실패 | 소프트캠프 | 소프트캠프 문의 |
| 8 | SHIELD Drive에 회사 또는 사용자 정보가 없음 | 고객사 관리자 | 사용자 프로비저닝 상태 확인 |
| 9 | 스토리지 정보 조회 실패 | 소프트캠프 | 소프트캠프 문의 |
| 10 | SHIELD Drive 스토리지 비활성화 상태 | 고객사 관리자 | 스토리지 활성화 |
| 11 | SHIELD Drive 스토리지 업로드 권한 없음 | 고객사 관리자 | 업로드 권한 부여 |
| 12 | 빈 파일(0 byte) 다운로드 시도 | 사용자 | 원본 파일 확인 |
| 13 | 기타 분류되지 않은 예외 | 소프트캠프 | 소프트캠프 문의 |
권장 조치
- 관리자 설정 계열(1·2·5·8·10·11)은 먼저 설정을 확인·보완
- 설정 정상 이후에도 발생 시 소프트캠프 문의
3.6 RBI_USAGE_ERROR (격리 브라우저 오류)
격리 브라우저 사용 중 발생한 시스템 오류를 모두 포괄하는 이벤트입니다. errorDetail 값으로 구체 원인이 구분되며, 상세 분류와 대응은 4장 RBI_USAGE_ERROR 상세 코드 가이드 를 참조해 주세요.
4. RBI_USAGE_ERROR 상세 코드 (errorDetail) 대응 가이드
RBI_USAGE_ERROR 이벤트와 함께 기록되는 errorDetail 필드로 구체 원인을 식별합니다. 분류 체계는 다음 8개 그룹 입니다.
| 그룹 | 분류 | 주요 성격 | 1차 책임 영역 |
|---|---|---|---|
| A | 컨테이너 / 세션 생성·할당 실패 | RBI 리소스 할당 단계 | 사용자(탭 한도) 또는 소프트캠프 |
| B | 세션 진입 / 검증 실패 | 사용자 세션 상태 이상 | 사용자 재진입 → 반복 시 소프트캠프 |
| C | 정책 조회 / 판정 실패 | 정책 서비스 연동 | 소프트캠프 (FAILED_NAVIGATED_PAGE는 대상 사이트 포함) |
| D | 컨테이너 연결 상태 | 런타임 연결 끊김 | 관리자 조치 결과 또는 소프트캠프 |
| E | 헬스체크 실패 | 격리 브라우저 인스턴스 기동 상태 | 고객사 관리자(방화벽/DNS) + 소프트캠프 |
| F | 브라우저 환경 | 사용자 PC의 크롬 버전 | 사용자 / 고객사 관리자(업데이트 정책) |
| G | 크롬 네트워크 계층 에러 | 격리 브라우저 → 외부 사이트 구간 | 고객사 관리자(네트워크·보안 점검) / 대상 사이트 측 |
| H | 기본값 (Fallback) | 분류 불가 예외 | 소프트캠프 |
💡 운영 팁 G 그룹은 사용자 수가 많아질수록 비중이 가장 크게 나타나는 그룹이며, 대부분 고객사의 네트워크·보안 장비 점검으로 1차 해소가 가능 합니다. 체크리스트(4.8.2)를 먼저 수행한 뒤에도 해소되지 않는 건 만 소프트캠프 문의로 전달하면 대응이 빨라집니다.
4.1 전체 errorDetail 인덱스
| 그룹 | errorDetail | 한 줄 요약 |
|---|---|---|
| A | FAILED_CREATING_CONTAINER | 격리 브라우저 컨테이너 생성 API 호출 실패 |
| A | ERROR_GET_CONTAINER_URL | 컨테이너 URL 획득 실패 (분류 외 예외의 대표 코드) |
| A | ERROR_GET_CONTAINER_URL_REASSIGN | 컨테이너 URL 재할당 경로 실패 |
| A | MAXIMUM_PODS_REACHED | 격리 브라우저 클러스터 수용량 초과 |
| A | MAXIMUM_TABS_REACHED | 사용자/테넌트 동시 오픈 탭 한도 초과 |
| B | NO_TAB_ID_SESSION | 세션 식별자 없음 또는 매핑 없음 (비정상 진입) |
| B | MISSING_SESSION_DATA | 세션 컨텍스트 없음 (만료 / 불일치) |
| B | MISSING_CURRENT_URL | 격리 대상 URL 비어 있음 |
| C | POLICY_QUERY_FAILED | 정책 서버 조회 실패 |
| C | FAILED_NAVIGATED_PAGE | 허용 URL이지만 실제 페이지 이동 실패 |
| D | CONTAINER_DISCONNECTED | 격리 브라우저 컨테이너 실시간 연결 끊김 |
| D | SESSION_TERMINATED_BY_ADMIN | 관리자가 세션 강제 종료 |
| E | HEALTH_CHECK_NETWORK_ERROR | 격리 브라우저 인스턴스 도달 실패 (TCP/TLS) |
| E | HEALTH_CHECK_TIMEOUT | 격리 브라우저 인스턴스 헬스체크 응답 지연 |
| F | BROWSER_VERSION_UPDATE_REQUIRED | 크롬 최소 버전 미달 |
| G | ERR_TIMED_OUT | 전체 요청 타임아웃 |
| G | ERR_NETWORK_CHANGED | 네트워크 전환 (Wi-Fi ↔ LAN, VPN 재접속) |
| G | ERR_CONNECTION_CLOSED | 송수신 중 연결 종료 |
| G | ERR_CONNECTION_RESET | 서버/경로 장비가 RST 전송 |
| G | ERR_CONNECTION_REFUSED | 대상 포트 listen 안 함 |
| G | ERR_CONNECTION_ABORTED | 연결 비정상 종료 (클라이언트 관점) |
| G | ERR_CONNECTION_FAILED | 일반 연결 실패 |
| G | ERR_NAME_NOT_RESOLVED | DNS 조회 실패 |
| G | ERR_INTERNET_DISCONNECTED | 클라이언트 인터넷 연결 없음 |
| G | ERR_SSL_PROTOCOL_ERROR | TLS 핸드셰이크 실패 |
| G | ERR_ADDRESS_INVALID | 잘못된 IP / 호스트 표기 |
| G | ERR_ADDRESS_UNREACHABLE | 라우팅상 도달 불가 |
| G | ERR_SSL_CLIENT_AUTH_CERT_NEEDED | mTLS 클라이언트 인증서 요구 |
| G | ERR_TUNNEL_CONNECTION_FAILED | HTTP CONNECT 프록시 터널링 실 패 |
| G | ERR_NO_SSL_VERSIONS_ENABLED | 사용 가능한 TLS 버전 없음 |
| G | ERR_SSL_VERSION_OR_CIPHER_MISMATCH | TLS 버전 / 암호 스위트 협상 실패 |
| G | ERR_CONNECTION_TIMED_OUT | TCP 연결 수립 타임아웃 |
| G | ERR_PROXY_CONNECTION_FAILED | 설정된 프록시 연결 실패 |
| G | SSL_CERTIFICATE_ERROR | 서버 인증서 유효성 오류 |
| G | ERR_CERT_AUTHORITY_INVALID | 발급 CA 신뢰 불가 |
| G | ERR_EMPTY_RESPONSE | 서버가 응답 없이 연결 종료 |
| H | UNKNOWN_SYSTEM_ERROR | 분류 불가 / 매핑 안 된 모든 예외의 기본값 |
4.2 A. 컨테이너 / 세션 생성·할당 실패
errorDetail | 원인 | 담당 |
|---|---|---|
FAILED_CREATING_CONTAINER | 격리 브라우저 컨테이너 생성 API 호출 자체가 실패. 주로 내부 관리 서비스 일시 장애, 인증 만료, 백엔드 예외. | 소프트캠프 |
ERROR_GET_CONTAINER_URL | 컨테이너 URL 획득 단계의 대표 오류 코드. 구체 원인이 별도 분류로 식별되지 않은 대부분의 예외가 이 값으로 집계됨. | 소프트캠프 |
ERROR_GET_CONTAINER_URL_REASSIGN | 기존 컨테이너가 비정상이어서 새 컨테이너로 재할당 을 시도하던 중 실패. | 소프트캠프 |
MAXIMUM_PODS_REACHED | 격리 브라우저 클러스터 전체의 수용량 상한에 도달. 신규 컨테이너 할당 거부. | 소프트캠프 |
MAXIMUM_TABS_REACHED | 사용자(또는 테넌트)당 동시 오픈 탭 한도 초과. 신규 탭 생성 단계에서 차단. | 사용자 |
권장 조치
MAXIMUM_TABS_REACHED: 사용자에게 사용하지 않는 탭을 닫도록 안내MAXIMUM_PODS_REACHED: 수용량 증설 협의 필요 — 소프트캠프 문의- 그 외 A 그룹 코드: 지속 재발 시 소프트캠프 문의
4.3 B. 세션 진입 / 검증 실패
errorDetail | 원인 |
|---|---|
NO_TAB_ID_SESSION | 세션 식별자(tabId)가 없거나, 클라이언트 세션 저장소에 매핑이 없는 비정상 진입. 북마크 / 직접 링크 열기, 부모 창 없이 격리 브라우저 페이지를 직접 여는 경우 등. |
MISSING_SESSION_DATA | 세션 식별자는 있으나 매칭되는 세션 컨텍스트(사용자/정책/대상 URL 등)가 없음. 세션 만료 후 재진입 또는 서버-클라이언트 상태 불일치. |
MISSING_CURRENT_URL | 격리 브라우저로 이동할 대상 URL이 비어 있음. 진입 경로 파라미터 누락 또는 부모 창으로부터의 URL 전달 실패. |
권장 조치
- [사용자] 관리자 페이지/사용자 페이지 정상 진입 경로에서 다시 접속
- 정상 경로에서 반복 발생 시 소프트캠프 문의
4.4 C. 정책 조회 / 판정
errorDetail | 원인 | 담당 |
|---|---|---|
POLICY_QUERY_FAILED | 정책 서버 조회 API 실패 (네트워크 / 5xx / 파싱 오류). 차단·허용 판정 자체가 불가한 상태라 페이지 접속이 차단됨. | 소프트캠프 |
FAILED_NAVIGATED_PAGE | 정책상 허용 으로 판정됐지만 실제 페이지 이동이 실패. 격리 브라우저 내부 네비게이션 실패 또는 리디렉션 루프 등. | 대상 사이트 측 / 소프트캠프 |
권장 조치
POLICY_QUERY_FAILED가 전체 사용자에게 동시 발생: 서비스 내부 이슈 → 즉시 소프트캠프 문의FAILED_NAVIGATED_PAGE가 특정 사이트에서만 발생: 해당 사이트 리디렉션/인증 구조 확인
4.5 D. 컨테이너 연결 상태 (런타임)
errorDetail | 원인 |
|---|---|
CONTAINER_DISCONNECTED | 사용 중이던 격리 브라우저 컨테이너와의 실시간 연결이 끊김. 서버 측 컨테이너 종료, 네트워크 단절, keep-alive 실패 등. |
SESSION_TERMINATED_BY_ADMIN | 관리자가 중앙 관리 콘솔에서 해당 사용자 세션을 강제 종료. 재연결은 시도하지 않고 화면이 비활성화됨. |
권장 조치
SESSION_TERMINATED_BY_ADMIN: 정상 기대 동작 — 관리자 조치의 결과CONTAINER_DISCONNECTED: 사용자 재접속 후에도 반복 발생 시 소프트캠프 문의
4.6 E. 헬스체크 실패
격리 브라우저 인스턴스의 상태 확인 단계에서의 실패입니다. 일반 경로에서는 WARN 수준으로 기록되고 통과하지만, 특정 진입 조건에서는 ERROR 페이지로 승격됩니다.
errorDetail | 원인 |
|---|---|
HEALTH_CHECK_NETWORK_ERROR | 격리 브라우저 인스턴스까지 TCP / TLS 레벨 도달 실패. 방화벽 / 웹필터 / 네트워크 DLP 차단, DNS 실패, 클라이언트 오프라인, 인증서 문제 가능성. |
HEALTH_CHECK_TIMEOUT | 인스턴스는 살아 있을 수 있으나 헬스체크 응답 2초 미도달. 인스턴스 기동 지연, 노드 과부하, 네트워크 RTT 급증. |
권장 조치
- [고객사 관리자] 사내 방화벽 / 웹필터 / DNS 설정에서 SHIELD Gate 도메인이 차단되고 있지 않은지 확인
- [사용자] VPN / 보안 에이전트 재기동 후 재시도
- 동일 시간대 다수 사용자에게 재현되면 인프라성 이슈 → 소프트캠프 문의
4.7 F. 브라우저 환경
errorDetail | 원인 |
|---|---|
BROWSER_VERSION_UPDATE_REQUIRED | 사용자가 사용 중인 크롬 버전이 지원 최소 버전 미달. 격리 브라우저 기능에 필요한 WebView API가 없어 업데이트 요구 화면으로 전환. |
권장 조치
- 사용자에게 크롬 업데이트 안내 (자동 업데이트 차단 정책 환경은 관리자가 업데이트 허용 필요)
4.8 G. 크롬 네트워크 계층 에러
격리 브라우저 → 외부 대상 웹서버 구간에서 Chromium이 반환한 에러 코드를 그대로 기록한 항목입니다.
이 구간의 오류는 사용자 PC ↔ SHIELD Gate 가 아니라 격리 브라우저 클러스터 ↔ 대상 사이트 구간에서 발생합니다. 점검은 격리 브라우저 측 egress 네트워크와 대상 사이트 측 ingress 정책을 우선합니다.
4.8.1 에러 코드 매핑
| Chrome code | errorDetail | 주요 원인 |
|---|---|---|
-7 | ERR_TIMED_OUT | 전체 요청 타임아웃. 느린 서버 / 경로. |
-21 | ERR_NETWORK_CHANGED | 네트워크 전환 (Wi-Fi↔LAN, VPN 재접속). |
-100 | ERR_CONNECTION_CLOSED | 서버가 데이터 송수신 중 연결 종료. |
-101 | ERR_CONNECTION_RESET | 서버 / 중간 장비의 RST 전송. L4 장비·프록시에서 강제 끊음. |
-102 | ERR_CONNECTION_REFUSED | 대상 포트가 listen 하지 않음. 서비스 다운 또는 포트 오타. |
-103 | ERR_CONNECTION_ABORTED | 비정상 연결 종료 (클라이언트 관점). |
-104 | ERR_CONNECTION_FAILED | 일반 연결 실패. 상세 분류 불가한 L4 이슈. |
-105 | ERR_NAME_NOT_RESOLVED | DNS 조회 실패. 도메인 부재 또는 DNS 서버 문제. |
-106 | ERR_INTERNET_DISCONNECTED | 클라이언트 인터넷 연결이 없음. |
-107 | ERR_SSL_PROTOCOL_ERROR | TLS 핸드셰이크 실패. |
-108 | ERR_ADDRESS_INVALID | 잘못된 IP/호스트 표기. |
-109 | ERR_ADDRESS_UNREACHABLE | 라우팅상 목적지 도달 불가. |
-110 | ERR_SSL_CLIENT_AUTH_CERT_NEEDED | 서버가 클라이언트 인증서 요구 (mTLS). |
-111 | ERR_TUNNEL_CONNECTION_FAILED | HTTP CONNECT 프록시 터널링 실패. |
-112 | ERR_NO_SSL_VERSIONS_ENABLED | 사용 가능한 TLS 버전 없음. |
-113 | ERR_SSL_VERSION_OR_CIPHER_MISMATCH | TLS 버전 / 암호 스위트 협상 실패. |
-118 | ERR_CONNECTION_TIMED_OUT | TCP 연결 수립 타임아웃. 방화벽 drop, 라우팅 실패 의심. |
-130 | ERR_PROXY_CONNECTION_FAILED | 설정된 프록시 연결 실패. |
-200 | SSL_CERTIFICATE_ERROR | 서버 인증서 유효성 오류 (포괄). |
-202 | ERR_CERT_AUTHORITY_INVALID | 발급 CA 신뢰 불가. 사설 CA 미설치 등. |
-324 | ERR_EMPTY_RESPONSE | 서버가 아무 응답도 주지 않고 연결 종료. |
4.8.2 고객사 관리자 점검 체크리스트
아래 에러는 격리 브라우저 클러스터 → 대상 웹서버 사이의 격리 환경 egress 구간 에서 발생합니다. 사용자 PC → SHIELD Gate 구간이 아닌, 격리 브라우저 클러스터 측 네트워크 / 정책을 우선 점검해 주세요.
① DNS 해석 실패 (ERR_NAME_NOT_RESOLVED)
- 격리 브라우저 클러스터에 설정된 DNS 서버(사내 / 외부)의 응답 정상 여부 확인
- 대상 도메인이 사내 DNS에만 존재하는 경우, 격리 브라우저 클러스터에서도 동일 DNS를 바라보고 있는지 확인
- 고객사 환경의 도메인 차단 정책(DNS 싱크홀, 카테고리 차단)에 걸려 있지 않은지 확인
- 특정 도메인만 실패하는지, 전체 도메인이 실패하는지 격리 브라우저 내 다른 사이트로 비교 테스트
② 네트워크 타임아웃 / 도달 실패 (ERR_TIMED_OUT, ERR_CONNECTION_TIMED_OUT, ERR_CONNECTION_FAILED, ERR_ADDRESS_UNREACHABLE)
격리 브라우저 측 (Outbound)
- 격리 브라우저 클러스터가 위치한 네트워크에서 대상 서버 IP/포트로 outbound 방화벽 허용 여부 확인
- 클러스터 egress 구간의 NAT GW / 프록시 / SD-WAN 라우팅 정상 여부 확인
- 격리 브라우저 노드의 CPU / 메모리 / 네트워크 RTT 지표 확인 (과부하로 인한 처리 지연 가능성)
대상 사이트 측 (Inbound)
- 대상 사이트의 inbound 방화벽 / 보안그룹 에서 격리 브라우저 클러스터 egress IP가 차단되어 있지 않은지 확인
- 대상 사이트가 IP 화이트리스트 정책을 운영 중이면 격리 브라우저 클러스터 egress IP가 등록되어 있는지 확인
- GeoIP / 국가 차단 정책에 격리 브라우저 클러스터 리전이 걸려 있지 않은지 확인 ( 해외 리전 사용 시 빈번)
- 클라우드 WAF(Cloudflare / Akamai 등) IP 평판 / 봇 차단 정책에 egress IP가 잡혀 있지 않은지 확인 (다수 사용자 트래픽이 단일 IP로 모여 평판 하락 가능)
- 대상 서버의 동시 연결 수 / Rate-Limit 임계치에 도달했는지 확인
비교 테스트
- 사용자 PC에서 동일 사이트가 직접 접속 되는지 비교 → 직접 접속도 실패면 대상 서버 / 인터넷 회선 이슈
- 다른 격리 브라우저 노드(다른 egress IP) 에서 동일 사이트 접속 비교 → 특정 IP 차단 여부 식별
③ 연결 거부 / 강제 종료 (ERR_CONNECTION_CLOSED, ERR_CONNECTION_RESET, ERR_CONNECTION_REFUSED, ERR_CONNECTION_ABORTED)
- 대상 웹서버 / 서비스 자체가 정상 기동 중인지 확인 (
ERR_CONNECTION_REFUSED는 보통 서비스 다운) - 경로상 L4 / WAF / IPS 장비가 격리 브라우저 egress 트래픽을 자동 차단 (RST 송출) 하고 있지 않은지 확인
- 대상 사이트에서 짧은 시간 다량 요청에 의한 Rate-Limit 차단 여부 확인 (다수 사용자 → 단일 출발지로 보임)
- 클라이언트 User-Agent / TLS fingerprint 기반 차단(봇 탐지) 정책 여부 확인
④ 인터넷 연결 / 네트워크 전환 (ERR_INTERNET_DISCONNECTED, ERR_NETWORK_CHANGED)
- 격리 브라우저 클러스터의 인터넷 회선 / NAT GW / egress IP 정상 여부 확인
- 동일 시간대 다른 사용자에게도 동일 에러가 발생했는지 확인 (전체 영향이면 인프라 이슈)
-
ERR_NETWORK_CHANGED는 클라이언트 PC 측 네트워크 전환에서도 발생 가능 → 사용자 회선(VPN 재접속, Wi-Fi ↔ LAN 스위칭) 동시 확인
⑤ TLS / SSL 협상 실패 (ERR_SSL_PROTOCOL_ERROR, ERR_NO_SSL_VERSIONS_ENABLED, ERR_SSL_VERSION_OR_CIPHER_MISMATCH)
- 대상 사이트가 요구하는 TLS 최소 버전 (예: TLS 1.2 / 1.3)이 격리 브라우저 정책과 호환되는지 확인
- 구버전 사이트(TLS 1.0 / 1.1만 지원) 접속 시 보안 정책상 허용 여부 검토
- 경로상 SSL 인터셉트(SSL Inspection) 장비가 협상 실패를 유발하지 않는지 확인
⑥ 서버 인증서 오류 (SSL_CERTIFICATE_ERROR, ERR_CERT_AUTHORITY_INVALID)
- 대상 사이트 인증서의 만료 / 도메인 불일치 / 자가서명 여부 확인
- 사내 사설 CA로 발급된 사이트라면 SHIELD Gate에 사설 CA 인증서 등록 상태 확인
⑦ 클라이언트 인증서 요구 (ERR_SSL_CLIENT_AUTH_CERT_NEEDED)
- 대상 사이트가 mTLS(상호 인증서) 를 요구하는지 확인
- 격리 브라우저 환경의 클라이언트 인증서 주입(노드 마운트 / 정책 배포) 구성 여부 검토
- mTLS 사이트의 경우 격리 브라우저 사용 자체가 정책상 부적합할 수 있음 → 예외 처리(직접 접속 허용) 검토
⑧ 프록시 / 터널링 실패 (ERR_TUNNEL_CONNECTION_FAILED, ERR_PROXY_CONNECTION_FAILED)
- 격리 브라우저 클러스터에 설정된 outbound 프록시 (PAC / Explicit Proxy) 정상 동작 여부 확인
- 프록시 인증 정보(계정 / 토큰) 만료 여부 확인
- 대상 사이트가 HTTPS CONNECT 터널링을 차단하고 있지 않은지 확인
⑨ 잘못된 주소 표기 (ERR_ADDRESS_INVALID)
- 사용자가 입력한 URL 형식 오류 여부 (포트 번호, 특수문자)
- 격리 브라우저 진입 경로 파라미터 인코딩 / 디코딩 과정의 손상 여부
⑩ 빈 응답 (ERR_EMPTY_RESPONSE)
- 대상 서버가 요청 수신 직후 응답 없이 연결을 끊는 상태 → 네트워크 또는 대상 사이트 이슈 확인 필요
공통 점검
- 동일 에러가 특정 사이트에만 발생 → 사이트(또는 사이트 정책) 이슈로 좁혀짐
- 동일 에러가 여러 사이트에 동시 다발 → 격리 브라우저 인프라 / egress 회선 이슈
- 동일 에러가 특정 사용자에게만 발생 → 해당 사용자의 정책 / 그룹 / 라우팅 정책 확인
- 발생 시각의 격리 브라우저 노드 상태(헬스체크, 컨테이너 재시작 이벤트) 함께 확인
4.9 H. 기본값 (Fallback)
errorDetail | 원인 |
|---|---|
UNKNOWN_SYSTEM_ERROR | 위 A~G 어느 분류에도 해당되지 않은 예외의 기본값. 원인 식별이 안 된 모든 케이스. |
실질적으로 이 값으로 귀결되는 추가 케이스:
- 헬스체크가 HTTP / 분류 불가 에러를 반환한 경우
- Chromium 에러 코드 매핑에 없는 코드가 넘어온 경우
- 세션 오류 처리 로직의 기본 분기
권장 조치
- 해당 코드가 빈번하게 집계된다면 분류 확장이 필요한 신호이므로 발생 시각·사용자·대상 URL을 수집해 소프트캠프에 전달
5. 부록
5.1 ERROR 레벨이 발생하지 않는 이벤트
다음 이벤트들은 설계상 INFO 레벨로만 기록되며 ERROR 로는 남지 않습니다.
NAVIGATE_TO_ADMIN_PAGE 관리자 페이지로 이동
POST_INQUIRY_WORK_ITEM_ACCESS_URL 브라우저 접속
RBI_URL_CHANGED 브라우저 접속 후 이동
RBI_CHECK_INPUT_TEXT 사용자 입력 민감정보 검사
RBI_CLIPBOARD_ACCESS_RB2PC 격리 브라우저 → 로컬 PC 복사
RBI_CLIPBOARD_ACCESS_PC2RB 로컬 PC → 격리 브라우저 붙여넣기
RBI_SESSION_TIMEOUT 격리 브라우저 세션 타임아웃
RBI_KEYBOARD_INPUT 키보드 입력 차단
RBI_FILE_VIEWER_REQUEST SHIELD Viewer 요청
5.2 소프트캠프 문의 시 전달 정보
문제 해결 소요 시간을 단축하기 위해 소프트캠프 문의 시 아래 항목을 함께 전달해 주세요.
| # | 항목 | 비고 |
|---|---|---|
| 1 | 발생 시각 (YYYY-MM-DD HH:MM:SS, 타임존 포함) | 정확한 시각 범위 필수 |
| 2 | 회사 식별자 / 테넌트명 | — |
| 3 | 영향받은 사용자 ID (또는 이메일) | 단일 사용자 / 다수 여부도 함께 |
| 4 | 이벤트 코드 | 예: RBI_USAGE_ERROR |
| 5 | errorDetail 값 | RBI_USAGE_ERROR인 경 우 필수 |
| 6 | 대상 URL (해당 시) | 격리 브라우저로 접속하던 사이트 주소 |
| 7 | 재현 여부 / 재현 단계 | 재현되면 단계별 기록 |
| 8 | 사용자 브라우저 / OS 버전 | 브라우저 환경 이슈(F 그룹) 구분용 |
| 9 | 동일 시간대 다른 사용자에게도 발생 여부 | 인프라성 이슈 판단 자료 |
| 10 | 직전 관리자 설정 변경 여부 | 정책 / 스토리지 / 방화벽 변경 이력 |