網路安全策略 API 參考

引導您如何透過程式化方式控制伺服器的本地防火牆設置及允許訪問的 IP 列表。

📋 概述

此 API 模組透過控制 GIIP [本地護衛] 項目，實時更新過濾伺服器出入站流量的安全策略。

🔐 認證與請求頭

所有請求必須包含通用的認證請求頭。

• Header: x-giip-ak: [Your Access Key]
• Header: x-giip-sk: [Your Secret Key]

🚀 核心 API 端點

1. 查詢各伺服器安全規則 (Get Security Rules)

• URL: POST /api/security/rules/list
• 描述: 查詢應用於特定伺服器的入站/出站允許規則資訊。
• 請求體 (Request Body):

{
  "serverIsn": 456
}

2. 添加允許的 IP (Add Allowed IP)

• URL: POST /api/security/rules/add
• 描述: 向防火牆策略中添加一個可以訪問特定端口的新 IP 或網段。
• 請求體 (Request Body):

{
  "serverIsn": 456,
  "port": 8080,
  "allowedIp": "1.2.3.4",
  "description": "Dev Team Access"
}

3. 批量部署安全策略 (Deploy Policy)

• URL: POST /api/security/policy/deploy
• 描述: 為特定專案所屬的所有伺服器一次性應用標準安全策略。
• 請求體 (Request Body):

{
  "projectIsn": 123,
  "policyId": "P-SEC-001"
}

🔍 響應數據示例

{
  "RstVal": 0,
  "RstMsg": "Success",
  "Data": {
    "affectedServers": 15,
    "status": "In Progress"
  }
}

💡 使用場景

• 動態 IP 白名單: 當居家辦公員工連接 VPN 時，自動將其當前 IP 註冊到伺服器防火牆中。
• 自動響應入侵: 當安全監控系統檢測到攻擊 IP 時，立即調用 API 在全公司伺服器中攔截該 IP。

🛡️ 巧用 Sk3 (高性能日誌)

在進行修改安全策略或 IP 白名單等敏感的基礎設施控制操作時，為了確保變更歷史的完整性並獲取詳細的審計日誌 (Audit Log)，建議使用 giipApiSk3 端點。

• 端點: https://giipfaw.azurewebsites.net/api/giipApiSk3
• 安全優勢: 若策略更新失敗，系統會立即記錄調用者的詳細環境資訊 (IP, UA) 和堆疊追蹤 (StackTrace)，助力快速分析是入侵嘗試還是配置錯誤的原因。
• 使用技巧: 將 text 命令與 jsondata 結合使用，可以在不丟失數據的情況下，安全地管理複雜的安全規則集，從而提升整體基礎設施的安全水平。

🔧 疑難排解

症狀	原因	解決方法
所有請求均以 401/認證錯誤失敗	缺少 x-giip-ak 或 x-giip-sk 請求頭，或使用了無效的密鑰	確認兩個認證請求頭均已包含，且所發放的 Access Key/Secret Key 正確無誤
POST /api/security/rules/add 響應中的 RstVal 不為 0	缺少 serverIsn，或 allowedIp 格式（IP/網段）錯誤	按規範重新核對 Request Body 中的 serverIsn、port、allowedIp 值
批量部署策略後 affectedServers 返回 0	projectIsn 錯誤，或該專案下沒有所屬伺服器	指定正確的 projectIsn 並確認專案下已註冊伺服器
傳輸複雜安全規則集時數據丟失	text 命令中的特殊字元未轉義	在 giipApiSk3 端點上組合使用 text 與 jsondata 以安全傳輸參數

---

版本: 1.1 最後更新: 2026-04-11 源碼: giipv3/public/help/api-network-security.zh-TW.md

---

相關文檔:

• API 結果代碼指南 (RstVal)