您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
優勢
擷取訊息中的資訊 (例如 URI 路徑、查詢參數、標頭、表單參數、變數、XML 酬載或 JSON 酬載),並根據預先定義的規則運算式評估該內容。如果任何指定的規則運算式評估為 true,系統會將訊息視為威脅並遭到拒絕。
影片
請觀看以下影片,進一步瞭解「規則運算式保護」政策。
影片 | 說明 |
---|---|
防範 SQL 插入攻擊 (新 Edge) | 請在 New Edge 體驗 UI 中使用規則運算式保護政策,防範 SQL 插入攻擊。 |
防範 SQL 插入攻擊 (傳統版 Edge) | 使用傳統版 Edge UI 中的規則運算式防護政策,防範 SQL 插入攻擊。 |
範例
GitHub
GitHub 上的規則運算式保護範例說明如何處理透過查詢參數發出的潛在 SQL 插入攻擊。此外,這個範例也示範如何設定一般的 400 錯誤狀態,以免駭客從回應中取得任何實用資訊。
JavaScript 包括攻擊防護
<RegularExpressionProtection name="JsonPathRegExProtection"> <DisplayName>Regular Expression Protection 1</DisplayName> <Source>request</Source> <JSONPayload escapeSlashCharacter="true"> <JSONPath> <Expression>$.</Expression> <Pattern><\s*script\b[^>]*>[^<]+<\s*\/\s*script\s*> </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>
上方範例說明如何使用 regexProtection 政策評估 JavaScript 包含攻擊的 JSON 酬載。具體來說,系統會對照 <JSONPath>
/<Expression>
擷取的內容與 <JSONPath>
/<Pattern>
中的規則運算式進行評估。
如果 <JSONPath>
/<Pattern>
中的規則運算式包含由 XML 保留的字元 (「, &、」、「<」或 .),您必須先以 XML 編碼,才能將其加入政策 XML 設定檔。舉例來說,在上述範例中,規則運算式 <\s*script\b[^>]*>[^<]+<\s*\/\s*script\s*>
已經過 XML 編碼為 <\s*script\b[^>]*>[^<]+<\s*\/\s*script\s*>
。
此外,如果您的規則運算式含有正斜線 (/),則必須將 <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 流量進行評估,找出遵循特定模式的常見內容層級威脅。
「規則運算式」簡稱「規則運算式」是一組在字串中指定模式的字串。規則運算式可讓您透過程式輔助的方式評估內容模式。例如,您可以使用規則運算式來評估電子郵件地址,以確保電子郵件地址結構正確。詳情請參閱 Java 教學課程中的「規則運算式」。
regexProtection 最常見用法,是評估 JSON 和 XML 酬載中是否含有惡意內容。
任何規則運算式都無法消除所有內容導向的攻擊,因此應該結合多種機制來啟用深入防禦機制。本節說明排除內容的建議模式。
排除模式範例
在政策的 XML 設定檔中,規則運算式必須採用 XML 編碼格式。
名稱 | 規則運算式 |
---|---|
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*> |
插入 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> 屬性
<RegularExpressionProtection async="false" continueOnError="false" enabled="true" name="Regular-Expression-Protection-1">
下表說明所有政策父項元素的通用屬性:
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
name |
政策的內部名稱。 您也可以選擇使用 |
不適用 | 需要 |
continueOnError |
如果設為 設為 |
false | 選用 |
enabled |
如要強制執行政策,請設為 設為 |
true | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName> 元素
除了 name
屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。
<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>/<命名空間> 元素
指定要在 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>/<命名空間>/<命名空間> 元素
指定要用於 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> <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 |
設為 |
true | 選用 |
<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>
預設: | 不適用 |
所在地: | 需要 |
類型: | 字串 |
錯誤參考資料
本節說明這項政策觸發錯誤時,傳回的錯誤代碼和訊息,以及 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} | build |
DuplicatePrefix | regexProtection {0}:前置字元重複 {1} | build |
EmptyJSONPathExpression | regexProtection {0}:空白 JSONPath 運算式 | build |
EmptyXPathExpression | regexProtection {0}:空白的 XPath 運算式 | build |
InvalidRegularExpression | regexProtection {0}:無效的規則運算式 {1},內容 {2} | build |
JSONPathCompilationFailed | regexProtection {0}:無法編譯 jsonpath {1}。內容{2} | build |
NONEmptyPrefixMappedToEmptyURI | regexProtection {0}:非空白前置字串 {1} 無法對應至空白 URI | build |
NoPatternsToEnforce | regexProtection {0}:{1} 中沒有可強制執行的模式 | build |
NothingToEnforce | RegularExpressionProtection {0}:至少須有一個 URIPath、QueryParam、Header、FormParam、XMLPayload 和 JSONPayload | build |
XPathCompilationFailed | regexProtection {0}:無法編譯 xpath {1}。內容{2} | build |
錯誤變數
系統會在這項政策觸發錯誤時設定這些變數。詳情請參閱「政策錯誤的注意事項」。
Variables | 地點 | 範例 |
---|---|---|
fault.name="fault_name" |
fault_name 是錯誤的名稱,如上表所列。 | fault.name Matches "ThreatDetected" |
regularexpressionprotection.policy_name.failed |
policy_name 是擲回錯誤的政策使用者指定的名稱。 | regularexpressionprotection.Regular-Expressions-Protection-1.failed = true |