規則運算式運算式

本頁內容適用於 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\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 套件的類別相同的 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 屬性值。
存在必要性	選用
類型	字串

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

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

錯誤參考資料

本節說明這項政策觸發錯誤時，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 威脅防護政策