# ICAP 內容驗證整合

> 本文件說明 MaiAgent 平台如何整合 ICAP (Internet Content Adaptation Protocol) 協定,實現對使用者上傳檔案和對話內容的安全掃描與驗證,防範惡意軟體和不當內容。

## 1. 什麼是 ICAP？

ICAP (Internet Content Adaptation Protocol) 是一個輕量級的協定,用於將內容轉發給外部服務進行處理,如病毒掃描、內容過濾、資料外洩防護等。

### 1.1 ICAP 的核心價值

| 考量面向    | 無內容驗證方案          | ICAP 內容驗證方案       |
| ------- | ---------------- | ----------------- |
| **安全性** | 使用者可能上傳惡意軟體或不當內容 | 自動掃描並阻擋惡意檔案和內容    |
| **合規性** | 難以符合企業資安政策要求     | 整合企業級防毒和 DLP 解決方案 |
| **靈活性** | 需自行開發內容檢測邏輯      | 使用標準協定整合第三方專業服務   |
| **維護性** | 需持續更新病毒碼和檢測規則    | 由專業廠商負責維護檢測引擎     |

### 1.2 常見應用場景

* **檔案上傳安全**: 使用者上傳到知識庫的文件需先經過病毒掃描
* **對話內容過濾**: 檢測對話中是否包含不當言論、敏感資訊
* **資料外洩防護 (DLP)**: 防止使用者上傳包含機密資訊的檔案
* **合規性檢查**: 確保內容符合 GDPR、HIPAA 等法規要求

***

## 2. MaiAgent ICAP 整合架構

{% @mermaid/diagram content="flowchart TB
subgraph Client\["客戶端"]
User\["使用者"]
WebChat\["WebChat 介面"]
end

```
subgraph MaiAgent["MaiAgent 平台"]
    API["Upload API"]
    Queue["處理佇列"]
    ICAP_Client["ICAP 客戶端"]
    DB[("資料庫")]
    Storage[("檔案儲存")]
end

subgraph ICAP_Service["ICAP 服務"]
    Scanner["防毒引擎"]
    DLP["DLP 引擎"]
    Filter["內容過濾器"]
end

User -- "上傳檔案" --> WebChat
WebChat -- "HTTP POST" --> API
API --> Queue
Queue --> ICAP_Client

ICAP_Client <-. "ICAP REQMOD" .-> Scanner
ICAP_Client <-. "ICAP RESPMOD" .-> DLP
ICAP_Client <-. "ICAP OPTIONS" .-> Filter

ICAP_Client -- "驗證通過" --> Storage
ICAP_Client -- "記錄結果" --> DB

ICAP_Client -. "驗證失敗<br/>發送事件" .-> WebChat
WebChat -. "顯示錯誤" .-> User" %}
```

### 2.1 核心元件說明

* **ICAP 客戶端**: MaiAgent 內建的 ICAP 協定實作,負責與 ICAP 伺服器通訊
* **ICAP 伺服器**: 第三方內容掃描服務,如 Symantec、McAfee、Trend Micro 的防毒閘道器
* **處理佇列**: 非同步處理檔案上傳和掃描任務,避免阻塞使用者操作
* **掃描記錄**: 儲存所有掃描結果,包括檔案雜湊、掃描時間、結果等資訊

### 2.2 ICAP 請求流程

{% @mermaid/diagram content="sequenceDiagram
participant User as 使用者
participant WebChat as WebChat
participant MaiAgent as MaiAgent API
participant ICAP as ICAP 伺服器
participant Storage as 檔案儲存

```
User->>WebChat: 上傳檔案
WebChat->>MaiAgent: POST /upload
MaiAgent->>MaiAgent: 生成檔案 ID

Note over MaiAgent,ICAP: ICAP REQMOD 請求
MaiAgent->>ICAP: REQMOD /scan HTTP/1.1<br/>Encapsulated: req-hdr=0, req-body=...
ICAP->>ICAP: 掃描檔案內容

alt 檔案安全
    ICAP-->>MaiAgent: 200 OK (檔案通過)
    MaiAgent->>Storage: 儲存檔案
    Storage-->>MaiAgent: 儲存成功
    MaiAgent-->>WebChat: 200 OK {fileId: ...}
    WebChat-->>User: 上傳成功
else 檔案有問題
    ICAP-->>MaiAgent: 403 Forbidden (病毒/違規內容)
    MaiAgent->>WebChat: Socket.IO: ICAP_BLOCKED 事件
    WebChat-->>User: 顯示錯誤訊息
    MaiAgent->>MaiAgent: 記錄掃描失敗
else ICAP 伺服器錯誤
    ICAP-->>MaiAgent: 500 Internal Server Error
    MaiAgent->>WebChat: Socket.IO: ICAP_ERROR 事件
    WebChat-->>User: 系統錯誤,請稍後再試
    MaiAgent->>MaiAgent: 記錄錯誤日誌
end" %}
```

***

## 3. ICAP 協定實作細節

### 3.1 ICAP 請求格式

MaiAgent 使用 REQMOD (Request Modification) 模式發送檔案給 ICAP 伺服器:

```http
REQMOD icap://icap-server.example.com/scan ICAP/1.0
Host: icap-server.example.com
Encapsulated: req-hdr=0, req-body=147
Allow: 204

POST /upload HTTP/1.1
Host: maiagent.ai
Content-Type: application/octet-stream
Content-Length: 1024

400
[Binary file content in chunked encoding]
0
```

**關鍵欄位說明**:

* **REQMOD**: 請求修改模式,用於在內容儲存前進行檢查
* **Encapsulated**: 描述 HTTP 請求的封裝格式
* **Allow: 204**: 告知 ICAP 伺服器如果內容無需修改可直接返回 204
* **Chunked Encoding**: 使用分塊傳輸編碼發送檔案內容

### 3.2 分塊傳輸編碼 (Chunked Transfer Encoding)

MaiAgent 正確實作了 HTTP 分塊傳輸編碼:

```
分塊傳輸格式:
<資料大小（十六進位）>\r\n
<資料內容>\r\n
...
0\r\n\r\n  (結束標記)
```

**為何需要正確的分塊編碼？**

* ICAP 協定要求使用 HTTP 分塊傳輸編碼來傳送請求和回應本體
* 錯誤的編碼格式會導致 ICAP 伺服器無法正確解析檔案內容
* MaiAgent 修正了分塊大小的十六進位格式表示,確保與 ICAP 標準相容

### 3.3 ICAP 回應處理

ICAP 伺服器可能返回以下回應:

| 狀態碼                    | 含義           | MaiAgent 處理方式                |
| ---------------------- | ------------ | ---------------------------- |
| **200 OK**             | 內容已檢查或修改     | 接受修改後的內容(如有),儲存檔案            |
| **204 No Content**     | 內容無需修改       | 直接儲存原始檔案                     |
| **403 Forbidden**      | 內容被禁止(如包含病毒) | 拒絕儲存,向客戶端發送 ICAP\_BLOCKED 事件 |
| **500 Internal Error** | ICAP 伺服器錯誤   | 記錄錯誤,向客戶端發送 ICAP\_ERROR 事件   |

***

## 4. WebChat 整合

當 ICAP 掃描完成後，系統會即時通知使用者掃描結果：

* **檔案被阻擋**: 顯示友善的錯誤訊息，說明檔案被拒絕的原因（如偵測到病毒）
* **系統錯誤**: 提示使用者稍後再試，並記錄錯誤日誌

### 使用者體驗優化

* **即時回饋**: 上傳檔案後立即顯示「掃描中」狀態
* **進度指示**: 大型檔案上傳時顯示進度條
* **友善錯誤訊息**: 使用易懂的語言說明檔案被拒絕的原因
* **重試機制**: 如果是暫時性錯誤,提供重新上傳選項

***

## 5. 掃描記錄管理

### 5.1 記錄保存

MaiAgent 會儲存所有 ICAP 掃描的詳細記錄:

每筆掃描記錄包含以下資訊:

| 欄位       | 說明                             |
| -------- | ------------------------------ |
| 檔案識別碼    | 被掃描檔案的唯一識別碼                    |
| 檔案名稱     | 原始檔案名稱                         |
| 檔案雜湊值    | SHA-256 雜湊，用於確認檔案完整性           |
| 掃描結果     | PASS（通過）、BLOCKED（阻擋）、ERROR（錯誤） |
| 掃描原因     | 當檔案被阻擋時，記錄具體原因                 |
| ICAP 伺服器 | 執行掃描的 ICAP 伺服器位址               |
| 掃描時間     | 掃描執行的時間戳記                      |
| 使用者/組織   | 發起掃描的使用者與所屬組織                  |

### 5.2 過期記錄清理

MaiAgent 實作了自動清理機制,定期刪除過期的掃描記錄:

系統會透過背景排程任務，自動清理超過保留期限的掃描記錄。

**清理策略**:

* **保留期限**: 預設保留 90 天的掃描記錄
* **執行頻率**: 每週執行一次清理任務
* **稽核保留**: 重要的安全事件(如發現病毒)可設定更長的保留期限

***

## 6. 配置與部署

### 6.1 ICAP 伺服器配置

管理員需要在 MaiAgent 後台配置 ICAP 伺服器資訊:

管理員可在後台設定以下 ICAP 參數:

| 設定項目       | 說明              |
| ---------- | --------------- |
| ICAP 伺服器位址 | ICAP 服務的連線 URL  |
| 逾時時間       | 掃描超時秒數          |
| 重試次數與間隔    | 掃描失敗時的重試策略      |
| 掃描範圍       | 選擇掃描檔案上傳和/或對話內容 |
| 檔案大小限制     | 超過此大小的檔案不進行掃描   |
| 副檔名白名單     | 指定不需掃描的檔案類型     |

### 6.2 支援的 ICAP 服務

MaiAgent 相容以下主流 ICAP 服務:

* **Symantec Protection Engine**: 企業級防毒和內容過濾
* **McAfee Web Gateway**: 閘道層級的內容掃描
* **Trend Micro IWSVA**: 整合式 Web 安全與內容掃描
* **Kaspersky Scan Engine**: Kaspersky 的 ICAP 掃描引擎
* **ClamAV (透過 c-icap)**: 開源防毒解決方案

### 6.3 效能考量

為確保系統效能,建議:

* **非同步掃描**: 大型檔案使用背景任務掃描,不阻塞上傳回應
* **快取機制**: 對相同檔案(相同雜湊值)的掃描結果進行快取
* **ICAP 連線池**: 維護與 ICAP 伺服器的持久連線,減少連線開銷
* **負載均衡**: 使用多個 ICAP 伺服器實例分散掃描負載

***

## 7. MaiAgent ICAP 整合的技術優勢

### 7.1 安全性優勢

* **多層防護**: 在檔案儲存前就進行掃描,防範惡意內容
* **即時阻擋**: 發現威脅立即阻擋,不會儲存到系統中
* **專業引擎**: 整合業界領先的防毒和 DLP 引擎
* **完整記錄**: 所有掃描活動都有詳細記錄,便於安全稽核

### 7.2 合規性優勢

* **標準協定**: 使用業界標準 ICAP 協定,易於整合現有企業安全設施
* **稽核軌跡**: 完整的掃描記錄符合合規要求
* **靈活配置**: 可根據不同產業的合規需求調整掃描策略
* **資料保護**: 支援 DLP 引擎,防止敏感資料外洩

### 7.3 運維優勢

* **解耦架構**: ICAP 掃描邏輯與應用程式解耦,易於維護
* **水平擴展**: 可輕鬆增加 ICAP 伺服器處理更多掃描請求
* **統一管理**: 企業可使用現有的 ICAP 基礎設施,統一管理所有應用的內容掃描
* **詳細日誌**: 完整的掃描日誌便於問題排查和效能優化

***

## 8. 相關文檔

* [AI 安全防護機制](https://docs.maiagent.ai/tech/advanced-genai-tech/guardrails) - 了解 MaiAgent 的多層次安全防護策略
* [檔案上傳與知識庫管理](https://docs.maiagent.ai/km/km-basic-settings)

### 參考連結

* [ICAP RFC 3507](https://datatracker.ietf.org/doc/html/rfc3507)
* [Chunked Transfer Encoding (RFC 7230)](https://datatracker.ietf.org/doc/html/rfc7230#section-4.1)
* [Open ICAP Forum](https://www.icap-forum.org/)