Google Cloud Recommender

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

Note: Integration version: 5.0

Prerequisites

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

Create and configure the IAM role

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

   Go to IAM Roles

2. Click Create role to create a custom role with permissions required for the integration.

3. For a new custom role, provide the Title, Description, and a unique ID.

4. Set the Role Launch Stage to General Availability.

5. 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

6. Click Create.

Create a service account

1. 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.

2. 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

Note: Some actions work only with specific recommendations.

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
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": "[e-mail]",
                "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/*": "[e-mail]",
                  "/iamPolicy/bindings/*/role": "roles/compute.admin"
                }
              }
            ]
          }
        ],
        "overview": {
          "resource": "//cloudresourcemanager.googleapis.com/projects/PROJECT_ID",
          "member": "user:[e-mail]",
          "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:[e-mail]",
                "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:[e-mail]",
                  "/iamPolicy/bindings/*/role": "roles/storage.admin"
                }
              }
            ]
          }
        ],
        "overview": {
          "resource": "//cloudresourcemanager.googleapis.com/projects/PROJECT_ID",
          "member": "user:[e-mail]",
          "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
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.

Note: The action returns insights only from the google.iam.policy.Recommender recommender.

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:[e-mail]",
                "/iamPolicy/bindings/*/role": "roles/chroniclesm.admin"
              }
            }
          ]
        }
      ],
      "overview": {
        "resource": "//cloudresourcemanager.googleapis.com/projects",
        "member": "user:[e-mail]",
        "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
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.