Google Cloud Recommender

This document provides guidance to help you configure and integrate Google Cloud Recommender with Google Security Operations SOAR.

Prerequisites

Make sure that you complete all the prerequisite steps before configuring the integration.

Create and configure the IAM role

In the Google Cloud console, go to the IAM Roles page.

Go to IAM Roles
Click Create role to create a custom role with permissions required for the integration.
For a new custom role, provide the Title, Description, and a unique ID.
Set the Role Launch Stage to General Availability.
Add the following permissions to the created role:
- iam.roles.create
- iam.roles.delete
- iam.roles.get
- iam.roles.list
- iam.roles.undelete
- iam.roles.update
- iam.serviceAccounts.create
- iam.serviceAccounts.delete
- iam.serviceAccounts.disable
- iam.serviceAccounts.enable
- iam.serviceAccounts.get
- iam.serviceAccounts.getIamPolicy
- iam.serviceAccounts.list
- iam.serviceAccounts.setIamPolicy
- iam.serviceAccounts.undelete
- iam.serviceAccounts.update
- recommender.iamPolicyInsights.get
- recommender.iamPolicyInsights.list
- recommender.iamPolicyLateralMovementInsights.get
- recommender.iamPolicyLateralMovementInsights.list
- recommender.iamPolicyRecommendations.get
- recommender.iamPolicyRecommendations.list
- recommender.iamPolicyRecommendations.update
- recommender.iamServiceAccountInsights.get
- recommender.iamServiceAccountInsights.list
- recommender.locations.get
- recommender.locations.list
- resourcemanager.folders.get
- resourcemanager.folders.getIamPolicy
- resourcemanager.folders.setIamPolicy
- resourcemanager.organizations.get
- resourcemanager.organizations.getIamPolicy
- resourcemanager.organizations.setIamPolicy
- resourcemanager.projects.get
- resourcemanager.projects.getIamPolicy
- resourcemanager.projects.list
- resourcemanager.projects.setIamPolicy
- securitycenter.assets.list
- securitycenter.findings.group
- securitycenter.findings.list
- securitycenter.findings.listFindingPropertyNames
- securitycenter.findings.setMute
- securitycenter.findings.setState
- securitycenter.sources.get
- securitycenter.sources.list
- securitycenter.userinterfacemetadata.get
Click Create.

Create a service account

To create a service account, follow the procedure for creating a service account.

Important: Make sure to grant your custom IAM role to the service account under Grant this service account access to project.
After you have created a service account, download it as a JSON file. You need to provide the content of a downloaded JSON file when configuring the integration parameters.

Integrate Google Cloud Recommender with Google Security Operations SOAR

For detailed instructions on how to configure an integration in Google SecOps SOAR, see Configure integrations.

Integration inputs

To configure the integration, use the following parameters:

Parameters
`API Root`	Required The API root of the Google Cloud Recommender service. Default value is `https://recommender.googleapis.com/v1/`
`Organization ID`	Optional The organization ID that should be used with the Google Cloud Recommender integration.
`User's Service Account`	Required The content of the Google Cloud Recommender service account. Make sure to provide the full content of the service account JSON file that you have downloaded when creating a service account.
`Verify SSL`	Optional When checked, the parameter verifies if the SSL certificate for connecting to the Google Cloud Recommender server is valid. Checked by default.

Actions

Apply IAM recommendations

Apply the IAM recommendations based on the provided input.

This action works only with the google.iam.policy.Recommender recommendations.

Entities

The action does not run on entities.

Action inputs

To configure the action, use the following parameters:

Parameters

Parameters
`IAM Recommendations JSON`	Required The JSON result of the recommendation. JSON result can be provided as a placeholder from the List recommendations or Get recommendation actions.

IAM Recommendations JSON

Required

The JSON result of the recommendation.

JSON result can be provided as a placeholder from the List recommendations or Get recommendation actions.

Action outputs

Action output type
Case wall attachment	N/A
Case wall link	N/A
Case wall table	N/A
Enrichment table	N/A
Entity insight	N/A
Insight	N/A
JSON result	Available
OOTB widget	N/A
Script result	Available

Script result

Script result name	Value
is_success	True/False

JSON result

{
  "applied_recommendations": [
    {
      "name": "projects/PROJECT_ID/locations/global/recommenders/google.iam.policy.Recommender/recommendations/217d3019-bae5-4a52-9968-787fdd546a53",
      "description": "Replace the current role with a smaller role to cover the permissions needed.",
      "lastRefreshTime": "2023-07-28T07:00:00Z",
      "primaryImpact": {
        "category": "SECURITY",
        "securityProjection": {
          "details": {
            "revokedIamPermissionsCount": 610
          }
        }
      },
      "content": {
        "operationGroups": [
          {
            "operations": [
              {
                "action": "add",
                "resourceType": "cloudresourcemanager.googleapis.com/Project",
                "resource": "//cloudresourcemanager.googleapis.com/projects/PROJECT_ID",
                "path": "/iamPolicy/bindings/*/members/-",
                "value": "USER_ID@example.com",
                "pathFilters": {
                  "/iamPolicy/bindings/*/condition/expression": "",
                  "/iamPolicy/bindings/*/role": "roles/compute.instanceAdmin"
                }
              },
              {
                "action": "remove",
                "resourceType": "cloudresourcemanager.googleapis.com/Project",
                "resource": "//cloudresourcemanager.googleapis.com/projects/PROJECT_ID",
                "path": "/iamPolicy/bindings/*/members/*",
                "pathFilters": {
                  "/iamPolicy/bindings/*/condition/expression": "",
                  "/iamPolicy/bindings/*/members/*": "USER_ID@example.com",
                  "/iamPolicy/bindings/*/role": "roles/compute.admin"
                }
              }
            ]
          }
        ],
        "overview": {
          "resource": "//cloudresourcemanager.googleapis.com/projects/PROJECT_ID",
          "member": "user:USER_ID@example.com",
          "removedRole": "roles/compute.admin",
          "addedRoles": [
            "roles/compute.instanceAdmin"
          ],
          "minimumObservationPeriodInDays": "0"
        }
      },
      "stateInfo": {
        "state": "SUCCEEDED",
        "stateMetadata": {
          "applied_by": "bulk_apply_by_automated_script-2023-08-11"
        }
      },
      "etag": "\"892d57ee41baa03e\"",
      "recommenderSubtype": "REPLACE_ROLE",
      "associatedInsights": [
        {
          "insight": "projects/PROJECT_ID/locations/global/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID"
        }
      ],
      "priority": "P4"
    },
    {
      "name": "projects/PROJECT_ID/locations/global/recommenders/google.iam.policy.Recommender/recommendations/RECOMMENDATION_ID",
      "description": "Replace the current role with a smaller role to cover the permissions needed.",
      "lastRefreshTime": "2023-07-28T07:00:00Z",
      "primaryImpact": {
        "category": "SECURITY",
        "securityProjection": {
          "details": {
            "revokedIamPermissionsCount": 19
          }
        }
      },
      "content": {
        "operationGroups": [
          {
            "operations": [
              {
                "action": "add",
                "resourceType": "cloudresourcemanager.googleapis.com/Project",
                "resource": "//cloudresourcemanager.googleapis.com/projects/PROJECT_ID",
                "path": "/iamPolicy/bindings/*/members/-",
                "value": "user:USER_ID@example.com",
                "pathFilters": {
                  "/iamPolicy/bindings/*/condition/expression": "",
                  "/iamPolicy/bindings/*/role": "roles/storage.objectAdmin"
                }
              },
              {
                "action": "remove",
                "resourceType": "cloudresourcemanager.googleapis.com/Project",
                "resource": "//cloudresourcemanager.googleapis.com/projects/PROJECT_ID",
                "path": "/iamPolicy/bindings/*/members/*",
                "pathFilters": {
                  "/iamPolicy/bindings/*/condition/expression": "",
                  "/iamPolicy/bindings/*/members/*": "user:USER_ID@example.com",
                  "/iamPolicy/bindings/*/role": "roles/storage.admin"
                }
              }
            ]
          }
        ],
        "overview": {
          "resource": "//cloudresourcemanager.googleapis.com/projects/PROJECT_ID",
          "member": "user:USER_ID@example.com",
          "removedRole": "roles/storage.admin",
          "addedRoles": [
            "roles/storage.objectAdmin"
          ],
          "minimumObservationPeriodInDays": "0"
        }
      },
      "stateInfo": {
        "state": "SUCCEEDED",
        "stateMetadata": {
          "applied_by": "bulk_apply_by_automated_script-2023-08-11"
        }
      },
      "etag": "\"af7635ffeb512998\"",
      "recommenderSubtype": "REPLACE_ROLE",
      "associatedInsights": [
        {
          "insight": "projects/PROJECT_ID/locations/global/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID"
        }
      ],
      "priority": "P4"
    }
  ],
  "failed_recommendations": []
}

Case wall

The action provides the following output messages:

Output message	Message description
`Successfully applied provided IAM recommendations.`	The action is successful.
`Successfully applied provided IAM recommendation, but some of the recommendations were not applied.`	The action is successful.
`No provided IAM recommendations were applied.`	Recommendation failed.
`Error executing action ACTION_NAME.`	The action returned an error.

Get recommendation

Get a specific recommendation from the Google Cloud Recommender service.

Entities

The action does not run on entities.

Action inputs

To configure the action, use the following parameters:

Parameters

Parameters
`Recommendation name`	Required Specifies the recommendation name to return. The action accepts multiple values as a comma-separated string. Example of the expected input: projects/projectname/locations/global/recommenders/google.iam.policy.Recommender/recommendations/0f262740-bf4a-4c3d-9573-0da3345cf3f7

Recommendation name

Required

Specifies the recommendation name to return.

The action accepts multiple values as a comma-separated string.

Example of the expected input:

    projects/projectname/locations/global/recommenders/google.iam.policy.Recommender/recommendations/0f262740-bf4a-4c3d-9573-0da3345cf3f7

Action outputs

Action output type
Case wall attachment	N/A
Case wall link	N/A
Case wall table	N/A
Enrichment table	N/A
Entity insight	N/A
Insight	N/A
JSON result	Available
OOTB widget	N/A
Script result	Available

Script result

Script result name	Value
is_success	True/False

JSON result

[
  {
    "name": "name",
    "description": "This role has not been used during the observation window.",
    "lastRefreshTime": "2023-07-28T07:00:00Z",
    "primaryImpact": {
      "category": "SECURITY",
      "securityProjection": {
        "details": {
          "revokedIamPermissionsCount": 68
        }
      }
    },
    "content": {
      "operationGroups": [
        {
          "operations": [
            {
              "action": "remove",
              "resourceType": "cloudresourcemanager.googleapis.com/Project",
              "resource": "//cloudresourcemanager.googleapis.com/projects/PROJECT_ID",
              "path": "/iamPolicy/bindings/*/members/*",
              "pathFilters": {
                "/iamPolicy/bindings/*/condition/expression": "",
                "/iamPolicy/bindings/*/members/*": "serviceAccount:SERVICE_ACCOUNT_ID.iam.gserviceaccount.com",
                "/iamPolicy/bindings/*/role": "roles/monitoring.admin"
              }
            }
          ]
        }
      ],
      "overview": {
        "resource": "//cloudresourcemanager.googleapis.com/projects/PROJECT_ID",
        "member": "serviceAccount:SERVICE_ACCOUNT_ID.iam.gserviceaccount.com",
        "removedRole": "roles/monitoring.admin",
        "minimumObservationPeriodInDays": "0"
      }
    },
    "stateInfo": {
      "state": "ACTIVE"
    },
    "etag": "",
    "recommenderSubtype": "REMOVE_ROLE",
    "associatedInsights": [
      {
        "insight": "projects/PROJECT_ID/locations/global/insightTypes/google.iam.policy.Insight/insights/"
      }
    ],
    "priority": "P4"
  }
]

Case wall

The action provides the following output messages:

Output message	Message description
`Successfully found recommendation in the Google Cloud Recommender service.`	The action is successful.
`No recommendations were found in the Google Cloud Recommender service.`	Data is not available.
`Error executing action ACTION_NAME`.	The action returned an error.

List recommendations

List available recommendations in the Google Cloud Recommender service.

Entities

The action does not run on entities.

Action inputs

To configure the action, use the following parameters:

Parameters
`Recommendation Filter`	Optional Specifies the filter to fetch the recommendations. The parameter should be a string in any of the following formats: `PROJECTS_OR_ORGANIZATIONS`/ `PROJECT_OR_ORGANIZATION_NAME_OR_ID` //cloudresourcemanager.googleapis.com/`PROJECTS_OR_ORGANIZATIONS`/ `PROJECT_OR_ORGANIZATION_NAME_OR_ID` If no value is provided, the action fetches the project ID from the configured service account.
`Recommendation Location`	Required Specifies the Google Cloud location to fetch recommendations. Default is `global`.
`Recommendation State`	Optional Specifies the recommendation state to return. Default is `Not Specified`. Possible values are: `Not Specified` `Active` `Dismissed`
`Recommendation Priority`	Optional Specifies the priority of a recommendation to return. Multiple values can be specified as a comma-separated string.
`Recommender Subtype`	Optional Specifies the returned recommender subtype. Default is `Not Specified`. Possible values are: `Not Specified` `REMOVE_ROLE` `REPLACE_ROLE`
`Max Records To Return`	Optional Specifies how many records to return. If no value is provided, the action returns 50 records by default.

Action outputs

Action output type
Case wall attachment	N/A
Case wall link	N/A
Case wall table	Available
Enrichment table	N/A
Entity insight	N/A
Insight	N/A
JSON result	Available
OOTB widget	N/A
Script result	Available

Script result

Script result name	Value
is_success	True/False

JSON result

[
  {
    "name": "name",
    "description": "This role has not been used during the observation window.",
    "lastRefreshTime": "2023-07-27T07:00:00Z",
    "primaryImpact": {
      "category": "SECURITY",
      "securityProjection": {
        "details": {
          "revokedIamPermissionsCount": 68
        }
      }
    },
    "content": {
      "operationGroups": [
        {
          "operations": [
            {
              "action": "remove",
              "resourceType": "cloudresourcemanager.googleapis.com/Project",
              "resource": "//cloudresourcemanager.googleapis.com/projects",
              "path": "/iamPolicy/bindings/*/members/*",
              "pathFilters": {
                "/iamPolicy/bindings/*/condition/expression": "",
                "/iamPolicy/bindings/*/members/*": "serviceAccount:SERVICE_ACCOUNT_ID",
                "/iamPolicy/bindings/*/role": "roles/monitoring.admin"
              }
            }
          ]
        }
      ],
      "overview": {
        "resource": "//cloudresourcemanager.googleapis.com/",
        "member": "serviceAccount:SERVICE_ACCOUNT_ID",
        "removedRole": "roles/monitoring.admin",
        "minimumObservationPeriodInDays": "0"
      }
    },
    "stateInfo": {
      "state": "ACTIVE"
    },
    "etag": "",
    "recommenderSubtype": "REMOVE_ROLE",
    "associatedInsights": [
      {
        "insight": "projects/i/locations/global/insightTypes/"
      }
    ],
    "priority": "P4"
  },
  {
    "name": "name",
    "description": "This role has not been used during the observation window.",
    "lastRefreshTime": "2023-07-27T07:00:00Z",
    "primaryImpact": {
      "category": "SECURITY",
      "securityProjection": {
        "details": {
          "revokedIamPermissionsCount": 5
        }
      }
    },
    "content": {
      "operationGroups": [
        {
          "operations": [
            {
              "action": "remove",
              "resourceType": "cloudresourcemanager.googleapis.com/Project",
              "resource": "//cloudresourcemanager.googleapis.com/projects/PROJECT_ID",
              "path": "/iamPolicy/bindings/*/members/*",
              "pathFilters": {
                "/iamPolicy/bindings/*/condition/expression": "",
                "/iamPolicy/bindings/*/members/*": "user:USER_ID@example.com",
                "/iamPolicy/bindings/*/role": "roles/chroniclesm.admin"
              }
            }
          ]
        }
      ],
      "overview": {
        "resource": "//cloudresourcemanager.googleapis.com/projects",
        "member": "user:USER_ID@example.com",
        "removedRole": "roles/chroniclesm.admin",
        "minimumObservationPeriodInDays": "0"
      }
    },
    "stateInfo": {
      "state": "ACTIVE"
    },
    "etag": "",
    "recommenderSubtype": "REMOVE_ROLE",
    "associatedInsights": [
      {
        "insight": "projects"
      }
    ],
    "priority": "P4"
  }
]

Case wall

The action provides the following output messages:

Output message	Message description
`Successfully found recommendations for the provided criteria in the Google Cloud Recommender service.`	The action is successful.
`No recommendations were found for the provided criteria in the Google Cloud Recommender service.`	No data is available.
`Error executing action ACTION_NAME.`	The action returned an error.

The action provides the following case wall table:

Available Recommendations
Columns	Name Description Category Recommendation Subtype Priority State Last Refresh Time

Ping

Test connectivity to the Google Cloud Recommender service with parameters provided at the integration configuration page in the Google Security Operations SOAR Marketplace tab.

Entities

The action does not run on entities.

Action inputs

N/A

Action outputs

Action output type
Case wall attachment	N/A
Case wall link	N/A
Case wall table	N/A
Enrichment table	N/A
Entity insight	N/A
Insight	N/A
JSON result	N/A
OOTB widget	N/A
Script result	Available

Script result

Script result name	Value
is_success	True/False

Case wall

The action provides the following output messages:

Output message	Message description
`Successfully connected to the Google Cloud Recommender service with the provided connection parameters!`	The action is successful.
`Failed to connect to the Google Cloud Recommender service!`	The action returned an error.

Update recommendation

Update the recommendation in the Google Cloud Recommender service.

Entities

The action does not run on entities.

Action inputs

Use the following parameters to configure the action:

Parameters

Parameters
`Recommendation name`	Required Specifies the recommendation name to update. The action accepts multiple values as a comma-separated string. Example of the expected input: `projects/projectname/locations/global/recommenders/google.iam.policy.Recommender/recommendations/0f262740-bf4a-4c3d-9573-0da3345cf3f7`
`Recommendation State`	Optional Specifies the state for the recommendation to change to. Default is `Not Specified`. Possible values are: `Not Specified` `Claimed` `Dismissed`
`Recommendation Result`	Optional Specifies the result for the recommendation to change to. Default is `Not Specified`. Possible values are: `Not Specified` `Failed` `Succeeded`

Recommendation name

Required

Specifies the recommendation name to update.

The action accepts multiple values as a comma-separated string.

Example of the expected input: projects/projectname/locations/global/recommenders/google.iam.policy.Recommender/recommendations/0f262740-bf4a-4c3d-9573-0da3345cf3f7

Recommendation State

Optional

Specifies the state for the recommendation to change to.

Default is Not Specified.

Possible values are:

Not Specified
Claimed
Dismissed

Recommendation Result

Optional

Specifies the result for the recommendation to change to.

Default is Not Specified.

Possible values are:

Not Specified
Failed
Succeeded

Action outputs

Action output type
Case wall attachment	N/A
Case wall link	N/A
Case wall table	N/A
Enrichment table	N/A
Entity insight	N/A
Insight	N/A
JSON result	Available
OOTB widget	N/A
Script result	Available

Script result

Script result name	Value
is_success	True/False

JSON result

[
  {
    "name": "name",
    "description": "This role has not been used during the observation window.",
    "lastRefreshTime": "2023-07-28T07:00:00Z",
    "primaryImpact": {
      "category": "SECURITY",
      "securityProjection": {
        "details": {
          "revokedIamPermissionsCount": 68
        }
      }
    },
    "content": {
      "operationGroups": [
        {
          "operations": [
            {
              "action": "remove",
              "resourceType": "cloudresourcemanager.googleapis.com/Project",
              "resource": "//cloudresourcemanager.googleapis.com/projects/PROJECT_ID",
              "path": "/iamPolicy/bindings/*/members/*",
              "pathFilters": {
                "/iamPolicy/bindings/*/condition/expression": "",
                "/iamPolicy/bindings/*/members/*": "serviceAccount:SERVICE_ACCOUNT_ID.iam.gserviceaccount.com",
                "/iamPolicy/bindings/*/role": "roles/monitoring.admin"
              }
            }
          ]
        }
      ],
      "overview": {
        "resource": "//cloudresourcemanager.googleapis.com/projects/PROJECT_ID",
        "member": "serviceAccount:SERVICE_ACCOUNT_ID.iam.gserviceaccount.com",
        "removedRole": "roles/monitoring.admin",
        "minimumObservationPeriodInDays": "0"
      }
    },
    "stateInfo": {
      "state": "ACTIVE"
    },
    "etag": "",
    "recommenderSubtype": "REMOVE_ROLE",
    "associatedInsights": [
      {
        "insight": "projects/PROJECT_ID/locations/global/insightTypes/google.iam.policy.Insight/insights/"
      }
    ],
    "priority": "P4"
  }
]

Case wall

The action provides the following output messages:

Output message	Message description
`Successfully updated recommendation in the Google Cloud Recommender service.`	The action is successful.
`No recommendations were found in the Google Cloud Recommender service.`	Data is not available.
`Error executing action ACTION_NAME`.	The action returned an error.