수신 파일을 Microsoft Defender로 검사하고 후속 처리하기

시작하기

기본 개념

외부 시스템이나 사용자로부터 수신한 파일을 내부 서버나 업무 환경으로 전송할 때는 파일을 바로 다음 시스템으로 전송하는 대신, 수신된 파일을 먼저 검사한 뒤 검사 결과에 따라 처리 경로를 결정할 수 있습니다.

예를 들어 외부에서 업로드된 압축 파일, 문서, 실행 파일이나 데이터 파일을 수신한 뒤 Microsoft Defender로 검사하고, 문제가 없는 파일만 내부 업무 서버나 스토리지로 전송하도록 구성할 수 있습니다.

검사 결과에 따라 파일 처리 흐름을 분리하면 모든 파일이 동일한 경로로 이동하는 것이 아니라, 정상 파일은 다음 작업으로 연결하고 추가 확인이 필요한 파일은 별도의 위치로 격리하거나 운영자가 확인할 수 있도록 구성할 수 있습니다.

Incoming Files
      │
      ▼
Receive Flow
      │
      ▼
Microsoft Defender Scan
      │
      ├───────────────┬────────────────┐
      ▼               ▼                ▼
    Clean        Detection/Error    Check Required
      │               │                │
      ▼               ▼                ▼
Next Transfer    Quarantine      Review / Retry

이렇게 구성하면 파일 수신 → 검사 실행 → 검사 결과 확인 → 정상 파일 후속 전송 → 확인 필요 파일 격리 → 처리 결과 확인까지 이어지는 파일 검사 흐름을 구성할 수 있습니다.

검사 대상

모든 파일을 동일한 기준으로 처리하기보다 수신 경로와 파일 유형, 업무 목적에 따라 검사 대상을 구분할 수 있습니다.

예를 들어 외부에서 수신되는 모든 파일을 검사할 수도 있고, 특정 업로드 폴더에 들어오는 파일이나 실행 파일과 압축 파일만 별도로 검사하도록 구성할 수도 있습니다.

Incoming Files
│
├── /incoming/documents/
│      ├── report.pdf
│      └── contract.docx
│
├── /incoming/archive/
│      └── package.zip
│
└── /incoming/software/
       └── installer.exe
                │
                ▼
         Defender Scan

이렇게 검사 대상을 구성하면 내부에서 생성된 파일까지 모두 동일하게 처리하는 대신, 외부에서 들어오는 파일과 추가 확인이 필요한 파일을 중심으로 검사 흐름을 적용할 수 있습니다.

처리 구조

파일 검사는 하나의 독립된 작업으로 실행할 수도 있지만, 실제 파일 전송 흐름 안에 검사 단계를 포함하면 수신 이후의 처리 과정을 하나의 Flow로 연결할 수 있습니다.

┌──────────────┐
│ External     │
│ Source       │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ Receive      │
│ Folder       │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ Defender     │
│ Scan         │
└──────┬───────┘
       │
   ┌───┴────┐
   ▼        ▼
 Clean    Detection
   │        │
   ▼        ▼
 Target   Quarantine

이 구조를 활용하면 파일을 먼저 수신한 뒤 검사 상태를 확인하고, 검사 결과가 정상인 파일만 다음 Target으로 전송하도록 구성할 수 있습니다.

IT 엔지니어

수신 경로

파일 검사를 구성하려면 먼저 외부 또는 다른 시스템에서 수신한 파일이 저장되는 위치를 확인하고 검사 Flow의 Source로 연결합니다.

예를 들어 /data/incoming 경로에 파일이 수신된 뒤 해당 경로에서 검사 작업을 시작하도록 구성할 수 있습니다.

File Sources
│
├── External Upload
│      └── /data/incoming/upload/
│
├── Remote Server
│      └── /data/incoming/transfer/
│
└── Partner System
       └── /data/incoming/system/

수신 환경에서는 다음 항목을 함께 확인할 수 있습니다.

예를 들어 새로운 파일이 /data/incoming/upload 경로에 생성되면 해당 파일을 검사 대상으로 확인하고 다음 검사 작업을 시작하도록 구성할 수 있습니다.

검사 연결

수신 파일과 Microsoft Defender 검사 작업을 연결해 파일이 준비된 뒤 자동으로 검사가 실행되도록 구성합니다.

파일이 수신된 직후 검사를 실행할 수도 있고, 이전 파일 전송 작업이 완료된 뒤 검사 단계를 이어서 실행할 수도 있습니다.

File Received
      │
      ▼
Transfer Completed
      │
      ▼
Scan Task
      │
      ▼
Result Evaluation

검사 작업의 실행 조건은 파일 처리 환경에 따라 구분할 수 있습니다.

이렇게 구성하면 파일이 수신된 이후 별도의 수동 작업으로 검사를 시작하는 대신, 파일 수신 흐름과 검사 작업을 연결할 수 있습니다.

결과 분기

검사가 완료된 뒤에는 결과에 따라 다음 파일 처리 경로를 다르게 구성할 수 있습니다.

정상적으로 검사된 파일은 내부 업무 서버나 스토리지로 전송하고, 검출되었거나 추가 확인이 필요한 파일은 별도의 격리 위치로 이동하도록 구성할 수 있습니다.

Defender Scan
      │
      ▼
Scan Result
      │
 ┌────┼───────────────┐
 ▼    ▼               ▼
Clean Detection     Error
 │        │            │
 ▼        ▼            ▼
Transfer Quarantine Review
 │        │
 ▼        ▼
Target   Isolated Storage

검사 결과별 처리 방식은 다음과 같이 구성할 수 있습니다.

예를 들어 정상 파일은 /data/approved 경로로 전송하고, 검출된 파일은 /data/quarantine 경로로 분리해 관리할 수 있습니다.

격리 관리

검출되었거나 즉시 다음 시스템으로 전송하기 어려운 파일은 일반 수신 파일과 분리된 위치에서 관리할 수 있습니다.

Incoming Files
      │
      ▼
Defender Scan
      │
      ▼
Detection
      │
      ▼
┌───────────────────┐
│ Quarantine Target │
│ /data/quarantine  │
└─────────┬─────────┘
          │
          ▼
    Review / Action

격리 영역에서는 다음과 같은 기준으로 파일을 구분할 수 있습니다.

이렇게 구성하면 추가 확인이 필요한 파일과 정상 파일이 동일한 내부 업무 경로에 반영되는 것을 방지하고, 확인이 필요한 파일만 별도로 관리할 수 있습니다.

후속 전송

검사 결과가 정상인 파일은 다음 Flow나 내부 시스템으로 자동 전송하도록 연결할 수 있습니다.

예를 들어 외부에서 수신한 파일을 검사한 뒤 정상 파일만 파일 서버에 저장하거나, 데이터 처리 서버 또는 프로젝트별 작업 공간으로 전송할 수 있습니다.

Clean File
     │
     ▼
Next Transfer
     │
 ┌───┼─────────────┐
 ▼   ▼             ▼
Server Storage Processing
 │      │             │
 └──────┴──────┬──────┘
               ▼
          Next Workflow

이를 통해 파일 검사와 실제 업무용 파일 전송을 별도의 작업으로 운영하는 대신, 검사 결과를 기준으로 다음 작업을 자동으로 연결할 수 있습니다.

실행 결과

검사와 후속 전송 작업이 실행되면 Runs에서 전체 처리 상태와 파일별 결과를 확인할 수 있습니다.

하나의 Run 안에서 파일 수신부터 검사, 결과 분기와 다음 Target 반영까지의 흐름을 확인할 수 있습니다.

각 Run에서는 다음과 같은 정보를 확인할 수 있습니다.

특정 Run을 선택하면 검사 결과와 파일별 처리 상태를 확인해 정상 파일과 추가 확인이 필요한 파일을 구분할 수 있습니다.

예외 대응

파일 검사 작업 중 오류가 발생하거나 특정 파일의 결과를 추가로 확인해야 하는 경우에는 Run 상세 정보를 통해 검사 단계와 파일 처리 상태를 확인합니다.

예를 들어 Microsoft Defender 검사 작업이 완료되지 않았거나 격리 Target으로 파일을 전송하는 과정에서 문제가 발생한 경우 해당 파일과 연결 상태를 확인할 수 있습니다.

Scan Run
    │
    ▼
View Details
    │
    ├── Source Path
    │
    ├── Scan Task
    │
    ├── Scan Result
    │
    └── Target Status
            │
            ▼
          Adjust
            │
            ▼
           Retry
            │
            ▼
       Result Verified

문제가 발생한 경우에는 다음 항목을 함께 확인할 수 있습니다.

문제가 해결된 뒤에는 모든 수신 파일을 처음부터 다시 처리하는 대신, 검사가 완료되지 않았거나 추가 확인이 필요한 파일을 중심으로 작업을 다시 실행할 수 있습니다.

이 과정을 통해 파일 수신 → 검사 대상 확인 → Microsoft Defender 검사 → 결과별 분기 → 정상 파일 후속 전송 → 확인 필요 파일 격리 → 실행 결과 확인 → 예외 파일 대응까지 이어지는 파일 검사와 후속 처리 흐름을 구성할 수 있습니다.

이를 통해 외부에서 수신되는 파일을 바로 내부 시스템으로 전송하는 대신, 검사 결과를 기준으로 파일의 처리 경로를 구분하고 정상 파일의 업무 활용과 추가 확인이 필요한 파일의 분리 관리까지 하나의 Flow로 연결할 수 있습니다.

개발자

전송 파일을 Defender로 검사하고 감염 파일을 구분해 후속 처리하기

Defender 보안 통합을 한 번 등록한 뒤, 전송 종료 후 파일 목록에서 검사 결과를 확인해 검사를 통과한 파일만 후속 전송합니다. 시작 전에 다음 항목을 준비합니다.

Python·Node.js는 REST를 직접 호출하는 최소 api() 헬퍼를 API 호출 레시피의 것을 재사용합니다. Java·C#은 번들 소스의 InnorixClient와 Json(C#은 J) 헬퍼를 사용합니다. 감염 판정은 파일 상태 5(skipped)와 코드 100112로 하므로 별도 상태 상수가 없어도 됩니다.

Defender 보안 통합 등록

type: "microsoft_defender", category: "security"로 통합을 등록합니다. scanTiming(검사 시점)·onDetection·scanScope는 규칙(GET /api/integrations/rules/microsoft_defender)의 옵션 값을 사용합니다.

def create_defender_integration(name, scan_timing="after_transfer_target",
                                on_detection="alert_only", scan_scope="all"):
    result = api("POST", "/api/integrations", {
        "name": name,
        "type": "microsoft_defender",
        "category": "security",
        "config": {
            "name": name,
            "scanTiming": scan_timing,   # before_transfer_source · after_transfer_target · both
            "onDetection": on_detection,  # block_transfer · alert_only · admin_confirm
            "scanScope": scan_scope,      # all · executable_files_only · custom_exceptions
        },
    }) or {}
    return result.get("integrationId")


integration_id = create_defender_integration("incoming-file-scan")

onDetection 동작 범위 현재 onDetection(block_transfer·alert_only·admin_confirm) 값은 통합 설정에 저장되지만 전송 동작에는 적용되지 않습니다. 설정값과 관계없이 Defender에서 감염이 탐지된 파일은 skipped 처리됩니다(block_transfer라도 전송 자체를 중단하지 않음). 차단·격리·관리자 승인 같은 후속 정책은 애플리케이션에서 별도로 구현해야 합니다. 정확한 설정 필드는 GET /api/integrations/rules/microsoft_defender를 따릅니다.

검사 시점과 파일 위치 before_transfer_source는 소스에서 전송 전에 검사하므로 감염 파일이 대상으로 전송되지 않습니다. after_transfer_target은 대상으로 전송한 뒤 검사하므로, 감염 파일이 대상에 도착한 상태에서 skipped로 기록되며 대상에 남아 있을 수 있습니다. 이 경우 애플리케이션에서 해당 파일을 격리 위치로 이동하거나 삭제해 처리합니다.

전송 후 검사 결과 확인

전송이 끝나면 파일 목록에서 감염 파일(상태 5 skipped + 코드 100112)과 전송 완료 파일(상태 2 completed)을 구분합니다. 검사가 수행된 전송에서는 완료 파일을 검사 통과 파일로 판단해 다음 단계로 전달하고, 감염 파일은 격리합니다.

VIRUS_CODE = "100112"   # EXCEPTION_VIRUS_SCAN
FILE_SKIPPED = 5
FILE_COMPLETED = 2
PAGE_SIZE = 500

def scan_results(monitor_id):
    infected, completed = [], []
    page = 1
    while True:   # page through until fewer than size are returned
        result = api("GET", f"/api/transfers/{monitor_id}/files", params={
            "state": "any", "page": page, "size": PAGE_SIZE,
        }) or {}
        children = result.get("children") or []
        for c in children:
            path = c.get("sourceFilePath")
            if c.get("status") == FILE_SKIPPED and str(c.get("code")) == VIRUS_CODE:
                infected.append(path)          # flagged by Defender
            elif c.get("status") == FILE_COMPLETED and path:
                completed.append(path)         # transfer-complete (scanned only when scanning ran)
        if len(children) < PAGE_SIZE:
            break
        page += 1
    return infected, completed


infected, completed = scan_results(monitor_id)
print("infected:", len(infected), "completed:", len(completed))
# if scanning ran: completed files -> forward; infected files -> quarantine (app-side)

감염 판정 기준 Defender가 감염으로 표시한 파일은 상태 4(error)나 9(partial)가 아니라 **5(skipped) + 코드 100112**로 기록됩니다. 반드시 두 조건을 함께 확인해야 일반 skip(중복 등)과 구분됩니다.

검사 시점·범위 scanTiming은 소스 전송 전(before_transfer_source)·타깃 전송 후(after_transfer_target)·양쪽(both)에서 선택합니다. 전송 상태 11(virus-scanning)과 파일 상태 8(virus-scanning)은 일시적이며 websocket으로만 전달돼 폴링 조회에는 보이지 않을 수 있으므로, 검사 결과는 전송 종료 후 파일 목록으로 확인합니다.

파일 상태 2의 의미 파일 상태 2(completed)는 전송 완료를 뜻합니다. 검사가 수행된 전송에서는 감염으로 표시되지 않은 완료 파일이 곧 검사 통과이지만, 대용량(massive) 전송은 검사가 생략되므로 이때의 상태 2는 검사 통과를 보장하지 않습니다. Defender 검사가 필요한 경우 검사가 생략되지 않는 전송 방식으로 구성해야 합니다.

검사를 통과한 파일은 POST /api/transfers/manual의 sourceItem에 지정해 다음 단계로 전달하고, 감염 파일은 별도 격리 위치로 옮기거나 목록으로 보고합니다(INNORIX는 자동 격리하지 않음). 파일 목록을 sourceItem으로 정확히 지정하는 방법은 API 호출 레시피를 참고합니다.

구현 결과

이 레시피를 적용하면 다음 흐름으로 수신 파일을 Defender로 검사하고 결과에 따라 처리할 수 있습니다.

전송 (Defender 검사 시점 지정)
   ↓  감염 파일 skip, 전송은 2/9로 종료  

파일 목록 조회 (GET .../files)
   ↓  상태 5 + code 100112 = 감염 · 상태 2 = 전송 완료  

검사 통과 파일 후속 전송 · 감염 파일 격리(애플리케이션 처리)

Defender 검사 결과를 확인해 감염 파일(상태 5+코드 100112)은 격리하고, 검사를 통과한 파일만 후속 전송할 수 있습니다.