RegularExpressionProtection ポリシー

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

概要

メッセージ（URI パス、クエリパラメータ、ヘッダー、フォームパラメータ、変数、XML ペイロード、JSON ペイロードなど）から情報を抽出し、その内容を事前定義済みの正規表現に対して評価します。指定された正規表現が true と評価されると、メッセージは脅威とみなされ、ポリシーはエラーになります。

このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

動画

RegularExpressionProtection ポリシー詳細については、次の動画をご覧ください。

動画	説明
SQL インジェクション攻撃からの保護	Apigee UI で RegularExpressionProtection ポリシーを使用して、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 エンコードを行う必要があります（たとえば、< を < に、> を > に置き換えます）。

また、正規表現にスラッシュ（/）が含まれる場合は、<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（文字データ）セクションを使用して正規表現をラップします。

RegularExpressionProtection ポリシーについて

Apigee では、実行時に API トラフィックに対して評価される正規表現を構成して、特定のパターンに従う一般的なコンテンツレベルの脅威を特定できます。

正規表現（regex）は、文字列内のパターンを指定する文字列のセットです。正規表現を使用すると、コンテンツがプログラムでパターンについて評価されるようになります。たとえば、メールアドレスが適切に構成されていることを確認するために正規表現を使用できます。詳細については、Java チュートリアルの正規表現をご覧ください。

RegularExpressionProtection の最も一般的な使用方法は、悪意のあるコンテンツに関する JSON や XML ペイロードの評価です。

コンテンツベースの攻撃をすべて排除できる正規表現はなく、複数のメカニズムを組み合わせて多層防御を実現する必要があります。このセクションでは、コンテンツを除外するための推奨パターンについて説明します。

除外パターンの例

正規表現は、ポリシーの XML 構成ファイルで XML エンコードされている必要があります。アンチパターン: RegularExpressionProtection ポリシーで最大量指定子を使用するもご覧ください。

名前	正規表現
SQL インジェクション	[\s]((delete)\|(exec)\|(drop\stable)\|(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 インジェクション	<\sscript\b[^>]>[^<]+<\s/\sscript\s> XML エンコード: <\sscript\b[^>]>[^<]+<\s/\sscript\s>

リクエストで XML または JSON ペイロードを使用して Content-Type ヘッダーを設定する

RegularExpressionProtection ポリシーのペイロードには、次の要素を含めることが可能です。

<XMLPayload> 要素: 情報を XML ペイロードから抽出し、提供される正規表現に対して評価する必要があることを指定します。
ポリシーで <XMLPayload> を使用する場合、リクエストの Content-Type ヘッダーは application/xml や text/xml などの XML コンテンツタイプにする必要があります。
<JSONPayload> 要素: 情報を JSON ペイロードから抽出し、提供される正規表現に対して評価する必要があることを指定します。
ポリシーで <JSONPayload> を使用する場合、リクエストの Content-Type ヘッダーは application/json などの JSON コンテンツタイプにする必要があります。

通常は、XML または JSON のいずれかを受け入れるように API を設計します。ただし、API が両方を受け入れるシナリオが存在することがあります。次に、<XMLPayload> 要素と <JSONPayload> 要素の両方を使用する RegularExpressionProtection ポリシーを定義します。Content-Type ヘッダーの値に基づいて特定のリクエストに適用される要素は一つだけです。

要素リファレンス

この要素リファレンスは、RegularExpressionProtection ポリシーの要素と属性について説明します。

注: このトピックの「REGEX PATTERN」は、目的のマッチングを行うために使用する有効な正規表現パターンを表します。Apigee では、Java 言語の java.util.regex パッケージのクラスと同じ正規表現ルールに従います。

<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 文字を超えることはできません。管理 UI プロキシエディタで `<DisplayName>` 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。	なし	必須
`continueOnError`	ポリシーが失敗したときにエラーを返す場合は、`false` に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、`true` に設定します。関連項目: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）現在のフローにおける障害処理	false	省略可
`enabled`	ポリシーを適用するには、`true` に設定します。ポリシーを無効にするには、`false` に設定します。ポリシーがフローに接続されている場合でも適用されません。	true	省略可
`async`	この属性は非推奨となりました。	false	非推奨

<DisplayName> 要素

管理 UI プロキシエディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<DisplayName>Policy Display Name</DisplayName>

デフォルト

デフォルト	なしこの要素を省略した場合、ポリシーの `name` 属性の値が使用されます。
要否	省略可
タイプ	文字列

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます。

要否省略可

タイプ文字列

<Source> 要素

情報を抽出する必要があるメッセージを示します。

<Source> 要素を省略すると、値はデフォルトで message になります。たとえば、<Source>message</Source> のようにします。message に設定すると、ポリシーはリクエストフローに接続されたときにリクエストメッセージをソースとして使用します。同様に、レスポンスフローに添付されたときは、レスポンスメッセージを使用します。

ソースメッセージを解決できない場合、またはメッセージ以外の型に解決される場合、ポリシーはエラーを返します。

<Source>response</Source>

デフォルト:	なし
プレゼンス:	省略可
型:	文字列

<IgnoreUnresolvedVariables> 要素

解決できない変数が検出されたときにエラーを返すかどうかを指定します。

false（デフォルト）に設定すると、解決できない変数が検出された場合にエラーが返されます。true に設定すると、未解決の変数は空の文字列（Null）として扱われます。

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

デフォルト:	false
プレゼンス:	省略可
型:	ブール値

<URIPath> 要素

情報をリクエスト URI パスから抽出し、提供される正規表現に対して評価する必要があることを指定します。一致する正規表現パターンを指定する <Pattern> 要素を少なくとも 1 つ指定する必要があります。

<URIPath>
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</URIPath>

デフォルト:	なし
プレゼンス:	省略可
型:	なし

<QueryParam> 要素

情報をリクエストクエリパラメータから抽出し、提供される正規表現に対して評価する必要があることを指定します。一致する正規表現パターンを指定する <Pattern> 要素を少なくとも 1 つ指定する必要があります。

<QueryParam name="a-query-param">
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</QueryParam>

デフォルト:	なし
プレゼンス:	省略可
型:	なし

属性

属性	説明	デフォルト	要否
name	提供される正規表現に対して評価するために情報を抽出する必要がある、リクエストクエリパラメータの名前。	なし	必須

<Header> 要素

情報をリクエストヘッダーとレスポンスヘッダーから抽出し、提供される正規表現に対して評価する必要があることを指定します。一致する正規表現パターンを指定する <Pattern> 要素を少なくとも 1 つ指定する必要があります。

<Header name="a-header">
  <Pattern>REGEX PATTERN</Pattern>
  <Pattern>REGEX PATTERN</Pattern>
</Header>

デフォルト:	なし
プレゼンス:	省略可
型:	なし

属性

属性	説明	デフォルト	要否
name	提供される正規表現に対して評価するために情報を抽出する必要がある、リクエストおよびリクエストヘッダーの名前。	なし	必須

<FormParam> 要素

情報をリクエストフォームパラメータから抽出し、提供される正規表現に対して評価する必要があることを指定します。一致する正規表現パターンを指定する <Pattern> 要素を少なくとも 1 つ指定する必要があります。

<FormParam name="a-form-param">
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</FormParam>

デフォルト:	なし
プレゼンス:	省略可
型:	なし

属性

属性	説明	デフォルト	要否
name	提供される正規表現に対して評価するために情報を抽出する必要がある、リクエストフォームパラメータの名前。	なし	必須

<Variable> 要素

特定の変数から情報を抽出し、提供される正規表現に対して評価する必要があることを指定します。

<Variable name="request.content">
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</Variable>

デフォルト:	なし
プレゼンス:	省略可
型:	なし

属性

属性	説明	デフォルト	要否
name	提供される正規表現に対して評価するために情報を抽出する必要がある、変数の名前。	なし	必須

<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>

デフォルト:	なし
プレゼンス:	省略可
型:	文字列

属性

属性	説明	デフォルト	要否
prefix	特定の名前空間を修飾するための接頭辞を提供します。	なし	必須

<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> 要素

目的の出力データ型を指定します。

通常は string または nodeset を使用します。xpath クエリの結果が最大で 1 つの値になることがわかっている場合、または最大で 1 つの値をチェックする場合は、string を使用します。xpath クエリが複数の値を返す可能性がある場合は、nodeset を指定してすべての値をチェックします。

たとえば、XPath 式 //*/@* について考えてみましょう。これは、すべての要素のすべての属性に一致します。Type として string を指定すると、Apigee はこのクエリの結果を単一の文字列に強制変換します。これは XML ドキュメント内のいずれかの要素に含まれる属性値の一つですが、どの属性とどの要素であるかは定義されません。Apigee は、その 1 つの属性の値のみに対してパターンマッチングを実行します。おそらく、これは望ましいことではありません。

逆に、その XPath 式の Type として nodeset を指定すると、Apigee は XML ドキュメント内の各要素の各属性値に対してパターンマッチングを実行します。

<XPath>
   <Expression>/apigee:Greeting/apigee:User</Expression>
   <Type>string</Type>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</XPath>

デフォルト:	string
要否:	省略可
型:	文字列
有効な値:	次のいずれかのキーワード: `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	`<JSONPath>`/`<Pattern>` の正規表現に含まれるスラッシュ（/）をエスケープするには、`true` に設定します。	true	省略可

<JSONPayload>/<JSONPath>/<Expression> 要素

変数に定義されている JSONPath 式を指定します。

<JSONPath>
   <Expression>$.store.book[*].author</Expression>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</JSONPath>

デフォルト:	なし
プレゼンス:	省略可
型:	文字列

<JSONPayload>/<JSONPath>/<Pattern> 要素

<JSONPath>
   <Expression>$.store.book[*].author</Expression>
   <Pattern>REGEX PATTERN</Pattern>
   <Pattern>REGEX PATTERN</Pattern>
</JSONPath>

デフォルト:	なし
要否:	必須
型:	文字列

エラーリファレンス

This section describes the error codes and messages returned and fault variables set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. If you want to capture an error and raise your own custom error, set the continueOnError="true" attribute on the policy root element. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Error Code	Message

`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}`

Deployment errors

Error Code	Message	Fix

`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 variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault, as listed in the table above.	`fault.name Matches "ThreatDetected"`
`regularexpressionprotection.policy_name.failed`	`policy_name` is the user-specified name of the policy that threw the fault.	`regularexpressionprotection.Regular-Expressions-Protection-1.failed = true`

RegularExpressionProtection ポリシー

概要

動画

サンプル

GitHub

JavaScript インクルード攻撃に対する防御

大文字と小文字を区別しないマッチング

フォーム パラメータのチェック

RegularExpressionProtection ポリシーについて

除外パターンの例

リクエストで XML または JSON ペイロードを使用して Content-Type ヘッダーを設定する

要素リファレンス

<RegularExpressionProtection> 属性

<DisplayName> 要素

<Source> 要素

<IgnoreUnresolvedVariables> 要素

<URIPath> 要素

<QueryParam> 要素

属性

<Header> 要素

属性

<FormParam> 要素

属性

<Variable> 要素

属性

<XMLPayload> 要素

<XMLPayload>/<Namespaces> 要素

<XMLPayload>/<Namespaces>/<Namespace> 要素

属性

<XMLPayload>/<XPath> 要素

<XMLPayload>/<XPath>/<Expression> 要素

<XMLPayload>/<XPath>/<Type> 要素

<XMLPayload>/<XPath>/<Pattern> 要素

<JSONPayload> 要素

属性

<JSONPayload>/<JSONPath>/<Expression> 要素

<JSONPayload>/<JSONPath>/<Pattern> 要素

エラー リファレンス

Runtime errors

Deployment errors

Fault variables

スキーマ

関連トピック

フォームパラメータのチェック

エラーリファレンス