Security Scores API と Security Profiles API

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

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

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

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

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

  • サポートされている JSON の入力フィールド:
    • timeRange: 期間の長さは最大 14 日にすることができ、期間の startTimeendTime は過去 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"
  }

startTimeendTime はどちらも過去 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"

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

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

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