Integrate SiemplifyUtilities with Google SecOps

Integration version: 20.0

This document explains how to integrate SiemplifyUtilities with Google Security Operations (Google SecOps).

Use cases

The SiemplifyUtilities integration can address the following use cases:

  • Export and sharing: Use Google SecOps capabilities with the Export Entities as OpenIOC File action to quickly generate standardized OpenIOC files from security entities (such as IPs, Filehashes, or URLs) and share them with threat intelligence platforms or other security teams.

  • List manipulation for logic: Use Google SecOps capabilities with the List Operations action to perform complex logic operations (such as intersection, union, subtract) on two different lists of values within a Playbook, providing advanced filtering or combining of data sources.

  • Data Transformation and Analysis: Use Google SecOps capabilities with the Extract top From JSON action to process and prioritize large, nested JSON datasets by sorting them based on a specific nested key (like a severity score) and returning only the top relevant results for immediate analysis.

  • Email Forensics: Use Google SecOps capabilities with the Parse EML to JSON action to convert raw, base64-encoded email messages (EML or MSG files) into a structured JSON format, making the email's headers, body, attachments, and links accessible for automated parsing and investigation.

Integration parameters

None.

Actions

For more information about actions, see Respond to pending actions from Your Workdesk and Perform a manual action.

Count Entities in Scope

Use the Count Entities in Scope to retrieve the number of entities in a specific scope.

This action runs on all Google SecOps entities.

Action inputs

The Count Entities in Scope action requires the following parameters:

Parameter Description
Entity Type

Required.

The type of the target entities.

Action outputs

The Count Entities in Scope 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

The Count Entities in Scope action can return the following output messages:

Output message Message description

There are NUMBER_OF_ENTITIES entities from ENTITY_TYPE type.

 The action succeeded.
Error executing action "Count Entities in Scope". Reason: ERROR_REASON

The 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 Count Entities in Scope action:

Script result name Value
list_count NUMBER_OF_ENTITIES

Count List

Use the Count List action to retrieve the number of items on a list.

This action doesn't run on Google SecOps entities.

Action inputs

The Count List action requires the following parameters:

Parameter Description
Input String

Optional.

A comma-separated list of strings, such as value1,value2,value3.
Delimiter

Optional.

The symbol used to separate individual values within the Input String.

Action outputs

The Count 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
Output messages

The Count List action can return the following output messages:

Output message Message description

List length is: NUMBER_OF_ENTITIES

 The action succeeded.
Error executing action "Count List". Reason: ERROR_REASON

The 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 Count List action:

Script result name Value
list_count NUMBER_OF_ENTITIES

Delete File

Use the Delete File action to delete a selected file from the file system.

This action doesn't run on Google SecOps entities.

Action inputs

The Delete File action requires the following parameters:

Parameter Description
File Path

Required.

The absolute path of the file to delete.

Action outputs

The Delete File 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 shows the JSON result outputs received when using the Delete File action:

{
"filepath": ""
"status": "deleted/not found"
}
Output messages

The Delete File action can return the following output messages:

Output message Message description

Successfully deleted file.

 The action succeeded.
Error executing action "Delete File". Reason: ERROR_REASON

The action failed.

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

The following table lists the value for the script result output when using the Delete File action:

Script result name Value
is_success true or false

Export Entities as OpenIOC File

Use the Export Entities as OpenIOC File action to package supported security artifacts from the current case into a standard OpenIOC file format. This file can be used for sharing, threat intelligence, or importing into other security tools.

This action runs on the following Google SecOps entities:

  • Filehash

  • IP Address

  • URL

  • Hostname

  • User

Action inputs

The Export Entities as OpenIOC File action requires the following parameters:

                       
ParameterDescription
Export Folder Path

Required.

   

The local path of the folder where the generated OpenIOC file will be saved.

   

Action outputs

The Export Entities as OpenIOC File 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 shows the JSON result outputs received when using the Export Entities as OpenIOC File action:

{
    "absolute_file_path": OpenIOC_{random_guid}.txt
}
Output messages

The Export Entities as OpenIOC File action can return the following output messages:

Output message Message description

Successfully created an OpenIOC file based on provided entities.

Action wasn't able to create an OpenIOC file, because there are no entities in the action execution scope.

 The action succeeded.
Error executing action "Export Entities as OpenIOC File". Reason: ERROR_REASON

The action failed.

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

Extract top From JSON

Use the Extract top From JSON action to sort an input JSON by a specific key and return the top-ranked branches or records.

This action doesn't run on Google SecOps entities.

Action inputs

The Extract top From JSON action requires the following parameters:

                                                                       
ParameterDescription
JSON Data

Required.

   

The JSON data to process.

   
Key To Sort By

Required.

   

The nested key used for sorting, with segments separated by dots.

Use * as a wildcard. For example, Host.*.wassap_list.Severity.

   
Field Type

Required.

   

The data type of the key specified for sorting.

The possible values are as follows:

  • int
  • string
  • Date
   
Reverse (DESC -> ASC)

Optional.

   

If selected, the sort order is Descending. If not selected, the sort order is Ascending.

   

Enabled by default.

   
Top Rows

Optional.

   

The number of top records (rows) to retrieve from the sorted JSON output.

   

Action outputs

The Extract top From JSON 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 shows the JSON result outputs received when using the Extract top From JSON action:

[
    {
        "HOST": {
            "DETECTION":{
                "QID": "82003",
                "SEVERITY": "1",
                "RESULTS": "Timestamp of host (network byte ordering): 03:40:14 GMT"
            },
            "IP": "1.1.1.1",
            "LAST_SCAN_DATETIME": "2018-08-13T10:24:35Z",
            "OS": "Windows 10"
        },
        "DATETIME": "2018-08-29T14:01:12Z"
    }, {
        "HOST":{
            "DETECTION": {
                "PORT": "443",
                "QID": "11827",
                "PROTOCOL": "tcp",
                "RESULTS": "X-Frame-Options or Content-Security-Policy: frame-ancestors HTTP Headers missing on port 443.",
                "SEVERITY": "2"
            },
            "IP": "1.1.1.1",
            "LAST_SCAN_DATETIME": "2018-08-13T08:31:58Z",
            "OS": "Linux 3.13"
        },
        "DATETIME": "2018-08-29T14:01:12Z"
    }, {
        "HOST": {
            "DETECTION": {
                "PORT": "53",
                "QID": "15033",
                "PROTOCOL": "udp",
                "RESULTS": "--- IPv4 --- ",
                "SEVERITY": "4"
            },
            "IP": "1.1.1.1",
            "LAST_SCAN_DATETIME": "2018-08-13T08:31:58Z",
            "OS": "Linux 3.13"
        },
        "DATETIME": "2018-08-29T14:01:12Z"
    }
]
Output messages

The Extract top From JSON action can return the following output messages:

Output message Message description

Results: RESULTS.

No branches were found.

 The action succeeded.
Error executing action "Extract top From JSON". Reason: ERROR_REASON

The action failed.

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

The following table lists the value for the script result output when using the Extract top From JSON action:

Script result name Value
result RESULTS

Filter JSON

Use the Filter JSON action to filter a JSON object based on a specified condition and extract specific results.

This action doesn't run on Google SecOps entities.

Action inputs

The Filter JSON action requires the following parameters:

                                                                                               
ParameterDescription
JSON Data

Required.

   

The JSON dictionary data to apply the filter to.

   
Root Key Path

Optional.

   

The dot-separated starting path for the JSON search.

   
Condition Path

Required.

   

The dot-separated path to the field whose value is evaluated against the filter condition.

   
Condition Operator

Required.

   

The comparison operator to use in the condition.

   

The possible values are as follows:

  • =
  • !=
  • >
  • <
  • >=
  • <=
  • in
  • not in
   
Condition Value

Required.

   

The specific value to use in the filter condition.

   
Output Path

Optional.

   

The dot-separated path to the specific data elements to return from the filtered JSON.

   
Delimiter

Optional.

   

The character used to join the output values if multiple elements are returned.

   

The default value is ,.

   

Action outputs

The Filter JSON action provides the following outputs:

                                                                                                                                                       
Action output typeAvailability
Case wall attachmentNot available
Case wall linkNot available
Case wall tableNot available
Enrichment tableNot available
JSON resultAvailable
Output messagesAvailable
Script resultAvailable
JSON result

The following example shows the JSON result output received when using the Filter JSON action:

{
    "a": {
        "HOST": [
            {
                "DETECTION": {
                    "QID": "82003",
                    "SEVERITY": "1",
                    "RESULTS": "Timestamp of host (network byte ordering): 03:40:14 GMT"
                },
                "IP": "1.1.1.1",
                "LAST_SCAN_DATETIME": "2018-08-13T10:24:35Z",
                "OS": "Windows 10"
            }
        ],
        "DATETIME": "2018-08-29T14:01:12Z"
    }
}
Output messages

The Filter JSON action can return the following output messages:

Output message Message description

Successfully filtered JSON.

 The action succeeded.
Error executing action "Filter JSON". Reason: ERROR_REASON

The action failed.

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

The following table lists the value for the script result output when using the Filter JSON action:

Script result name Value
is_success true or false

Get Deployment URL

Use the Get Deployment URL action to retrieve the deployment URL for your current Google SecOps instance.

This action doesn't run on Google SecOps entities.

Action inputs

None.

Action outputs

The Get Deployment URL 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 shows the JSON result outputs received when using the Get Deployment URL action:

{
"url": ""
}
Output messages

The Get Deployment URL action can return the following output messages:

Output message Message description

Successfully retrieved deployment URL.

 The action succeeded.
Error executing action "Get Deployment URL". Reason: ERROR_REASON

The action failed.

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

The following table lists the value for the script result output when using the Get Deployment URL action:

Script result name Value
is_success true or false

List Operations

Use the List Operations action to perform set operations between two provided comma-separated lists.

This action doesn't run on Google SecOps entities.

Action inputs

The List Operations action requires the following parameters:

                                                           
ParameterDescription
First List

Required.

   

The first list of comma-separated values for the set operation.

Second List

Required.

   

The second list of comma-separated values for the set operation.

Delimiter

Optional.

   

The symbol or character used to separate values in both the First List and Second List.

   

The default value is ,.

Operator

Required.

   

The type of set operation to perform.

   

The possible values are as follows:

  • intersection
  • union
  • subtract
  • xor (exclusive OR).

Action outputs

The List Operations 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 shows the JSON result outputs received when using the List Operations action:

{
    "results": {
        "count": 6,
        "data": [
            "item",
            "item1",
            "item2"
        ]
    }
}​​
Script result

The following table lists the value for the script result output when using the List Operations action:

Script result name Value
result_list RESULTS

Parse EML to JSON

Use the Parse EML to JSON action to convert the content of an EML or MSG email file into a structured JSON object within Google SecOps.

This action doesn't run on Google SecOps entities.

Action inputs

The Parse EML to JSON action requires the following parameters:

                                               
ParameterDescription
EML Content

Required.

   

The base64-encoded content of the EML or MSG file.

Blacklisted Headers

Optional.

   

A comma-separated list of headers to exclude from the final JSON output.

Use Blacklist As Whitelist

Optional.

   

If selected, the list provided in Blacklisted Headers acts as a whitelist, including only those listed headers in the JSON output.

Action outputs

The Parse EML to JSON 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 shows the JSON result outputs received when using the Parse EML to JSON action:

{
    "HTML Body": "<div><br></div>",
    "Attachments": {},
    "Recipients": "[email protected]",
    "CC": "",
    "Links": {
        "urls_1": "https://lh4.googleusercontent.com/rE6-WYjfFuiHbHUV33G31NCtUeBl9YGnw4bvlorqMeNaC60qWagqtohFwCpq2eJxlMYMJPPDAqqXRZW6Oja8GqOjt3jB3aB6tzJP-jdtbCBoj-m3vu49tttHmWpXGJUSI6UuTUYS",
        "urls_2": "https://lh4.googleusercontent.com/Uih5TalWnJjBbG_QaRICp8emX5wIakbCmstEDP3YHT7l45qdjIllcxg_Ddapvrh5DqGKszK3KKM5M0kEoC1YX6TgbWKJKPX0OxD5BeWr3uu6SRAHs7lwP20khjHSlxsIM46egQ-M"
    },
    "BCC": "",
    "To": "[email protected]",
    "Date": "Mon, 13 Aug 2018 13:20:34 +0300",
    "From": "[email protected]",
    "Subject": "TEST6:::Test:::ADVANCE NOTICE: 07.08.2018-Disable Accounts-user\\\r\\\\n Office Il Office"
}
Script result

The following table lists the value for the script result output when using the Parse EML To JSON action:

Script result name Value
parsed_eml RESULTS

The action's JSON output for the with field is restructured to separate the ID value into a dedicated field. This change applies to version 10 and later of the integration as described in the following table:

                                               
Integration VersionField Structure and DescriptionExample JSON
Version 9 and earlierThe ID and the protocol are combined into the with field.{"with": "smtp id ID"}
Version 10 and laterThe ID is stored in the new id field, and the with field contains only the protocol.{"id": "ID", "with": "SMTP"}

Ping

Use the Ping action to test the connectivity to SiemplifyUtilities.

This action doesn't run on Google SecOps entities.

Action inputs

None.

Action outputs

The Ping 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

The Ping action provides the following output messages:

Output message Message description
Connection Established. The action succeeded.
Failed to connect to SiemplifyUtilities. Error is ERROR_REASON

The 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

Query Joiner

Use the Query Joiner action to dynamically construct a structured query string by combining a list of search values, a target field, and a logical operator.

This action doesn't run on Google SecOps entities.

Action inputs

The Query Joiner action requires the following parameters:

                                                                       
ParameterDescription
Values

Required.

   

A comma-separated list of values to search for, such as value1,value2,value3.

Query Field

Required.

   

The target field name to search in, such as SrcIP, DestHost, or UserName.

Query Operator

Required.

   

The logical operator used to combine the values, such as AND or OR.

   
Add Quotes

Optional.

   

If selected, single quotes (') are added around each item in the Values list.

Not enabled by default.

   
Add Double Quotes

Optional.

   

If selected, double quotes (") are added around each item in the Values list.

Not enabled by default.

   

Action outputs

The Query Joiner 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

The Query Joiner action can return the following output messages:

Output message Message description

Successfully formed query: QUERY_FIELD= VALUE_1 OPERATOR QUERY_FIELD= VALUE_2 OPERATOR QUERY_FIELD= VALUE_3

 The action succeeded.
Error executing action "Query Joiner". Reason: ERROR_REASON

The action failed.

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

The following table lists the value for the script result output when using the Query Joiner action:

Script result name Value
query QUERY_FIELD= VALUE_1 OPERATOR QUERY_FIELD= VALUE_2 OPERATOR QUERY_FIELD= VALUE_3

Need more help? Get answers from Community members and Google SecOps professionals.