規則運算式運算式

本頁內容適用於 ApigeeApigee 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 編碼,例如將 < 替換為 &lt;,並將 > 替換為 &gt;

此外,如果規則運算式包含正斜線 (/),您必須將 <JSONPayload> escapeSlashCharacter 屬性設為 true,才能逸出正斜線。

不區分大小寫的相符項目

不區分大小寫的相符項目是常見的用途。以下範例說明如何使用 (?i) 結構,在規則運算式中達成這項目的。舉例來說,在本範例中,DELETEdeleteDelete 會評估為 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/xmltext/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> 元素,在管理 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> 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>
預設值: 字串
外觀狀態: 選用
類型: 字串
有效值:

下列任一關鍵字:stringbooleanintlongfloatdoublenodeset

<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 威脅防護政策