設定自訂規則語言屬性

每項 Google Cloud Armor 安全性政策規則都有優先順序、比對條件和動作。Cloud Armor 會對符合要求的最高優先順序規則執行動作。即使規則具有相同的比對條件，系統也不會評估優先順序低於最高優先順序比對規則的規則。

每項安全性政策規則都支援兩種比對條件：

  • 基本比對條件包含 IP 位址清單或 IP 位址範圍清單。使用 Google Cloud CLI 建立規則時，請使用 --src-ip-ranges 旗標定義基本比對條件。
  • 進階比對條件包含最多五個子運算式的運算式，可比對連入要求的各種屬性。使用 Google Cloud CLI 建立規則時，請使用 --expression 旗標定義進階比對條件。

本頁面將說明進階比對條件，以及用於在安全性政策規則的進階比對條件中編寫運算式的 Cloud Armor 自訂規則語言。Cloud Armor 自訂規則語言是一般運算語言 (CEL) 的子集。以 Cloud Armor 自訂規則語言編寫的運算式需要兩個元件：

  • 屬性：要檢查的資料
  • 運算：如何使用資料

舉例來說，下列運算式會在 inIpRange 運算中使用 origin.ip 和 198.51.100.0/24 屬性。在本範例中，如果 origin.ip 位於 198.51.100.0/24 IP 位址範圍內，運算式就會傳回 true。

inIpRange(origin.ip, '198.51.100.0/24')

即使上一個範例運算式只比對用戶端 IP 位址，在 Cloud Armor 安全性政策規則中使用該範例運算式時，從配額角度來看，該規則仍會視為具有進階比對條件的規則。詳情請參閱「Cloud Armor 配額與限制」。

作業

以下參考資料說明可搭配屬性 (以 x、y 和 k 表示) 使用的運算子，用於定義規則運算式。

作業 運算式 說明
平等 x == y 如果 x 等於 y，則傳回 true。
相等、字串常值 x == "foo" 如果 x 等於指定的常數字串常值，則傳回 true。
相等、原始字串常值 x == R"fo'o" 如果 x 等於指定的原始字串文字 (不解譯逸出序列)，則傳回 true。原始字串文字很適合用來表示本身必須使用逸出序列字元的字串。
邏輯 NOT !x 如果布林值 x 為 False，則傳回 True；如果布林值 x 為 True，則傳回 False。
不平等 x != y 如果 x 不等於 y，則傳回 true。
串連 x + y 傳回串連字串 xy。
邏輯 AND x && y 如果 x 和 y 均為 true，則傳回 true。
邏輯 OR x || y 如果 x 和/或 y 為 True，則傳回 True。
包含子字串 x.contains(y) 如果字串 x 包含子字串 y，則傳回 true。
以子字串開頭 x.startsWith(y) 如果字串 x 以子字串 y 開頭，則傳回 true。
結尾為子字串 x.endsWith(y) 如果字串 x 的結尾為子字串 y，則傳回 true。
規則運算式比對 x.matches(y) 如果字串 x 部分符合指定的 RE2 模式 y，則傳回 true。RE2 模式是以 RE2::Latin1 選項編譯，該選項會停用 Unicode 功能。
IP 位址在範圍內 inIpRange(x, y) 如果 IP 位址 x 位於 IP 範圍 y 內，則傳回 true。
小寫 x.lower() 傳回字串 x 的小寫值。
Uppercase x.upper() 傳回字串 x 的大寫值。
Base64 解碼值 x.base64Decode() 傳回 x 的 Base64 解碼值；底線 (_) 和連字號 (-) 會先分別替換為正斜線 (/) 和加號 (+)。如果 x 不是有效的 Base64 值，則傳回 "" (空字串)。
機碼對應值 m['k'] 如果鍵 k 可用，則傳回字串對應字串對映 m 中的值；否則傳回錯誤。建議先使用 "has(m['k'])==true" 檢查可用性。
在地圖中查看金鑰可用性 has(m['k']) 如果索引鍵 k 可在對應 m 中使用，則傳回 true。
轉換為整數 int(x) 將 x 的字串結果轉換為 int 型別。然後，您可以使用標準算術運算子 (例如 > 和 <=) 進行整數比較。這只適用於應為整數的值。
長度 size(x) 傳回字串 x 的長度。
解碼網址 x.urlDecode() 傳回 x 的網址解碼值。%## 格式的字元序列會替換為對應的非 ASCII 字元，+ 則會替換為空格。無效的編碼會照原樣傳回。
解碼網址 (Unicode) x.urlDecodeUni() 傳回 x 的網址解碼值。除了 urlDecode() 之外，也會處理 %u### 格式的 Unicode 字元序列。無效的編碼會照原樣傳回。
將 UTF-8 轉換為 Unicode x.utf8ToUnicode() 傳回 UTF-8 編碼 x 的小寫 Unicode 表示內容。

屬性

屬性代表來自傳入要求的資訊，例如用戶端 IP 位址或要求的網址路徑。

欄位 類型 欄位說明
origin.ip 字串 發起要求的用戶端 IP 位址。
origin.user_ip 字串 原始用戶端的 IP 位址，會由上游 Proxy 納入 HTTP-HEADER。使用這項屬性前，您必須在安全政策的 advancedOptionsConfig 欄位中設定 userIpRequestHeaders[] 選項，以比對 True-Client-IP、X-Forwarded-For 或 X-Real-IP 等來源。詳情請參閱「使用者 IP 位址總覽」。

如果未設定 userIpRequestHeaders[] 選項、設定的標頭含有無效的 IP 位址值，或設定的標頭不存在，origin.user_ip 會預設為 origin.ip。詳情請參閱 securityPolicy 資源參考資料。
origin.tls_ja4_fingerprint 字串 JA4 TLS/SSL 指紋 (如果用戶端使用 HTTPS、HTTP/2 或 HTTP/3 連線)。如果無法取得，系統會傳回空字串。
origin.tls_ja3_fingerprint 字串 JA3 TLS/SSL 指紋 (如果用戶端使用 HTTPS、HTTP/2 或 HTTP/3 連線)。如果無法取得，則會傳回空字串。
request.headers 地圖 HTTP 要求標頭的字串對字串對應。如果標頭含有多個值，這項對應中的值會是以半形逗號分隔的字串，當中包含標頭的所有值。這項對應中的鍵都是小寫。系統會檢查外部應用程式負載平衡器接受的所有標頭，並套用相同的標頭限制。

建議先使用 has() 檢查可用性，例如 has(request.headers['header-key']) && request.headers['header-key'] != 'header-value'。
request.method 字串 HTTP 要求方法。
request.path 字串 要求的 HTTP 網址路徑。撰寫規則時，如果符合 request.path，建議您將路徑正規化，以便在網址編碼、大小寫變化或反斜線的情況下，簡化比對語法。如需更多資訊和範例，請參閱路徑遍歷和正規化。
request.scheme 字串 HTTP 網址配置，例如 http 或 https。這個屬性的值一律為小寫。
request.query 字串 HTTP 網址查詢，格式為 name1=value&name2=value2，如 HTTP 要求的第一行所示。未執行任何解碼作業。
origin.region_code 字串 與用戶端 IP 相關聯的 Unicode 國家/地區代碼，例如 US。如果您要建立使用 ISO 3166-1 alpha 2 國家/地區代碼的規則或運算式，Cloud Armor 會個別處理每個代碼。Cloud Armor 規則和運算式會明確使用這些區域代碼，允許或拒絕要求。
origin.asn 整數 與用戶端 IP 位址相關聯的自治系統編號 (ASN)。系統會根據支援含有用戶端 IP 位址的 IP 位址前置字元的網路業者，判斷全球唯一的 ASN。

reCAPTCHA 屬性

本節列出的屬性僅適用於 reCAPTCHA 權杖或豁免 Cookie。如果待評估的 reCAPTCHA 權杖或豁免 Cookie 無效，或因下列其中一個原因而無法使用，根據這些屬性的子運算式就會傳回 false：

  • 權杖格式錯誤，無法解碼。
  • 權杖含有無效屬性。舉例來說，權杖是使用與規則相關聯的 reCAPTCHA 金鑰不符的 reCAPTCHA 金鑰產生。
  • 權杖已過期。
欄位 類型 欄位說明
token.recaptcha_exemption.valid bool 存在有效的 reCAPTCHA 豁免 Cookie。

動作符記屬性

欄位 類型 欄位說明
token.recaptcha_action.score float reCAPTCHA 動作權杖的分數。有效分數範圍為 0.0 到 1.0，其中 0.0 代表使用者極有可能為非法使用者，1.0 則代表使用者極有可能為合法使用者。
token.recaptcha_action.captcha_status string reCAPTCHA 動作權杖的驗證碼狀態。有效狀態為 NONE、