RegularExpressionProtection 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

内容

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

视频

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

视频 说明
保护 防范 SQL 注入攻击（新 Edge） 在 全新的 Edge 体验界面。
保护 防范 SQL 注入攻击（传统版 Edge） 在 传统 Edge 界面。

示例

GitHub

GitHub 上的正则表达式保护示例说明了如何捕获通过查询参数发出的潜在 SQL 注入攻击。此外，该示例还演示了设置一个通用 400 错误状态来防止黑客从响应中获取任何有用的信息。

JavaScript 包括攻击防护

<RegularExpressionProtection name="JsonPathRegExProtection">
    <DisplayName>Regular Expression Protection 1</DisplayName>
    <Source>request</Source>
    <JSONPayload escapeSlashCharacter="true">
       <JSONPath>
          <Expression>$</Expression>
          <Pattern>&lt;\s*script\b[^&gt;]*&gt;[^&lt;]+&lt;\s*\/\s*script\s*&gt;
          </Pattern>
          <Pattern>n\s*\\\\\s*slash</Pattern>
          <Pattern>n\s*\/\s*slash</Pattern>
          <Pattern>n\s*\\"\s*quotes</Pattern>
          <Pattern>n\s*\\b\s*space</Pattern>
          <Pattern>n\s*\\f\s*forwardfeed</Pattern>
          <Pattern>n\s*\\n\s*newline</Pattern>
          <Pattern>n\s*\\r\s*carria</Pattern>
          <Pattern>n\s*\\t\s*tab</Pattern>
          <Pattern>n\s*\\uFFFF\s*hex</Pattern>
       </JSONPath>
    </JSONPayload>
 </RegularExpressionProtection>

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

如果 <JSONPath>/<Pattern> 中的正则表达式包含 XML 预留的字符（"、&、'、< 或 .），您必须先对 XML 进行编码，然后才能将其包括在政策 XML 配置文件中。例如，在上面的示例中，正则表达式 <\s*script\b[^>]*>[^<]+<\s*\/\s*script\s*> 已 XML 编码为 &lt;\s*script\b[^&gt;]*&gt;[^&lt;]+&lt;\s*\/\s*script\s*&gt;。

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

不区分大小写匹配

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

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

关于正则表达式保护政策

利用 Apigee Edge，您可以配置正则表达式， 根据运行时的 API 流量进行评估，以识别 某些模式。

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

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

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

排除模式示例

正则表达式必须在政策的 XML 配置文件中进行 XML 编码。

名称 正则表达式
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;
Java 异常注入 
.*?Exception in thread.*

在使用 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 政策的元素和属性。

<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">

The following table describes attributes that are common to all policy parent elements:

Attribute Description Default Presence
name

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

 N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

 false Optional
enabled

Set to true to enforce the policy.

Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.

 true Optional
async

This attribute is deprecated.

 false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default

N/A

If you omit this element, the value of the policy's name attribute is used.
Presence Optional
Type String

<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>
默认： 不适用
状态： 可选
类型： 不适用

特性

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

<Header> 元素

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

<Header name="a-header">
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</Header>
默认： 不适用
状态： 可选
类型： 不适用

特性

属性 说明 默认 状态
名称

需要从中提取信息以根据提供的正则表达式进行评估的请求和响应标头的名称。

 无 必需

<FormParam> 元素

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

<FormParam name="a-form-param">
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</FormParam>
默认： 不适用
状态： 可选
类型： 不适用

特性

属性 说明 默认 状态
名称

需要从中提取信息以根据提供的正则表达式进行评估的请求表单参数的名称。

 无 必需

<Variable> 元素

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

<Variable name="request.content">
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</Variable>
默认： 不适用
状态： 可选
类型： 不适用

特性

属性 说明 默认 状态
名称

需要从中提取信息以根据提供的正则表达式进行评估的变量的名称。

 无 必需

<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>
默认： 不适用
状态： 可选
类型： 字符串

特性

属性 说明 默认 状态
prefix

提供前缀，以帮助限定给定命名空间。

 无 必需

<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> 元素

指定数据类型。
<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>
默认： 不适用
状态： 可选
类型： 不适用

特性

属性 说明 默认 状态
escapeSlashCharacter

设置为 true 可对 <JSONPath>/<Pattern> 中的正则表达式中的任何正斜杠 (/) 字符进行转义。

 是 可选

<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>
默认： 不适用
状态： 必填
类型： 字符串

错误参考信息

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

从 Edge 政策返回的错误会遵循一致的格式（请参阅错误代码参考）。

运行时错误

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

错误代码 消息
ExecutionFailed 未能执行 RegularExpressionProtection StepDefinition {0}。原因：{1}
InstantiationFailed 未能实例化 RegularExpressionProtection StepDefinition {0}
NonMessageVariable 变量 {0} 无法解析为消息
SourceMessageNotAvailable {0} 消息不适用于 RegularExpressionProtection StepDefinition {1}
ThreatDetected 在 {0}: regex: {1} input: {2} 中检测到正则表达式威胁
VariableResolutionFailed 无法解析变量 {0}

部署错误

错误代码 消息 修复
CannotBeConvertedToNodeset RegularExpressionProtection {0}：xpath {1} 的结果无法转换为 nodeset。上下文 {2}
DuplicatePrefix RegularExpressionProtection {0}：重复的前缀 {1}
EmptyJSONPathExpression RegularExpressionProtection {0}：空 JSONPath 表达式
EmptyXPathExpression RegularExpressionProtection {0}：空 XPath 表达式
InvalidRegularExpression RegularExpressionProtection {0}：正则表达式 {1} 无效，上下文 {2}
JSONPathCompilationFailed RegularExpressionProtection {0}：未能编译 jsonpath {1}。上下文 {2}
NONEmptyPrefixMappedToEmptyURI RegularExpressionProtection {0}：非空前缀 {1} 不能映射到空 uri
NoPatternsToEnforce RegularExpressionProtection {0}：{1} 中无要强制执行的模式
NothingToEnforce RegularExpressionProtection {0}：必须至少提供 URIPath、QueryParam、Header、FormParam、XMLPayload、JSONPayload 中的一个
XPathCompilationFailed RegularExpressionProtection {0}：编译 xpath {1} 失败。上下文 {2}

故障变量

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

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

架构

相关主题

JSON 威胁防范政策

XML 威胁防范政策