配置自定义规则语言属性

每个 Google Cloud Armor 安全政策规则都有优先级、匹配条件和操作。Cloud Armor 会执行与请求匹配的最高优先级规则的操作。优先级低于最高优先级匹配规则的规则不会进行评估，即使它们具有相同的匹配条件也是如此。

每个安全政策规则都支持两种类型的匹配条件：

  • 基本匹配条件包含 IP 地址列表或 IP 地址范围列表。 基本匹配条件是在通过 Google Cloud CLI 创建规则时使用 --src-ip-ranges 标志定义的。
  • 高级匹配条件包含一个最多具有 5 个子表达式的表达式，可匹配传入请求的各种属性。高级匹配条件是在通过 Google Cloud CLI 创建规则时使用 --expression 标志定义的。

本页面介绍了高级匹配条件和 Cloud Armor 自定义规则语言，您可以使用该语言在安全政策规则的高级匹配条件中编写表达式。Cloud Armor 自定义规则语言是通用表达式语言 (CEL) 的子集。使用 Cloud Armor 自定义规则语言编写的表达式需要两个组成部分：

  • 属性：要检查的数据
  • 操作：如何使用数据

例如，以下表达式在操作 inIpRange() 中使用属性 origin.ip 和 9.9.9.0/24。在这种情况下，如果 origin.ip 在 9.9.9.0/24 IP 地址范围内，则表达式返回 true。

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

尽管前面的示例表达式仅匹配客户端 IP 地址，但当您在 Cloud Armor 安全政策规则中使用该示例表达式时，该规则在配额方面会被视为具有高级匹配条件的规则。如需了解详情，请参阅 Cloud Armor 配额和限制。

运维

以下参考信息描述了可与属性（由 x、y 和 k 表示）搭配使用来定义规则表达式的运算符。

运维 表达式 说明
相等 x == y 如果 x 等于 y，则返回 true。
相等，字符串字面量 x == "foo" 如果 x 等于指定常量字符串字面量，则返回 true。x
相等，原始字符串字面量 x == R"fo'o" 如果 x 等于不解释转义序列的指定原始字符串字面量，则返回 true。x原始字符串字面量便于表示自己必须使用转义序列字符的字符串。
逻辑非 !x 如果布尔值 x 为 false，则返回 true；如果布尔值 x 为 true，则返回 false。
不相等 x != y 如果 x 不等于 y，则返回 true。
串联 x + y 返回串联的字符串 xy。
逻辑与 x && y 如果 x 和 y 均为 true，则返回 true。
逻辑或 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 模式是使用停用 Unicode 功能的 RE2::Latin1 选项编译的。
范围内的 IP 地址 inIpRange(x, y) 如果 IP 地址 x 包含在 IP 范围 y 内，则返回 true。
小写 x.lower() 返回字符串 x 的小写值。x
大写 x.upper() 返回字符串 x 的大写值。x
Base64 解码值 x.base64Decode() 返回 xx 的 base64 解码值；字符 _ - 首先被相应替换为 / +。如果 xx 不是有效的 base64 值，则返回 ""（空字符串）。
键映射值 m['k'] 如果 k 可用，则返回字符串到字符串映射 m 中的键 k 处的值；否则返回错误。建议先使用 "has(m['k'])==true" 检查可用性。
在映射中检查键可用性 has(m['k']) 如果键 'k' 在映射 'm' 中可用，则返回 true。
转换为整数 int(x) 将字符串结果 x 转换为 int 类型。x接着可以将其用于使用标准算术运算符（例如 > 和 <=）进行整数比较。这仅适用于应该为整数的值。
长度 size(x) 返回字符串 x 的长度。x
解码网址 x.urlDecode() 返回 xx 的网址解码值；%## 格式的字符序列会被替换为非 ASCII 等效字符，而 + 则被替换为空格。无效编码会按原样返回。
解码网址 (Unicode) x.urlDecodeUni() 返回 xx 的网址解码值；除了 urlDecode() 之外，还会处理 %u### 格式的 Unicode 字符序列。无效编码会按原样返回。
将 utf8 转换为 Unicode x.utf8ToUnicode() 返回 UTF-8 编码 xx 的小写 Unicode 表示形式。

属性

属性表示来自传入请求的信息，例如客户端 IP 地址或请求的网址路径。

字段 类型 字段说明
origin.ip 字符串 发起请求的客户端的 IP 地址。
origin.user_ip 字符串 来源客户端的 IP 地址，由上游代理添加在 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.method 字符串 HTTP 请求方法。
request.path 字符串 所请求的 HTTP 网址路径。 当您编写与 request.path 匹配的规则时，我们建议您对路径进行规范化，以便在出现网址编码、大小写变体或反斜杠时，能够轻松匹配语法。如需了解详情和示例，请参阅路径遍历和规范化。
request.scheme 字符串 HTTP 网址架构，例如 http 或 https。此属性的值均为小写。
request.query 字符串