Google Cloud Storage

Integration version: 4.0

Note: This integration uses one or more open source components. You can download a copy of the full source code of this integration from the storage bucket.

Use Cases

1. Manage buckets
2. Download files from buckets
3. Upload files to buckets

Configure Google Cloud Storage integration in Google Security Operations SOAR

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

Integration parameters

Use the following parameters to configure the integration:

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Service Account	Password	N/A	Yes	Specify the full content of the service account JSON file to use in the integration.

Note: You can make changes at a later stage if needed. Once configured, the Instances can be used in Playbooks. For detailed information on configuring and supporting multiple instances, please see Supporting multiple instances.

Create a Service Account:

1. Go to the Google documentation and follow the procedure in the Creating a Service Account section. After you create a service account, a Service Account Private Key file is downloaded.

2. Grant the Storage Admin permission to the Service Account to enable the Service Account to perform all Google Storage API commands.

3. Configure Google Cloud Storage integration with the JSON contents of the file you downloaded in step 1.

Actions

Ping

Description

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

Run On

This action doesn't run on entities.

Action Results

Script Result

Script Result Name	Value Options
is_success	is_success=False
is_success	is_success=True

Case Wall

Result Type	Value / Description	Type
Output message*	The action should not fail nor stop a playbook execution: if successful: "Successfully connected to the Cloud Storage server with the provided connection parameters!" The action should fail and stop a playbook execution: if not successful: "Failed to connect to the Cloud Storage server! Error is {0}".format(exception.stacktrace)	General

List Buckets

Description

Retrieve a list of buckets from Cloud Storage.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Max Results	Integer	50	no	Maximum number of buckets to return

Run On

This action doesn't run on entities.

Action Results

Script Result

Script Result Name	Value Options
is_success	is_success=False
is_success	is_success=True

JSON Result

{
    "Buckets": [
        {
            "CreationDate": '2020-11-09T12:57:03.981Z' → bucket._properties['timeCreated']
     "ModificationDate": '2020-11-09T12:57:03.981Z' → bucket._properties['updated']
            "Name": "testsiemplify" → bucket.name
         "Owner": "testsiemplify" → bucket.owner (if exists)
        }]
}

Case Wall

Result Type	Value / Description	Type
Output message*	The action should not fail nor stop a playbook execution: If status code == 200 (is_success = true): "Successfully listed available buckets in Cloud Storage". If other status code (is_success=false): "Action wasn't able to list available buckets in Cloud Storage". The action should fail and stop a playbook execution: if fatal error, like wrong credentials, no connection to server, other: "Error executing action "List Buckets". Reason: {0}''.format(error.Stacktrace)	General

Get a Bucket's Access Control List

Description

Retrieve the access control list (ACL) for a Cloud Storage bucket.

Note: Access control lists are a legacy access control system for Cloud Storage designed for interoperability with Amazon S3. You can specify access and apply permissions at both the bucket level and per individual object. More info available here: https://cloud.google.com/storage/docs/access-control/lists

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Bucket Name	String	N/A	Yes	Specify name of the bucket from which to retrieve Access Control list.Comma separated names.

Run On

This action doesn't run on entities.

Action Results

Script Result

Script Result Name	Value Options
is_success	is_success=False
is_success	is_success=True

JSON Result

[
  {"BucketName": "ziv",
   "BucketACLs": [
                  {"Entity": 'project-owners-881112408707',
                   "Role": 'OWNER'}
                 ]
  }
]

Case Wall

Result Type	Value / Description	Type
Output message*	The action should not fail nor stop a playbook execution: If status code == 200 (is_success = true)/ If at least one bucket was correct (is_success=true): "Successfully retrieved the access control list (ACL) for the Cloud Storage buckets {0}." If bucket has uniform bucket level: "Action wasn't able to return the access control list(ACL) for the Cloud Storage buckets {0}." 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" If other status code for all of buckets (is_success=false): "Action wasn't able to return the access control list(ACL) for the Cloud Storage buckets {0}." The action should fail and stop a playbook execution: if fatal error, like wrong credentials, no connection to server, other: "Error executing action "Get a Bucket's Access Control List". Reason: {0}''.format(error.Stacktrace)	General

Update an ACL entry on Bucket

Description

Updates an ACL entry on the specified bucket.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Bucket Name	String	N/A	Yes	Specify the name of the bucket on which you want to modify the Access Control List.
Entity	String	N/A	Yes	The entity holding the permission. Can be user-userId, user-emailAddress, group-groupId, group-emailAddress, allUsers, or allAuthenticatedUsers. For more information, please see this reference: here
Role	DDL	N/A	Yes	The access permission for the entity. Possible values: "OWNER", "READER", "WRITER"

Run On

This action doesn't work on entities.

Action Results

Script Result

Script Result Name	Value Options
is_success	is_success=False
is_success	is_success=True

Case Wall

Result Type	Value / Description	Type
Output message*	The action should not fail nor stop a playbook execution: If the existing role is OWNER and the param value is - WRITER: "Action wasn't able to update the ACL entity: "{0}" to role: '{1}' in bucket '{2}'. ".+ "Reason: OWNERs are WRITERs" If the existing role is WRITER and the param value is - READER: "Action wasn't able to update the ACL entity: "{0}" to role: '{1}' in bucket '{2}'.". + "Reason: WRITERs are READERs" If the entity is invalid from updates perspective (not part of the possible values appear in the entity parameter description - e.g. entity = 'project-editors-881112408707': "Action wasn't able to update the ACL entity: "{0}" to role: '{1}' in bucket '{2}' ". + "The entity holding the permission can be user-user Id, user-email Address, group-group Id, group-email Address, all Users, or all Authenticated Users." If successfully update entity role: "Successfully updated ACL entity: "{0}" to role: '{1}' in bucket '{2}' ". The action should fail and stop a playbook execution: If the entity does not exist, action should fail: "Error executing action "Update an ACL entry on Bucket". Reason: Entity {entity} does not exist in the ACL of bucket {bucket_name} if fatal error, like wrong credentials, no connection to server, other: "Error executing action "Update an ACL entry on Bucket". Reason: {0}''.format(error.Stacktrace)	General

List Bucket Objects

Description

List objects stored in the Cloud Storage bucket.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Bucket Name	String	N/A	Yes	Specify name of the bucket from which to retrieve objects.
Max Objects to Return	Integer	50	No	Specify how many objects to return.
Retrieves the Access Control List of an object	Boolean	Unchecked	No	If checked, retrieve the Access Control List of an object.

Run On

This action doesn't run on entities.

Action Results

Script Result

Script Result Name	Value Options
is_success	is_success=False
is_success	is_success=True

JSON Result

When Return ACL param is unchecked

{
    "Objects": [
        {
            "ObjectName": "test.txt", (blob.name)
        "Bucket:
        "ContentType":
            "TimeCreated": " ", (blob.time_created)
            "TimeUpdated": " ", (blob.updated)
            "Size": 18,(blob.size)
            "MD5": '7CjVfQ+Oz/C0pI08IKRdvQ==',
            "Owner": '',
            "CR32c": 'RQEqxA==',
            "id": 'siemplify-tip/test.txt/1604926667310271'
        },
        {
         …..
        }
    ]
}

When Return ACL param is checked

{
    "Objects": [
        {
            "ObjectName": "test.txt", (blob.name)
        "Bucket: "siemplify-tip", (blob.bucket.name)
        "ContentType": 'text/plain'
            "TimeCreated": " ", (blob.time_created)
            "TimeUpdated": " ", (blob.updated)
            "Size": 18,(blob.size)
            "MD5": '7CjVfQ+Oz/C0pI08IKRdvQ==',
            "Owner": '',
            "CR32c": 'RQEqxA==',
            "id": 'siemplify-tip/test.txt/1604926667310271',
            "ObjectACL": [
                {
                    "entity": '[e-mail]',
                    "role": "OWNER"
                }]
        },
        {
         …..
        }
    ]
}

Case Wall

Result Type	Value / Description	Type
Output message*	The action should not fail nor stop a playbook execution: If status code == 200 (is_success = true): "Successfully returned objects of the "{0}" bucket in AWS S3". If other status code (is_success=false): "Action wasn't able to return objects of the '{0}' bucket in AWS S3". The action should fail and stop a playbook execution: if fatal error, like wrong credentials, no connection to server, other: "Error executing action "List Bucket Objects". Reason: {0}''.format(error.Stacktrace)	General

Download an Object From a Bucket

Description

Download an object from a Cloud Storage bucket.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Bucket Name	String	N/A	Yes	Specify the name of the bucket in which the object resides
Object Name	String	N/A	Yes	Specify the name of the object in the bucket to download.
Download Path	String	/{folder_1}/{folder_2}/{filename}	Yes	Specify the absolute path, where to download the file. Example: /folder_1/folder_2/filename

Note: Please note, objects which are stored inside folders in the bucket, will be downloaded to the inner folder in the specified path. Object's relative path to the bucket will match relative path in the Download Path. Example: download_path/inner_folder

Run On

This action doesn't run on entities.

Action Results

Script Result

Script Result Name	Value Options
is_success	is_success=False
is_success	is_success=True

JSON Result

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

Case Wall

Result Type	Value / Description	Type
Output message*	The action should not fail nor stop a playbook execution: If successful: "Blob {} successfully downloaded to '{}' ". If bucket was invalid(is_success = false): "Action wasn't able to download '{0}'. Reason: Bucket {1} Not found". If object_name was invalid(is_success = false): "Action wasn't able to download '{0}'. Reason: No such object". The action should fail and stop a playbook execution: if fatal error, like wrong credentials, no connection to server, SDK errors, other: "Error executing action "Download an Object From a Bucket". Reason: {0}''.format(error.Stacktrace)	General

Upload an Object To a Bucket

Description

Upload an object to a Cloud Storage bucket.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Bucket Name	String	N/A	Yes	Specify the name of the bucket in which to upload the object.
Source File Path	String	/{local}/{path to}/{filename}	Yes	Specify the absolute path to the file that needs to be uploaded. Example: /local/path/to/filename
Object Name	String	{filename}	Yes	Specify the name of the uploaded object within the bucket.

Run On

This action doesn't run on entities.

Action Results

Script Result

Script Result Name	Value Options
is_success	is_success=False
is_success	is_success=True

JSON Result

{
   "object_id":"siemplify-tip/errorlog.txt/1610616919132517", (blob.id)
   "Object_name":"errorlog.txt", (blob.name)
   "md5_hash":"PTdL8D6pBwIKyMfIXR/H9A==", (blob.md5_hash)
   "object_path":"/b/siemplify-tip/o/errorlog.txt" (blob.path)
}

Case Wall

Result Type	Value / Description	Type
Output message*	The action should not fail nor stop a playbook execution: If status code == 200 (is_success = true): "Successfully uploaded '{0}' to bucket: {1}". If file does not exist (is_success = false): "Action wasn't able to upload '{0}' to Cloud Storage. Reason: No such file or directory: {source_file_path}" The action should fail and stop a playbook execution: if fatal error, like wrong credentials, no connection to server, SDK errors, other: "Error executing action "Upload an Object To a Bucket". Reason: {0}''.format(error.Stacktrace)	General