Malware Scan Request

Used for SHIELDEX malware scan requests.

It operates asynchronously and responds immediately to requests. The inspection results can be checked through a separate status inquiry API.

Notes

• Malware Engine: Perform real-time checks using the TurboVaccine vaccine engine.
• Tenant SupportSupports a multi-tenant environment, with data stored separately for each tenant.
• Backup: When the inspection request is successfully accepted, a backup of the original file encrypted will be automatically created.
• Status Check: Test results areGET /inspection/malware/{jobId}You can query through the API.
• Egnine Process: Parallel processing is possible up to the number of CPU cores on the server.
• Queue Size: The request queue is the number of cores * 12. If exceeded, it returns an exception response.

---

Method

POST

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

---

Request Path Parameter

KEY	OBJECT	DESC
jobId	String	Task ID (optional, a time-based UUID will be automatically generated if not entered. Maximum 36 characters)

---

Request Parts (multipart/form-data)

KEY	OBJECT	DESC
data	JSON	Malware Scan Request Data (Required)
file	File	File to be inspected (required)

---

Request Data JSON Structure

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

---

Request Data Fields

KEY	OBJECT	REQUIRED	DESC
userInfo.userId	String	Yes	User ID (1-40 characters)
userInfo.name	String	No	Username (up to 40 characters)
userInfo.department	String	No	User Department (up to 256 characters)
userInfo.dutyname	String	No	User Job Title (up to 40 characters)
userInfo.sysCode	String	Yes	Channel code, used for API access control. (up to 40 characters)
userInfo.businessCode	String	Yes	Used for business code and API access control. (Maximum 40 characters)
fileInfo.fileName	String	Yes	File Name

---

Response Body (json)

KEY	OBJECT	DESC
code	int	Response Codes (see table below)
msg	String	Result Message
jobId	String	Work ID (used when checking inspection results)
logReason	int	Result code values for exceptions or errors

---

Response Code

CODE	DESC	DESC_DETAIL
0	Inspection request successful	The inspection request has been received normally. Please check the inspection results through the status inquiry API.
1	Inspection Request Exception	The check was not executed due to duplicate job ID, file size exceeding limits, etc.
2	Inspection Request Error	The request has failed due to file save failure, service error, etc.
5	Access Denied	The request has been blocked due to API access control.

---

Log Reason List

This is the result returned in case of exceptions or errors.

exception

code: 1

CODE	TITLE	MESSAGE
990008	[Exception] Vaccine scan file size exceeded	The file size exceeds the virus scan limit, so the scan was not performed.
990010	[Exception] Duplicate Task ID Check Request	A request for inspection was not performed with the existing work ID. Please use a different work ID.
990011	[Exception] Vaccine Check Not Used	The vaccine inspection feature is disabled.
990015	[Exception] Vaccine Check Queue Overflow	The server's processing queue is full and cannot accept requests. Please try again later.

Error

code: 2

CODE	TITLE	MESSAGE
990014	[Error] Vaccine Inspection Request Error	An error occurred before the request to the vaccine service, so it could not be checked.

---

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 - Inspection request successful (200 OK)

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

RESPONSE - [Exception] Duplicate Work ID Check Request (200 OK)

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

RESPONSE - [Exception] Vaccine inspection file size exceeded (200 OK)

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

RESPONSE - [Exception] Vaccine Check Not Used (200 OK)

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

RESPONSE - [Exception] Vaccine Check Queue Overflow (200 OK)

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

RESPONSE - [Error] Vaccine inspection request error (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

• This flow is provided to the customer for reference only.
• cdrbroker.propertiesUse the following values in the configuration file (for development records)

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)