本頁內容適用於 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 編碼: <!--#(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 編碼: <\s*script\b[^>]*>[^<]+<\s*/\s*script\s*> |
在含有 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 |
政策的內部名稱。 您可以選擇使用 |
不適用 | 必填 |
continueOnError |
將其設為 將其設為 |
false | 選用 |
enabled |
設為 設為 |
是 | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName> 元素
除了 name
屬性之外,您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。
<DisplayName>Policy Display Name</DisplayName>
預設 |
不適用 如果省略這個元素,系統會使用政策的 |
---|---|
存在必要性 | 選用 |
類型 | 字串 |
<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>
預設值: | 字串 |
外觀狀態: | 選用 |
類型: | 字串 |
有效值: |
下列任一關鍵字: |
<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 |
設為 |
是 | 選用 |
<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} |
build |
DuplicatePrefix |
RegularExpressionProtection {0}: Duplicate prefix {1} |
build |
EmptyJSONPathExpression |
RegularExpressionProtection {0}: Empty JSONPath expression |
build |
EmptyXPathExpression |
RegularExpressionProtection {0}: Empty XPath expression |
build |
InvalidRegularExpression |
RegularExpressionProtection {0}: Invalid Regular Expression {1}, Context {2} |
build |
JSONPathCompilationFailed |
RegularExpressionProtection {0}: Failed to compile jsonpath {1}. Context {2} |
build |
NONEmptyPrefixMappedToEmptyURI |
RegularExpressionProtection {0}: Non-empty prefix {1} cannot be mapped to empty
uri |
build |
NoPatternsToEnforce |
RegularExpressionProtection {0}: No patterns to enforce in {1} |
build |
NothingToEnforce |
RegularExpressionProtection {0}: at least one of URIPath, QueryParam, Header,
FormParam, XMLPayload, JSONPayload is mandatory |
build |
XPathCompilationFailed |
RegularExpressionProtection {0}: Failed to compile xpath {1}. Context {2} |
build |
錯誤變數
系統會在這項政策觸發錯誤時設定這些變數。詳情請參閱「關於政策錯誤的相關資訊」。
變數 | 地點 | 範例 |
---|---|---|
fault.name="fault_name" |
fault_name 是錯誤名稱,如上表所列。 | fault.name Matches "ThreatDetected" |
regularexpressionprotection.policy_name.failed |
policy_name 是擲回錯誤的政策的使用者指定名稱。 | regularexpressionprotection.Regular-Expressions-Protection-1.failed = true |