Security Reports API

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

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

Apigee UI でセキュリティレポートを使用するだけでなく、Security Reports API を使用してすべてのセキュリティレポート機能を利用できます。このセクションでは、Security Reports API を使用する方法について説明します。

注: Apigee Analytics パイプラインへのデータフローには、平均で最大 15～20 分の遅延があります。その結果、終了時刻が過去 20 分未満のセキュリティレポートでは、誤った結果が返される場合があります。

API 呼び出しの例のパラメータ

次のセクションでは、Security Reports API を使用する API 呼び出しの例を示します。API 呼び出しには次のパラメータが含まれます。

ORG は、あなたの組織です。
ENV は、レポートを計算する環境です。
ENVGROUP は、環境を含む環境グループです。
REPORT_ID は、セキュリティレポートを作成するための呼び出しによって返されるレポート ID です。
$TOKEN は、OAuth アクセストークンの環境変数です。
timeRange はレポートの期間です。

セキュリティレポートを作成する

セキュリティレポートを作成するには、次のようなコマンドを入力します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

ここで、Query.json はクエリを定義するクエリテンプレートです。クエリテンプレートの例を以下に示します。

{
  "dimensions": [
    "ax_resolved_client_ip",
  ],
  "metrics": [
    {
      "aggregation_function": "count_distinct",
      "name": "bot"
    },
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    },
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

クエリには次のパラメータがあります。

指標
- bot。これにより、bot のソースとして識別された一意の IP アドレスの数がカウントされます。
  
  集計関数: count_distinct
- bot_traffic。bot のソースである IP アドレスからのリクエストの合計数。
  
  集計関数: sum
指標と集計関数をご覧ください。
ディメンション: ax_resolved_client_ipこれにより、レポート内の bot の数が、ソースの IP アドレスごとにグループ化されます。
ディメンションをご覧ください。
フィルタ: environment
groupByTimeUnit: minute
timeRange: last7days。期間をご覧ください。

この API 呼び出しは、Apigee UI を使用して作成された bot IP アドレスのレポートの例と同じレポートを返します。

期間

レポートの期間。timeRange フィールドは、次のいずれかの方法で設定できます。

どれだけ過去までレポートを表示するかを指定します。次の選択肢があります。
```
"timeRange": "{last60minutes/last24hours/last7days}"
```
レポートの開始時刻と終了時刻を次の形式で指定します。
```
"timeRange": {
        "start": "YYYY-MM-DDT00:00:00Z",
        "end": "YYYY-MM-DDT00:00:00Z"
        }
```
start と end の両方は過去のものである必要があり、レポートを作成する現在から 1 年以内にできます。

レスポンスの例

上記のクエリは、次のようなレスポンスを返します。

{
  "self": "/organizations/ORG/environments/ENV/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "enqueued",
  "created": "2021-08-06T22:28:28Z"
}

レスポンスには次のものが含まれます。

レポート ID。完了したレポートを取得するために使用できます。上記の例では、レポート ID は 3964675e-9934-4398-bff5-39dd93a67201 です。
"state": レポートジョブの状態。次のいずれかになります。
- enqueued: レポートジョブは作成されたばかりですが、まだ実行されていません。
- running: レポートジョブは実行中です。
- completed: レポートジョブが完了しました。この段階でレポートを表示できます。
- expired: レポートジョブの有効期限が切れたため、レポートを表示できなくなります。

レポートのステータスを取得する

レポートのステータスを取得するには、次のようなリクエストを送信します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID" \
       -X GET  -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

ここで REPORT_ID はレポート ID です。API 呼び出しの例のパラメータをご覧ください。

レスポンスには、レポートパラメータのサマリーとレポートの現在のステータスが含まれます。この例では、ステータスが "completed" であるため、レポートの結果を確認できます。

{
  "self": "/organizations/sense-staging-test/environments/local/securityReports/bd2f4fe0-a906-44c2-8dcb-2c618e4b565d",
  "state": "completed",
  "created": "2022-06-27T13:00:25-07:00",
  "updated": "2022-06-27T13:01:08-07:00",
  "result": {
    "self": "/organizations/sense-staging-test/environments/local/securityReports/bd2f4fe0-a906-44c2-8dcb-2c618e4b565d/result",
    "expires": "2022-07-04T13:01:08-07:00"
  },
  "resultRows": "848",
  "resultFileSize": "5.10 KB",
  "executionTime": "43 seconds",
  "queryParams": {
    "metrics": [
      "name:bot,func:count_distinct,alias:count_distinct_bot,op:,val:",
      "name:bot_traffic,func:sum,alias:sum_bot_traffic,op:,val:"
    ],
    "dimensions": [
      "ax_resolved_client_ip"
    ],
    "startTimestamp": "2022-06-20T20:00:25.098237292Z",
    "endTimestamp": "2022-06-27T20:00:25.098237292Z",
    "mimeType": "json",
    "timeUnit": "minute"
  },
  "displayName": "Sample Query Bot"
}

レポートを取得

セキュリティレポートをダウンロードするには、次のようなリクエストを送信します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H "Authorization: Bearer $TOKEN"

ここで REPORT_ID はレポート ID です。API 呼び出しの例のパラメータをご覧ください。

これにより、名前が OfflineQueryResult-{ID}.zip という形式のレポートを含むファイルが返されます。レポートを表示するには

OfflineQueryResult-{ID}.zip を解凍します。
「gzip -d QueryResults-{ID}*.json.gz」と入力します。
「cat QueryResults-{ID}*.json」と入力します

bot トラフィックの例

次の例では、bot_traffic に関するレポートを作成します。

{
  "dimensions": [
    "bot_reason"
  ],
   "metrics": [
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    }
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

クエリには次のパラメータがあります。

指標: bot_trafficこれは、bot ソースとして識別された IP アドレスからのリクエスト（1 分間隔）の合計です。

指標と集計関数をご覧ください。
ディメンション: bot_reasonbot_reason は、bot の検出ルールのあらゆる組み合わせにできます。bot が検出される場合、bot_reason は bot のトラフィックパターンが一致した検出ルールのサブセットで構成されます。

ディメンションをご覧ください。
フィルタ: environment
groupByTimeUnit: minute
timeRange: last7days

この API 呼び出しは、Apigee UI を使用して作成された bot IP アドレスのレポートの例と同じレポートを返します。

bot 検出データの遅延

bot 検出の処理遅延は平均で 15～20 分です。

環境グループのセキュリティレポートを作成する

セキュリティレポート API を使用すると、（環境だけでなく）環境グループのデータのレポートを作成できます。これを行うには、次のようなコマンドを入力します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

クエリテンプレート Query.json に次の行が含まれていることを確認します。

"envgroup_hostname": "ENVGROUP"

ここで、ENVGROUP は、環境を含む環境グループの名前です。環境グループの名前は、Apigee UI の [Admin] > [Environments] > [Groups] で確認できます。

注:

環境グループレベルの Report API は、集計関数 sum を使用する指標 message_count のみをサポートします。
環境グループレベルの Report API は bot_reason または incident_id のディメンションをサポートしていませんが、セキュリティレポート用の他のすべてのディメンションはサポートしています。

レポートのステータスを取得する

レポートのステータスを取得するには、次のようなコマンドを入力します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID" \
       -X GET  -H 'Content-type: application/json' -i \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

レポートリクエストの概要とレポートの現在の状態が返されます。レスポンスの例を次に示します。

{
  "self": "/organizations/ngsaas-runtime-staging/environments/test/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "completed",
  "created": "2021-08-06T15:28:28-07:00",
  "updated": "2021-08-06T15:28:40-07:00",
  "result": {
    "self": "/organizations/ngsaas-runtime-staging/environments/test/securityReports/3964675e-9934-4398-bff5-39dd93a67201/result",
    "expires": "2021-08-13T15:28:40-07:00"
  },
  "resultRows": "60",
  "resultFileSize": "0.31 KB",
  "executionTime": "11 seconds",
  "queryParams": {
    "metrics": [
      "name:message_count,func:sum,alias:sum_message_count,op:,val:"
    ],
    "dimensions": [
      "apiproxy"
    ],
    "startTimestamp": "2021-08-06T21:28:28.570770570Z",
    "endTimestamp": "2021-08-06T22:28:28.570770570Z",
    "mimeType": "json",
    "timeUnit": "minute"
  }
}

ステータスが "completed" であるため、次に説明するように、レポートを表示できます。

セキュリティレポートの表示

セキュリティレポートを表示するには、次のようなコマンドを入力します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

これにより、名前が OfflineQueryResult-{ID}.zip という形式のレポートを含むファイルが返されます。レポートを表示するには

OfflineQueryResult-{ID}.zip を解凍します。
「gzip -d QueryResults-{ID}*.json.gz」と入力します。
「cat QueryResults-{ID}*.json」と入力します

指標と集計関数

次の指標と集計関数を使用して指標から統計情報を計算し、レポートで表示できます。

指標	説明	`Aggregation function`
`bot`	1 分間隔で検出された bot の個別の IP アドレス数。	`count_distinct`
`bot_traffic`	1 分間隔で検出された bot の IP アドレスからのメッセージ数。	`sum`
`message_count`	Apigee によって 1 分間隔で処理された API 呼び出しの合計数。注: `message_count` は、同じレポート内の他の指標と一緒に使用できません。	`sum`
`response_size`	返されるレスポンスペイロードのサイズ（バイト単位）。	`sum`、`avg`、`min`、`max`
`bot_first_detected`	bot が最初に検出された日時。API を介してのみ利用可能です。	`min`
`bot_last_detected`	bot が最後に検出された日時。API を介してのみ利用可能です。	`max`

ディメンション

ディメンションによって、関連するデータのサブセットに基づいて、指標値をまとめてグループ化できます。次の表に、Advanced API Security に固有のディメンションを示します。

ディメンション	説明
`bot_reason`	セキュリティ検出ルールは任意の組み合わせが可能です。`bot_reason` は、bot のトラフィックパターンが一致した検出ルールのサブセットで構成されます。
`incident_id`（プレビュー版）	セキュリティインシデントの UUID。Incidents API の呼び出しで返されます。例: 詳細または特定のインシデントを取得するをご覧ください。
`security_action`	セキュリティアクション。使用できる値は、`ALLOW`、`DENY`、`FLAG` です。
`security_action_name`	セキュリティアクションの名前。
`security_action_headers`	フラグセキュリティアクションのクエリに使用できるヘッダー。

注: bot_reason と incident_id は次の指標でのみ機能します。

bot
bot_traffic
response_size

前述のディメンションに加えて、Advanced API Security では次のディメンションもサポートしています。

access_token
api_product
apiproxy
ax_dn_region
ax_edge_execution_fault_code
ax_geo_city
ax_geo_continent
ax_geo_country
ax_geo_region
ax_isp
ax_resolved_client_ip
ax_ua_agent_family
ax_ua_agent_type
ax_ua_agent_version
ax_ua_agent_category
ax_ua_os_family
bot_reason
client_id
developer
developer_app
developer_email
envgroup_hostname
environment
incident_id（プレビュー版）
proxy_basepath
proxy_pathsuffix
request_uri
request_verb
response_status_code
target_host
target_url
useragent

セキュリティレポートに関する制限事項

セキュリティレポートに関する制限事項をご覧ください。

Security Reports API

API 呼び出しの例のパラメータ

セキュリティ レポートを作成する

期間

レスポンスの例

レポートのステータスを取得する

レポートを取得

bot トラフィックの例

bot 検出データの遅延

環境グループのセキュリティ レポートを作成する

レポートのステータスを取得する

セキュリティ レポートの表示

指標と集計関数

ディメンション

セキュリティ レポートに関する制限事項

セキュリティレポートを作成する

環境グループのセキュリティレポートを作成する

セキュリティレポートの表示

セキュリティレポートに関する制限事項