Security Scores API と Security Profiles API

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

Apigee Edge のドキュメントはこちらをご覧ください。

概要

このページでは、API を使用してリスク評価のセキュリティスコアとセキュリティプロファイル（単に「プロファイル」とも呼ばれます）を管理する方法について説明します。このページでは、API リクエストの例を示します。

制限事項などのリスク評価機能の概要と UI の使用方法については、リスク評価の概要と UI をご覧ください。

リスク評価 v2 API の例

v2 API の例のパラメータ

このセクションの例では、次のパラメータを使用できます。

ORG は、あなたの組織です。
ENV は、スコアを計算する環境です。
PROFILE_ID は、プロファイルの名前です。PROFILE_ID は、google-default または作成したカスタムプロファイルの名前です。
PROFILE_DESC（省略可）は、プロファイルの説明です。プロファイルの説明は人間が読み取れる形式にして、他のプロファイルと区別するのに十分な情報を提供する必要があります。
PROXY_NAME: プロキシの名前です。
$TOKEN は、OAuth アクセストークンの環境変数です。

バッチセキュリティ評価の結果を取得する

Security Admin ロールまたは Security Viewer ロールを持つユーザーには、アドホックのリスク評価コンピューティングを実施する権限が付与されています。セキュリティプロファイル、スコープ（Apigee 環境）、評価するリソースを指定する必要があります。リソースを include_all_resources: true にすると、スコープ内のすべてのリソースでコンピューティングできます。一部のリソースでのみ実施することもできます。この機能の詳細については、Apigee Management API リファレンスドキュメントの securityAssessmentResults.batchCompute をご覧ください。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityAssessmentResults:batchCompute" \
  -X POST \
  -H "Authorization: Bearer $TOKEN"
  -H 'Content-type: application/json' \
  -d '{
    "profile": "google-default",
    "scope": "ENV",
    "include_all_resources": {}
  }'

リクエストに対するレスポンスは次のようになります。

  {
    "security_assessment_results": [
      {
        "resource": {
          "name" : "my-proxy-1",
          "revision": "1"
        },
        "create_time": "2023-11-22T03:04:05Z",
        "score": 99,
        "severity": "low",
        "failed_assessment_by_weight": {
          "MINOR": 1
        },
        "assessment_recommendations": {
          "CORS-Check": {
            "weight": "MINOR",
            "recommendations": [
              {
                "description": "add CORS policy to your proxy",
                "learn_more_link": "https://example.com"
              }
            ]
          }
        }
      },
      {
        "resource": {
          "name" : "my-proxy-2",
          "revision": "3"
        },
        "create_time": "2023-11-22T03:04:05Z",
        "score": 100,
        "severity": "low",
        "resource_revision": "1",
        "failed_assessment_by_weight": {
          "MINOR": 0
        },
        "assessment_recommendations": {}
      }
    ]
  }

セキュリティプロファイルを管理する

このセクションでは、API を使用してセキュリティプロファイルを管理する例を示します。ただし、この例がすべてではありません。詳細については、securityProfilesV2 API リファレンスドキュメントをご覧ください。

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

次のコマンドで、プロジェクトのすべてのセキュリティプロファイルの情報を取得します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2" \
      -H "Authorization: Bearer $TOKEN"

次のコマンドで、特定のセキュリティプロファイルのメタデータを取得します。google-default プロファイルとカスタムプロファイルの情報を取得するために使用できます。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID" \
      -H "Authorization: Bearer $TOKEN"

新しいカスタムセキュリティプロファイルを作成する

新しいカスタムセキュリティプロファイルを作成するには、次のようなコマンドを使用します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2?security_profile_v2_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H 'Content-type: application/json' \
       -d '{
          "description": "PROFILE_DESC",
          "profile_assessment_configs": {
            "auth-policies-check": {"weight": "MINOR"},
            "threat-policies-check": {"weight": "MODERATE"}
          }
       }'
}

既存のカスタムセキュリティプロファイルを更新する

既存のプロファイルを更新するには、次のようなコマンドを使用します。

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID?update_mask=UPDATE_MASK" \
       -X PATCH \
       -H "Authorization: Bearer $TOKEN" \
       -H 'Content-type: application/json' \
       -d '{"description": "PROFILE_DESC"}'

ここで、UPDATE_MASK（ある場合）は、description、profile_assessment_configs、description,profile_assessment_configs、または *（すべて）のいずれかにすることができます。* 更新マスクを指定すると、このリクエストですべてのフィールドが更新されます。リクエストに値が含まれていない場合、その値は削除される可能性があります。

update_mask を省略すると、更新リクエストで指定されたフィールドのみが更新されます。

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

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

curl "https://apigee.googleapis.com/v1/organizations/$ORG/securityProfilesV2/PROFILE_ID" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN"

リスク評価 v1

このセクションでは、リスク評価 v1 API の情報と例を示します。

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

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

サポートされている JSON の入力フィールド:
- timeRange: computEnvironmentScores API リファレンスに記載されている条件によって値が制限されます。
- filters: API でサポートされているフィルタをご覧ください。
- pageSize: 1 ページで返されるサブコンポーネントの最大数: 100。
複数の入力フィルタはサポートされていません。
レスポンスの影響フィールドはサポートされていません。影響フィールドは、この推奨事項が総スコアに与える潜在的な影響です。これは、この推奨事項がスコアを改善することが重要であることを示しています。

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

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

以降のセクションでは、API 呼び出しの例を示します。次のパラメータを使用できます。

ORG は、あなたの組織です。
ENV は、スコアを計算する環境です。
ENVGROUP は、環境を含む環境グループです。
PROFILE_ID は、プロファイルの名前です。PROFILE_ID は、default または作成したカスタムプロファイルの名前にすることができます。
PROFILE_ID は 1～63 文字にする必要があります。小文字、0～9 の数字、ハイフンを使用できます。最初の文字は小文字にする必要があります。最後の文字は小文字か数字にする必要があります。
PROXY_NAME: プロキシの名前です。
RESOURCES は次のいずれかになります。
- {"all_resources":true}: スコープ内のすべてのリソースです。
- {"includes": { "resources": [{"name": "<proxy-name>"}]}: 指定されたプロキシをモニタリングします。たとえば、my-proxy-1 というプロキシをモニタリングするには、{"includes": { "resources": [{"name": "my-proxy-1"}]} にします。
- {"excludes": { "resources": [{"name": "<proxy-name>"}]}: 指定されたプロキシを除くすべてのリソースをモニタリングします。たとえば、my-proxy-1 というプロキシを除くすべてのリソースをモニタリングするには、{"excludes": { "resources": [{"name": "my-proxy-1"}]} にします。
$TOKEN は、OAuth アクセストークンの環境変数です。
timeRange は、スコアの期間です。

リスク評価 v1 API の例

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

次の表に、API でサポートされているフィルタと、そのコンポーネントパスを示します。

フィルタ	コンポーネントパス
環境スコア	`/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`

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

次の例では、デフォルトのセキュリティプロファイルを使用する方法を示します。例で使用されているパラメータについては、サンプルの 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"

Security Scores API と Security Profiles API

概要

リスク評価 v2 API の例

v2 API の例のパラメータ

バッチ セキュリティ評価の結果を取得する

セキュリティ プロファイルを管理する

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

新しいカスタム セキュリティ プロファイルを作成する

既存のカスタム セキュリティ プロファイルを更新する

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

リスク評価 v1

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

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

リスク評価 v1 API の例

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

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

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

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

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

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

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

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

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

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

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

環境のスコアを取得する

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

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

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

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

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

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

バッチセキュリティ評価の結果を取得する

セキュリティプロファイルを管理する

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

新しいカスタムセキュリティプロファイルを作成する

既存のカスタムセキュリティプロファイルを更新する

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

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

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

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

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

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

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

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

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

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