RegularExpressionProtection 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

内容

从消息中提取信息（例如 URI 路径、查询参数、标头、表单参数、变量、XML 载荷或 JSON 载荷），并根据预定义的正则表达式评估这些内容。如果任何指定的正则表达式的评估结果为 true，则消息被视为威胁，并且政策将抛出故障。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

注意：本主题并非旨在包含正则表达式的详细说明。其主要目的是解释此政策的结构和用法。

如果您想详细了解正则表达式，有许多资源可供您探索。您可以在与条件相匹配的匹配主题中找到正则表达式示例和其他指南。

视频

观看以下视频，详细了解正则表达式保护政策。

视频	说明
防范 SQL 注入攻击	在 Apigee 界面中使用正则表达式保护政策防范 SQL 注入攻击。

示例

GitHub

GitHub 上的正则表达式保护示例说明了如何捕获通过可能在 <script> 标记中包含恶意代码的查询参数发出的潜在 SQL 注入攻击。该示例还演示了设置一个通用 400 错误状态来防止黑客从响应中获取任何有用信息的最佳做法。

JavaScript 包括攻击防护

<RegularExpressionProtection name="JsonPathRegExProtection">
    <Source>request</Source>
    <JSONPayload escapeSlashCharacter="true">
       <JSONPath>
          <Expression>$</Expression>
          <Pattern><![CDATA[ <\s*script\b[^>]*>[^<]+<\s*\/\s*script\s*> ]]></Pattern>
       </JSONPath>
    </JSONPayload>
 </RegularExpressionProtection>

上面的示例介绍了如何使用 RegularExpressionProtection 政策评估 JavaScript 载荷是否有 JSON 包括攻击。具体而言，由 <JSONPath>/<Expression> 提取的内容将根据 <JSONPath>/<Pattern> 中的正则表达式进行评估。

如果 <JSONPath>/<Pattern> 中的正则表达式包含 XML 预留的字符（"、&、'、< 或 >），则必须将其封装在 CDATA（字符数据）部分中（如以上示例所述），或对预留字符进行 XML 编码：例如，通过将 < 替换为 < 并将 > 替换为 >。

此外，如果您的正则表达式包含正斜杠 (/)，则必须将 <JSONPayload> escapeSlashCharacter 属性设置为 true，以对其进行转义。

不区分大小写匹配

一种常见的用例是不区分大小写匹配。以下示例说明如何使用构造 (?i) 在正则表达式中执行此操作。例如，DELETE、delete 和 Delete 的评估结果为 true。

<Pattern>[\s]*(?i)((delete)|(exec)|(drop\s*table)|(insert)|(shutdown)|(update)|(\bor\b))</Pattern>

表单参数检查

<RegularExpressionProtection name="REP-Formparam">
  <Source>request</Source>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <FormParam name="firstname">
    <Pattern><![CDATA[[-+=$%&]]]></Pattern>
  </FormParam>
  <FormParam name="lastname">
    <Pattern><![CDATA[[-+=$%&]]]></Pattern>
  </FormParam>
</RegularExpressionProtection>

此 RegularExpressionProtection 政策配置将评估 [-+=$%&] 集的表单参数中是否存在特殊字符。仅当请求中的 content-type 标头为 application/x-www-form-urlencoded 时，此政策才会生效。政策配置使用 CDATA（字符数据）部分来封装正则表达式，因为存在 & 字符，它在 XML 中属于特殊字符。

---

关于正则表达式保护政策

通过 Apigee，您可以配置可针对运行时 API 流量评估的正则表达式，以识别遵循某些模式的常见内容级别威胁。

正则表达式（简称为 regex）是一组字符串，用于采用字符串指定模式。正则表达式使得可以通过编程方式针对模式评估内容。例如，您可以使用正则表达式来评估电子邮件地址，以确保其结构正确。如需了解详情，请参阅 Java 教程中的正则表达式。

RegularExpressionProtection 最常见的用法是评估 JSON 和 XML 载荷是否存在恶意内容。

任何正则表达式都不能消除所有基于内容的攻击，并且应该组合多个机制来实现深度防御。本部分介绍一些排除内容的推荐模式。

排除模式示例

正则表达式必须在政策的 XML 配置文件中进行 XML 编码。 另请参阅“反模式：在 RegularExpressionProtection 政策中使用贪婪限定符”。

名称	正则表达式
SQL 注入	[\s]*((delete)|(exec)|(drop\s*table)|(insert)|(shutdown)|(update)|(\bor\b))
服务器端包括注入	<!--#(include|exec|echo|config|printenv)\s+.* XML 编码： &lt;!--#(include|exec|echo|config|printenv)\s+.*
XPath 缩写语法注入	(/(@?[\w_?\w:\*]+(\[[^]]+\])*)?)+
XPath 展开语法注入	/?(ancestor(-or-self)?|descendant(-or-self)?|following(-sibling))
JavaScript 注入	<\s*script\b[^>]*>[^<]+<\s*/\s*script\s*> XML 编码： &lt;\s*script\b[^&gt;]*&gt;[^&lt;]+&lt;\s*/\s*script\s*&gt;

在使用 XML 或 JSON 载荷的请求中设置 Content-Type 标头

正则表达式保护政策的载荷可以包含以下元素：

• <XMLPayload> 元素：指定需要从 XML 载荷中提取信息，并根据提供的正则表达式进行评估。

  如果您在政策中使用 <XMLPayload>，则请求的 Content-Type 标头必须是 XML 内容类型，例如 application/xml 或 text/xml。

• <JSONPayload> 元素：指定需要从 JSON 载荷中提取信息，并根据提供的正则表达式进行评估。

  如果您在政策中使用 <JSONPayload>，则请求的 Content-Type 标头必须是 JSON 内容类型，例如 application/json。

通常，您设计 API 来接受 XML 或 JSON 格式。但是，可能出现 API 同时接受这两者的场景。然后，您可以定义同时使用 <XMLPayload> 和 <JSONPayload> 元素的正则表达式保护政策。根据 Content-Type 标头的值，只有一个元素适用于特定请求。

元素参考

元素参考描述了 RegularExpressionProtection 政策的元素和属性。

注意：在本主题中，“REGEX PATTERN”代表用于执行所需匹配的有效正则表达式模式。Apigee 遵循与与 Java 语言中的 java.util.regex 软件包中的类相同的正则表达式规则。

<RegularExpressionProtection async="false" continueOnError="false" enabled="true" name="Regular-Expression-Protection-1">
   <DisplayName>Regular Expression Protection 1</DisplayName>
   <Source>response</Source>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <URIPath>
     <Pattern>REGEX PATTERN</Pattern>
     <Pattern>REGEX PATTERN</Pattern>
   </URIPath>
   <QueryParam name="a-query-param">
     <Pattern>REGEX PATTERN</Pattern>
     <Pattern>REGEX PATTERN</Pattern>
   </QueryParam>
   <Header name="a-header">
     <Pattern>REGEX PATTERN</Pattern>
     <Pattern>REGEX PATTERN</Pattern>
   </Header>
   <FormParam name="a-form-param">
     <Pattern>REGEX PATTERN</Pattern>
     <Pattern>REGEX PATTERN</Pattern>
   </FormParam>
   <Variable name="request.content">
     <Pattern>REGEX PATTERN</Pattern>
     <Pattern>REGEX PATTERN</Pattern>
   </Variable>
   <XMLPayload>
     <Namespaces>
       <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     </Namespaces>
     <XPath>
       <Expression>/apigee:Greeting/apigee:User</Expression>
       <Type>string</Type>
       <Pattern>REGEX PATTERN</Pattern>
       <Pattern>REGEX PATTERN</Pattern>
     </XPath>
   </XMLPayload>
   <JSONPayload>
     <JSONPath>
       <Expression>$.store.book[*].author</Expression>
       <Pattern>REGEX PATTERN</Pattern>
       <Pattern>REGEX PATTERN</Pattern>
     </JSONPath>
    </JSONPayload>
</RegularExpressionProtection>

<RegularExpressionProtection> 属性

<RegularExpressionProtection async="false" continueOnError="false" enabled="true" name="Regular-Expression-Protection-1">

下表介绍了所有政策父元素通用的特性：

属性	说明	默认	Presence
name	政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。 （可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。	不适用	必需
continueOnError	设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。 设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅： 故障规则仅在错误状态下触发（关于 continueOnError） 处理当前流中的故障	false	可选
enabled	设置为 true 可强制执行政策。 设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。	true	可选
async	此特性已弃用。	false	已弃用

<DisplayName> 元素

用于在 name 属性之外在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>

默认	不适用 如果省略此元素，则会使用政策的 name 属性的值。
Presence	可选
类型	字符串

<Source> 元素

表示需要从中提取信息的消息。

如果省略 <Source> 元素，则值默认为 message。例如 <Source>message</Source>。如果设置为 message，该政策会在附加到请求流时使用请求消息作为来源。同样，该政策会在附加到响应流时使用响应消息。

如果来源消息无法解析或解析为非消息类型，则政策将返回错误。

<Source>response</Source>

默认：	不适用
状态：	可选
类型：	字符串

<IgnoreUnresolvedVariables> 元素

确定政策遇到无法解析的变量时是否会返回错误。

如果设置为 false（默认值），则遇到无法解析的变量时，政策会返回错误。如果设置为 true，则未解析的变量将被视为空字符串 (Null)。

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

默认：	false
状态：	可选
类型：	布尔值

<URIPath> 元素

指定需要从请求 URI 路径中提取信息，并根据提供的正则表达式进行评估。您必须至少提供一个 <Pattern> 元素来指定要匹配的正则表达式模式。

<URIPath>
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</URIPath>

默认：	不适用
状态：	可选
类型：	不适用

<QueryParam> 元素

指定需要从请求查询参数中提取信息并根据提供的正则表达式进行计算。您必须至少提供一个 <Pattern> 元素来指定要匹配的正则表达式模式。

<QueryParam name="a-query-param">
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</QueryParam>

默认：	不适用
状态：	可选
类型：	不适用

属性

属性	说明	默认值	Presence
name	需要从中提取信息以根据提供的正则表达式进行评估的请求查询参数的名称。	不适用	必需

<Header> 元素

指定需要从请求和响应标头中提取信息并根据提供的正则表达式进行评估。您必须至少提供一个 <Pattern> 元素来指定要匹配的正则表达式模式。

<Header name="a-header">
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</Header>

默认：	不适用
状态：	可选
类型：	不适用

属性

属性	说明	默认值	Presence
name	需要从中提取信息以根据提供的正则表达式进行评估的请求和响应标头的名称。	不适用	必需

<FormParam> 元素

指定需要从请求表单参数中提取信息并根据提供的正则表达式进行计算。您必须至少提供一个 <Pattern> 元素来指定要匹配的正则表达式模式。

<FormParam name="a-form-param">
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</FormParam>

默认：	不适用
状态：	可选
类型：	不适用

属性

属性	说明	默认值	Presence
name	需要从中提取信息以根据提供的正则表达式进行评估的请求表单参数的名称。	不适用	必需

<Variable> 元素

指定需要从给定变量中提取信息，并根据提供的正则表达式进行评估。

<Variable name="request.content">
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</Variable>

默认：	不适用
状态：	可选
类型：	不适用

属性

属性	说明	默认值	Presence
name	需要从中提取信息以根据提供的正则表达式进行评估的变量的名称。	不适用	必需

<XMLPayload> 元素

指定需要从 XML 载荷中提取信息，并根据提供的正则表达式进行评估。

<XMLPayload>
   <Namespaces>
      <Namespace prefix="apigee">http://www.apigee.com</Namespace>
   </Namespaces>
   <XPath>
      <Expression>/apigee:Greeting/apigee:User</Expression>
      <Type>string</Type>
      <Pattern>REGEX PATTERN</Pattern>
      <Pattern>REGEX PATTERN</Pattern>
   </XPath>
</XMLPayload>

默认：	不适用
状态：	可选
类型：	不适用

<XMLPayload>/<Namespaces> 元素

指定要在 XPath 评估中使用的命名空间。

<XMLPayload>
   <Namespaces>
      <Namespace prefix="apigee">http://www.apigee.com</Namespace>
   </Namespaces>
   <XPath>
      <Expression>/apigee:Greeting/apigee:User</Expression>
      <Type>string</Type>
      <Pattern>REGEX PATTERN</Pattern>
      <Pattern>REGEX PATTERN</Pattern>
   </XPath>
</XMLPayload>

默认：	不适用
状态：	可选
类型：	字符串

<XMLPayload>/<Namespaces>/<Namespace> 元素

指定要在 XPath 评估中使用的每个命名空间。

<Namespaces>
   <Namespace prefix="apigee">http://www.apigee.com</Namespace>
</Namespaces>

默认：	不适用
状态：	可选
类型：	字符串

属性

属性	说明	默认值	Presence
前缀	提供前缀，以帮助限定给定命名空间。	不适用	必需

<XMLPayload>/<XPath> 元素

指定要评估的 XPath。

<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>

默认：	不适用
状态：	可选
类型：	不适用

<XMLPayload>/<XPath>/<Expression> 元素

指定为变量定义的 XPath 表达式。仅支持 XPath 1.0 表达式。例如，<Expression>/company/employee[@age>=$request.header.age]</Expression> 可提取年龄大于或等于 request.header.age 中指定的值的员工的详细信息。

<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>

默认：	不适用
状态：	可选
类型：	字符串

<XMLPayload>/<XPath>/<Type> 元素

指定所需的输出数据类型。

通常您可以使用“string”或“nodeset”。如果您确定 xpath 查询最多会产生一个值，或者您希望最多检查一个值，请使用“string”。如果您的 xpath 查询可能会返回多个值，请指定“nodeset”以检查所有值。

例如，假设使用 JIT 表达式 //*/@*。它匹配所有元素的所有属性。如果将“string”指定为 Type，Apigee 会将此查询的结果强制转换为单个字符串；它将成为 XML 文档中某个元素的其中一个属性的值，但哪个属性未定义，以及哪个元素未定义。然后，Apigee 会根据该单个属性的值执行模式匹配。这可能不是您想要的结果。

相反，如果将“nodeset”指定为 Type 表达式，则 Apigee 会根据 XML 文档中每个元素上的每个属性值执行模式匹配。

<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>

默认：	字符串
状态：	可选
类型：	字符串
有效值：	这些关键字之一：string、boolean、int、long、float、double 和 nodeset。

<XMLPayload>/<XPath>/<Pattern> 元素

定义正则表达式模式。如果 <Pattern> 元素中的正则表达式包含 XML 预留的字符（"、&、'、< 或 .），则必须在包含之前对其进行 XML 编码。

<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>

默认：	不适用
状态：	必需
类型：	字符串

<JSONPayload> 元素

指定需要从 JSON 载荷中提取信息，并根据提供的正则表达式进行评估。

<JSONPayload>
   <JSONPath>
      <Expression>$.store.book[*].author</Expression>
      <Pattern>REGEX PATTERN</Pattern>
      <Pattern>REGEX PATTERN</Pattern>
   </JSONPath>
</JSONPayload>

默认：	不适用
状态：	可选
类型：	不适用

属性

属性	说明	默认值	Presence
escapeSlashCharacter	设置为 true 可对 <JSONPath>/<Pattern> 中的正则表达式中的任何正斜杠 (/) 字符进行转义。	true	可选

<JSONPayload>/<JSONPath>/<Expression> 元素

指定为变量定义的 JSONPath 表达式。

<JSONPath>
   <Expression>$.store.book[*].author</Expression>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</JSONPath>

默认：	不适用
状态：	可选
类型：	字符串

<JSONPayload>/<JSONPath>/<Pattern> 元素

定义正则表达式模式。如果 <Pattern> 元素中的正则表达式包含 XML 预留的字符（"、&、'、< 或 .），则必须在包含之前对其进行 XML 编码。

<JSONPath>
   <Expression>$.store.book[*].author</Expression>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</JSONPath>

默认：	不适用
状态：	必需
类型：	字符串

错误参考信息

本部分介绍当此政策触发错误时返回的错误代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如果要捕获错误并引发自定义错误，请在政策根元素上设置 continueOnError="true" 属性。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

提示：需要我们帮助来解决错误吗？点击“修复”列中的 以获取详细的问题排查信息。

错误代码	消息
ExecutionFailed	Failed to execute the RegularExpressionProtection StepDefinition {0}. Reason: {1}
InstantiationFailed	Failed to instantiate the RegularExpressionProtection StepDefinition {0}
NonMessageVariable	Variable {0} does not resolve to a Message
SourceMessageNotAvailable	{0} message is not available for RegularExpressionProtection StepDefinition {1}
ThreatDetected	Regular Expression Threat Detected in {0}: regex: {1} input: {2}
VariableResolutionFailed	Failed to resolve variable {0}

部署错误

提示：需要我们帮助来解决错误？点击“修复”列中的 以获取详细的问题排查信息。

错误代码	消息	修复
CannotBeConvertedToNodeset	RegularExpressionProtection {0}: Result of xpath {1} cannot be converted to nodeset. Context {2}
DuplicatePrefix	RegularExpressionProtection {0}: Duplicate prefix {1}
EmptyJSONPathExpression	RegularExpressionProtection {0}: Empty JSONPath expression
EmptyXPathExpression	RegularExpressionProtection {0}: Empty XPath expression
InvalidRegularExpression	RegularExpressionProtection {0}: Invalid Regular Expression {1}, Context {2}
JSONPathCompilationFailed	RegularExpressionProtection {0}: Failed to compile jsonpath {1}. Context {2}
NONEmptyPrefixMappedToEmptyURI	RegularExpressionProtection {0}: Non-empty prefix {1} cannot be mapped to empty uri
NoPatternsToEnforce	RegularExpressionProtection {0}: No patterns to enforce in {1}
NothingToEnforce	RegularExpressionProtection {0}: at least one of URIPath, QueryParam, Header, FormParam, XMLPayload, JSONPayload is mandatory
XPathCompilationFailed	RegularExpressionProtection {0}: Failed to compile xpath {1}. Context {2}

故障变量

此政策触发错误时设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

变量	其中	示例
fault.name="fault_name"	fault_name 是上表中列出的故障的名称。	fault.name Matches "ThreatDetected"
regularexpressionprotection.policy_name.failed	policy_name 是抛出故障的政策的用户指定名称。	regularexpressionprotection.Regular-Expressions-Protection-1.failed = true

架构

示例：查看我们的 GitHub 代码库示例，了解最新架构。

相关主题

JSON 威胁防范政策

XML 威胁防范政策