HTTP v2

This document provides guidance on how to integrate HTTP v2 with the SOAR module of Google Security Operations and work with the Execute HTTP Request action.

Integration version: 5.0

Overview

Use HTTP v2 to integrate with third-party products without writing code and solve use cases such as executing API requests, working with files, and managing asynchronous flows.

Authentication flows

Depending on the product that you authenticate to, HTTP v2 supports the following authentication flows:

• Basic authentication flow
• API key flow
• Dedicated authentication flow

Basic authentication flow

With the basic authentication flow, authenticate using the Test URL , Basic Auth Username , and Basic Auth Password parameters.

API key flow

With the API key flow, authenticate using the Test URL , API Key Field Name , and API Key Field Value parameters.

Dedicated authentication flow

In the dedicated authentication flow, the following two-step authentication is used:

1. An action generates an access token.

   When either Ping or the Execute HTTP Request action runs, the integration retrieves the parameters required for authentication.

2. An action uses the generated access token to authenticate to API requests.

The dedicated authentication flow requires the following integration parameters:

• Dedicated Auth API Request Method
• Dedicated Auth API Request URL
• Dedicated Auth API Request Headers
• Dedicated Auth API Request Body
• Dedicated Auth API Request Token Field Name

For more details about the integration parameters, see Integrate HTTP v2 with Google SecOps .

To use the token from the response, provide the key name in the Dedicated Auth API Request Token Field Name parameter. In the following response example, the key name is access_token :

  { 
  
 "access_token" 
 : 
  
 "eyJhbGciOiJSUzI1NiIsImtpZCIO4" 
 , 
  
 "expires_in" 
 : 
  
 1799 
 , 
  
 "token_type" 
 : 
  
 "bearer" 
 } 
 

To apply the token, the integration requires the following dedicated placeholder: {{integration.token}} . When you provide this placeholder in the payload, the integration uses the generated token.

If the access_token key in the JSON response appears nested, provide the full token location for the Dedicated Auth API Request Token Field Name parameter value. For example, instead of the access_token provide the data_access_token key for the nested response like the following:

  { 
  
 "data" 
 : 
  
 { 
  
 "access_token" 
 : 
  
 "eyJhbGciOiJSUzI1NiIsImtpZCIZMI3DQAQsYibMpO4" 
 , 
  
 "expires_in" 
 : 
  
 1799 
 , 
  
 "token_type" 
 : 
  
 "bearer" 
  
 } 
 } 
 

The following example shows the request for the dedicated authentication flow to the Crowdstrike API:

  POST 
  
 / 
 fal 
 co 
 n 
 x/e 
 nt 
 i 
 t 
 ies/submissio 
 ns 
 /v 
 1 
  
 HTTP/ 
 1.1 
 Hos 
 t 
 : 
  
 api.crowds 
 tr 
 ike.com 
 Co 
 ntent 
 - 
 Type 
 : 
  
 applica 
 t 
 io 
 n 
 /jso 
 n 
 Au 
 t 
 horiza 
 t 
 io 
 n 
 : 
  
 Bearer 
  
 eyJhbGciOiJSUzI 
 1 
 NiIsIm 
 t 
 pZCI 
 6 
 Co 
 ntent 
 - 
 Le 
 n 
 g 
 t 
 h 
 : 
  
 209 
 { 
  
 "sandbox" 
 : 
  
 [{ 
  
 "sha256" 
 : 
  
 "9854c9dfded29d8442499daba01082ba5d164aa02e44" 
 , 
  
 "environment_id" 
 : 
  
 100 
 , 
  
 "submit_name" 
 : 
  
 "filename.pdf" 
  
 }] 
 } 
 

The example uses the Authorization header with a Bearer token to authenticate to the API. To populate the header with the correct information, the HTTP v2 integration requires the following input: Authorization: Bearer {{integration.token}} .

Integrate HTTP v2 with Google SecOps

The integration requires the following parameters:

{
    "Content-type": "application/x-www-form-urlencoded"
    }

{
    "client_id": " CLIENT_ID 
",
    "client_secret": " CLIENT_SECRET 
"
    }

It's a good practice to create a separate instance of HTTP v2 integration for every third-party product that you integrate with in your environment. For more information about multiple integration instances, see Supporting multiple instances .

How to use the HTTP v2 integration

This section explains how to use the HTTP v2 integration by modifying the Execute HTTP Request action parameters .

Work with the Body Payload parameter

To ensure that the body is constructed correctly, provide the correct Content-Type header in the Headers parameter. The Execute HTTP Request action generates different payloads for the same following parameter input:

  { 
  
 "Id" 
 : 
  
 "123123" 
 , 
  
 "sorting" 
 : 
  
 "asc" 
 } 
 

For the "Content-Type:" "application/x-www-form-urlencoded" header value, the generated payload is Id=123123&sorting=asc .

For the "Content-Type": "application/json" header value, the generated payload is as follows:

  { 
  
 "Id" 
 : 
  
 "123123" 
 , 
  
 "sorting" 
 : 
  
 "asc" 
 } 
 

When working with XML, provide an XML-formatted input like the following:

 <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
   <NumberToWords xmlns="http://www.dataaccess.com/webservicesserver/">
     <ubiNum>500</ubiNum>
   </NumberToWords>
 </soap:Body>
</soap:Envelope> 

Work with the asynchronous flow

Asynchronous API flows like creating and running a search job require waiting for the result to complete processing before executing the next API request. For example, you can create a search job in Google SecOps SIEM, wait for the search job to complete execution, and then retrieve results using the Expected Response Values parameter.

In the following response example, the state key can contain error , in_progress , or finished value:

  { 
  
 "state" 
 : 
  
 "in_progress" 
 , 
  
 "percentage" 
 : 
  
 "10" 
 } 
 

You can request the Execute HTTP Request action to run in an asynchronous mode until the response contains the finished state by setting the Expected Response Values parameter to the following value:

  { 
  
 "state" 
 : 
  
 "finished" 
 } 
 

To not wait until timeout when an error occurs, provide an additional condition in the parameter value. In the following input example, the action stops running when the state is either finished or error :

  { 
  
 "state" 
 : 
  
 [ 
  
 "finished" 
 , 
  
 "error" 
  
 ] 
 } 
 

In the following example, the action stops running when the state is finished and the percentage key value is 100 :

  { 
  
 "state" 
 : 
  
 "finished" 
 , 
  
 "percentage" 
 : 
  
 "100" 
 } 
 

You can combine multiple key conditions in one input, such as the following:

  { 
  
 "state" 
 : 
  
 [ 
  
 "finished" 
 , 
  
 "error" 
  
 ], 
  
 "percentage" 
 : 
  
 "100" 
 } 
 

You can configure the Expected Response Values parameter to expect an output for a specific key-value pair. The Execute HTTP Request action searches the entire JSON response object for a specific key and considers that the expected output is reached only when you set all matching key names to an identical expected key value. For example, for the action to search for the finished state match in the JSON response and ignore any other states, set all state keys in the Expected Response Values parameter input to the finished value:

  { 
 "data" 
 : 
  
 { 
  
 "state" 
 : 
  
 "finished" 
  
 }, 
  
 "state" 
 : 
  
 "finished" 
 } 
 

The Expected Response Values parameter retrieves the required value from the nested JSON object. For the following example, only provide the state key, not data_state or data-state :

  { 
  
 "data" 
 : 
  
 { 
  
 "state" 
 : 
  
 [ 
  
 "finished" 
 , 
  
 "error" 
  
 ], 
  
 "percentage" 
 : 
  
 "100" 
  
 } 
 } 
 

Work with files

Working with files includes two separate workflows:

• Downloading a file
• Uploading a file

Download files

The Execute HTTP request action can return files as base64 output in the JSON object or save files to the Case Wall as zip files.

To return the data as part of a JSON result in the base64 format, select the Base64 Output parameter. To save files to the Case Wall, select the Save To Case Wall parameter.

If you work with sensitive files like malware, select the Password Protect Zip parameter. For all password-protected zip files, the action automatically sets the password to infected .

Upload files

To upload files, convert them to the base64 format and submit them as a part of the Body Payload parameter value. The example of an image file converted to the base64 format is as follows:

 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 

For more information about how to use the Body Payload parameter, see the Work with the Body Payload parameter section of this document.

Blocks-as-code

You can use the HTTP v2 integration and the playbook block capability in Google SecOps to build reusable content. For example, you can create a playbook block containing an HTTP v2 action and configure an integration to use the action results as block inputs. For more information about playbook blocks, see Working with playbook blocks .

Create playbook blocks

To create a playbook block, complete the following steps:

1. In Google SecOps, go to Response > Playbooks.
2. In the Playbookspage navigation bar, select add Add New Playbook or Block. The Create Newwindow opens.
3. In the Create Newwindow, set the Type parameter to Block .
4. For the Choose Folder parameter, select the folder to save the new block to.
5. For the Environment parameter, select your environment.
6. Click Create. The New Blockpage opens. Configure the new playbook block to use it in multiple playbooks.

The following section is an example of how to configure a playbook block.

Playbook block configuration example

The following example is a custom Execute HTTP Request action that sends comments to ServiceNow. The action uses the comment , sys_id , and table_name parameters that the custom playbook block created as input parameters. To configure the action parameters , complete the following steps:

1. Set the Method parameter to PUT .

2. Set the URL Path parameter to the following value:

    https:// SERVICE_NOW_INSTANCE 
   .service-now.com/api/now/table/[ Input.table_name 
   ]/[ Input.sys_id 
   ] 
   

3. Set the Headers parameter to the following value:

    {"Content-type": "application/json; charset=utf-8",
   "Accept": "application/json", "User-Agent": "GoogleSecops"} 
   

4. Set the Body Payload parameter to the following value:

    {
   "work_notes": "[ Input.comment 
   ]"
   } 
   

To use the values that are provided for the block inputs as placeholders for the action, the placeholders must contain the Input. prefix before the parameter name. If the input for the block is keyname , the placeholder for it is [Input.keyname] .

Actions

The HTTP v2 integration includes the following actions:

• Execute HTTP Request
• Ping

Execute HTTP Request

Execute an HTTP request using the HTTP v2 integration.

Use this action to create a custom HTTP request and return information about it. All parameters in this action are modifiable.

This action doesn't run on entities.

Action inputs

The Execute HTTP Request action requires the following parameters:

{
    "parameter": "value",
    "sorting": "asc"
    }

{
    "URL Field Name": " URL_FIELD_VALUE 
"
    }

{
    "Accept": "application/json",
    "User-Agent": "Google Secops"
    }

{
    "Content-Type": "application/json; charset=utf-8",
    "Accept": "application/json",
    "User-Agent" : "GoogleSecOps"
    }

{
    "PHPSESSID": "298zf09hf012fh2",
    "csrftoken": "u32t4o3tb3gg43"
    }

{
    "Cookie_1": " COOKIE_1_VALUE 
"
    }

{
    "Body Field Name": " BODY_FIELD_VALUE 
"
    }

Action outputs

The Execute HTTP Request action provides the following outputs:

JSON result

The following example describes the JSON result output received when using the Execute HTTP Request action:

  { 
  
 "response_data" 
 : 
  
 { 
  
 "data" 
 : 
  
 { 
  
 "relationships" 
 : 
  
 { 
  
 "comment" 
 : 
  
 [ 
  
 { 
  
 "name" 
 : 
  
 "item" 
 , 
  
 "description" 
 : 
  
 "Object to which the comment belongs to." 
  
 }, 
  
 { 
  
 "name" 
 : 
  
 "author" 
 , 
  
 "description" 
 : 
  
 "User who wrote the comment." 
  
 } 
  
 ] 
  
 } 
  
 } 
  
 }, 
  
 "redirects" 
 : 
  
 [], 
  
 "response_code" 
 : 
  
 200 
 , 
  
 "cookies" 
 : 
  
 {}, 
  
 "response_headers" 
 : 
  
 { 
  
 "Content-Type" 
 : 
  
 "application/json" 
 , 
  
 "X-Cloud-Trace-Context" 
 : 
  
 "1ca450b35c66634a2ae01248cca50b19" 
 , 
  
 "Date" 
 : 
  
 "Fri, 03 Nov 2023 16:14:13 GMT" 
 , 
  
 "Server" 
 : 
  
 "Google Frontend" 
 , 
  
 "Content-Length" 
 : 
  
 "36084" 
  
 }, 
  
 "apparent_encoding" 
 : 
  
 "ascii" 
 } 
 

Output messages

On a Case Wall, the Execute HTTP Request action provides the following output messages:

Script result

The following table describes the values for the script result output when using the Execute HTTP Request action:

Ping

Use this action to test the connectivity.

Action inputs

None.

Action outputs

The Ping action provides the following outputs:

Output messages

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

Script result

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

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