HTTP v2

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

Integration version: 5.0

Overview

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

Authentication flows

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

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

Basic authentication flow

With the basic authentication flow, authenticate using theTest URL,BasicAuth Username, andBasic Auth Password parameters.

API key flow

With the API key flow, authenticate using theTest URL,API Key Field Name, andAPI Key Field Value parameters.

Dedicated authentication flow

In the dedicated authentication flow, the following two-step authentication isused:

1. An action generates an access token.

   When eitherPing or theExecute HTTP Requestaction runs, the integration retrieves the parameters required forauthentication.

2. An action uses the generated access token to authenticate to APIrequests.

The dedicated authentication flow requires the following integrationparameters:

• 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, seeIntegrate HTTP v2 withGoogle SecOps.

To use the token from the response, provide the key name in theDedicated Auth API Request Token Field Name parameter. Inthe following response example, the key name isaccess_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 thisplaceholder in the payload, the integration uses the generated token.

If theaccess_token key in the JSON response appears nested, provide the fulltoken location for theDedicated Auth API Request Token Field Name parametervalue. For example, instead of theaccess_token provide thedata_access_tokenkey 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 flowto the Crowdstrike API:

POST/falconx/entities/submissions/v1HTTP/1.1Host:api.crowdstrike.comContent-Type:application/jsonAuthorization:BearereyJhbGciOiJSUzI1NiIsImtpZCI6Content-Length:209{"sandbox":[{"sha256":"9854c9dfded29d8442499daba01082ba5d164aa02e44","environment_id":100,"submit_name":"filename.pdf"}]}

The example uses theAuthorization header with aBearer token to authenticateto the API. To populate the header with the correct information, the HTTP v2integration 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"    }

For instructions about how to configure an integration inGoogle SecOps, seeConfigureintegrations.

You can make changes at a later stage, if needed. After you configure anintegration instance, you can use it in playbooks. For more information abouthow to configure and support multiple instances, seeSupportingmultiple instances.

Actions

The HTTP v2 integration includes the following actions:

• Execute HTTP Request
• Ping

Execute HTTP Request

Use theExecute HTTP Request action to construct and execute a customizedHTTP API request against a target URL.

This action doesn't run on Google SecOps entities.

Action behavior

This action supports complex behaviors including asynchronous polling, dynamicpayload construction, and file management.

Asynchronous polling

WhenExpected Response Values is provided, theaction operates in asynchronous mode. In this mode, the action repeatedly pollsthe target endpoint to track the state of a response (for example, waiting for a long-running task to complete).

The action evaluates the response body against the JSON conditions provided inthe parameter and continues execution until the conditions are met or the actionreaches its timeout.

Condition logic

The action supports the following logic for tracking response states:

• Single field matching: The action waits for a specific field to reach asingle value.

  {"state":"finished"}

• Multiple values (OR logic): The action stops execution if a field matchesany value in a provided list. This is useful for stopping on both "success" and"error" states to avoid unnecessary polling.

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

• Multiple fields (AND logic): The action waits until all specified fieldsmatch their respective values simultaneously.

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

• Combined logic: You can combine multiple conditions within the JSONobject.

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

JSON parsing behavior

When evaluating conditions, the action follows these rules:

• Global search: The action searches the entire JSON response object for thespecified keys. Provide the key name exactly as it appears in theJSON without prepending parent object names or using prefixes (for example, use"state", not"data_state" or"data-state").

• Multiple identical keys: If the response contains multiple keys with thesame name at different levels of the JSON hierarchy, the expected output is onlyreached when all matching key names satisfy the identical expected value.

  For example, to search for thefinished state in the JSON response andignore other states, set allstate keys inExpected Response Values tofinished:

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

Body payload construction

The action constructs the request body based on theContent-Type headerprovided inHeaders.

This is theBody Payload input used forthe following construction examples:

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

• application/x-www-form-urlencoded: The action generates the payload asId=123123&sorting=asc.

• application/json: The action generates the following JSON payload:

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

• XML: If the third-party product requires XML, provide an XML-formattedinput directly inBody Payload:

  <?xmlversion="1.0"encoding="utf-8"?><soap:Envelopexmlns:soap="[http://schemas.xmlsoap.org/soap/envelope/](http://schemas.xmlsoap.org/soap/envelope/)"><soap:Body><NumberToWordsxmlns="[http://www.dataaccess.com/webservicesserver/](http://www.dataaccess.com/webservicesserver/)"><ubiNum>500</ubiNum></NumberToWords></soap:Body></soap:Envelope>

File handling

The action supports the following workflows for managing files:

• Downloading files:

  • To return file data as part of the JSON result in base64 format, selectBase64 Output.

  • To save a file directly to the Case Wall as a ZIP archive, selectSave To Case Wall.

• Uploading files: To upload a file, convert it to a base64-encoded stringand include it as part of theBody Payload value.

  The following example shows an image file converted to a base64-encodedstring:

  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

• Security: For sensitive files (such as malware), selectPassword Protect Zip. This automatically encrypts thesaved ZIP archive created usingSave To Case Wall with the passwordinfected.

Playbook block configuration

The following configuration demonstrates how to use theExecute HTTP Requestaction within a playbook block. Use this example to understand how to applyplaceholders and input prefixes.

When using block inputs as placeholders, you must include theInput. prefix(for example,[Input.comment]).

• Method:PUT

• URL Path:

  https://{API_URL}/[Input.table_name]/[Input.sys_id]

• Headers:

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

• Body Payload:

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

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 theExecute 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 outputmessages:

Script result

The following table describes the values for the script result output when usingthe 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 usingthe Ping action:

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