Security Scores API と Security Profiles API

このページは Apigee と Apigee ハイブリッドに適用されます。

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

セキュリティスコアとセキュリティプロファイルは、Apigee UI で見るだけでなく、Security scores and profiles API を使用してアクセスすることもできます。このページでは、Security Scores API と Profiles API の使用例を紹介します。

API 使用時のセキュリティスコアの制限

Security Scores API と Profiles API からセキュリティスコアを使用する場合については、次の制限事項があります。

サポートされている JSON の入力フィールド:
- timeRange: 期間の長さは最大 14 日にすることができ、期間の startTime と endTime は過去 90 日以内であることが必要です。期間をご覧ください。
- filters: API でサポートされているフィルタをご覧ください。
- pageSize: 1 ページで返されるサブコンポーネントの最大数: 100。
複数の入力フィルタはサポートされていません。
レスポンスの影響フィールドはサポートされていません。影響フィールドは、この推奨事項が総スコアに与える潜在的な影響です。これは、この推奨事項がスコアを改善することが重要であることを示しています。

API からの使用に固有ではない一般的なセキュリティスコアの制限事項については、セキュリティスコアの制限をご覧ください。

データの遅延

Advanced API Security セキュリティスコアのデータには、データの処理方法により、次のような遅延が発生します。

組織で Advanced API Security を有効にした場合、既存のプロキシとターゲットのスコアが環境に反映されるまでに最長で 6 時間かかる可能性があります。
環境のプロキシ（デプロイとデプロイ解除）とターゲット（作成、更新、削除）に関連する新しいイベントが、環境のスコアに反映されるまでに最長で 6 時間かかる場合があります。
Apigee Analytics パイプラインへのデータフローには、平均で最大 15～20 分の遅延があります。その結果、ソーススコアの不正使用データの処理には、15～20 分程度の遅延が発生します。

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

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

ORG は、あなたの組織です。
ENV は、スコアを計算する環境です。
ENVGROUP は、環境を含む環境グループです。
PROFILE_ID は、プロファイルの名前です。PROFILE_ID は、default または作成したカスタムプロファイルの名前です。
PROFILE_ID は 1～63 文字にする必要があります。小文字、0～9 の数字、ハイフンを使用できます。最初の文字は小文字にする必要があります。最後の文字は小文字か数字にする必要があります。
$TOKEN は、OAuth アクセストークンの環境変数です。
timeRange は、スコアの期間です。

期間

この期間のデータについて、セキュリティスコアが計算されます。期間を設定するには、スコアの開始日時と終了日時を次の形式で指定します。

"timeRange":
  {
    "startTime": "YYYY-MM-DDT00:00:00Z",
    "endTime": "YYYY-MM-DDT00:00:00Z"
  }

startTime と endTime はどちらも過去 90 日以内である必要があります。

デフォルトのセキュリティプロファイルを使用する

次の例では、デフォルトのセキュリティプロファイルを使用する方法を示します。例で使用されているパラメータについては、サンプルの API 呼び出しのパラメータをご覧ください。

デフォルトのセキュリティプロファイルを環境に接続する

セキュリティスコアを表示するには、セキュリティを評価する環境にプロファイルを接続する必要があります。デフォルトのセキュリティプロファイルを環境に接続するには、次のコマンドを使用します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments" \
       -X POST \
       -d '{"name": "ENV"}' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

注: パラメータ securityProfileRevisionId は非推奨になりました。このパラメータを API 呼び出しに設定すると、Advanced API Security ではパラメータの値に関係なく、プロファイルの最新リビジョンが使用されます。

デフォルトのセキュリティプロファイルの定義を取得する

デフォルトのセキュリティプロファイルの定義を取得するには、次のコマンドを入力します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default" \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

デフォルトのセキュリティプロファイルを環境から切断する

環境からデフォルトのプロファイルを接続解除する必要がある場合は、次のようにします。

  curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments/ENV" \
         -X DELETE 
         -H 'Content-type: application/json' \
         -H "Authorization: Bearer $TOKEN"

カスタムセキュリティプロファイルを使用する

次のいずれかの方法で、API 呼び出しでカスタムセキュリティプロファイルを作成できます。

呼び出しの本文でプロファイルを明示的に定義します。
プロファイル定義を含む JSON ファイルを呼び出しに関連付けます。

次のセクションでは、この両方の方法の例を紹介します。例で使用されているパラメータについては、サンプルの API 呼び出しのパラメータをご覧ください。

サンプル API 呼び出しの次のフィールドで、カスタムプロファイルを指定します。

description: カスタムプロファイルの説明。

profileConfig: カスタムプロファイルに含めるカテゴリのリスト。これは、次のセキュリティカテゴリの任意のサブセットになります。

abuse
authorization
cors
mtls
mediation
threat

API 呼び出しの本文でプロファイルを定義する

API 呼び出しの本文でカスタムプロファイルを定義するには、次のようなコマンドを入力します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles?security_profile_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
         "description":"test custom profile", 
         "profileConfig" : {
           "categories":[
             {"cors":{}},
             {"threat":{}}
           ]
         }
       }'

これにより、カテゴリ cors と脅威を含むカスタムプロファイルが作成され、次のレスポンスが返されます。

{
  "name": "PROFILE_ID",
  "revisionId": "1",
  "revisionCreateTime": "2023-07-17T18:47:08Z",
  "revisionUpdateTime": "2023-07-17T18:47:08Z",
  "scoringConfigs": [
    {
      "title": "json",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat/json",
      "description": "Check if JSONThreatProtection policy is configured."
    },
    {
      "title": "xml",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat/xml",
      "description": "Check if XMLThreatProtection policy is configured."
    },
    {
      "title": "cors",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors",
      "description": "Check if CORS policy is configured."
    }
  ],
  "maxScore": 1200,
  "minScore": 200,
  "profileConfig": {
    "categories": [
      {
        "cors": {}
      },
      {
        "threat": {}
      }
    ]
  },
  "description": "test custom profile"
  }

API 呼び出しに JSON ファイルを関連付けてプロファイルを定義する

プロファイルを定義する JSON ファイルを API 呼び出しに関連付けて、カスタムセキュリティプロファイルを定義することもできます。例として、次の JSON ファイルをまず作成します。

{
  "description": "test custom profile", 
  "profileConfig" : {
    "categories":[
      {"cors":{}}, 
      {"threat" :{}},
    ]
  }
}

カテゴリ cors と脅威を含むプロファイルを定義します。その後、次のように、これらのカテゴリに基づいてプロファイルを作成できます。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles?security_profile_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -d @create_profile.json

ここで、create_profile.json は前述の JSON ファイルの名前です。

カスタムセキュリティプロファイルの定義を取得する

カスタムセキュリティプロファイルの定義を取得するには、次のようなコマンドを入力します。

  curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
         -X GET \
         -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json"

環境からカスタムセキュリティプロファイルを切断する

環境からカスタムセキュリティプロファイルを切断するには、次のようなコマンドを入力します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json"

カスタムセキュリティプロファイルを削除する

カスタムセキュリティプロファイルを削除するには、次のようなコマンドを入力します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json"

環境のスコアを取得する

以降のセクションでは、環境のスコアを取得する例を示します。例で使用されているパラメータについては、サンプルの API 呼び出しのパラメータをご覧ください。

環境のすべてのスコアを取得する

環境のすべてのスコアを取得するには、次のようなコマンドを入力します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              }
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

リクエストとレスポンスの説明については、computeEnvironmentScores のリファレンスページをご覧ください。

環境のソーススコアを取得する

環境のソーススコアを取得するには、次のようなコマンドを入力します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/source"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

環境のソースの不正行為スコアを取得する

環境のソースにおける不正行為スコアを取得するには、次のようなコマンドを入力します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

環境にあるすべてのプロキシのスコアを取得する

環境内のすべてのプロキシのスコアを取得するには、次のようなコマンドを入力します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

環境にある特定のプロキシのスコアを取得する

環境内の特定のプロキシのスコアを取得するには、次のようなコマンドを入力します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

ここで、PROXY は、スコアを取得するプロキシです。

環境にある特定のターゲットのスコアを取得する

環境内の特定のターゲットのスコアを取得するには、次のようなコマンドを入力します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/target@TARGET"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

API でサポートされているフィルタ

次の表に、API でサポートされているフィルタと、そのコンポーネントパスを示します。コンポーネントパスでは、次のように変数を置き換えます。

ORG: あなたの組織。
ENV: スコアを表示する環境。
PROXY_NAME: プロキシの名前。

フィルタ	コンポーネントパス
環境スコア	`/org@ORG/envgroup@ENVGROUP/env@ENV`
基盤となるすべてのコンポーネントのソーススコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/source`
不正行為スコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse`
すべてのプロキシのスコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies`
特定のプロキシのスコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME`
特定のプロキシのポリシースコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies` `/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual`
特定のプロキシのメディエーションポリシースコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/mediation`
特定のプロキシのセキュリティポリシースコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security`
特定のプロキシの認証ポリシースコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/auth`
特定のプロキシの CORS ポリシースコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/cors`
特定のプロキシの脅威ポリシースコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/threat`
環境内のすべてのプロキシのポリシースコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies` `/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual`
環境内のすべてのプロキシのメディエーションポリシースコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/mediation`
環境内のすべてのプロキシのセキュリティポリシースコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security`
環境内のすべてのプロキシの認証ポリシースコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/auth`
環境内のすべてのプロキシの CORS ポリシースコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors`
環境内のすべてのプロキシの脅威ポリシースコア	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat`

Security Scores API と Security Profiles API

API 使用時のセキュリティ スコアの制限

データの遅延

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

期間

デフォルトのセキュリティ プロファイルを使用する

デフォルトのセキュリティ プロファイルを環境に接続する

デフォルトのセキュリティ プロファイルの定義を取得する

デフォルトのセキュリティ プロファイルを環境から切断する

カスタム セキュリティ プロファイルを使用する

API 呼び出しの本文でプロファイルを定義する

API 呼び出しに JSON ファイルを関連付けてプロファイルを定義する

カスタム セキュリティ プロファイルの定義を取得する

環境からカスタム セキュリティ プロファイルを切断する

カスタム セキュリティ プロファイルを削除する

環境のスコアを取得する

環境のすべてのスコアを取得する

環境のソーススコアを取得する

環境のソースの不正行為スコアを取得する

環境にあるすべてのプロキシのスコアを取得する

環境にある特定のプロキシのスコアを取得する

環境にある特定のターゲットのスコアを取得する

API でサポートされているフィルタ

API 使用時のセキュリティスコアの制限

デフォルトのセキュリティプロファイルを使用する

デフォルトのセキュリティプロファイルを環境に接続する

デフォルトのセキュリティプロファイルの定義を取得する

デフォルトのセキュリティプロファイルを環境から切断する

カスタムセキュリティプロファイルを使用する

カスタムセキュリティプロファイルの定義を取得する

環境からカスタムセキュリティプロファイルを切断する

カスタムセキュリティプロファイルを削除する