Create an enrichment playbook block

Supported in:

This document describes how to create a reusable block you can use in Google Security Operations playbooks to enrich entities, such as IPs, domains, file hashes, and users, with data from various third-party threat intelligence and information services. Using a block promotes modularity, consistency, and easier maintenance across multiple playbooks.

Core concepts

  • Entity: An object of interest within an alert or case, such as an IP address, domain name, file hash, URL, or username.
  • Enrichment: The process of adding context or information to an entity from external data sources. This can include reputation scores, geolocation, WHOIS data, malware analysis results, or user-directory details.
  • Block: A reusable set of actions and logic within Google SecOps, similar to a function or subroutine. You can call blocks from multiple playbooks to reduce duplication.
  • Third-party intelligence services: External services that provide data for enrichment. Examples include VirusTotal, Mandiant, AbuseIPDB, WHOIS services, and internal custom threat feeds.

Design the enrichment block

Review the following principles and requirements before you build a block that processes various entity types and queries multiple third-party services.

  • Inputs: The block typically operates on the entities present in the alert's context. Actions automatically target entities, so you don't usually need special block inputs.
  • Outputs: The block modifies the entities in the alert context by adding new fields or properties that contain the enrichment data. It doesn't usually need to return a specific output value.
  • Abstraction principles:
    • Service-agnostic: Add or remove intelligence sources.
    • Entity type handling: Conditionally execute actions based on the entity type.
    • Configurable: Lets you toggle sources and set parameters. For example, set thresholds for suspicious flags through integration settings or environment variables.

Create the enrichment block

This section describes how to create the enrichment block.

Define the block

This example creates a block called TPI_Enrich_Entities (Third-Party Intelligence Enrich Entities).

To define the block, follow these steps:

  1. Go to Response > Playbooks.
  2. Click Add and select Block.
  3. Enter the name for the block: TPI_Enrich_Entities.
  4. Provide a clear description: Enriches entities (IPs, domains, hashes, URLs) using various third-party intelligence services..
  5. Make the block available for all environments unless service keys are environment-specific.

Add enrichment actions

To add enrichment actions to the block, drag the following actions (and other services) from the Actions set for each third-party service, as required:

  • VirusTotal v3:
    • Enrich Hash
    • Enrich IP
    • Enrich Domain
    • Enrich URL
  • Mandiant Threat Intelligence:
    • Mandiant Enrich Entities This action often handles multiple entity types internally.
  • AbuseIPDB:
    • Enrich IP

Configure actions

To configure actions, follow these steps:

  1. Double-click each step to configure its parameters.
  2. Select the appropriate integration instance for the environments that need the block. Use Dynamic if your integrations aren't in the shared environment.
  3. Thresholds: For services, such as VirusTotal, set appropriate detection thresholds (for example: engine_threshold).
  4. Scope: Most enrichment actions automatically run on all relevant entities in the alert.

Error handling

To configure the block to deal with errors:

  • Within each action's settings, turn on the Retry on failure slider. It's generally best to allow at least one retry on enrichment actions in case of any self-correcting issues with the network or load on the third-party side. Further retries will depend on your API allotments and subject-matter expertise in the third-party integration.
  • Configure the If action fails option. It's generally best to set this to Skip to prevent the failure of one service from stopping the entire enrichment process. You can view any failed steps manually.

Save the block

When you finish setting up the block, save it to add to your playbook blocks.

Extend the block

To extend the block by adding new enrichment sources, follow these steps:

  1. Verify that the integration for the new service is installed and configured in the Content Hub.
  2. Open the TPI_Enrich_Entities block to edit it.
  3. Add Actions by dragging the relevant enrichment actions from the integration into the block.
  4. Define the new action's parameters and specific settings.
  5. Test the block with entities relevant to the new source.

Use the enrichment block in playbooks

To use the block in playbooks, follow these steps:

  1. Open the playbook where you want to add enrichment. This typically applies to most playbooks.
  2. In the Playbook editor, go to the Blocks tab.
  3. Drag the TPI_Enrich_Entities block into your playbook flow, typically after the trigger and initial triage steps. The block instance doesn't usually need special parameters because it acts on the alert's entities.

Example: Default playbook flow

  1. Trigger: All alerts

  2. Action: Set case stage to Triage

  3. Run block: TPI_Enrich_Entities

  4. Action: Continue with manual review or additional analysis.

Troubleshooting

Issue Suggestions
Enrichment data not appearing
  • Check the case playbook execution log or case wall for errors in the block's actions.
  • Confirm the alert entities match the types supported by the block.
  • Verify you've not exceeded API rate limits.
Action failures
  • Review error messages in the execution log. Common issues can include network problems, invalid API keys, or service outages.
  • Because actions are set to `Skip` on failure, other services should still run.
Unexpected data
  • Look at the raw JSON output from the enrichment action to understand the structure.
  • Adjust any custom field mappings or display widgets as needed.

Best practices

The following are recommended practices for working with blocks.

Security

Manage your API keys securely within the settings. Don't hardcode any credentials in playbooks or blocks.

Efficiency

  • Monitor API rate limits for each third-party service.
  • Avoid excessive calls.
  • Integrations often handle entity-type filtering internally.

Data handling

  • Prefix field names: When enrichment data is added to an entity, use the source name as a key prefix. This is to avoid conflicts and provide clarity. Many integrations do this automatically. If you parse data manually, add prefixes, such as VT_DetectionRatio, MDT_Score, AIPDB_Confidence.
  • Normalization: While full normalization within the block can be complex, be aware of different data formats. Aim for consistency in data formats where possible.
  • JSON Results: Many actions return JSON. Use built-in JSON-path expressions to extract key information from actions that return JSON.

Maintenance

  • Update integrations to their latest versions.
  • Periodically review the effectiveness and reliability of each third-party service.
  • Document the included services in the block description.

Testing

  • Test the block with various alert scenarios containing different entity types.
  • Verify the block adds enrichment data correctly and handles failures gracefully.

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