このページは 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\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 ヘッダーを設定する
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 ポリシーの要素と属性について説明します。
<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 |
ポリシーの内部名。 管理 UI プロキシ エディタで |
なし | 必須 |
continueOnError |
ポリシーが失敗したときにエラーを返す場合は、 ポリシーが失敗した後もフローの実行を続行する場合は、 |
false | 省略可 |
enabled |
ポリシーを適用するには、 ポリシーを無効にするには、 |
true | 省略可 |
async |
この属性は非推奨となりました。 |
false | 非推奨 |
<DisplayName> 要素
管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。
<DisplayName>Policy Display Name</DisplayName>
| デフォルト |
なし この要素を省略した場合、ポリシーの |
|---|---|
| 要否 | 省略可 |
| タイプ | 文字列 |
<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 |
| 要否: | 省略可 |
| 型: | 文字列 |
| 有効な値: |
次のいずれかのキーワード: |
<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>
| デフォルト: | なし |
| 要否: | 必須 |
| 型: | 文字列 |
エラー リファレンス
このセクションでは、このポリシーでエラーをトリガーしたときに返されるエラーコードとメッセージ、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 |