Google Cloud Storage

This document provides guidance on how to integrate Cloud Storage with the SOAR module of Google Security Operations.

Integration version: 8.0

This integration uses one or more open source components. You can download a copy of the source code of this integration from a Cloud Storage bucket.

Use cases

In the Google SecOps SOAR platform, the Google Cloud Storage integration solves the following use cases:

  • Incident evidence storage: playbooks can automatically collect and store incident-related evidence like logs and malware samples in Cloud Storage buckets to provide a tamper-proof repository for evidence preservation.

  • Threat intelligence sharing: your security team can use Cloud Storage to securely share threat intelligence feeds like lists of malicious IP addresses and domains with other teams or organizations. Sharing feeds enables collaborative threat defense and faster response times.

  • Malware analysis sandbox integration: playbooks can automatically submit suspicious files from an incident to a cloud-based malware analysis sandbox. You can store the analysis results in Cloud Storage for review and further action to provide efficient and scalable malware analysis.

  • Security configuration backup: use the SOAR capabilities of Google SecOps to automate regular backups of critical security configurations like firewall rules and intrusion detection system signatures to Cloud Storage. Automating backups provides business continuity and faster recovery in case of accidental or malicious changes.

  • Phishing campaign artifact storage: use the SOAR capabilities of Google SecOps to store phishing emails, attachments, and other artifacts in Cloud Storage while investigating a phishing campaign. Artifact storage allows for centralized analysis and preservation of evidence for potential legal action.

Before you begin

To use the integration, you need a Google Cloud service account. You can use an existing service account or create a new one.

Create a service account

  1. For guidance on creating a service account, see Create service accounts.

  2. Under Grant this service account access to project, grant your service account the following role:

    • Storage Admin

  3. If you don't run workloads on Google Cloud, you need to create a service account key in JSON after you create a service account. If you don't use a Workload Identity email, you need to provide the content of the downloaded JSON file when configuring the integration parameters.

    For security reasons, we recommend using the Workload Identity email addresses instead of service account JSON keys. For more information about the workload identities, see Identities for workloads.

Integrate Cloud Storage with Google SecOps

The integration requires the following parameters:

Parameters Description
Service Account Optional

The content of the service account key JSON file.

You can configure either this parameter or the Workload Identity Email parameter.

To configure this parameter, provide the full content of the service account JSON file that you have downloaded when creating a service account.

Workload Identity Email Optional

The client email address of your service account.

You can configure either this parameter or the Service Account parameter.

To impersonate service accounts with the Workload Identity email address, grant the Service Account Token Creator role to your service account. For more details about workload identities and how to work with them, see Identities for workloads.
Project ID Optional

The project ID to use for the Cloud Storage integration. If you set no value for this parameter, the project ID is retrieved from the JSON file content provided in the Service Account parameter.
Quota Project ID Optional

The Google Cloud project ID that you use for Google Cloud APIs and billing. This parameter requires you to grant the Service Usage Consumer role to your service account.

If you set no value for this parameter, the project ID is retrieved from the JSON file content provided in the Service Account parameter.

For detailed instructions about configuring an integration in Google SecOps, see Configure integrations.

You can make changes at a later stage if needed. After you configure an integration instance, you can use it in playbooks. For more information about configuring and supporting multiple instances, see Supporting multiple instances.

Actions

For actions that work with access control lists (ACLs), you can specify access and apply permissions for both the bucket and individual object. For more information, see Access control lists (ACLs).

Download an Object From a Bucket

Use this action to download a specific object (file) from a Cloud Storage bucket.

This action doesn't run on entities.

Action inputs

The Download an Object From a Bucket action requires the following parameters:

Parameters Description
Bucket Name Required

The name of the Cloud Storage bucket containing the object to download.

Object Name Required

The full name of the object to download.

If the object is located within a folder in the bucket, include the folder path, such as folderA/mydocument.pdf.
Download Path Required

The absolute path for the downloaded object that leads to an existing directory, for example, /tmp/downloads/.

Action outputs

The Download an Object From a Bucket action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Available
Output messages Available
Script result Available
JSON result

The following example describes the JSON result output received when using the Download an Object From a Bucket action:

{
"object_name": "123.txt"
"download_path": "/usr/bin/share/download.txt"
}
Output messages

On a Case Wall, the Download an Object From a Bucket action provides the following output messages:

Output message Message description

OBJECT_NAME successfully downloaded to DESTINATION_PATH.

Action wasn't able to download OBJECT_NAME. Reason: Bucket BUCKET_NAME not found.

Action wasn't able to download OBJECT_NAME. Reason: No such object.

 Action succeeded.
Error executing action "Download an Object From a Bucket". Reason: ERROR_REASON

Action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Download an Object From a Bucket action:

Script result name Value
is_success True or False

Get a Bucket's Access Control List

Use the Get a Bucket's Access Control List action to retrieve and display ACLs for the specified Cloud Storage buckets.

This action doesn't run on entities.

Action inputs

The Get a Bucket's Access Control List action requires the following parameters:

Parameters Description
Bucket Name Required

The name of the Cloud Storage bucket that you want to retrieve the ACL for. To retrieve ACLs for multiple buckets, enter the bucket names as a comma-separated string, such as bucket1,bucket2,bucket3.

Action outputs

The Get a Bucket's Access Control List action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
JSON result
[
  {"BucketName": "ziv",
   "BucketACLs": [
                  {"Entity": "project-owners-ID",
                   "Role": "OWNER"}
                 ]
  }
]
Output messages

On a Case Wall, the Get a Bucket's Access Control List action provides the following output messages:

Output message Message description

Successfully retrieved the access control list (ACL) for the Cloud Storage buckets BUCKET_NAMES

Action wasn't able to return the access control list(ACL) for the Cloud Storage buckets BUCKET_NAMES. Reason: Cannot get legacy ACL for a bucket that has uniform bucket-level access. Read more at https://cloud.google.com/storage/docs/uniform-bucket-level-access

Action wasn't able to return the access control list(ACL) for the Cloud Storage buckets BUCKET_NAMES.

 Action succeeded.
Error executing action "Get a Bucket's Access Control List". Reason: ERROR_REASON

Action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Get a Bucket's Access Control List action:

Script result name Value
is_success True or False

List Bucket Objects

Use the List Bucket Objects action to list objects that are stored in the Cloud Storage bucket.

This action doesn't run on entities.

Action inputs

The List Bucket Objects action requires the following parameters:

Parameters Description
Bucket Name Required

The name of the bucket to retrieve objects from.
Max Objects to Return Optional

The number of objects to return.

By default, the action returns 50 objects for every action execution.
Retrieves the Access Control List of an object Optional

If selected, the action retrieves the object ACL.

Not selected by default.

Action outputs

The List Bucket Objects action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Available
Output messages Available
Script result Available
JSON result

The following examples describe the JSON result outputs received when using the List Bucket Objects action:

  • If the Retrieves the Access Control List of an object parameter is not selected:

    {
    "Objects": [
        {
            "ObjectName": "test.txt",
        "Bucket":
        "ContentType":
            "TimeCreated": " ",
            "TimeUpdated": " ",
            "Size": 18,
            "MD5": "7CjVfQ+Oz/C0pI08IKRdvQ==",
            "Owner": "",
            "CR32c": "RQEqxA==",
            "id": "siemplify-tip/test.txt/1604926667310271"
        }
    ]
}

  • If the Retrieves the Access Control List of an object parameter is selected:

    {
    "Objects": [
        {
            "ObjectName": "test.txt",
        "Bucket": "BUCKET_NAME",
        "ContentType": "text/plain"
            "TimeCreated": " ",
            "TimeUpdated": " ",
            "Size": 18,
            "MD5": "7CjVfQ+Oz/C0pI08IKRdvQ==",
            "Owner": "",
            "CR32c": "RQEqxA==",
            "id": "BUCKET_NAME/test.txt/1604926667310271",
            "ObjectACL": [
                {
                    "entity": "user@example.com",
                    "role": "OWNER"
                }]
        },
    ]
}
Output messages

On a Case Wall, the List Bucket Objects action provides the following output messages:

Output message Message description

Successfully returned objects of the BUCKET_NAME bucket in Google Cloud Storage.

Action wasn't able to return objects of the BUCKET_NAME bucket in Google Cloud Storage.

 Action succeeded.
Error executing action "List Bucket Objects". Reason: ERROR_REASON

Action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the List Bucket Objects action:

Script result name Value
is_success True or False

List Buckets

Use the List Buckets action to retrieve a list of buckets from Cloud Storage.

This action doesn't run on entities.

Action inputs

The List Buckets action requires the following parameters:

Parameters Description
Max Results Optional

The maximum number of buckets to return.

By default, the action returns 50 buckets.

Action outputs

The List Buckets action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Available
Output messages Available
Script result Available
JSON result

The following example describes the JSON result output received when using the List Buckets action:

{
    "Buckets": [
        {
            "CreationDate": "2020-11-09T12:57:03.981Z",
            "ModificationDate": "2020-11-09T12:57:03.981Z",
            "Name": "testexample",
            "Owner": "testexample"
        }]
}
Output messages

On a Case Wall, the List Buckets action provides the following output messages:

Output message Message description

Successfully listed available buckets in Google Cloud Storage.

Action wasn't able to list available buckets in Google Cloud Storage.

Action succeeded.
Error executing action "List Buckets". Reason: ERROR_REASON

Action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the List Buckets action:

Script result name Value
is_success True or False

Ping

Use the Ping action to test connectivity to Cloud Storage.

This action doesn't run on entities.

Action inputs

None.

Action outputs

The action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Output messages

On a Case Wall, the Ping action provides the following output messages:

Output message Message description
Successfully connected to the Google Cloud Storage server with the provided connection parameters! Action succeeded.
Failed to connect to the Google Cloud Storage server! Error is ERROR_REASON

Action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Ping action:

Script result name Value
is_success True or False

Remove Public Access From Bucket

Use the Remove Public Access From Bucket action to remove public access from the Cloud Storage bucket.

This action requires you to grant the Storage Admin role to the service account that you use in the integration.

This action doesn't run on entities.

Action inputs

The Remove Public Access From Bucket action requires the following parameters:

Parameters Description
Resource Name Required

The resource name of the bucket.
Prevent Public Access From Bucket Required

If selected, the action configures the bucket to prevent possible public access.

Action outputs

The Remove Public Access From Bucket action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Output messages

On a Case Wall, the Remove Public Access From Bucket action provides the following output messages:

Output message Message description
Successfully removed public access from bucket using Google Cloud Storage: RESOURCE_NAME Action succeeded.
Error executing action "Remove Public Access From Bucket". Reason: ERROR_REASON

Action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Remove Public Access From Bucket action:

Script result name Value
is_success True or False

Update an ACL entry on Bucket

Use the Update an ACL entry on Bucket action to update an ACL entry in the specified Cloud Storage bucket.

Action inputs

The Update an ACL entry on Bucket action requires the following parameters:

Parameters Description
Bucket Name Required

The name of the bucket to modify the ACL for.
Entity Required

The entity that holds the permission.

Possible values are as follows:

  • user-userId
  • user-emailAddress
  • group-groupId
  • group-emailAddress
  • allUsers
  • allAuthenticatedUsers

For more information about entities, see Resource representations.
Role Required

The access permission that is required for the entity.

Possible values are as follows:

  • OWNER
  • READER
  • WRITER

Action outputs

The Update an ACL entry on Bucket action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Output messages

On a Case Wall, the Update an ACL entry on Bucket action provides the following output messages:

Output message Message description

Action wasn't able to update the ACL entity: ENTITY to role: ROLE in bucket BUCKET_NAME. Reason: OWNERs are WRITERs.

Action wasn't able to update the ACL entity: ENTITY to role: ROLE in bucket BUCKET_NAME. Reason: OWNERs are WRITERs.

 Action succeeded. The existing role mismatches the Role parameter value. Check the Role parameter value.
Successfully updated ACL entity: ENTITY to role: ROLE in bucket BUCKET_NAME. Action succeeded.

Error executing action "Update an ACL entry on Bucket". Reason: Entity ENTITY does not exist in the ACL of bucket BUCKET_NAME.

Action wasn't able to update the ACL entity: ENTITY to role: ROLE in bucket BUCKET_NAME. The entity holding the permission can be user-userId, user-emailAddress, group-groupId, group-emailAddress, allUsers, or allAuthenticatedUsers.

Error executing action "Update an ACL entry on Bucket". Reason: ERROR_REASON

Action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Update an ACL entry on Bucket action:

Script result name Value
is_success True or False

Upload an Object To a Bucket

Use the Upload an Object To a Bucket action to upload an object to the Cloud Storage bucket.

This action doesn't run on entities.

Action inputs

The Upload an Object To a Bucket action requires the following parameters:

Parameters Description
Bucket Name Required

The name of the bucket to upload an object to.
Source File Path Required

The absolute path to the file to upload, such as /local/path/to/filename.
Object Name Required

The name of the uploaded object in the bucket.

Action outputs

The Upload an Object To a Bucket action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Available
Output messages Available
Script result Available
JSON result
{
   "object_id":"BUCKET_NAME/errorlog.txt/1610616919132517",
   "Object_name":"errorlog.txt",
   "md5_hash":"PTdL8D6pBwIKyMfIXR/H9A==",
   "object_path":"/b/BUCKET_NAME/o/errorlog.txt"
}
Output messages

On a Case Wall, the Upload an Object To a Bucket action provides the following output messages:

Output message Message description

Successfully uploaded SOURCE_PATH to bucket: BUCKET_NAME.

Action wasn't able to upload SOURCE_PATH to Google Cloud Storage. Reason:No such file or directory: SOURCE_PATH.

Action succeeded.
Error executing action "Upload an Object To a Bucket". Reason: ERROR_REASON

Action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table describes the values for the script result output when using the Upload an Object To a Bucket action:

Script result name Value
is_success True or False