본문으로 건너뛰기

멀웨어 검사 요청

SHIELDEX 멀웨어 검사 요청을 위해 사용합니다.

비동기로 동작하며, 요청 즉시 응답합니다. 검사 결과는 별도의 상태 조회 API를 통해 확인할 수 있습니다.

Notes​

  • Malware Engine: TurboVaccine 백신 엔진을 사용하여 실시간 검사를 수행합니다.
  • Tenant Support: 멀티 테넌트 환경을 지원하며, 테넌트별로 데이터가 분리 저장됩니다.
  • Backup: 검사 요청이 성공적으로 수락되면 원본 파일을 암호화한 백업이 자동으로 생성됩니다.
  • Status Check: 검사 결과는 GET /inspection/malware/{jobId} API를 통해 조회할 수 있습니다.
  • Egnine Process: 서버의 CPU 코어 수만큼 병렬처리가 가능합니다.
  • Queue Size: 요청 대기열은 코어수 * 12 입니다. 초과시 예외 응답을 반환합니다.

Method​

POST​

/inspection/malware
/inspection/malware/{jobId}

Request Path Parameter​

KEYOBJECTDESC
jobIdString작업 ID (선택사항, 미입력 시에 시간 기반 UUID가 자동 생성됩니다. 최대 36자)

Request Parts (multipart/form-data)​

KEYOBJECTDESC
dataJSON멀웨어 검사 요청 데이터 (필수)
fileFile검사 대상 파일 (필수)

Request Data JSON Structure​

{
  "userInfo": {
    "userId": "string",
    "name": "string",
    "department": "string",
    "dutyname": "string",
    "sysCode": "string",
    "businessCode": "string"
  },
  "fileInfo": {
    "fileName": "string"
  }
}

Request Data Fields​

KEYOBJECTREQUIREDDESC
userInfo.userIdStringYes사용자 ID (1-40자)
userInfo.nameStringNo사용자 이름 (최대 40자)
userInfo.departmentStringNo사용자 부서 (최대 256자)
userInfo.dutynameStringNo사용자 직책명 (최대 40자)
userInfo.sysCodeStringYes채널 코드, API 접근제어에 사용됩니다. (최대 40자)
userInfo.businessCodeStringYes업무 코드, API 접근제어에 사용됩니다. (최대 40자)
fileInfo.fileNameStringYes파일명

Response Body (json)​

KEYOBJECTDESC
codeint응답 코드 (아래 테이블 참조)
msgString결과 메시지
jobIdString작업 ID (검사 결과 조회 시 사용)
logReasonint예외나 오류 시 결과 코드값

Response Code​

CODEDESCDESC_DETAIL
0검사 요청 성공검사 요청이 정상적 접수되었습니다. 검사 결과는 상태조회 API로 확인하세요.
1검사 요청 예외중복 작업 ID, 파일 크기 초과 등으로 검사가 실행되지 않았습니다.
2검사 요청 오류파일 저장 실패, 서비스 오류 등으로 요청이 실패했습니다.
5접근 차단API 접근제어에 의해 요청이 차단되었습니다.

Log Reason List​

예외, 오류 시 반환하는 결과입니다.

예외​

code: 1​

CODETITLEMESSAGE
990008[예외] 백신 검사 파일 크기 초과파일 크기가 백신 검사 제한 크기를 초과하여 검사가 수행되지 않았습니다.
990010[예외] 중복 작업 ID 검사 요청기존에 사용된 작업 ID로, 검사 요청을 수행하지 않았습니다. 다른 작업 ID를 사용해 주세요
990011[예외] 백신 검사 미사용백신 검사 기능이 비활성화되어 있습니다.
990015[예외] 백신 검사 대기열 초과서버의 처리 대기열이 가득차 요청을 수락하지 못했습니다. 잠시 후 다시 시도해 주세요

오류​

code: 2​

CODETITLEMESSAGE
990014[오류] 백신 검사 요청 오류백신 서비스로 요청 전 오류가 발생하여 검사하지 못했습니다.

Sample​

REQUEST​

curl -X POST "/inspection/malware" \
  -H "Content-Type: multipart/form-data" \
  -F 'data={
    "userInfo": {
      "userId": "user001",
      "name": "홍길동",
      "department": "보안팀",
      "dutyname": "보안관리자",
      "sysCode": "SYS001",
      "businessCode": "BIZ001"
    },
    "fileInfo": {
      "fileName": "suspicious_file.exe"
    }
  };type=application/json' \
  -F "file=@/path/to/suspicious_file.exe"

RESPONSE - 검사 요청 성공 (200 OK)​

{
   "code": 0,
   "msg": "success",
   "jobId": "8bc422e1-af1b-11f0-bf7b-7117406ac6f5"
}

RESPONSE - [예외] 중복 작업 ID 검사 요청 (200 OK)​

{
   "code": 1,
   "msg": "기존에 사용된 작업 ID로, 검사 요청을 수행하지 않았습니다. 다른 작업 ID를 사용해 주세요",
   "jobId": "8bc422e1-af1b-11f0-bf7b-7117406ac6f5",
   "logReason": 990010
}

RESPONSE - [예외] 백신 검사 파일 크기 초과 (200 OK)​

{
   "code": 1,
   "msg": "파일 크기가 백신 검사 제한 크기를 초과하여 검사가 수행되지 않았습니다.",
   "jobId": "7a3c5d9e-af1c-11f0-bf7b-7117406ac6f5",
   "logReason": 990008
}

RESPONSE - [예외] 백신 검사 미사용 (200 OK)​

{
   "code": 1,
   "msg": "백신 검사 기능이 비활성화되어 있습니다.",
   "jobId": "9f2e8b4a-af1c-11f0-bf7b-7117406ac6f5",
   "logReason": 990011
}

RESPONSE - [예외] 백신 검사 대기열 초과 (200 OK)​

{
   "code": 1,
   "msg": "서버의 처리 대기열이 가득차 요청을 수락하지 못했습니다. 잠시 후 다시 시도해 주세요",
   "jobId": "c4d7f3e2-af1c-11f0-bf7b-7117406ac6f5",
   "logReason": 990015
}

RESPONSE - [오류] 백신 검사 요청 오류 (200 OK)​

{
   "code": 2,
   "msg": "백신 서비스로 요청 전 오류가 발생하여 검사하지 못했습니다.",
   "jobId": "395ebb96-af1c-11f0-bf7b-7117406ac6f5",
   "logReason": 990014
}

RESPONSE - Access Denied (200 OK)​

{
   "code": 5,
   "msg": "Sanitization Request Blocked by API Access control.",
   "jobId": "52617927-af1c-11f0-bf7b-7117406ac6f5"
}

Exception Messages (400 Bad Request)​

{
    "code": 1,
    "msg": "필수 요청 파라미터가 누락되었습니다.",
    "details": {
        "missingPart": "file",
        "description": "'file' 파라미터를 포함하여 요청해 주세요."
    }
}

{
    "code": 1,
    "msg": "잘못된 JSON 형식입니다.",
    "details": {
        "missingPart": "line 10, column 2",
        "description": "line 10, column 2에서 JSON 문법 오류가 발생했습니다. 콤마, 중괄호, 대괄호 등을 확인해주세요."
    }
}
{
    "code": 1,
    "msg": "요청 값이 올바르지 않습니다.",
    "details": {
        "missingPart_1": "userInfo.businessCode",
        "description_1": "공백일 수 없습니다",
        "missingPart_2": "userInfo.sysCode",
        "description_2": "공백일 수 없습니다",
        "missingPart_3": "userInfo.userId",
        "description_3": "공백일 수 없습니다"
    }
}

Processing Flow​

  • 해당 플로우는 참고용으로 고객에게 제공 X
  • cdrbroker.properties 설정 파일의 다음 값들 사용 (개발 기록용)
shieldex.vaccine.scan.useVaccine=true  // 기본값: false | 백신 사용 여부, cdrApiService의 백신도 해당 설정 사용
shieldex.vaccine.scan.time-out=60      // 기본값: 60 | 백신 검사의 타임아웃, 
shieldex.vaccine.scan.maxSizeMB=30     // 기본값: 30 | 백신 검사 최대 크기, cdrApiService의 백신도 해당 설정 사용
shieldex.vaccine.scan.queue-size-mulitpiter=12 // 기본값: 12 | 백신 검사 대기열 크기 배율, CPU * 설정값(4 * 12 = 48)