Author: Yuriy Landovskyy
Co-Author: Oleg Siminel

Overview

This guide provides detailed insights into the integration item, “Action”.

Google Cloud Security Operations (SecOps) Actions are Python scripts executed within playbooks to automate security tasks. These scripts are categorized under Integrations, which are packages installed from the SecOps Marketplace. Each Integration offers a set of sub-actions, such as assigning analysts to cases or updating external product agents. Before using Actions, it is important to ensure the necessary Integrations are downloaded and configured from the Marketplace. Refer to the Google Cloud documentation on configuring integrations for detailed instructions. When a playbook executes an Action, it returns information displayed on the Case Wall or in the Case screen's right-hand panel. This information can include output messages, tables, attachments, links, and JSON data. The script's result is also available, but only within the playbook itself.

The SecOps Marketplace provides a central repository for various tools, including Integrations, Use Cases, and Power Ups. Integrations connect SecOps with third-party applications, while Use Cases offer pre-built playbook workflows for automated incident response. Power Ups are tools developed by Google SecOps Professional Services to enhance playbook automation. New Power Ups are regularly added to the Marketplace. Custom Actions can be created using the SecOps IDE, allowing for tailored automation based on specific organizational needs. These custom actions can be added to the Marketplace for use across the organization or kept private. The IDE provides templates and helpful comments to simplify the development process. 

Actions can be configured to run automatically or manually, with options to define timeouts and default return values for situations where the action does not return a result within the specified time. The configuration options also include specifying which entities the action will run on and the instance to use.

Sync vs Async Actions

When talking about actions, there are two types of them: sync and async.

Sync Actions

Most actions in the Marketplace are sync type. Sync action means that the action will execute one or more API requests and return immediate results without waiting.

If you encounter a timeout error, you need to optimize the action configuration to handle data in smaller chunks.

Use Case with Sync Actions:

Scenario: Suspicious login attempts from an unusual geographic location.

A Security Information and Event Management (SIEM) alert is generated indicating multiple failed login attempts from an IP address geographically distant from the user's usual login location. The trigger condition could be defined within the playbook to specify the number of failed attempts and the distance threshold.

Playbook Actions (Automated):

1. Enrichment: The playbook automatically enriches the alert with threat intelligence data from various sources (e.g., Google Threat Intelligence) to determine if the IP address is known to be malicious. This action uses the "automatic" action type.
2. IP Address Blocking: If the IP address is flagged as malicious, the playbook automatically initiates a block on the identified IP address using a network security tool integrated with Google SecOps. This action is also configured as "automatic".
3. User Notification: The playbook automatically sends an email notification to the security team and/or the affected user, providing details about the suspicious activity and the actions taken. This action is configured as "automatic".
4. Case Creation/Update: The playbook automatically creates a new case in Google SecOps or updates an existing case with the relevant information, including the enriched threat intelligence and the remediation steps taken. This action is configured as "automatic".
5. Log Event: The playbook logs all actions taken, including timestamps and results, for auditing and reporting purposes. This action is configured as "automatic".

Configuration:

• Each action within the playbook is configured to run automatically ("Action Type" set to "Automatic").
• The "Choose Instance" parameter for each action is set to "Dynamic" to allow the playbook to adapt to different alert contexts.
• The "If Step Fails" parameter for each action is configured to determine the playbook's behavior in case of failure (e.g., stop execution, skip to the next action).
• The "Entities" parameter for each action specifies the relevant entities (e.g., IP address, username) that the action should affect.

Benefits:

• Reduced Response Time: Automates the initial response to suspicious login attempts, significantly reducing the time it takes to mitigate the threat.
• Improved Efficiency: Frees up security analysts to focus on more complex investigations.
• Increased Consistency: Ensures a consistent and repeatable response to similar incidents.
• Enhanced Security: Proactively blocks malicious IP addresses, minimizing the potential impact of attacks.

This use case highlights the power of Google SecOps' automated playbook capabilities using sync actions to streamline incident response and enhance overall security posture. The specific integrations and actions used can be customized based on the organization's security infrastructure and requirements.

Async Actions

Async actions are designed for a special situation, where during the business logic, we need to wait until a certain process will finish execution. 

For example, in many situations, if you are performing a search query via API, you will first need to create a search job, wait for it to be completed, and then retrieve the data. In order to make this process easier, instead of creating 3 steps in the playbook, we will consolidate it under 1 action and handle all of the logic in the script itself.

With async action, there are 2 important parameters to understand:

• Async Action Timeout - for how long the action should execute before raising timeout. 
• Async Polling Interval - how frequently the action should poll for a status update. 

When the action is in waiting state, you will see an orange case wall item. Like in the screenshot below:

When Async actions are in a waiting state, they remain lightweight and do not impact platform performance.

Important! By default, most actions have the Async Action Timeout set to 1 day and the Async Polling Interval set to 1 hour. It's important to understand these settings, as they can sometimes lead to confusion - what might appear to be a stalled action is often simply a result of the configured timing parameters.

These settings can be configured as needed, either through the IDE or directly within the Playbook.

Use Case with Asynchronous action - Email Validation

This use case describes a SecOps playbook that uses asynchronous actions to validate a key step with an end-user via email. The process automatically sends an email, waits for a reply, and then continues automatically once the response is received.

Playbook Workflow:

1. Trigger: The playbook is triggered by a rule detection or other event in SecOps.
2. Send Email Action: An email is automatically sent to the end-user using the Send Email action (Email V2, Gmail, or Exchange integration, depending on the email system). The email should clearly state the required action and provide clear instructions for the user to reply. The email should include a unique identifier (e.g., a case ID or ticket number) to help the system match the response to the correct playbook instance.
3. Wait for User Reply Action: The playbook then uses an asynchronous Wait for User Reply action (e.g., Wait for Email From User,  Wait for Thread Reply). This action will periodically check the specified mailbox for a reply matching the unique identifier from the sent email. The timeout for this action should be configured appropriately in the Google SecOps IDE to prevent indefinite waiting. The Wait Stage Exclude pattern parameter can be used to filter out unwanted replies, such as automatic out-of-office messages. The Folder to Check for Reply parameter can specify the mailbox folder to search for the reply. If desired, the Fetch Response Attachments option can be enabled to automatically retrieve any attachments included in the user's reply.
4. Response Analysis: Once a reply is received, the playbook analyzes the response. This might involve checking for keywords, comparing against expected values, or using more sophisticated natural language processing techniques.
5. Conditional Logic: Based on the analysis of the user's reply, the playbook branches to different actions. For example:
• If the user confirms the step, the playbook proceeds to close the case.
• If the user requires further information or disagrees, the playbook can loop back to the Send Email action, sending a follow-up email with additional details or clarification.
6. Case Closure or Escalation: The playbook concludes by either closing the case (if the user's response is satisfactory) or escalating the issue to a higher tier of support (if the user's response indicates a problem).

Key Considerations:

• Integration Selection: Choose the appropriate email integration (Email V2, Gmail, or Exchange) based on the organization's email system.
• Timeout Configuration: Carefully configure the timeout value for the Wait for User Reply action to balance responsiveness with resource consumption.
• Error Handling: Implement robust error handling to manage situations where the user does not reply within the timeout period or if there are issues with email delivery or retrieval.
• Security: Ensure that the email communication is secure and adheres to relevant security policies. Consider using secure email protocols and encryption.
• User Experience: Design the email communication to be clear, concise, and user-friendly. Provide clear instructions and context for the user's required action.

This approach leverages the asynchronous capabilities of Google SecOps to automate the validation process while ensuring that the SecOps analyst can efficiently manage the interaction with the end-user. The use of conditional logic allows for flexible handling of various user responses.

When you are updating these properties inside IDE, they become the new default for the action. Meaning that any new playbook will inherit the default configuration for the action from the IDE. Also, when you run the action manually, it will use the IDE configuration.

If you are updating the playbook, then only that playbook will have the changes.

Known issue: you can't run Async actions properly from IDE. If you want to test the action, you need to manually run it from the case.

Action Inputs

Overall, when talking about actions the input can be:

• via Entities
• via input parameters
• Combined

Most of the actions that work with entities will reference this information inside the action description, for example, like here:

The wording itself might be a little bit different, but most actions will reference that they are executed on entities.

Action Outputs

Currently, action support the following outputs/outcomes:

• Script Result
• JSON Result
• Entity Enrichment Table (this one is not necessarily an output, but actions can set custom properties for entities)
• Insights
• Widgets

Script Result, JSON Result and Entity Enrichment Table can be used inside playbooks via placeholders.

Here are examples of the outputs:

Script Result

JSON Result