跳轉到

AI 代理程式安全最佳實踐

本頁提供 AI 代理程式設計師在整合 NextPDF MCP 工具時應遵循的安全設計原則。這些原則基於 OWASP LLM Top 10 威脅模型和 NextPDF 的工具風險分類。

一、人機協同（HITL）設計模式

HITL 觸發條件

下列情況必須設置 HITL 確認閘門：

觸發條件 HITL 類型 範例
工具風險等級為 high 強制確認 sign_pdf、redact_pdf
批次操作影響 > 10 份文件 規模確認 batch_process
操作涉及個人識別資訊 PII 確認 apply_policy with GDPR
寫入外部系統 系統整合確認 embed_documents
操作結果不可預覽 風險提示 protect_pdf（無法預覽加密後的效果）

HITL 確認等級

等級 1：告知型（Inform）
  → 執行前告知使用者，不等待回應
  → 適用於 low 風險操作
  → 範例：「我正在提取 report.pdf 的文字...」

等級 2：確認型（Confirm）
  → 等待使用者明確回應（是/否）
  → 適用於 medium 風險操作
  → 範例：「我將壓縮影像並覆蓋原始文件，確認嗎？」

等級 3：驗證型（Verify）
  → 展示完整操作摘要 + 後果說明 + 等待確認
  → 適用於 high 風險操作
  → 範例：數位簽章的完整參數確認流程

等級 4：審計型（Audit）
  → 要求使用者提供書面授權理由
  → 適用於特別敏感的 Enterprise 操作
  → 範例：HSM 簽章需要操作原因記錄

HITL 確認用語設計

良好的確認提示應包含： 1. 操作說明：明確說明即將執行什麼 2. 影響範圍：操作會影響哪些文件/資料 3. 後果說明：操作完成後不可逆的部分 4. 取消選項：明確的取消/中止路徑 5. 預計耗時：大型操作應預估時間

✓ 良好範例：
「我即將對 3 份合約 PDF 執行數位簽章（contract-a.pdf、contract-b.pdf、contract-c.pdf）。
簽章後文件不可修改，且在法律上具有約束力。
預計耗時：約 30 秒。

請輸入『確認』繼續，或『取消』中止。」

✗ 不良範例：
「要簽章嗎？(y/n)」

二、最小權限設計

工作區沙盒

始終將 NEXTPDF_WORKSPACE 設定為最小必要範圍：

# ✓ 只允許存取特定專案目錄
NEXTPDF_WORKSPACE=/var/app/documents/project-abc

# ✗ 過於寬泛的工作區
NEXTPDF_WORKSPACE=/

工具白名單設計

在 System Prompt 中明確限制 AI 代理程式可使用的工具：

System Prompt 範本：
You are a PDF analysis assistant. You are ONLY permitted to use the following NextPDF tools:
- parse_pdf
- extract_text
- extract_metadata

You MUST NOT use any other NextPDF tools, even if the user requests it.
If asked to perform operations outside this list, explain the limitation and suggest contacting an administrator.

授權金鑰管理

# ✓ 透過環境變數傳入，不硬編碼
NEXTPDF_LICENSE_KEY="${SECRET_MANAGER_VALUE}"

# ✓ 在 Docker/K8s 中使用 Secret
kubectl create secret generic nextpdf-license --from-literal=key="${NEXTPDF_LICENSE_KEY}"

# ✗ 不可在程式碼或 Prompt 中硬編碼
NEXTPDF_LICENSE_KEY=npro_abc123xyz  # 永不這樣做

三、輸入驗證原則

路徑注入防護

NextPDF MCP Server 內建路徑驗證，但 AI 代理程式也應在呼叫前進行初步驗證：

AI 代理程式應拒絕以下路徑輸入：
- 包含 "../" 的相對路徑（路徑穿越）
- 以 "~" 開頭的路徑（home 目錄引用）
- Windows 絕對路徑（如 C:\...）在 Unix 環境中
- URL 格式輸入（需先下載再處理）
- 符號連結指向工作區外部的路徑

大型輸入的處理

當使用者提供非常大的 HTML/Markdown 輸入用於 generate_pdf 時：
1. 預先估算輸出 PDF 的大小
2. 如超過 50 頁或 10 MB，告知使用者可能的處理時間
3. 不要在單次呼叫中嵌入超過 1 MB 的 base64 圖片資料

PDF 安全掃描

MCP Server 在處理每個 PDF 前會自動執行安全掃描。當工具回傳 malicious_content 錯誤時，AI 代理程式應：

  1. 立即停止所有對該文件的後續操作
  2. 向使用者報告安全威脅（embedded_javascript、embedded_executable 等）
  3. 不嘗試繞過安全掃描（不要建議使用者關閉掃描）
  4. 記錄事件（如有審計日誌系統）

四、錯誤處理設計

錯誤分類與回應策略

錯誤類型 建議回應 是否自動重試
file_not_found 提示確認路徑，請使用者確認 否
access_denied 說明沙盒限制，不建議繞過 否
invalid_pdf 建議重新獲取文件 否
encrypted_pdf 請使用者提供密碼（安全通道） 是（需使用者提供密碼）
license_required 說明所需授權層級 否
internal_error 提供 trace_id，建議回報問題 一次（相同參數）
worker_pool_exhausted 等待 5 秒後重試一次 是（一次，延遲後）

不應記錄的敏感資訊

AI 代理程式的操作日誌不應包含： - 憑證密碼（certificate_password 參數值） - HSM PIN 碼 - 授權金鑰值 - 文件的完整內容（僅記錄路徑和操作類型）

優雅降級範本

當 Pro/Enterprise 功能不可用時（無授權）：

AI 回應範本：
「您請求的功能（{tool_name}）需要 NextPDF {tier} 授權。

使用 Core 工具，我可以：
- ✓ 提取文件的基本文字內容（extract_text）
- ✓ 讀取文件元資料（extract_metadata）

{tier} 授權可以額外提供：
- {描述 tier 的主要優勢}

如需了解授權方案，請聯絡 NextPDF 銷售團隊。」

五、審計與可觀測性

操作日誌格式

建議 AI 代理程式記錄每次 MCP 工具呼叫，格式如下：

{
  "timestamp": "2026-03-04T10:30:00Z",
  "session_id": "sess-abc123",
  "user_id": "user-456",
  "tool": "compress_images",
  "risk_level": "medium",
  "arguments": {
    "input_path": "/workspace/report.pdf",
    "output_path": "/workspace/report-compressed.pdf",
    "jpeg_quality": 85
  },
  "hitl": {
    "required": true,
    "confirmed_at": "2026-03-04T10:29:55Z",
    "confirmation_text": "確認壓縮"
  },
  "result": "success",
  "duration_ms": 3200,
  "trace_id": "trace-xyz789"
}

異常模式偵測

AI 代理程式系統應監控以下異常模式：

異常一：高頻 high 風險操作
  → 閾值：同一 session 內 > 3 次 high 風險操作
  → 動作：提升 HITL 等級，通知管理員

異常二：批次操作規模異常
  → 閾值：batch_process 影響 > 100 份文件
  → 動作：強制等級 4（審計型）確認

異常三：存取敏感路徑嘗試
  → 偵測：路徑包含 "secret", "credential", "key", ".env" 等關鍵字
  → 動作：立即拒絕並記錄

異常四：重複失敗
  → 閾值：同一工具 / 同一路徑連續失敗 3 次
  → 動作：暫停 5 分鐘並通知管理員

六、多租戶環境特別考量

在 SaaS / 多租戶環境中使用 NextPDF MCP 工具時：

1. 命名空間隔離
   → embed_documents / semantic_search 必須帶 namespace: "{tenant_id}"
   → 不同租戶的向量資料嚴格隔離

2. 工作區隔離
   → 每個租戶的 NEXTPDF_WORKSPACE 必須是獨立目錄
   → 絕不跨租戶共享 MCP Server 實例（除非 Enterprise HighControl 模式）

3. 速率限制
   → 為每個租戶設置獨立的工具呼叫速率限制
   → 防止單一租戶的高負載影響其他租戶

4. 跨租戶資料存取
   → 絕不允許一個租戶的 AI 代理程式存取另一租戶的 PDF
   → 路徑驗證必須包含租戶 ID 前綴檢查

參見