建立及查看 Cloud Armor 安全性政策規則

每項 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 配額與限制」。

建立安全性政策規則

請按照本節中的步驟，將規則新增至 Cloud Armor 安全性政策。

控制台

1. 前往 Google Cloud 控制台的「Cloud Armor policies」(Cloud Armor 政策) 頁面。

   前往「Cloud Armor policies」(Cloud Armor 政策)

2. 按一下安全性政策名稱，開啟「Policy details」(政策詳細資料) 頁面，然後按一下「Rules」(規則) 分頁標籤。

3. 按一下「Add rule」(新增規則)。

4. 選用：輸入規則說明。

5. 選取模式：

   • 基本模式：根據 IP 位址或 IP 範圍允許或拒絕流量。
   • 進階模式：根據規則運算式允許或拒絕流量。

6. 在「Match」(比對) 欄位中，指定規則適用的條件：

   • 基本模式：輸入 1 到 10 個 IP 位址範圍，用於比對規則。最多可新增 10 個 IP 位址範圍。如要瞭解限制，請參閱「Cloud Armor 配額與限制」。

   • 進階模式：

     • 比對條件建構工具 (預先發布版)：使用視覺化建構工具建立運算式，不必編寫原始 CEL 程式碼。合併及分組條件，以及套用字串轉換。請參閱「使用比對條件建構工具」。
     • 比對條件編輯器：輸入運算式，用於評估傳入的要求。詳情請參閱「作業」和「屬性」。

7. 在「Action」(動作) 清單中，選取「Allow」(允許) 或「Deny」(拒絕)。

8. 如果您要設定拒絕規則，請在「Response code」(回應代碼) 清單中選取回應代碼。

9. 如要啟用規則的預覽模式，請選取「啟用」。

10. 在「Priority」(優先順序) 欄位中，輸入介於 0 至 2,147,483,646 之間的整數。Cloud Armor 會依優先順序評估規則，從 0 (最高) 到 2,147,483,647 (最低)。預設規則的優先順序為 2,147,483,647。

11. 按一下「新增」。

gcloud

使用 gcloud compute security-policies rules create PRIORITY 指令。將 PRIORITY 替換為政策中規則的優先順序：

gcloud compute security-policies rules create PRIORITY \
    --security-policy POLICY_NAME \
    --description DESCRIPTION \
    --src-ip-ranges IP_RANGES | --expression EXPRESSION \
    --action=[ allow | deny-403 | deny-404 | deny-502 ] \
    --preview

舉例來說，下列指令會新增優先順序為 1000 的規則，封鎖來自 IP 位址範圍 192.0.2.0/24 和 198.51.100.0/24 的流量：

gcloud compute security-policies rules create 1000 \
    --security-policy my-policy \
    --description "block traffic from 192.0.2.0/24 and 198.51.100.0/24" \
    --src-ip-ranges "192.0.2.0/24","198.51.100.0/24" \
    --action "deny-403"

使用 --expression 旗標指定條件。下列指令會新增規則，允許來自 IP 位址 1.2.3.4 且 User-Agent 標頭中包含字串 example 的流量：

gcloud compute security-policies rules create 1000 \
    --security-policy my-policy \
    --expression "inIpRange(origin.ip, '1.2.3.4/32') && has(request.headers['user-agent']) && request.headers['user-agent'].contains('example')" \
    --action allow \
    --description "Block User-Agent 'example'"

下列指令會新增一項規則，在要求 Cookie 含有特定值時封鎖要求：

gcloud compute security-policies rules create 1000 \
    --security-policy my-policy \
    --expression "has(request.headers['cookie']) && request.headers['cookie'].contains('80=SomeValue')" \
    --action deny-403 \
    --description "Cookie Block"

下列指令會新增規則，封鎖來自 AU 區域的要求：

gcloud compute security-policies rules create 1000 \
    --security-policy my-policy \
    --expression "origin.region_code == 'AU'" \
    --action deny-403 \
    --description "AU block"

下列指令會新增規則，封鎖來自 AU 區域且不在指定 IP 範圍內的要求：

gcloud compute security-policies rules create 1000 \
    --security-policy my-policy \
    --expression "origin.region_code == \"AU\" && !inIpRange(origin.ip, '1.2.3.0/24')" \
    --action deny-403 \
    --description "country and IP block"

下列指令會新增規則，封鎖 URI 符合規則運算式的要求：

gcloud compute security-policies rules create 1000 \
    --security-policy my-policy \
    --expression "request.path.matches('/example_path/')" \
    --action deny-502 \
    --description "regex block"

下列指令會新增規則，如果 user-id 標頭的 Base64 解碼值包含特定值，就會封鎖要求：

gcloud compute security-policies rules create 1000 \
    --security-policy my-policy \
    --expression "has(request.headers['user-id']) && request.headers['user-id'].base64Decode().contains('myValue')" \
    --action deny-403 \
    --description "country and IP block"

下列指令會新增一項規則，使用 OWASP 核心規則集 (CRS) 4.22 的預先設定運算式集，防範 SQL 注入 (SQLi) 攻擊：

gcloud compute security-policies rules create 1000 \
    --security-policy my-policy \
    --expression "evaluatePreconfiguredWaf('sqli-v422-stable')" \
    --action deny-403

使用比對條件建構工具

預覽

這項產品或功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

比對條件建構工具是 Google Cloud 控制台中的視覺化介面，可協助您建立複雜的 Cloud Armor 規則運算式，不必編寫一般運算語言 (CEL) 程式碼。您不必編寫程式碼，只要使用建構工具的結構化 UI，即可結合條件和群組邏輯，避免語法錯誤，並更清楚地呈現規則結構。建立工具支援平面清單和巢狀邏輯，最多可達五個運算式層級。設定規則時，請使用這項工具，協助保護多雲端後端或混合式部署，您可能需要在轉送流量前檢查特定要求屬性。

比對條件建構工具的功能

比對條件建構工具包含下列功能：

• 邏輯和巢狀結構：使用 AND 和 OR 運算子合併多個條件。建構工具支援分組和巢狀結構，最多可達五個運算式。
• 字串轉換：如果是字串屬性 (例如 request.path 或 request.headers)，請先套用轉換，將資料標準化後再進行評估。支援的轉換包括：
  • 大小寫
  • Base64 解碼
  • 網址解碼和網址解碼 (Unicode)
  • UTF-8 轉換為 Unicode
• 雙向剖析：在視覺化「比對條件建構工具」和原始文字「比對條件編輯器」之間切換。使用者介面會自動將原始 CEL 程式碼剖析為視覺化區塊。
• 函式支援：建構工具提供函式型運算式的 UI 控制項，例如預先設定的 WAF 規則、位址群組和威脅情報。

限制

比對條件建構工具是建立進階規則的預設介面。如果運算式包含不支援的邏輯 (例如未知的巨集)，建構工具就會停用。在這種情況下，請使用「Match condition editor」(比對條件編輯器) 中的原始文字編輯規則。

此外，建構工具中是否提供特定運算式，取決於專案的 Google Cloud Armor Enterprise 級別和安全性政策類型。

運算式範例

以下是運算式範例。如要進一步瞭解支援的作業和屬性，請參閱「作業」和「屬性」。

如果規則或運算式使用 ISO 3166-1 alpha-2 國家/地區代碼，Cloud Armor 會獨立處理每個代碼。Cloud Armor 規則和運算式會使用這些代碼來允許或拒絕要求。

• 下列運算式會比對來自 IP 位址 1.2.3.4 的要求，且 User-Agent 標頭中包含 example 字串：

  inIpRange(origin.ip, '1.2.3.4/32') && has(request.headers['user-agent']) && request.headers['user-agent'].contains('example')
  

  或者，您也可以使用 origin.user_ip 屬性，比對自訂用戶端 IP 位址標頭的 IP 位址範圍：

  inIpRange(origin.user_ip, '1.2.3.4/32') && has(request.headers['user-agent']) && request.headers['user-agent'].contains('example')
  

• 下列運算式會比對含有特定值 Cookie 的要求：

  has(request.headers['cookie']) && request.headers['cookie'].contains('cookie_name=cookie_value')
  

• 下列運算式會比對來自 AU 區域的要求：

  origin.region_code == 'AU'
  

• 下列運算式會比對來自 AU 區域，且不在指定 IP 範圍內的要求：

  origin.region_code == "AU" && !inIpRange(origin.ip, '1.2.3.0/24')
  

• 如果 URI 符合規則運算式，下列運算式會比對具有編號變數路徑的要求，並指向特定檔案：

  request.path.matches('/path/[0-9]+/target_file.html')
  

• 如果 user-id 標頭的 Base64 解碼值包含特定值，下列運算式會比對要求：

  has(request.headers['user-id']) && request.headers['user-id'].base64Decode().contains('myValue')
  

• 下列運算式使用 OWASP CRS 4.22 規則集預先設定的運算式集，比對 SQLi 攻擊：

  evaluatePreconfiguredWaf('sqli-v422-stable')
  

路徑遍歷和正規化

正規化路徑規則中的內容，管理路徑遍歷和編碼規則，並建立一般化規則，避免大小寫或內容專屬編碼。

編寫規則時，如果使用 startsWith、endsWith 或 contains 比對 request.path，請使用 lower 和 urlDecode 正規化路徑，再進行比對。這有助於防止使用網址編碼或大小寫變化版本繞過限制。

舉例來說，如要禁止存取 /admin 目錄，請使用下列運算式：

request.path.lower().urlDecode().startsWith('/admin')

這項規則會封鎖 /admin、/Admin、/a%64min 和其他變化版本的請求。

編寫規則時，如果使用 matches 比對 request.path，請在規則運算式中加入反斜線字元 (\)。

舉例來說，如要封鎖對 /admin 目錄的存取，請使用下列運算式，封鎖使用反斜線字元 (\) 的略過行為：

request.path.matches(r'^/\\*admin')

搭配使用 urlDecode，即可同時處理網址編碼和反斜線字元 (\) 略過：

request.path.urlDecode().matches(r'^/\\*admin')

查看安全性政策規則

以下各節說明如何列出安全性政策中設定的規則，以及查看可用的預先設定 WAF 規則。

列出安全性政策中的規則

請按照本節中的步驟，列出 Cloud Armor 安全性政策中的規則。

控制台

1. 前往 Google Cloud 控制台的「Cloud Armor policies」(Cloud Armor 政策) 頁面。

   前往「Cloud Armor policies」(Cloud Armor 政策)

2. 按一下特定安全性政策的名稱。「Policy details」(政策詳細資料) 頁面的「Rules」(規則) 分頁會顯示政策規則。

gcloud

使用下列 gcloud 指令，列出安全性政策中的所有規則：

gcloud compute security-policies describe NAME

使用下列 gcloud 指令，列出指定區域中單一安全性政策的所有規則，以及政策說明：

gcloud compute security-policies describe NAME \
  --region REGION

使用下列 gcloud 指令說明規則：

gcloud compute security-policies rules describe PRIORITY \
    --security-policy POLICY_NAME

舉例來說，下列指令會說明安全性政策 my-policy 中優先順序為 1000 的規則：

gcloud compute security-policies rules describe 1000 \
    --security-policy my-policy

輸出內容：

action: deny(403)
description: block traffic from 192.0.2.0/24 and 198.51.100.0/24
kind: compute#securityPolicyRule
match:
  srcIpRanges:
  - '192.0.2.0/24'
  - '198.51.100.0/24'
preview: false
priority: 1000

詳情請參閱「gcloud compute security-policies describe」。

列出可用的預先設定規則

除了自行設定規則外，您也可以在安全性政策中使用 Cloud Armor 預先設定的規則。您可以列出預先設定的規則，查看 Cloud Armor 提供的預先定義應用程式保護規則和簽章，例如 OWASP 核心規則集 (CRS)。這些規則包含內建簽章，Cloud Armor 會根據這些簽章評估傳入的要求。您可以使用自訂規則語言，將這些預先設定的規則新增至新規則或現有規則。建議您盡可能使用最新版的 CRS 規則。

gcloud

1. 執行 gcloud compute security-policies list-preconfigured-expression-sets 指令：

   gcloud compute security-policies list-preconfigured-expression-sets
   

   以下範例顯示指令的輸出格式：

   EXPRESSION_SET
   expression-set-1
      RULE_ID                SENSITIVITY
      expression-set-1-id-1  sensitivity-value-1
      expression-set-1-id-2  sensitivity-value-2
   expression-set-2
      alias-1
      RULE_ID                SENSITIVITY
      expression-set-2-id-1  sensitivity-value-1
      expression-set-2-id-2  sensitivity-value-2
   

   以下範例包含指令實際輸出的範例。請注意，實際輸出內容包含「調整 Cloud Armor WAF 規則」中列出的所有規則。

   gcloud compute security-policies list-preconfigured-expression-sets
   

   EXPRESSION_SET
   sqli-canary
       RULE_ID                          SENSITIVITY
       owasp-crs-v042200-id942120-sqli  2
       …
   xss-canary
       RULE_ID                         SENSITIVITY
       owasp-crs-v042200-id941110-xss  1
       owasp-crs-v042200-id941120-xss  2
   …
   sourceiplist-fastly
   sourceiplist-cloudflare
   sourceiplist-imperva
   

作業

下列參考資料說明可與屬性 (以 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 中鍵 k 的值；否則傳回錯誤。建議您先使用 "has(m['k'])==true" 檢查可用性。
查看地圖中的金鑰可用性	has(m['k'])	如果對應 m 中有鍵 k，則傳回 true。
轉換為整數	int(x)	將 x 的字串結果轉換為 int 類型。接著，您可以使用標準算術運算子 (例如 > 和 <=) 進行整數比較。這項功能僅適用於應為整數的值。
長度	size(x)	傳回字串 x 的長度。
解碼網址	x.urlDecode()	傳回 x 的網址解碼值。%## 格式的字元序列會替換為對應的非 ASCII 字元，+ 則會替換為空格。無效的編碼會照原樣傳回。
解碼網址 (Unicode)	x.urlDecodeUni()	傳回 x 的網址解碼值。除了 urlDecode() 之外，也會處理 %u### 格式的 Unicode 字元序列。無效的編碼會照原樣傳回。
將 utf8 轉換為 Unicode	x.utf8ToUnicode()	傳回 UTF-8 編碼 x 的小寫 Unicode 表示內容。
已存在	m.exists(k, expr)	如果對應 m 中至少有一個項目符合 expr，則傳回 true，其中 k 代表每個對應項目的鍵。 注意：只有在規則運算式中存在 request.body 或 request.params 時，這個運算子才會生效。
已存在一個	m.exists_one(k, expr)	如果對應 m 中只有一個項目符合 expr，則傳回 true，其中 k 代表每個對應項目的鍵。 注意：只有在規則運算式中存在 request.body 或 request.params 時，這個運算子才會生效。
全部	m.all(k, expr)	如果對應 m 中的所有項目都符合 expr，則傳回 true，其中 k 代表每個對應項目的鍵。 注意：只有在規則運算式中存在 request.body 或 request.params 時，這個運算子才會生效。
篩選器	m.filter(k, expr)	傳回僅包含對應 m 中項目的對應，其中項目滿足 expr，其中 k 代表每個對應項目的鍵。 注意：只有在規則運算式中存在 request.body 或 request.params 時，這個運算子才會生效。
地圖	m.map(k, expr)	傳回一份清單，其中包含對應 m 中每個鍵的 expr 評估結果，其中 k 代表每個對應項目的鍵。 注意：只有在規則運算式中存在 request.body 或 request.params 時，這個運算子才會生效。

注意：CEL 邏輯運算子的優先順序為 NOT、AND 和 OR。您可以使用括號覆寫這個順序。詳情請參閱「語法」。

注意：只有在規則運算式中存在 request.body 或 request.params 時，對應疊代運算子 (m.exists、m.exists_one、m.all、m.filter 和 m.map) 才會運作。

屬性

屬性代表傳入要求中的資訊，例如用戶端 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	字串	如果用戶端使用 HTTPS、HTTP/2 或 HTTP/3 連線，則為 JA4 TLS/SSL 指紋。如果無法取得，則會傳回空白字串。
origin.tls_ja3_fingerprint	字串	如果用戶端使用 HTTPS、HTTP/2 或 HTTP/3 連線，則為 JA3 TLS/SSL 指紋。如果無法取得，則會傳回空白字串。
request.headers	地圖	HTTP 要求標頭的字串/字串對應，如果標頭有多個值，這項對應中的對應值會是單一字串，當中包含所有值，並以半形逗號分隔。這項對應中的鍵都是小寫。外部應用程式負載平衡器會檢查所有接受的標頭，且適用相同的標頭限制。 使用 has() 檢查是否可用，例如 has(request.headers['header-key']) && request.headers['header-key'] != 'header-value'。 您可以疊代對應，檢查鍵和值。不過，您只能在 request.headers 上使用對應疊代運算子 (exists()、exists_one()、all()、filter() 和 map())，並在同一個運算式中與 request.body 或 request.params 搭配使用，例如 request.body && request.headers.exists(k, k.lower().startsWith('header-prefix'))。
request.body	字串	以原始字串表示要求主體。可代表任何 Content-Type 的資料。它會將內容儲存為字串，不會自動剖析。
request.params	地圖	附加至網址或包含在要求主體中的鍵/值組合對應。 URI 要求：name1=value1&name2=value2 含有 Content-Type: application/json 的 JSON 要求主體： { "username": "johndoe", "email": "[e-mail]" } 含有 Content-Type: application/graphql 的 GraphQL POST 要求主體： { Username: "exampleUser", query: "/* other fields */" } 含有 Content-Type: application/x-www-form-urlencoded 的表單 POST 要求主體： "username=exampleUser&email=johndoe%40example.com"
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)。全域專屬 ASN 的判斷依據，是支援 IP 位址前置字元 (包含用戶端 IP 位址) 的網路營運商。

注意：邊緣安全性政策僅支援根據 origin.asn、origin.ip、origin.region_code、request.headers、request.method、request.path、request.query 和 request.scheme 進行篩選。

reCAPTCHA 屬性

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

• 權杖格式錯誤，無法解碼。
• 權杖含有無效屬性。例如，產生權杖時使用的 reCAPTCHA 金鑰，與規則相關聯的 reCAPTCHA 金鑰不符。
• 權杖已過期。

豁免 Cookie 屬性

欄位	類型	欄位說明
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、PASS 或 FAIL，其中 NONE 是指 reCAPTCHA 評估期間未涉及任何驗證問題，因此動作權杖中缺少驗證碼欄位。
token.recaptcha_action.action	string	reCAPTCHA 動作權杖的動作名稱 (最多 100 個字元)。 請參閱「動作名稱」。
token.recaptcha_action.valid	bool	有效的 reCAPTCHA 動作權杖。

工作階段符記屬性

欄位	類型	欄位說明
token.recaptcha_session.score	float	reCAPTCHA 工作階段權杖的分數。有效分數介於 0.0 到 1.0 之間，0.0 表示極可能是不合法的使用者，1.0 則表示極可能是合法的使用者。
token.recaptcha_session.valid	bool	是否有有效的 reCAPTCHA 工作階段符記。

運算式範例

對於上述每個運算式，系統會根據運算式包含在拒絕規則或允許規則中，採取相應動作。

根據 IPv4 或 IPv6 的 IP 位址範圍，允許或拒絕存取

• 下列運算式會比對來自 198.51.100.0/24 IP 位址範圍的要求：

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

• 下列運算式會比對來自 2001:db8::/32 IP 位址範圍的要求：

  inIpRange(origin.ip, '2001:db8::/32')
  

根據上游 Proxy 後方的自訂用戶端 IP 位址範圍，允許或拒絕存取

如果您已設定 origin.user_ip 運算子，可以根據 advancedOptionsConfig.userIpRequestHeaders[] 欄位中指定的標頭值進行比對。

• 下列運算式會比對源自 192.0.2.0/24 IP 位址範圍的要求：

  inIpRange(origin.user_ip, '192.0.2.0/24')
  

• 下列運算式會比對源自 2001:db8::/32 IP 位址範圍的要求：

  inIpRange(origin.user_ip, '2001:db8::/32')
  

允許或拒絕含有特定 Cookie 的流量

• 下列運算式會比對含有 80=BLAH 的 Cookie 要求：

  has(request.headers['cookie']) && request.headers['cookie'].contains('80=BLAH')
  

允許或拒絕含有非空白 referer 標頭的流量

• 下列運算式會比對 referer 標頭不為空白的要求：

  has(request.headers['referer']) && request.headers['referer'] != ""
  

根據主機標頭允許或拒絕流量

您可以根據要求中 Host 標頭的值，允許或拒絕流量。

• 下列運算式會使用 == 比對特定網址的要求：

  request.headers['host'].lower() == 'test.example.com'
  

• 下列運算式會使用 endsWith 比對特定網址的要求：

  request.headers['host'].lower().endsWith('.example.com')
  

• 下列運算式會使用 contains 比對特定網址的要求：

  request.headers['host'].lower().contains('test.example.com')
  

注意：如要比對特定主機，請使用 ==；如要比對包含特定子字串的主機，請使用 contains。請謹慎使用 contains，以免發生非預期的比對結果。詳情請參閱「作業」。

• 下列運算式會比對使用 contains 傳送至多個網域的要求：

  request.headers['host'].lower().contains('test.example.com') || request.headers['host'].lower().contains('test22.example.com')
  

• 下列運算式會使用 matches 比對網域及其子網域的要求：

  request.headers['host'].matches('(?i:(?:sub\.)?test\.example\.com)')
  

允許或拒絕來自特定區域的流量

如果您的網頁應用程式不適用於 AU 區域，則必須封鎖來自該區域的所有要求。

• 在拒絕規則中，使用下列運算式，比對來自 AU 區域的要求：

  origin.region_code == 'AU'
  

或者，如果您的網頁應用程式「僅」在 AU 區域提供，則必須封鎖來自所有其他區域的要求。

• 在拒絕規則中，使用下列運算式，比對來自 AU 區域以外所有區域的要求：

  origin.region_code != 'AU'
  

區域代碼採用 ISO 3166-1 alpha 2 代碼。在某些情況下，區域會對應至國家/地區，但並非總是如此。例如，US 代碼包含美國所有州、一個特區和六個外圍地區。

允許或拒絕來自特定 ASN 的流量

如果網頁應用程式需要封鎖特定網路營運商服務的客戶，您可以使用網路營運商的 ASN 號碼進行封鎖。

• 在拒絕規則中，使用下列運算式比對特定 ASN 的要求：

  origin.asn == 123
  

或者，如果您的網頁應用程式「僅」提供給特定網路營運商的客戶，則必須封鎖來自所有其他網路營運商的要求。

• 在拒絕規則中，使用下列運算式，比對您想允許的網路運算子以外的所有其他網路運算子：

  origin.asn != 123
  

多個運算式

如要在單一規則中加入多個條件，請合併多個子運算式。

• 在以下範例中，AU 區域中 1.2.3.0/24 (例如 Alpha 版測試人員) 的要求符合下列運算式：

  origin.region_code == "AU" && inIpRange(origin.ip, '1.2.3.0/24')
  

• 下列運算式會比對來自 1.2.3.4 的要求，其中使用者代理程式包含字串 WordPress：

  inIpRange(origin.ip, '1.2.3.4/32') &&
  has(request.headers['user-agent']) && request.headers['user-agent'].contains('WordPress')
  

允許或拒絕與規則運算式相符的要求 URI 流量

• 下列運算式會比對 URI 中包含 /example_path/ 字串的要求：

  request.path.matches('/example_path/')
  

• 下列運算式會比對 User-Agent 標頭欄位中含有 Chrome 的要求：

  request.headers['user-agent'].matches('Chrome')
  

• 下列運算式會針對包含 wordpress 的 User-Agent 標頭進行不區分大小寫的比對，並與 User-Agent:WordPress/605.1.15、User-Agent:wordPress 和 wordpress 的其他變化版本比對：

  request.headers['user-agent'].matches('(?i:wordpress)')
  

允許或拒絕含有特定 base64 解碼值的流量

• 下列運算式會比對 user-id 標頭的 base64 解碼值為 myValue 的要求：

  has(request.headers['user-id']) && request.headers['user-id'].base64Decode().contains('myValue')
  

允許或拒絕含有特定長度字串值的流量

• 下列運算式會比對網址長度超過 10 個字元的要求：

  size(request.path) > 10
  

• 下列運算式會比對標頭 x-data 長度大於或等於 1024 個字元的要求：

  size(request.headers['x-data']) >= 1024
  

允許或拒絕 HTTP 主體中含有零個 content-length 的流量

• 下列運算式會比對 HTTP 主體中 content-length 為零的要求：

  int(request.headers["content-length"]) == 0
  

允許或拒絕含有特定網址編碼值的流量

• 下列運算式會比對 Cookie 值包含 %3c 的要求：

  has(request.headers['cookie']) && request.headers['cookie'].urlDecode().contains('<')
  

允許或拒絕含有特定網址編碼值 (Unicode 字串) 的流量

• 下列運算式會比對 Cookie 值等於 Match%2BValue 或 Match%u002BValue 的要求：

  has(request.headers['cookie']) && request.headers['cookie'].urlDecodeUni() == 'Match+Value'
  

允許或拒絕含有 UTF-8 文字特定 Unicode 字串的流量

• 下列運算式會比對 Cookie 值等於 ¬ 的要求：

  has(request.headers['cookie']) && request.headers['cookie'].utf8ToUnicode() == '%u00ac'
  

根據已知的 JA4 指紋，允許或拒絕流量

• 下列運算式會比對 JA4 指紋等於 t13d1516h2_8daaf6152771_b186095e22b6 的要求：

  origin.tls_ja4_fingerprint == 't13d1516h2_8daaf6152771_b186095e22b6'
  

根據 JA4 指紋清單允許或拒絕流量

• 下列運算式會比對 JA4 指紋等於下列任一 JA4 指紋的要求：

  • t00d0000h0_000000000000_000000000000
  • t13d1516h2_8daaf6152771_b186095e22b6

  origin.tls_ja4_fingerprint == 't00d0000h0_000000000000_000000000000' || origin.tls_ja4_fingerprint == 't13d1516h2_8daaf6152771_b186095e22b6'
  

根據要求主體內容允許或拒絕流量

• 下列運算式會比對要求主體中包含 malicious-value 的 POST 要求：

  request.method == 'POST' && request.body.contains('malicious-value')
  

• 下列運算式會比對開頭為 <!DOCTYPE html> 的要求：

  request.body.startsWith('<!DOCTYPE html>')
  

• 下列運算式會比對主體符合規則運算式 \w+@\w+.com 的要求：

  request.body.matches('\w+@\w+.com')
  

根據要求參數允許或拒絕流量

• 下列運算式會比對不含 category 參數的要求：

  !has(request.params.category)
  

• 下列運算式會比對 category 參數為 electronics 的要求：

  request.params.category == 'electronics'
  

• 下列運算式會比對所有參數值皆非空白的要求：

  request.params.all(k, request.params[k] != '')
  

• 下列運算式會比對任何參數包含 admin 字串的要求：

  request.params.exists(k, request.params[k].contains('admin'))
  

• 下列運算式會比對只有一個參數名稱包含 admin 的要求：

  request.params.exists_one(k, k.contains('admin'))
  

• 下列運算式會比對至少有一個參數名稱包含 id 的要求：

  size(request.params.filter(k, k.contains('id'))) > 0
  

• 下列運算式會比對參數值包含字串 admin 的要求：

  request.params.map(k, request.params[k]).contains('admin')
  

根據要求主體中的結構化資料，允許或拒絕流量

• 下列運算式會比對 JSON 要求主體中 password 欄位包含 123 的要求：

  has(request.params.password) && request.params.password.contains('123')
  

• 下列運算式會比對表單資料中 city 欄位為 NewYork 的要求：

  has(request.params.city) && request.params.city == 'NewYork'
  

• 下列運算式會比對巢狀 newsletter 欄位為 true 的要求：

  has(request.params.preferences) && has(request.params.preferences.newsletter) && request.params.preferences.newsletter == true
  

• 下列運算式會比對 friends 陣列中第一個元素的 name 欄位為 johndoe 的要求：

  request.params['friends'][0]['name'] == 'johndoe'
  

預先設定的 WAF 規則

預先設定的 WAF 規則會使用預先設定的靜態簽章、規則運算式或兩者，比對 HTTP 要求主體、HTTP 要求標頭和查詢參數。可用的預先設定 WAF 規則是以 OWASP 核心規則集 4.22 為基礎。Cloud Armor 提供多項預先定義且預先設定的 WAF 規則。如需預先設定 WAF 規則的完整清單，請參閱「Cloud Armor 預先設定 WAF 規則總覽」。

如要列出所有可用的預先設定 WAF 規則，請參閱「列出可用的預先設定 WAF 規則」。

如要進一步瞭解預先設定的 WAF 規則，請參閱「使用預先設定的 WAF 規則緩解應用程式層攻擊」一文。

預先設定的 WAF 規則名稱

預先設定的 WAF 規則名稱格式為 <attack category>-<OWASP CRS version>-<version field>。攻擊類別會指定您要防範的攻擊類型，例如 xss (跨網站指令碼攻擊) 或 sqli (SQL 注入)。

支援的版本欄位為 stable 和 canary。規則的新增和修改內容會先在 canary 版本中發布。當新增和修改內容被視為安全且穩定時，就會升級至 stable 版本。

預先設定的 WAF 規則成員 ID

預先設定的 WAF 規則包含多個運算式，每個運算式都有其簽章。舉例來說，預先設定的 WAF 規則 xss-v422-stable 包含名為 owasp-crs-v042200-id941100-xss 的運算式，對應至 4.22 版的規則 ID id941100。您可以使用簽章排除特定運算式，如果特定運算式持續觸發偽陽性，這項功能就非常實用。詳情請參閱偽陽性疑難排解資訊。

如要瞭解核心規則集和不同敏感度層級的調整，請參閱「調整 Cloud Armor WAF 規則」。

預先設定 WAF 規則的運算子

運算式	說明
evaluatePreconfiguredWaf(string, MAP<string, dyn>)	如果指定 WAF 規則集內的任何 WAF 簽章傳回 true，則傳回 true。第一個引數是 WAF 規則集的名稱，例如 xss-v422-stable。第二個引數 (選用) 是對應，其中鍵是字串，值則會根據鍵動態輸入。這個引數的用途是微調要評估的 WAF 簽章。可接受的鍵包括： sensitivity：這對應 OWASP 核心規則集的偏執等級，共有 4 個等級，範圍從 1 到 4。這個值是整數，有效範圍為 0 到 4。請注意，與 opt_in_rule_ids (後文說明) 搭配使用時，0 是保留的有效值。指定敏感度 x (x >= 1) 時，系統會評估所有敏感度值介於 1 到 x 的相關聯 WAF 簽章。如果省略，系統會使用 4 做為敏感度值。 opt_out_rule_ids：要從評估中排除的 WAF 簽章 (以規則 ID 表示)，其中基本組合由機密程度值決定。其值為字串清單。規則 ID 數量上限為 128 個。 opt_in_rule_ids：要選擇加入評估的 WAF 簽章 (以規則 ID 表示)，其中基本組合為空白。其值為字串清單。規則 ID 數量上限為 128 個。使用這項功能時，必須指定 0 的 sensitivity。 opt_out_rule_ids 和 opt_in_rule_ids 鍵互斥。如果您想查看並手動選擇加入日後新增至現有規則集的 WAF 簽章，可以選擇使用 opt_in_rule_ids。
evaluatePreconfiguredWaf(string, LIST)	注意：evaluatePreconfiguredExpr() 已淘汰。建議您改用 evaluatePreconfiguredWaf()。 如果指定預先設定 WAF 規則中的任何運算式傳回 true，則傳回 true。 第一個引數是預先設定的 WAF 規則名稱，例如 xss-stable。第二個引數 (選用) 是以半形逗號分隔的字串清單，列出必須從評估中排除的 ID。如果預先設定的 WAF 規則中，有特定成員觸發偽陽性，排除清單就派得上用場。

預先設定的 WAF 規則範例

• 下列運算式使用 xss-v422-stable 預先設定的 WAF 規則，緩解 XSS 攻擊：

  evaluatePreconfiguredWaf('xss-v422-stable')
  

• 下列運算式會使用 xss-v422-stable 預先設定 WAF 規則中的所有運算式，但排除會員 ID 941100 和 941110：

  evaluatePreconfiguredWaf('xss-v422-stable', {'opt_out_rule_ids': ['owasp-crs-v042200-id941100-xss',
  'owasp-crs-v042200-id941110-xss']})
  

• 下列運算式使用預先設定的 WAF 規則，緩解來自 198.51.100.0/24 IP 位址範圍的 SQLi 攻擊：

  inIpRange(origin.ip, '198.51.100.0/24') && evaluatePreconfiguredWaf('sqli-v422-stable')
  

• 下列運算式使用 xss-v422-stable 預先設定的 WAF 規則，針對傳送至 example.com 的要求，緩解 XSS 攻擊，但不包括開頭為 /login/api/ 的路徑：

  request.headers['host'].lower() == 'example.com' && !request.path.startswith('/login/api/') && evaluatePreconfiguredWaf('xss-v422-stable')
  

代管規則

Google Cloud Armor 代管規則會自動更新安全性簽章，保護網頁應用程式和 API 端點。代管規則由 Thales Imperva 提供，並直接整合至 Cloud Armor，可簡化資安營運。代管規則可免除手動更新簽章的需求，並減少設定偏移，讓資安團隊專注於開發和營運。

代管規則的運算子

運算式

說明

evaluateManagedRules(string, MAP<string, dyn>)

如果指定代管規則中的任何簽章傳回 true，則傳回 true。第一個引數是類別的完整名稱，例如 google:xss:stable 或 google:sqli:canary。第二個引數 (選用) 是對應，其中鍵是字串，值則會根據鍵動態輸入。可接受的鍵包括： opt_in_rule_ids：對應規則集中的規則 ID 清單，只有這些規則會接受評估。例如：evaluateManagedRules('google:xss:canary', {'opt_in_rule_ids': ['google-xss-8057544707029182464']})。 opt_out_rule_ids：對應規則集中不列入評估的規則 ID 清單。例如：evaluateManagedRules('google:xss:canary', {'opt_out_rule_ids': ['google-xss-8057544707029182464']})。

代管規則範例

• 下列運算式使用穩定的 SQL 注入 (sqli) 代管規則，協助防範 SQLi 攻擊：

  evaluateManagedRules('google:sqli:stable')
  

• 只有在要求具有主機 example.com 時，下列運算式才會使用穩定的 xss 代管規則：

  request.headers['host'].lower() == 'example.com' && evaluateManagedRules('google:xss:stable')
  

其他運算子

運算式	說明
evaluateThreatIntelligence(string) evaluateThreatIntelligence(string, LIST) evaluateThreatIntelligence(string, string, LIST)	如果用戶端 IP 位址與指定 IP 清單中的任何 IP 範圍相符，則傳回 true，除非已明確列入排除清單。 第一個引數是 Google Threat Intelligence 動態饋給名稱，例如 iplist-known-malicious-ips。如果第二個引數是字串 (選用)，則會決定 IP 位址的擷取來源，可以是 origin.ip、origin.user_ip 或特定標頭名稱。如果第二或第三個引數 (選用) 是以半形逗號分隔的字串清單，且每個字串都是 IP 位址或 CIDR 範圍，則會從評估中排除。如果動態饋給包含會觸發偽陽性的 IP 位址，排除清單就非常實用。 注意：使用 origin.user_ip 時，您必須在安全性政策的 advancedOptionsConfig 欄位中設定 userIpRequestHeaders[] 選項。
evaluateAddressGroup(string, string) evaluateAddressGroup(string, string, LIST) evaluateOrganizationAddressGroup(string, string) evaluateOrganizationAddressGroup(string, string, LIST)	如果用戶端 IP 位址與指定位址群組中的任何 IP 範圍相符，則傳回 true，除非已明確列入排除清單。 第一個引數是位址群組名稱。第二個引數決定 IP 位址的擷取來源，可以是 origin.ip、origin.user_ip 或特定標頭名稱。第三個引數 (選用) 是以半形逗號分隔的字串清單，其中每個字串都是 IP 位址或 CIDR 範圍，會從評估中排除。如果位址群組包含會觸發偽陽性的 IP 位址，排除清單就非常實用。 注意：使用 origin.user_ip 時，您必須在安全性政策的 advancedOptionsConfig 欄位中設定 userIpRequestHeaders[] 選項。
evaluateAdaptiveProtection(string)	如果要求與 Google Cloud Armor Adaptive Protection 產生的攻擊特徵相符，則傳回 true。 引數是 Adaptive Protection 偵測到攻擊時產生的特定警告 ID。
evaluateAdaptiveProtectionAutoDeploy()	如果要求來自高頻率 IP 位址，且符合 Adaptive Protection 偵測到的攻擊特徵，則傳回 true。

範例

• 下列運算式會根據 Google Threat Intelligence iplist-known-malicious-ips 動態饋給比對傳入要求，防範已知惡意 IP 清單：

  evaluateThreatIntelligence('iplist-known-malicious-ips')
  

• 下列運算式會根據 Google Threat Intelligence iplist-known-malicious-ips 動態饋給比對傳入要求，防範已知惡意 IP 清單中的 IP，但 203.0.113.0/24 中的 IP 除外：

  evaluateThreatIntelligence('iplist-known-malicious-ips', ['203.0.113.0/24'])
  

• 下列運算式會比對使用者 IP 的自訂要求標頭與名為 my-own-list-of-bad-ips 的位址群組：

  evaluateAddressGroup('my-own-list-of-bad-ips', origin.user_ip)
  

後續步驟

• 建立及查看 Cloud Armor 安全性政策
• 管理 Cloud Armor 安全性政策
• 管理 Cloud Armor 安全性政策規則
• 調整 Cloud Armor 預先設定的 WAF 規則
• 排解 Cloud Armor 問題
• 配額與限制