分析情報の管理

Recommender は推奨事項を提案するだけでなく、機械学習(ML)を使用して詳細な分析情報も提供します。この分析情報により、リソースで特徴的な使用パターンを確認できます。たとえば、プロジェクトの権限の使用状況に関する追加情報を収集できます。また、未使用のサービス アカウントを特定することもできます。一部の分析情報は、関連付けられたレコメンデーションの根拠を示すため、レコメンデーションにリンクされています。

Identity and Access Management(IAM)は次のタイプの分析情報を提供します。

  • ポリシーの分析情報: プロジェクト内の権限の使用状況に関する ML ベースの分析結果。
  • サービス アカウントの分析情報: プロジェクト内のサービス アカウントに関する分析結果(過去 90 日間未使用のサービス アカウントなど)。

始める前に

必要な権限

分析情報を使用するために必要な権限は、実行する操作によって異なります。

分析情報の表示権限

分析情報を表示するには、次の権限を含むロールが必要です。insight-type は、iamPolicyInsights または iamServiceAccountInsights です。

  • recommender.insight-type.get
  • recommender.insight-type.list

これらの権限を最小権限の原則に従って取得するには、管理者に次のロールのいずれかを付与するよう依頼してください。

  • IAM Recommender 閲覧者(roles/recommender.iamViewer
  • IAM セキュリティ審査担当者(roles/iam.securityReviewer

あるいは、必要な権限を含む別のロールを管理者に付与してもらうこともできます。たとえば、カスタムロールや、許容範囲がより広い事前定義ロールなどです。

分析情報の変更権限

分析情報を変更するには、次の権限を含むロールが必要です。insight-type は、iamPolicyInsights または iamServiceAccountInsights です。

  • recommender.insight-type.get
  • recommender.insight-type.list
  • recommender.insight-type.update

最小権限の原則に従ってこれらの権限を取得するには、管理者に IAM Recommender 管理者ロール(roles/recommender.iamAdmin)を付与するよう依頼してください。

あるいは、必要な権限を含む別のロールを管理者に付与してもらうこともできます。たとえば、カスタムロールや、許容範囲がより広い事前定義ロールなどです。

分析情報の一覧表示

プロジェクトの特定のタイプの分析情報を一覧表示するには、次のいずれかの方法を使用します。

gcloud

gcloud recommender insights list コマンドを使用して、プロジェクトの特定のタイプの分析情報をすべて表示します。

insight-type-id は、一覧を取得する分析情報タイプで置き換えます。ポリシーの分析情報の場合は google.iam.policy.Insight、サービス アカウントの分析情報の場合は google.iam.serviceAccount.Insight を使用します。

gcloud recommender insights list --insight-type=insight-type-id \
    --location=global

出力には、プロジェクトの特定のタイプの分析情報が一覧表示されます。たとえば、プロジェクトのポリシーに関する分析情報を一覧表示すると、次のような結果が出力されます。

INSIGHT_ID                            LOCATION  INSIGHT_TYPE               CATEGORY  INSIGHT_STATE  LAST_REFRESH_TIME
07841f74-02ce-4de8-bbe6-fc4eabb68568  global    google.iam.policy.Insight  SECURITY  ACCEPTED       2020-07-12T07:00:00Z
0d3ce433-f067-4e78-b6ae-03d7d1f6f040  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
0e2cc488-38fb-4b9b-942c-cfe06a0ab88f  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
12b557be-d48f-49cf-a0b0-b3b73a178edf  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
279ef748-408f-44db-9a4a-1ff8865b9839  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
29a4553d-9ffb-4508-9f13-77f40fc4e8b6  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
2a00a91a-3e37-4dca-81f7-fb607d18053f  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
2baea818-df89-4ab3-8a48-0e752459d816  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
4a59da9d-cde8-46cc-9c68-6980487175fb  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
78fee8d9-c25c-4070-9f1b-ae5e4a4a164b  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z

REST

Recommender API の insights.list メソッドを使用して、プロジェクトの特定のタイプの分析情報を一覧表示します。

後述のリクエストのデータを使用する前に、次のように置き換えます。

  • project-id: Google Cloud プロジェクト ID。
  • insight-type-id: 一覧表示する分析情報のタイプ。ポリシーの分析情報の場合は、google.iam.policy.Insight を使用します。サービス アカウントの分析情報の場合は、google.iam.serviceAccount.Insight を使用します。

HTTP メソッドと URL:

GET https://recommender.googleapis.com/v1/projects/project-id/locations/global/insightTypes/insight-type-id/insights

リクエストを送信するには、次のいずれかのオプションを展開します。

レスポンスには、プロジェクトの特定のタイプの分析情報が一覧表示されます。たとえば、プロジェクト内のポリシーに関する分析情報の一覧を取得できます。

{
  "insights": [
    {
      "name": "projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/07841f74-02ce-4de8-bbe6-fc4eabb68568",
      "description": "0 of the permissions in this role binding were used in the past 90 days.",
      "content": {
        "role": "roles/viewer",
        "member": "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com",
        "condition": {
          "expression": "",
          "title": "",
          "description": "",
          "location": ""
        },
        "exercisedPermissions": [],
        "inferredPermissions": []
      },
      "lastRefreshTime": "2020-07-12T07:00:00Z",
      "observationPeriod": "7776000s",
      "stateInfo": {
        "state": "ACTIVE"
      },
      "category": "SECURITY",
      "associatedRecommendations": [
        {
          "recommendation": "projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/b1932220-867d-43d1-bd74-fb95876ab656"
        }
      ],
      "targetResources": [
        "//cloudresourcemanager.googleapis.com/projects/1234567890"
      ],
      "insightSubtype": "PERMISSIONS_USAGE",
      "etag": "\"b153ab487e4ae100\""
    },
    {
      "name": "projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/f4292f55-105b-4744-9dc3-fcacf59685bb",
      "description": "4 of the permissions in this role binding were used in the past 90 days.",
      "content": {
        "role": "roles/owner",
        "member": "serviceAccount:my-service-account2@my-project.iam.gserviceaccount.com",
        "condition": {
          "expression": "",
          "title": "",
          "description": "",
          "location": ""
        },
        "exercisedPermissions": [
          {
            "permission": "iam.roles.create"
          },
          {
            "permission": "iam.roles.delete"
          },
          {
            "permission": "iam.roles.list"
          },
          {
            "permission": "iam.roles.update"
          }
        ],
        "inferredPermissions": []
      },
      "lastRefreshTime": "2020-07-12T07:00:00Z",
      "observationPeriod": "7776000s",
      "stateInfo": {
        "state": "ACTIVE"
      },
      "category": "SECURITY",
      "associatedRecommendations": [
        {
          "recommendation": "projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/6ab16c1d-edce-45e5-8d82-570fdd49892a"
        }
      ],
      "targetResources": [
        "//cloudresourcemanager.googleapis.com/projects/1234567890"
      ],
      "insightSubtype": "PERMISSIONS_USAGE",
      "etag": "\"49bb705553338fc3\""
    }
  ]
}

分析情報のコンポーネントの詳細については、このページの分析情報の確認をご覧ください。

単一の分析情報の取得

1 つの分析情報に関する詳細(分析情報の説明、ステータス、レコメンデーションなど)を取得するには、次のいずれかの方法を使用します。

gcloud

分析情報の ID を指定して gcloud recommender insights describe コマンドを実行すると、1 つの IAM の分析結果に関する情報を表示できます。

このサンプルを使用する前に、次のように置き換えます。

  • insight-id: 表示する分析情報の ID。ID を確認するには、プロジェクトの分析情報を一覧表示します。

  • insight-type-id: 表示する分析情報のタイプ。ポリシーの分析情報の場合は google.iam.policy.Insight、サービス アカウントの分析情報の場合は google.iam.serviceAccount.Insight を使用します。

gcloud recommender insights describe insight-id \
    --insight-type=insight-type-id --location=global

出力に分析情報の詳細が表示されます。たとえば、次の分析情報は、my-service-account@my-project.iam.gserviceaccount.com が過去 90 日間に閲覧者のロール(roles/viewer)の権限をまったく使用していないことを示しています。

associatedRecommendations:
- recommendation: projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/0573b702-96a5-4622-a916-c762e7b0731f
category: SECURITY
content:
  condition:
    description: ''
    expression: ''
    location: ''
    title: ''
  exercisedPermissions: []
  inferredPermissions: []
  member: serviceAccount:my-service-account@my-project.iam.gserviceaccount.com
  role: roles/viewer
description: 0 of the permissions in this role binding were used in the past 90 days.
etag: '"d3cdec23cc712bd0"'
insightSubtype: PERMISSIONS_USAGE
lastRefreshTime: '2020-07-11T07:00:00Z'
name: projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/0d3ce433-f067-4e78-b6ae-03d7d1f6f040
observationPeriod: 7776000s
stateInfo:
  state: ACTIVE
targetResources:
- //cloudresourcemanager.googleapis.com/projects/1234567890

分析情報のコンポーネントの詳細については、このページの分析情報の確認をご覧ください。

REST

1 つの分析情報を取得するには、Recommender API の insights.get メソッドを使用します。

後述のリクエストのデータを使用する前に、次のように置き換えます。

  • project-id: Google Cloud プロジェクト ID。
  • insight-type-id: 表示する分析情報のタイプ。ポリシーの分析情報の場合は、google.iam.policy.Insight を使用します。サービス アカウントの分析情報の場合は、google.iam.serviceAccount.Insight を使用します。
  • insight-id: 表示する分析情報の ID。分析情報 ID が不明な場合は、プロジェクト内で分析情報を一覧表示することにより確認できます。分析情報の name フィールドの insights/ より後の部分が分析情報の ID です。

HTTP メソッドと URL:

GET https://recommender.googleapis.com/v1/projects/project-id/locations/global/insightTypes/insight-type-id/insights/insight-id

リクエストを送信するには、次のいずれかのオプションを展開します。

レスポンスに分析情報が含まれます。次に例を示します。

{
  "name": "projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/07841f74-02ce-4de8-bbe6-fc4eabb68568",
  "description": "0 of the permissions in this role binding were used in the past 90 days.",
  "content": {
    "role": "roles/viewer",
    "member": "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com",
    "condition": {
      "expression": "",
      "title": "",
      "description": "",
      "location": ""
    },
    "exercisedPermissions": [],
    "inferredPermissions": []
  },
  "lastRefreshTime": "2020-07-12T07:00:00Z",
  "observationPeriod": "7776000s",
  "stateInfo": {
    "state": "ACTIVE"
  },
  "category": "SECURITY",
  "associatedRecommendations": [
    {
      "recommendation": "projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/b1932220-867d-43d1-bd74-fb95876ab656"
    }
  ],
  "targetResources": [
    "//cloudresourcemanager.googleapis.com/projects/123456789012"
  ],
  "insightSubtype": "PERMISSIONS_USAGE",
  "etag": "\"b153ab487e4ae100\""
}

分析情報のコンポーネントの詳細については、このページの分析情報の確認をご覧ください。

分析情報の確認

分析情報はタイプとサブタイプで分類されます。分析情報のタイプは分析対象のリソースタイプを表します。分析情報のサブタイプは、分析情報に含まれている情報の種類を表します。

IAM の分析情報には次のタイプとサブタイプがあります。

分析情報のタイプ 分析情報のサブタイプ
ポリシーの分析情報 PERMISSION_USAGE: プロジェクトの権限の使用状況に関する ML ベースの分析結果。
サービス アカウントの分析情報 SERVICE_ACCOUNT_USAGE: プロジェクトで過去 90 日間に使用されていないサービス アカウントの分析結果。

分析情報のコンテンツはサブタイプによって決まります。上の表の分析情報のサブタイプには次のコンポーネントがあります。

  • associatedRecommendations: 分析情報に関連付けられているレコメンデーションの ID。分析情報に関連付けられたレコメンデーションがない場合、このフィールドは空白になります。
  • category: PERMISSION_USAGESERVICE_ACCOUNT_USAGE の分析情報のカテゴリは常に SECURITY になります。
  • content: content フィールド内の情報は分析情報のサブタイプによって決まります。

    分析情報のサブタイプ 内容
    PERMISSION_USAGE

    特定のロールのメンバー権限の使用状況を報告します。このフィールドには次のコンポーネントが含まれます。

    • member: 権限の使用状況が分析されるメンバー。
    • role: 権限の使用状況が分析されたロール。
    • condition: メンバーにロールを付与するバインディングに関連付けられている条件。条件がない場合、このフィールドには空の条件が含まれます。
    • exercisedPermissions: モニタリング期間中にメンバーが使用したロールの権限。
    • inferredPermissions: ML により IAM Recommender が特定したロールの権限。使用された権限の情報から必要になる可能性が高い権限を特定します。
    SERVICE_ACCOUNT_USAGE

    サービス アカウントが最後に認証された時間を報告します。このフィールドには次のコンポーネントが含まれます。

    • serviceAccountId: サービス アカウントの一意の数値 ID。
    • email: サービス アカウントのメールアドレス。
    • lastAuthenticatedTime: サービス アカウントが最後に認証された時刻。サービス アカウントに記録された認証がない場合、このフィールドは含まれません。
  • description: 人が読める形式の分析情報の概要。

  • etag: 分析情報の現在の状態を識別する固有のフィンガープリント。分析情報が変わるたびに、新しい etag 値が割り当てられます。

    分析情報の状態を変更するには、既存の分析情報に etag を指定します。etag を使用すると、最後に取得した後に分析情報が変更されていない場合にのみ、オペレーションを実行できます。

  • insightSubtype: 分析情報のサブタイプ(PERMISSION_USAGE または SERVICE_ACCOUNT_USAGE)。

  • lastRefreshTime: 分析情報が最後に更新された日付。分析情報の生成に使用されたデータの鮮度を表します。

  • name: 分析情報の名前。次の形式になります。

    projects/project-id/locations/global/insightTypes/insight-type-id/insights/insight-id

    プレースホルダの値は次のとおりです。

    • project-id: 分析情報が生成されたプロジェクトの ID。
    • insight-type-id: 分析情報のタイプ。ポリシーの分析情報の場合、タイプは google.iam.policy.Insight です。サービス アカウントの分析情報の場合、タイプは google.iam.serviceAccount.Insight です。
    • insight-id: 分析情報の一意の ID。
  • observationPeriod: 分析情報の期間。分析情報の生成に使用されるソースデータは lastRefreshTime で終了し、lastRefreshTime から observationPeriod を引いた時間に開始します。

  • stateInfo: 分析情報が提案後、多くの状態遷移が発生します。

    • ACTIVE: 分析情報が生成されていますが、アクションが実行されていません。あるいは、分析情報の状態を更新せずに処理が行われています。アクティブな分析情報は、基になるデータが変更されると更新されます。
    • ACCEPTED: 分析情報に基づいて一部の操作が行われています。関連するレコメンデーションが CLAIMEDSUCCEEDED、または FAILED とマークされるか、分析結果が直接承認されると、分析情報は承認された状態になります。分析情報が ACCEPTED 状態の場合、分析情報のコンテンツは変更できません。承認された分析情報は、承認後 90 日間保持されます。
  • targetResources: 分析対象となる Google Cloud プロジェクトの完全なリソース名。例: //cloudresourcemanager.googleapis.com/projects/1234567890

分析情報を ACCEPTED としてマークする

アクティブな分析情報に基づいてアクションを実行する場合は、その分析情報を ACCEPTED としてマークします。ACCEPTED 状態は、この分析情報に基づいてアクションを実行したことを Recommender API に通知します。この情報はレコメンデーションの改善に役立ちます。

承諾された分析情報は、ACCEPTED とマークされてから 90 日間保持されます。

gcloud

分析情報 ID を指定して gcloud recommender insights mark-accepted コマンドを使用し、分析情報を ACCEPTED とマークします。

サンプル コマンドを使用する前に、次の値を置き換えます。

  • insight-id: ACCEPTED としてマークする分析情報の ID。ID を確認するには、プロジェクトの分析情報を一覧表示します。

  • insight-type-id: ACCEPTED としてマークする分析情報のタイプ。ポリシーの分析情報の場合は、google.iam.policy.Insight を使用します。サービス アカウントの分析情報の場合は、google.iam.serviceAccount.Insight を使用します。

  • etag: 分析情報のバージョンの ID。etag を取得するには、次のようにします。

    1. gcloud recommender insights describe コマンドで分析情報を取得します。
    2. 出力から etag 値を見つけてコピーします(引用符も含む)。例: "d3cdec23cc712bd0"
gcloud recommender insights mark-accepted insight-id \
    --insight-type=insight-type-id --location=global \
    --etag=etag

出力に、ACCEPTED 状態の分析情報が表示されます。

associatedRecommendations:
- recommendation: projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/recommendations/0573b702-96a5-4622-a916-c762e7b0731f
category: SECURITY
content:
  condition:
    description: ''
    expression: ''
    location: ''
    title: ''
  exercisedPermissions: []
  inferredPermissions: []
  member: serviceAccount:my-service-account@my-project.iam.gserviceaccount.com
  role: roles/viewer
description: 0 of the permissions in this role binding were used in the past 90 days.
etag: '"d3cdec23cc712bd0"'
insightSubtype: PERMISSIONS_USAGE
lastRefreshTime: '2020-07-11T07:00:00Z'
name: projects/123456789012/locations/global/insightTypes/google.iam.policy.Insight/insights/0d3ce433-f067-4e78-b6ae-03d7d1f6f040
observationPeriod: 7776000s
stateInfo:
  state: ACCEPTED
targetResources:
- //cloudresourcemanager.googleapis.com/projects/1234567890

分析情報の状態の詳細については、このページの分析情報の確認をご覧ください。

REST

Recommender API の insights.markAccepted メソッドを使用して、分析情報を ACCEPTED としてマークします。

後述のリクエストのデータを使用する前に、次のように置き換えます。

  • project-id: Google Cloud プロジェクト ID。
  • insight-type-id: ACCEPTED としてマークする分析情報のタイプ。ポリシーの分析情報の場合は、google.iam.policy.Insight を使用します。サービス アカウントの分析情報の場合は、google.iam.serviceAccount.Insight を使用します。
  • insight-id: ACCEPTED としてマークする分析情報の ID。分析情報 ID が不明な場合は、プロジェクト内で分析情報を一覧表示することにより確認できます。分析情報の name フィールドの insights/ より後の部分が分析情報の ID です。
  • etag: 分析情報のバージョンの ID。etag を取得する方法は次のとおりです。
    1. insights.get メソッドで分析情報を取得します。
    2. レスポンスから etag 値を見つけてコピーします。

HTTP メソッドと URL:

POST https://recommender.googleapis.com/v1/projects/project-id/locations/global/insightTypes/insight-type-id/insights/insight-id:markAccepted

JSON 本文のリクエスト:

{
  "etag": "etag"
}

リクエストを送信するには、次のいずれかのオプションを展開します。

レスポンスには、状態が ACCEPTED の分析情報が含まれます。

{
  "name": "projects/1234567890/locations/global/insightTypes/google.iam.policy.Insight/insights/07841f74-02ce-4de8-bbe6-fc4eabb68568",
  "description": "0 of the permissions in this role binding were used in the past 90 days.",
  "content": {
    "role": "roles/viewer",
    "member": "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com",
    "condition": {
      "expression": "",
      "title": "",
      "description": "",
      "location": ""
    },
    "exercisedPermissions": [],
    "inferredPermissions": []
  },
  "lastRefreshTime": "2020-07-12T07:00:00Z",
  "observationPeriod": "7776000s",
  "stateInfo": {
    "state": "ACCEPTED"
    },
  "category": "SECURITY",
  "associatedRecommendations": [
    {
      "recommendation": "projects/1234567890/locations/global/recommenders/google.iam.policy.Recommender/recommendations/b1932220-867d-43d1-bd74-fb95876ab656"
    }
  ],
  "targetResources": [
    "//cloudresourcemanager.googleapis.com/projects/1234567890"
  ],
  "insightSubtype": "PERMISSIONS_USAGE",
  "etag": "\"b153ab487e4ae100\""
}

分析情報の状態の詳細については、このページの分析情報の確認をご覧ください。

次のステップ