規則運算式運算式

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

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

影片

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

影片 說明
防範 SQL 注入式攻擊 (新版 Edge) 在 New Edge 體驗的使用者介面中，使用規則運算式防護政策防範 SQL 植入攻擊。
防範 SQL 注入攻擊 (傳統版 Edge) 在 Classic Edge UI 中，使用規則運算式防護政策防範 SQL 植入攻擊。

範例

GitHub

GitHub 上的 regex-protection 範例說明如何攔截透過查詢參數發出的潛在 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 政策評估 JSON 酬載，防範 JavaScript 插入攻擊。具體來說，我們會根據 <JSONPath>/<Pattern> 中的規則運算式，評估 <JSONPath>/<Expression> 擷取的內容。

如果 <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> attributes

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

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

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以 包含英文字母、數字、空格、連字號、底線和半形句號。此值不能 超過 255 個半形字元

視需要使用 <DisplayName> 元素，為政策加上標籤： 管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。

 不適用 必填
continueOnError

如果設為「false」，系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true，即使政策已發生，流程執行作業仍會繼續執行 失敗。

 false 選用
enabled

如要強制執行政策，請設為 true。

設為 false 即可停用政策。這項政策不會 仍會強制執行 政策。

 true 選用
async

此屬性已淘汰。

 false 已淘汰

&lt;DisplayName&gt;元素

除 name 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然語言名稱。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素，政策的 name 屬性值會是

存在必要性 選用
類型 字串

<Source> 元素

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

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

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

<Source>response</Source>
預設值： N/A
外觀狀態： 選用
類型： 字串

<IgnoreUnresolvedVariables> 元素

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

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

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
預設值： false
外觀狀態： 選用
類型： 布林值

<URIPath> 元素

指定要從要求 URI 路徑擷取資訊，並根據提供的規則運算式進行評估。您必須提供至少一個 <Pattern> 元素，指定要比對的規則運算式模式。

<URIPath>
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</URIPath>
預設值： N/A
外觀狀態： 選用
類型： N/A

<QueryParam> 元素

指定需要從要求查詢參數擷取資訊，並根據提供的規則運算式進行評估。您必須提供至少一個 <Pattern> 元素，指定要比對的規則運算式模式。

<QueryParam name="a-query-param">
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</QueryParam>
預設值： N/A
外觀狀態： 選用
類型： N/A

屬性

屬性 說明 預設 存在必要性
名稱 要求查詢參數的名稱，系統會從中擷取資訊，並根據提供的規則運算式進行評估。 N/A 必填

<Header> 元素

指定需要從要求和回應標頭擷取資訊，並根據提供的規則運算式進行評估。您必須提供至少一個 <Pattern> 元素，指定要比對的規則運算式模式。

<Header name="a-header">
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</Header>
預設值： N/A
外觀狀態： 選用
類型： N/A

屬性

屬性 說明 預設 存在必要性
名稱

要求和回應標頭的名稱，系統會從中擷取資訊，並根據提供的規則運算式進行評估。

 N/A 必填

<FormParam> 元素

指定需要從要求表單參數擷取資訊，並根據提供的規則運算式進行評估。您必須提供至少一個 <Pattern> 元素，指定要比對的規則運算式模式。

<FormParam name="a-form-param">
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</FormParam>
預設值： N/A
外觀狀態： 選用
類型： N/A

屬性

屬性 說明 預設 存在必要性
名稱

要求表單參數的名稱，系統會從中擷取資訊，並根據提供的規則運算式進行評估。

 N/A 必填

<Variable> 元素

指定需要從指定變數擷取資訊，並根據提供的規則運算式進行評估。

<Variable name="request.content">
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</Variable>
預設值： N/A
外觀狀態： 選用
類型： N/A

屬性

屬性 說明 預設 存在必要性
名稱

要從中擷取資訊以評估是否符合所提供規則運算式的變數名稱。

 N/A 必填

<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>
預設值： N/A
外觀狀態： 選用
類型： N/A

<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>
預設值： N/A
外觀狀態： 選用
類型： 字串

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

指定要在 XPath 評估中使用的每個命名空間。
<Namespaces>
   <Namespace prefix="apigee">http://www.apigee.com</Namespace>
</Namespaces>
預設值： N/A
外觀狀態： 選用
類型： 字串

屬性

屬性 說明 預設 存在必要性
前置字串

提供前置字元，協助限定特定命名空間。

 N/A 必填

<XMLPayload>/<XPath> 元素

指定要評估的 XPath。
<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>
預設值： N/A
外觀狀態： 選用
類型： N/A

<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>
預設值： N/A
外觀狀態： 選用
類型： 字串

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

指定資料型別。
<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> element

定義規則運算式模式。如果 <Pattern> 元素中的規則運算式包含 XML 保留字元 (「"」、「&」、「'」、「<」或「.」)，您必須先進行 XML 編碼，才能加入該運算式。

<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>
預設值： N/A
外觀狀態： 必填
類型： 字串

<JSONPayload> 元素

指定需要從 JSON 酬載擷取資訊，並根據提供的規則運算式進行評估。

<JSONPayload>
   <JSONPath>
      <Expression>$.store.book[*].author</Expression>
      <Pattern>REGEX PATTERN</Pattern>
      <Pattern>REGEX PATTERN</Pattern>
   </JSONPath>
</JSONPayload>
預設值： N/A
外觀狀態： 選用
類型： N/A

屬性

屬性 說明 預設 存在必要性
escapeSlashCharacter

設為 true，即可逸出 <JSONPath>/<Pattern> 中規則運算式的所有正斜線 (/) 字元。

 true 選用

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

指定為變數定義的 JSONPath 運算式。

<JSONPath>
   <Expression>$.store.book[*].author</Expression>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</JSONPath>
預設值： N/A
外觀狀態： 選用
類型： 字串

<JSONPayload>/<JSONPath>/<Pattern> element

定義規則運算式模式。如果 <Pattern> 元素中的規則運算式包含 XML 保留字元 (「"」、「&」、「'」、「<」或「.」)，您必須先進行 XML 編碼，才能加入該元素。

<JSONPath>
   <Expression>$.store.book[*].author</Expression>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</JSONPath>
預設值： N/A
外觀狀態： 必填
類型： 字串

錯誤參考資料

本節說明這項政策觸發錯誤時，傳回的錯誤代碼和訊息，以及 Edge 設定的錯誤變數。如果您正在開發錯誤規則來處理錯誤，請務必瞭解這項資訊。如要擷取錯誤並引發自訂錯誤，請為政策根元素設定 continueOnError="true" 屬性。詳情請參閱「 政策錯誤須知」和「處理錯誤」。

Edge 政策傳回的錯誤遵循一致的格式，詳情請參閱錯誤代碼參考資料。

執行階段錯誤

執行政策時，可能會發生這些錯誤。

錯誤代碼 訊息
ExecutionFailed 無法執行 RegularExpressionProtection StepDefinition {0}。原因：{1}
InstantiationFailed 無法將 RegularExpressionProtection StepDefinition {0} 例項化
NonMessageVariable 變數「{0}」無法解析為訊息
SourceMessageNotAvailable {0} 訊息不適用於 RegularExpressionProtection StepDefinition{1}
ThreatDetected 在 {0} 中偵測到規則運算式威脅：規則運算式：{1} 輸入：{2}
VariableResolutionFailed 無法解析變數「{0}」

部署錯誤

錯誤代碼 訊息 修正
CannotBeConvertedToNodeset regexProtection {0}：xpath {1} 的結果無法轉換為 nodeset。 內容{2}
DuplicatePrefix regexProtection {0}：前置字元重複 {1}
EmptyJSONPathExpression regexProtection {0}：空白 JSONPath 運算式
EmptyXPathExpression regexProtection {0}：空白的 XPath 運算式
InvalidRegularExpression regexProtection {0}：無效的規則運算式 {1}，內容 {2}
JSONPathCompilationFailed regexProtection {0}：無法編譯 jsonpath {1}。內容{2}
NONEmptyPrefixMappedToEmptyURI regexProtection {0}：非空白前置字串 {1} 無法對應至空白 URI
NoPatternsToEnforce regexProtection {0}：{1} 中沒有可強制執行的模式
NothingToEnforce RegularExpressionProtection {0}：至少須有一個 URIPath、QueryParam、Header、FormParam、XMLPayload 和 JSONPayload
XPathCompilationFailed regexProtection {0}：無法編譯 xpath {1}。內容{2}

錯誤變數

系統會在這項政策觸發錯誤時設定這些變數。詳情請參閱「政策錯誤的注意事項」。

Variables 地點 範例
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 威脅防護政策