SHIELDEX File 6.0 — 무해화 결과 응답 명세서 (6.2026.0731.04)
# SHIELDEX File 6.0 — 무해화 결과 응답 명세서 (6.2026.0731.01)
SHIELDEX File 6.0 무해화 API 연동 시 결과 응답 필드를 정의합니다. 최종 결과 분기는
code로 판단하고, 상세 사유는logReason/msg(또는 무해화 로그리즌 표)를 참고합니다.
- 문서 버전: 6.2026.0731.04 (
detailCode·server필드 추가 기준)
- 출처:
SHIELDEX_API(cdrbroker) 6.2026.0731.04 ·SHIELDEX_SERVICE_API(cdrApiService) 6.2026.0731.05 — TASK#65613 (detailCode/server) · 문서 업데이트 2026-07-31 - 관련 문서: 무해화 로그리즌 표
- 본문 구성: 동기 결과 → 비동기(접수·상태조회·콜백) → 공통 필드(
code/detailCode/server)
안내 기존 결과 응답(
jobID·code·msg·logReason)에 더해 두 필드가 추가되었습니다.
detailCode:code만으로 세부 분기가 어려운 연동을 위한 부가 분류값 (정수)server: 파일을 처리한 무해화 서버 정보 (serverId / serverName / ipList / macList)
1. 결과 수신 방식 개요
| 구분 | 방식 | 엔드포인트 | 결과 수신 시점 |
|---|---|---|---|
| 동기 | Sync | POST /v5/cdr-sync | 요청 응답으로 최종 결과를 즉시 수신 |
| 비동기 | 접수 | POST /v5/cdr | 즉시 접수 응답만 반환 (결과 아님) |
| 비동기 | 상태 조회(폴링) | GET /v5/cdr/{jobID} | 주기 조회(권장 200ms) 후 완료 시 결과 응답 |
| 비동기 | 콜백(Callback) | 요청 시 result.callbackURL 지정 | 완료 시 지정 URL 로 결과 PUSH |
접수 응답 ≠ 결과 응답 비동기
POST /v5/cdr의 즉시 응답은 접수 확인(code·msg·jobID)일 뿐입니다. 실제 무해화 결과는 동기(/v5/cdr-sync) 또는 상태 조회·콜백으로 받습니다.
2. 동기 — 결과 응답 (POST /v5/cdr-sync)
동기 API는 서버가 무해화 완료까지 대기한 뒤 최종 결과를 한 번에 반환합니다. code: 3(진행 중)은 반환되지 않으며, 실제 수신 코드는 0 / 1 / 2 입니다.
2.1 응답 필드
| KEY | TYPE | 필수 | 설명 |
|---|---|---|---|
jobID | String | 필수 | 작업 ID |
code | int | 필수 | 결과 등급 코드 (§5) — 동기에서는 0 / 1 / 2 만 수신 |
msg | String | 필수 | 결과 사유 메시지 (= logReason 의 사유 텍스트) |
logReason | int | 필수 | 상세 결과(로그리즌) 코드 — 무해화 로그리즌 표 참조 |
detailCode | int | 선택 | 부가 분류값 (§6). 연동 협의로 활성화된 경우에만 포함 |
server | Object | 필수 | 파일을 처리한 서버 정보 (§7) |
2.2 detailCode 별 예시
아래 예시는 동기(/v5/cdr-sync) · 상태 조회 결과 응답에 공통으로 적용됩니다. server 객체는 모든 예시에서 동일 형태입니다.
detailCode: 0 — 위험 요소 없음 (안전)
{
"jobID": "ed43f9a5-8caa-11f1-a4cd-f5c4fa6d387e",
"code": 0,
"msg": "[안전] 컨텐츠 요소 없음",
"logReason": 200004,
"detailCode": 0,
"server": {
"serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
"serverName": "SANITIZE-NODE-01",
"ipList": ["10.10.12.226"],
"macList": ["00:50:56:aa:41:ec"]
}
}
detailCode: 1 — 위험 요소 있음 (의심 · 경고 · 위험 · 위변조)
{
"jobID": "ed43f9a5-8caa-11f1-a4cd-f5c4fa6d387e",
"code": 0,
"msg": "[의심] 컨텐츠 요소 감지",
"logReason": 200005,
"detailCode": 1,
"server": {
"serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
"serverName": "SANITIZE-NODE-01",
"ipList": ["10.10.12.226"],
"macList": ["00:50:56:aa:41:ec"]
}
}
{
"jobID": "ed43f9a5-8caa-11f1-a4cd-f5c4fa6d387e",
"code": 2,
"msg": "[차단] 확장자 위변조 파일 차단",
"logReason": 220355,
"detailCode": 1,
"server": {
"serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
"serverName": "SANITIZE-NODE-01",
"ipList": ["10.10.12.226"],
"macList": ["00:50:56:aa:41:ec"]
}
}
detailCode: 2 — 백신(바이러스) 검출
{
"jobID": "ed43f9a5-8caa-11f1-a4cd-f5c4fa6d387e",
"code": 2,
"msg": "[심각] 바이러스 검출 (감염 파일 삭제)",
"logReason": 990003,
"detailCode": 2,
"server": {
"serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
"serverName": "SANITIZE-NODE-01",
"ipList": ["10.10.12.226"],
"macList": ["00:50:56:aa:41:ec"]
}
}
detailCode: 3 — 미지원 파일 (예외 · 차단)
{
"jobID": "ed43f9a5-8caa-11f1-a4cd-f5c4fa6d387e",
"code": 2,
"msg": "[차단] 미지원 확장자",
"logReason": 210211,
"detailCode": 3,
"server": {
"serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
"serverName": "SANITIZE-NODE-01",
"ipList": ["10.10.12.226"],
"macList": ["00:50:56:aa:41:ec"]
}
}
detailCode: -1 — 오류
{
"jobID": "ed43f9a5-8caa-11f1-a4cd-f5c4fa6d387e",
"code": 2,
"msg": "[오류] 인터페이스 통신 오류",
"logReason": 900052,
"detailCode": -1,
"server": {
"serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
"serverName": "SANITIZE-NODE-01",
"ipList": ["10.10.12.226"],
"macList": ["00:50:56:aa:41:ec"]
}
}
핵심:
detailCode: -1은 오류를 의미합니다. 로그리즌 마스터의logtype_id=V20(오류)에 해당하는 다수의 로그리즌을 개별 값으로 나누지 않고, 공통으로-1로 통합 처리합니다. 어떤 오류인지의 상세 사유는logReason/msg로 확인합니다.
3. 비동기 — 접수 응답 (POST /v5/cdr)
비동기 요청의 즉시 응답입니다. 무해화 결과가 아니므로 detailCode · server 는 포함되지 않습니다.
| KEY | TYPE | 설명 |
|---|---|---|
code | int | 접수 코드 (0 접수 성공 / 1 중복 요청 / 2 차단 / 3 서비스 연결 실패 / 5 접근 제어 차단) |
msg | String | 접수 메시지 |
jobID | String | 작업 ID |
{
"code": 0,
"msg": "success",
"jobID": "ed43f9a5-8caa-11f1-a4cd-f5c4fa6d387e"
}
접수 후 결과는 상태 조회(§4) 또는 콜백(§4.2) 으로 수신합니다.
4. 비동기 — 결과 수신 (상태 조회 · 콜백)
4.1 상태 조회 (GET /v5/cdr/{jobID})
응답 필드·의미는 동기 결과(§2) 와 동일합니다. 처리가 끝나지 않은 경우 code: 3(진행 중)이 반환될 수 있습니다.
| KEY | TYPE | 필수 | 설명 |
|---|---|---|---|
jobID | String | 필수 | 작업 ID |
code | int | 필수 | 결과 등급 코드 (§5) — 0 / 1 / 2 / 3(진행 중) |
msg | String | 필수 | 결과 사유 메시지 |
logReason | int | 필수 | 상세 결과(로그리즌) 코드 |
detailCode | int | 선택 | 부가 분류값 (§6, 활성 시에만) |
server | Object | 필수 | 처리 서버 정보 (§7) — 결과 응답에 포함 |
detailCode 별 JSON 예시는 §2.2 를 참고하세요.
4.2 콜백(Callback) 결과 전문
요청 시 result.callbackURL 을 지정하면 무해화 완료 시 해당 URL 로 결과가 PUSH 됩니다. 동기·상태 조회 응답과 필드 표기만 일부 다릅니다(값의 의미는 동일).
- 결과 사유 텍스트를 별도 필드
logReasonMsg로 제공합니다. msg는"success"고정입니다(사유 텍스트는logReasonMsg에 담김).
| KEY | TYPE | 설명 |
|---|---|---|
jobID | String | 작업 ID |
code | int | 결과 등급 코드 (§5) |
detailCode | int | 부가 분류값 (§6, 활성 시에만) |
logReason | int | 상세 결과(로그리즌) 코드 |
logReasonMsg | String | 상세 결과 사유 텍스트 |
msg | String | "success" 고정 |
server | Object | 처리 서버 정보 (§7) |
{
"jobID": "ed43f9a5-8caa-11f1-a4cd-f5c4fa6d387e",
"code": 0,
"detailCode": 0,
"logReason": 200004,
"logReasonMsg": "[안전] 컨텐츠 요소 없음",
"msg": "success",
"server": {
"serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
"serverName": "SANITIZE-NODE-01",
"ipList": ["10.10.12.226"],
"macList": ["00:50:56:aa:41:ec"]
}
}
detailCode 0~3 · -1 의미와 매핑은 §2.2 · §6 과 동일합니다.
5. 결과 code 정의
| code | 의미 | 다운로드 | 성격 |
|---|---|---|---|
0 | 무해화 성공(완료) | 가능 | 최종 |
1 | 정책에 의한 원본 파일 반입 | 가능 | 최종 |
2 | 반입 차단 / 시스템·엔진 오류 | 불가 | 최종 |
3 | 처리 진행 중 | — | 미완료(폴링 전용) |
- 동기(
/v5/cdr-sync) 는 완료까지 대기 후 반환하므로 실제 수신 코드는0/1/2입니다.3(진행 중)은 반환되지 않습니다. code1개에 다수의logReason이 매핑됩니다(1:N). 연동 분기는 반드시code값을 기준으로 하고,logReason(msg)은 상세 사유 식별·사용자 안내·로그 기록 용도로 사용하세요.- 상태 조회 API 에서는 결과가 아닌 조회 제어 응답으로 작업 ID 없음(
-3), 유효하지 않은 요청(5)이 반환될 수 있습니다.
6. detailCode — 부가 분류값
code(0/1/2)만으로 세부 분기가 어려운 연동을 위한 정수 부가 분류값입니다.
활성화된 연동에서만 응답에 포함됩니다. 미활성 시 필드 자체가 응답에 나타나지 않으므로 기존 규격과 100% 동일합니다. 활성화 여부는 연동 시 협의합니다.
| detailCode | 의미 | 대표 예시 (logReason) |
|---|---|---|
-1 | 오류 — logtype_id=V20 로그리즌을 공통 -1로 통합 | 900052 등 V20(오류) 계열 다수 |
0 | 위험 요소 없음 (안전) | 200004 [안전] 컨텐츠 요소 없음 |
1 | 위험 요소 있음 (의심 · 경고 · 위험 · 위변조) | 200005~`200007, 220355` 등 |
2 | 백신(바이러스) 검출 | 990003 [심각] 바이러스 검출 |
3 | 미지원 파일 (예외 · 차단) | 210211, 230213, 240215 |
산출 기준(요약) — 결과 로그리즌과 위험도로 판정합니다.
- 명시 매핑:
200004→0,200005~`200007/220355등→1,990003→2,210211/230213/240215(미지원)→3` - '파일 재구성 완료'(
200000/200001)는 위험도에 따라0(안전)/1(의심·경고·위험·위 변조)/2(심각) 로 판정 - 오류(
logtype_id=V20)에 시스템·엔진 오류 해당하는 다수의 로그리즌 → 공통detailCode: -1
전체 JSON 예시는 §2.2 를 참고하세요.
7. server — 처리 서버 정보
무해화를 실제로 처리한 서버를 식별할 수 있도록 결과 응답에 포함됩니다.
| KEY | TYPE | 설명 |
|---|---|---|
serverId | String | 처리 서버 ID |
serverName | String | 서버명 |
ipList | String[] | 서버 대표 IP (1개) |
macList | String[] | 대표 IP 에 대응하는 MAC 주소 (1개) |
"server": {
"serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
"serverName": "SANITIZE-NODE-01",
"ipList": ["10.10.12.226"],
"macList": ["00:50:56:aa:41:ec"]
}
ipList·macList는 서버의 대표 IP/MAC 1쌍만 담습니다(전체 NIC 목록 아님).- 서버 정보를 찾지 못한 경우
serverId만 채우고serverName은 빈 문자열,ipList·macList는 빈 배열([])로 응답합니다.- 비동기 접수 응답(§3) 에는
server가 포함되지 않습니다.
변경 이력
| 날짜 | 문서 버전 | 내용 |
|---|---|---|
| 2026-07-31 | 6.2026.0731.01 | 초안 |