封鎖清單

security.blocklist 外掛從發佈位址清單的地方取得需要拒絕存取的位址：威脅情報來源、信譽服務、伺服器之間共用的封鎖清單。使用者設定來源後，Nginx UI 依每個來源的重新整理間隔呼叫外掛，把結果寫成 nginx deny 規則儲存到自己的檔案中，並在清單變化時重新載入 nginx。

方法	必要	用途
blocklist.fetch	是	取得一個來源目前的完整清單。

外掛必須請求 network 權限。

宣告來源類型

"capabilities": ["security.blocklist"],
"permissions": ["network"],
"blocklist": {
  "sources": [
    {
      "code": "threatfeed",
      "name": "ThreatFeed",
      "refresh_seconds": 900,
      "configuration": {
        "fields": [
          { "key": "api_key", "display_name": "API key", "required": true, "secret": true },
          { "key": "min_score", "type": "number", "display_name": "Minimum score", "help_text": "Only list addresses scored at least this high" }
        ]
      }
    }
  ]
}

code、name 和 configuration.fields 的用法與通知通道相同。refresh_seconds 是該類型來源的預設重新整理間隔：0 或不填表示一小時，否則至少為 60，因為變化更快的清單無法靠重新載入 nginx 來提供。

取得

{ "jsonrpc": "2.0", "id": 48, "method": "blocklist.fetch", "params": { "source": "threatfeed", "config": { "api_key": "key_live_xxx", "min_score": "80" } } }

回覆目前的完整清單，而不是自上次呼叫以來的變化：

{
  "jsonrpc": "2.0", "id": 48,
  "result": {
    "entries": [
      { "cidr": "198.51.100.23", "reason": "SSH brute force" },
      { "cidr": "203.0.113.0/24", "reason": "Botnet command and control" },
      { "cidr": "2001:db8:bad::/48" }
    ],
    "ttl_seconds": 900
  }
}

欄位	意義
entries[].cidr	IPv4 或 IPv6 位址，或 CIDR 網段。不含連接埠、區域或主機名稱。
entries[].reason	來源列出它的原因，僅供顯示。選用。
ttl_seconds	清單的有效期。0 表示由重新整理間隔決定。

每個位址只傳送一次，絕不要傳送涵蓋所有位址的項目（0.0.0.0/0、::/0）。

警告

無法取得清單時，回覆錯誤，絕不要回覆空清單。 空清單會讓 Nginx UI 不拒絕任何位址，而錯誤會保留目前的清單。原因在於設定（包括必填欄位為空）時回覆帶 data.field 的 -32003，其他情況回覆 -32000。絕不要把 config 的值寫入日誌、錯誤或 reason。

Nginx UI 如何處理結果

• 它把每個項目解析為位址或網段，捨棄其他項目以及涵蓋所有位址的項目，並回報捨棄的數量。結果中的其他文字（包括 reason）都不會進入設定。項目會被正規化、去除重複、排序，並且最多保留 100000 個。

• 它把每個來源的清單寫入 <nginx 設定目錄>/blocklists/<來源 ID>.conf：

  # generated by nginx-ui
  deny 198.51.100.23;
  deny 203.0.113.0/24;
  deny 2001:db8:bad::/48;

• 只有檔案變化時才重新載入 nginx，重新載入前先測試設定，測試失敗時還原先前的檔案。取得失敗時保留目前的檔案。

• 它從不自行把檔案加入某個 server，而是向使用者顯示需要加在清單生效位置的那一行：include blocklists/<來源 ID>.conf;。

Nginx UI 在來源的間隔之後再次取得；上次結果的 ttl_seconds 更短時會提前取得，但最多每分鐘一次。取得失敗時，在 5 分鐘和間隔兩者中較短的時間後重試。最近一次取得的結果顯示在來源旁邊。blocklist.fetch 最多等待 60 秒。