規則運算式運算式

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

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

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

注意：本主題並未詳細介紹規則運算式。主要目的是說明這項政策的結構和用法。

如要進一步瞭解規則運算式，您可以參考許多資源。如需規則運算式範例和其他指南，請參閱「使用條件進行模式比對」一文。

影片

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

影片	說明
防範 SQL 注入攻擊	使用 Apigee UI 中的規則運算式防護政策，防範 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 政策設定會評估表單參數，找出是否有 [-+=$%&] 集合內的特殊字元。只有在要求中的內容類型標頭為 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 套件中類別相同的規則。

<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> 元素，在管理 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> 元素

指定為變數定義的 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 查詢最多只會產生一個值，或您只想檢查一個值，請使用「字串」。如果 xpath 查詢可能會傳回多個值，請指定「nodeset」來檢查所有值。

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

相反地，如果您將「nodeset」指定為該 XPath 運算式的 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 威脅防護政策