運用機器學習自動探索 API 端點並產生結構描述

現在，Cloudflare 會自動探索所有 API 端點並學習我們所有 API Gateway 客戶的 API 結構描述。即使客戶目前對其現有 API 知之甚少，也可以使用這些新功能在其 API 端點上實施積極的安全模型。

保護 API 安全的第一步是瞭解 API 主機名稱和端點。我們經常聽到客戶被迫開始他們的 API 編目和管理工作，類似於「我們透過電子郵件傳送試算表並要求開發人員列出他們的所有端點」。

您能想像這種方法的問題嗎？也許您親眼見證過這些問題。「傳送電子郵件並詢問」方法建立了一個時間點詳細目錄，這一詳細目錄可能會隨著下一個程式碼發布而改變。它依賴部落知識，而這些知識可能會隨著人們離開組織而消失。最後，它很容易出現人為錯誤。

即使您透過團隊努力收集了準確的 API 詳細目錄，透過實施 API 結構描述來驗證 API 是否如預期般使用也需要更多的集體知識來建立該結構描述。現在，API Gateway 的新 API 探索和結構描述學習功能相結合，可自動保護 Cloudflare 全球網路中的 API，並消除手動 API 探索和構建結構描述的需求。

API Gateway 透過稱為 API 探索的功能來探索 API。以前，API 探索使用客戶特定的工作階段識別項（HTTP 標頭或 cookie）來識別 API 端點並向客戶顯示其分析結果。

以這種方式進行探索是有效的，但它有三個缺點：

1. 客戶必須知道他們使用哪個標頭或 cookie 來描述工作階段。雖然工作階段識別項很常見，但找到正確的權杖可能需要時間。

2. 由於 API 探索需要工作階段識別項，我們無法監控和報告完全未經驗證的 API。如今，客戶仍然希望瞭解無工作階段流量，以確保記錄所有 API 端點並將濫用降至最低。

3. 將工作階段識別項輸入儀表板後，客戶必須等待長達 24 小時才能完成探索過程。沒有人喜歡等待。

雖然這種方法有缺點，但我們知道，透過從基於工作階段的產品開始，我們可以快速為客戶提供價值。隨著我們獲得客戶並透過系統傳遞更多流量，我們知道新的標記資料對於進一步建立我們的產品非常有用。如果我們可以使用現有的 API 中繼資料和新的標記資料來訓練機器學習模型，我們將不再需要工作階段識別項來確定 API 的端點。所以我們決定建立這種新方法。

我們利用從基於工作階段標識項的資料中學到的知識，建立了一個機器學習模型，以發現到某個網域的所有 API 流量，而不管工作階段標識項如何。藉助我們基於機器學習的新 API 探索，Cloudflare 不斷探索透過我們網路路由的所有 API 流量，無需客戶提前輸入任何內容。透過此版本，API Gateway 客戶將能夠比以往更快地開始使用 API 探索，並且他們將發現以前無法發現的未經驗證 API。

工作階段標識項對於 API Gateway 仍然很重要，因為它們構成了我們的容量濫用預防速率限制以及序列分析的基礎。請參閱下面的「工作原理」部分，瞭解有關新方法如何執行的更多資訊。

現在，您已經使用 API 探索找到了新的 API，那麼如何保護它們呢？為了防禦攻擊，API 開發人員必須確切瞭解他們期望如何使用 API。幸運的是，開發人員能夠以程式設計方式產生 API 結構描述檔案，該檔案將可接受的輸入編碼到 API 中，並將其上傳到 API Gateway 的結構描述驗證中。

然而，我們已經討論過有多少客戶無法像開發人員建立 API 那樣快速地找到自己的 API。當他們找到 API 後，也很難為可能數百個 API 端點中的每一個端點準確建立唯一的 OpenAPI 結構描述，因為安全團隊很少在其記錄中看到 HTTP 請求方法和路徑以外的內容。

當我們查看 API Gateway 的使用模式時，我們發現客戶會探索 API，但幾乎從不強制執行結構描述。當我們問他們「為什麼不呢？」，答案很簡單：「即使我知道某個 API 存在，也需要花費大量時間追蹤每個 API 擁有者，以便讓他們提供結構描述。我很難將這些任務優先於其他必須完成的安全項目」。時間和專業知識是我們的客戶在實施保護方面最欠缺的東西。

所以我們決定縮小這一差距。我們發現，用於探索 API 端點的相同學習過程可以在發現端點後套用至端點，以便自動學習結構描述。使用此方法，我們現在可以為我們發現的每個端點即時產生 OpenAPI 格式的結構描述。我們將這個新功能稱為「結構描述學習」。然後，客戶可以將 Cloudflare 產生的結構描述上傳到結構描述驗證中，以實施積極的安全模型。

利用 RESTful API，請求由不同的 HTTP 方法和路徑組成。以 Cloudflare API 為例。您會注意到一個常見趨勢，即可能使對此 API 的請求在此部落格的請求中非常顯眼的路徑：API 請求全部以 /client/v4 開頭，後面為服務名稱、唯一識別碼，有時還包括服務功能名稱和進一步的識別碼。

我們如何輕鬆識別 API 請求？乍一看，似乎很容易透過「以 /client 開頭的路徑」之類的啟發式方法以程式設計方式探索到這些請求，但我們新探索功能的核心包含一個機器學習模型，該模型為對 HTTP 交易進行評分的分類器提供支援。如果 API 路徑如此結構化，為什麼需要機器學習來實現這一點，而不能只使用一些簡單的啟發式方法呢？

答案歸結為一個問題：API 請求實際上是由什麼構成的？它與非 API 請求有何不同？讓我們來看兩個範例。

與 Cloudflare API 一樣，我們許多客戶的 API 都遵循一些模式，例如在 API 請求的路徑前面加上「api」識別碼和版本作為首碼，例如：/api/v2/user/7f577081-7003-451e-9abe-eb2e8a0f103d。

因此，僅在路徑中尋找「api」或版本就已經是一個很好的啟發式方法，它告訴我們這很可能是 API 的一部分，但不幸的是並不總是那麼容易。

讓我們考慮另外兩個範例，/users/7f577081-7003-451e-9abe-eb2e8a0f103d.jpg 和 /_users/7f577081-7003-451e-9abe-eb2e8a0f103d，_兩者的差別只在於 .jpg 副檔名。第一個路徑可以只是靜態資源，例如使用者的縮圖。而第二條路徑僅從它本身來看，並沒有給我們提供太多線索。

手動製作此類啟發式方法很快就會變得困難。雖然人類擅長尋找模式，但考慮到 Cloudflare 每天看到的資料規模，建立啟發式方法卻具有驗證性。因此，我們使用機器學習來自動推導這些啟發式方法，以便我們知道它們是可重現的並有一定的準確性。

訓練的輸入是 HTTP 請求/回應樣本的特徵，例如我們透過前面提到的基於工作階段標識項的探索收集的內容類型或檔案副檔名。遺憾的是，資料中並非所有內容都是 API。此外，我們還需要代表非 API 流量的樣本。因此，我們從工作階段標識項探索資料開始，手動清理它並派生出更多的非 API 流量樣本。我們非常小心地避免模型與資料過度擬合。也就是說，我們希望模型能夠泛化到訓練資料之外。

為了訓練模型，我們使用了 CatBoost 庫，我們已經對其擁有大量專業知識，因為它也為我們的機器人管理 ML 模型提供支援。簡單地說，我們可以將產生的模型視為一個流程圖，它告訴我們應該依次檢查哪些條件，例如：如果路徑包含「api」，則也要檢查有沒有檔案副檔名等等。該流程圖的末尾是一個分數，它告訴我們一個 HTTP 交易屬於 API 的可能性。

給定訓練好的模型，我們可以輸入透過 Cloudflare 網路執行的 HTTP 請求/回應的特徵，並計算該 HTTP 交易屬於 API 或不屬於 API 的可能性。特徵擷取和模型評分是在 Rust 中完成的，在我們的全球網路上只需要幾微秒的時間。由於探索功能從我們強大的資料管道中獲取資料，因此實際上沒有必要對_每筆_交易進行評分。我們可以透過僅對我們知道最終會進入資料管道的那些交易進行評分，來減少伺服器上的負載，從而節省 CPU 時間，並使該功能具有成本效益。

透過資料管道中的分類結果，我們可以使用與基於工作階段標識項的探索相同的 API 探索機制。這個現有系統運作良好，使我們能夠有效地重複使用程式碼。它還幫助我們將結果與基於工作階段標識項的探索進行比較，因為這些系統是可以直接比較的。

為了使 API 探索結果有用，探索的首要任務是將我們看到的唯一路徑簡化為變數。我們之前已經討論過這個問題。要推斷我們在全球網路中看到的各種不同的識別碼方案並非易事，當網站使用超出簡單 GUID 或整數格式的自訂識別碼時尤為如此。API 探索在一些不同的變數分類器和監督學習的幫助下適當地標準化了包含變數的路徑。

只有在標準化路徑之後，探索結果才能供我們的使用者以簡單的方式使用。

那麼，機器學習探索與基於工作階段標識項的探索（依賴標頭或 cookie 來標記 API 流量）相比如何？

我們的期望是它偵測到一組非常相似的端點。然而，在我們的資料中，我們知道會有兩個差距。首先，我們有時會發現客戶無法使用工作階段標識項僅清晰地剖析 API 流量。發生這種情況時，探索會顯示非 API 流量。其次，由於我們在 API 探索的第一個版本中需要工作階段標識項，因此不屬於工作階段一部分的端點（例如登入端點或未經驗證的端點）在概念上是不可發現的。

下圖顯示了兩種發現變體在客戶網域上偵測到的端點數量的長條圖。

從鳥瞰角度來看，結果看起來非常相似，這很好地表明機器學習探索的表現符合預期。該圖中存在一些明顯的差異，這也是預料之中的，因為我們還將探索概念上僅使用工作階段標識項無法發現的端點。事實上，如果我們仔細觀察逐個網域的比較，我們會發現大約 46% 的網域沒有變化。下圖比較了基於工作階段和基於機器學習的探索之間的差異（按端點百分比）：

對於約 15% 的網域，我們看到增加了 1 到 50 個端點，對於約 9% 的網域，端點數量減少了 1 到 50 個。對於約 28% 的網域，我們發現了額外 50 多個端點。

這些結果表明機器學習探索能夠發現先前沒被注意到的其他端點，從而擴展了 API Gateway 提供的工具集，幫助您的 API 環境變得有序。

完成 API 探索後，從業人員如何保護新發現的端點？我們已經查看了 API 請求中繼資料，現在讓我們看看 API 請求主體。一個 API 所有 API 端點的所有預期格式的編譯稱為 API 結構描述。API Gateway 的結構描述驗證是防範 OWASP 十大 API 攻擊的好方法，可確保請求的正文、路徑和查詢字串以預期格式包含該 API 端點的預期資訊。但是如果您不知道預期的格式，該怎麼辦？

即使客戶不知道特定 API 的結構描述，使用此 API 的用戶端也將被程式設計為主要傳送符合此未知結構描述的請求（否則它們將無法成功查詢端點）。結構描述學習利用這一事實，查看對此 API 的成功請求，以自動為客戶重建輸入結構描述。例如，API 可能期望請求中的使用者 ID 參數採用 id12345-a 形式。即使沒有明確說明這項期望，想要與 API 成功互動的用戶端也會以此格式傳送使用者 ID。

結構描述學習首先識別最近對 API 端點的所有成功請求，然後根據每個請求的位置和類型剖析不同的輸入參數。剖析所有請求後，結構描述學習會查看每個位置的不同輸入值，並確定它們具有哪些共同特徵。在驗證所有觀察到的請求都具有這些共通性後，結構描述學習會建立一個輸入結構描述，限制輸入以符合這些共通性，並且可以直接用於結構描述驗證。

為了獲得更準確的輸入結構描述，結構描述學習可以識別參數何時可以接收不同類型的輸入。假設您想要編寫一個 OpenAPIv3 結構描述檔案，並在查詢參數是 unix 時間戳記的一小部分請求樣本中進行手動觀察。您編寫一個 API 結構描述，強制該查詢參數為大於去年 unix 紀元起始點的整數。如果您的 API 也允許採用 ISO 8601 格式的該參數，則當不同格式（但有效）的參數存取 API 時，您的新規則將產生誤判。結構描述學習會自動為您完成所有這些繁重的工作，並擷取手動檢查無法擷取的內容。

為了防止誤判，結構描述學習對這些值的分佈執行統計測試，並且僅在分佈具有高置信度時才寫入結構描述。

那麼它的效果如何呢？以下是我們看到的有關參數類型和值的一些統計資料：

參數學習將略多於一半的參數分類為字串，其次是整數，幾乎佔三分之一。剩下的 17% 由陣列、布林值和數字（浮點）參數組成，而物件參數在路徑和查詢中很少見。

路徑中的參數數量通常非常少，94% 的端點在其路徑中最多看到一個參數。

對於查詢，我們確實看到了更多的參數，有時一個端點會達到 50 個不同的參數！

參數學習能夠以 99.9% 的置信度估計大多數觀察到的參數的數值限制。這些限制可以是參數的值、長度或大小的最大值/最小值，也可以是參數必須採用的一組有限的唯一值。

從今天開始，所有 API Gateway 客戶只需點擊幾下即可探索和保護 API，即使您之前沒有任何資訊。在 Cloudflare 儀表板中，按一下 API Gateway 並進入探索索引標簽，以觀察發現的端點。這些端點將立即可用，無需您執行任何動作。然後，將相關端點從「探索」新增至端點管理。結構描述學習會針對新增到端點管理的所有端點自動執行。24 小時後，匯出學習到的結構描述並將其上傳到結構描述驗證。

尚未購買 API 閘道的企業客戶可以在 Cloudflare 儀表板中啟用 API 閘道試用版或聯絡客戶經理以開始使用。

我們計劃透過支援更多格式的更多學習參數來增強結構描述學習，例如具有 JSON 和 URL 編碼格式的 POST 正文參數以及標頭和 cookie 結構描述。未來，結構描述學習也會在偵測到所識別的 API 結構描述變更時通知客戶，並提供更新的結構描述。

我們希望聽到您對這些新功能的意見反應。請將您的意見反應傳回給客戶團隊，以便我們可以優先考慮正確的改進領域。我們期待您的回音！