規則運算式運算式

本頁適用於 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 編碼保留字元：例如，將 < 替換為 &lt;，將 > 替換為 &gt;。

此外，如果規則運算式包含正斜線 (/)，您必須將 <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 政策的元素和屬性。

<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，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：

 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

結構定義

相關主題

JSON 威脅防護政策

XML 威脅防護政策