此页面由 Cloud Translation API 翻译。

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 编码为 <\s*script\b[^>]*>[^<]+<\s*\/\s*script\s*>。

此外，如果您的正则表达式包含正斜杠 (/)，则必须将 <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\stable)\|(insert)\|(shutdown)\|(update)\|(\bor\b))
服务器端包括注入	<!--#(include\|exec\|echo\|config\|printenv)\s+.* XML 编码： <!--#(include\|exec\|echo\|config\|printenv)\s+.*
XPath 缩写语法注入	(/(@?[\w_?\w:\]+(\[[^]]+\]))?)+
XPath 展开语法注入	/?(ancestor(-or-self)?\|descendant(-or-self)?\|following(-sibling))
JavaScript 注入	<\sscript\b[^>]>[^<]+<\s/\sscript\s> XML 编码： <\sscript\b[^>]>[^<]+<\s/\sscript\s>
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 政策的元素和属性。

注意：在本主题中，“REGEX PATTERN”代表用于执行所需匹配的有效正则表达式模式。Edge 遵循相同的正则表达式将规则定义为 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">

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

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

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

默认

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

不适用

如果省略此元素，则会使用政策的 name 属性的值。

状态可选

类型字符串

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

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

错误参考信息

This section describes the error codes and messages returned and fault variables set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. If you want to capture an error and raise your own custom error, set the continueOnError="true" attribute on the policy root element. To learn more, see What you need to know about policy errors and Handling faults.

Errors returned from Edge policies follow a consistent format as described in the Error code reference.

Runtime errors

These errors can occur when the policy executes.

Error Code	Message

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}

Deployment errors

Error Code	Message	Fix

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 variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault, as listed in the table above.	`fault.name Matches "ThreatDetected"`
`regularexpressionprotection.policy_name.failed`	`policy_name` is the user-specified name of the policy that threw the fault.	`regularexpressionprotection.Regular-Expressions-Protection-1.failed = true`

RegularExpressionProtection 政策

内容

视频

示例

GitHub

JavaScript 包括攻击防护

不区分大小写匹配

关于正则表达式保护政策

排除模式示例

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

元素参考

<RegularExpressionProtection> 属性

<DisplayName> 元素

<Source> 元素

<IgnoreUnresolvedVariables> 元素

<URIPath> 元素

<QueryParam> 元素

特性

<Header> 元素

特性

<FormParam> 元素

特性

<Variable> 元素

特性

<XMLPayload> 元素

<XMLPayload>/<Namespaces> 元素

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

特性

<XMLPayload>/<XPath> 元素

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

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

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

<JSONPayload> 元素

特性

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

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

错误参考信息

Runtime errors

Deployment errors

Fault variables

架构

相关主题