本頁面由 Cloud Translation API 翻譯而成。

規則運算式運算式

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

從訊息中擷取資訊 (例如 URI 路徑、查詢參數、標頭、表單參數、變數、XML 酬載或 JSON 酬載)，並根據預先定義的規則運算式評估該內容。如果任何指定的規則運算式評估結果為 true，系統就會將郵件視為威脅，並觸發政策錯誤。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

影片

觀看下方影片，進一步瞭解規則運算式保護政策。

影片	說明
防範 SQL 植入攻擊	在 Apigee 使用者介面中，透過規則運算式防護政策防範 SQL 植入攻擊。

範例

GitHub

GitHub 上的 regex-protection 範例說明如何攔截透過查詢參數發出的潛在 SQL 注入攻擊，這些參數可能在 <script> 標記中含有惡意程式碼。這個範例也說明瞭設定一般 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 政策評估 JSON 酬載，防範 JavaScript 包含攻擊。具體來說，系統會根據 <JSONPath>/<Pattern> 中的規則運算式，評估 <JSONPath>/<Expression> 擷取的內容。

如果 <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 時，這項政策才會生效。由於存在 XML 中的特殊字元「&」，因此政策設定會使用 CDATA (字元資料) 區段包裝規則運算式。

關於規則運算式防護政策

Apigee 可讓您設定規則運算式，在執行階段針對 API 流量進行評估，找出符合特定模式的常見內容層級威脅。

規則運算式 (簡稱 regex) 是一組字串，可指定字串中的模式。規則運算式可讓系統以程式輔助方式評估內容模式。舉例來說，您可以使用規則運算式評估電子郵件地址，確保格式正確。詳情請參閱 Java 教學課程中的「規則運算式」。

RegularExpressionProtection 最常見的用途是評估 JSON 和 XML 酬載是否含有惡意內容。

沒有任何規則運算式可以完全杜絕內容型攻擊，因此應結合多種機制，實現縱深防禦。本節說明排除內容的建議模式。

排除格式範例

政策的 XML 設定檔中必須經過 XML 編碼的正規運算式。另請參閱「反模式：在 RegularExpressionProtection 政策中使用窮盡量詞」。

名稱	規則運算式
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>

在含有 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 套件的類別相同的 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> attributes

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

下表說明所有政策父項元素的共同屬性：

屬性	說明	預設	存在必要性
`name`	政策的內部名稱。`name` 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。您可以選擇使用 `<DisplayName>` 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。	不適用	必填
`continueOnError`	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤	false	選用
`enabled`	設為 `true` 即可強制執行政策。設為 `false` 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。	是	選用
`async`	此屬性已淘汰。	false	已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>

預設

預設	不適用如果省略這個元素，系統會使用政策的 `name` 屬性值。
存在必要性	選用
類型	字串

不適用

如果省略這個元素，系統會使用政策的 name 屬性值。

存在必要性選用

類型字串

<Source> 元素

指出需要擷取資訊的訊息。

如果省略 <Source> 元素，值會預設為 message。例如 <Source>message</Source>。如果設為 message，政策會將要求訊息做為來源，並附加至要求流程。同樣地，如果政策附加至回覆流程，就會使用回覆訊息。

如果無法解析來源訊息，或解析為非訊息類型，政策會傳回錯誤。

<Source>response</Source>

預設值：	不適用
外觀狀態：	選用
類型：	字串

<IgnoreUnresolvedVariables> 元素

決定政策在遇到無法解析的變數時，是否會傳回錯誤。

如果設為「false」(預設值)，當系統遇到無法解析的變數時，這項政策會傳回錯誤。如果設為 true，系統會將未解析的變數視為空字串 (空值)。

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

預設值：	不適用
外觀狀態：	選用
類型：	字串

屬性

屬性	說明	預設	存在必要性
前置字串	提供前置字元，協助限定特定命名空間。	不適用	必填

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

指定為變數定義的 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> element

指定所需的輸出資料類型。

通常會使用「string」或「nodeset」。如果確定 XPath 查詢最多會產生一個值，或只想檢查最多一個值，請使用「string」。如果 XPath 查詢可能會傳回多個值，請指定「nodeset」來檢查所有值。

舉例來說，請考慮 XPath 運算式 //*/@*。它會比對所有元素的所有屬性。如果您將 Type 指定為「string」，Apigee 會將這項查詢的結果強制轉換為單一字串，也就是 XML 文件中某個元素的其中一個屬性值，但未定義是哪個屬性和元素。Apigee 接著會對該單一屬性的值執行模式比對。這可能不是您要的結果。

反之，如果您為該 XPath 運算式指定「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>

預設值：	不適用
外觀狀態：	選用
類型：	不適用

屬性

屬性	說明	預設	存在必要性
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 Apigee 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.

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`

規則運算式運算式 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

結果

影片

範例

GitHub

JavaScript 納入攻擊防護

不區分大小寫的相符項目

表單參數檢查

關於規則運算式防護政策

排除格式範例

在含有 XML 或 JSON 酬載的要求中設定 Content-Type 標頭

元素參考資料

<RegularExpressionProtection> attributes

<DisplayName> 元素

<Source> 元素

<IgnoreUnresolvedVariables> 元素

<URIPath> 元素

<QueryParam> 元素

屬性

<Header> 元素

屬性

<FormParam> 元素

屬性

<Variable> 元素

屬性

<XMLPayload> 元素

<XMLPayload> 元素/<Namespaces> 元素

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

屬性

<XMLPayload>/<XPath> 元素

<XMLPayload>/<XPath>/<Expression> element

<XMLPayload>/<XPath>/<Type> element

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

<JSONPayload> 元素

屬性

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

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

錯誤參考資料

Runtime errors

Deployment errors

Fault variables

結構定義

相關主題

規則運算式運算式