Integrate Vertex AI with Google SecOps

This document explains how to integrate Vertex AI with Google Security Operations.

Use cases

The Vertex AI integration supports the following use cases:

  • Automated malicious email analysis: Analyze raw EML files to extract threat levels, identify phishing links or social engineering indicators, and recommend verification steps.

  • Contextual entity enrichment: Generate natural language summaries of security entities to accelerate investigator comprehension during triage.

  • Flexible playbook orchestration: Run unstructured generative text prompts inside playbooks to assist with predictive defense or complex security analysis.

  • Custom data transformation: Automate programmatic transformations of arbitrary JSON data structures using natural language instructions.

Before you begin

Before you configure the Vertex AI integration in Google SecOps, complete the following prerequisite steps:

  1. Create a service account.

  2. Grant the necessary Identity and Access Management roles to your service account.

  3. Choose and configure one of the following authentication methods:

    • Option 1: Workload Identity (recommended): This method uses short-lived tokens using service account impersonation.

    • Option 2: Service account JSON key: This method relies on a static, long-lived secret key file.

For detailed information regarding service charges, review Vertex AI pricing.

Create a service account

  1. In the Google Cloud console, go to IAM & Admin > Service Accounts.

    Go to Service Accounts

  2. Click addCreate service account.

  3. Provide a name and description, and click Done. Note the service account's Email address.

Grant IAM roles

To allow the integration to interact with platform services, you must grant permissions to your principal.

  1. In the Google Cloud console, go to IAM.

    Go to IAM

  2. Find your service account and click Edit principal (edit).

  3. Click Add another role and select Vertex AI User (roles/aiplatform.user).

  4. Click Save.

Configure Workload Identity credentials

Workload Identity is the recommended approach because it uses short-lived access tokens using service account impersonation.

Identify the unique instance identity

Establishing a connection requires granting your Google SecOps instance permission to impersonate your service account.

  1. In Google SecOps, go to Content Hub > Response Integrations.

  2. Select the Vertex AI integration and enter your service account email in Workload Identity Email.

  3. Click Save > Test. The test is expected to fail.

  4. Click close_small next to the Test button and locate the identity email beginning with gke-init-python@... or soar-python@....

  5. Copy this unique email address.

Authorize the instance identity in Google Cloud

  1. In the Google Cloud console, go to IAM & Admin > Service Accounts.

    Go to Service Accounts

  2. Select the target service account and go to Permissions > Grant Access.

  3. Paste the unique email address into New principals and assign the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator).

Configure a JSON key

Static, long-lived secret key files require manual rotation. Only use this method if Workload Identity authentication is unavailable.

  1. In the Google Cloud console, go to IAM & Admin > Service Accounts and select your service account.

    Go to Service Accounts

  2. Go to the Keys tab and click Add key > Create new key.

  3. Select JSON and click Create. The browser downloads the JSON file to your computer.

Integration parameters

The Vertex AI integration requires the following parameters:

Parameter Description
API Root

Required.

The API root of the Vertex AI instance.

The default value is https://LOCATION-aiplatform.googleapis.com.

Workload Identity Email

Optional.

The client email address of your service account.

Only configure this parameter if you're authenticating using a Workload Identity. If configured, Service Account JSON File Content is ignored.

Service Account JSON File Content

Optional.

The full content of the service account key JSON file.

Configure this parameter for service account key authentication.

Project ID

Optional.

The project ID to target in Pub/Sub.

If no value is provided, the integration retrieves the ID from the service account credentials.

Default Model

Optional.

The name of the default model to target.

The default value is gemini-1.5-flash-002.

Location

Optional.

The location ID for the Vertex AI API.

If no value is provided, the integration extracts the location ID from the API root.

Verify SSL

Required.

Validates the SSL certificate for the connection to the server. Enabled by default.

For instructions about how to configure an integration in Google SecOps, see Configure integrations.

You can make changes at a later stage, if needed. After you configure an integration instance, you can use it in playbooks. For more information about how to configure and support multiple instances, see Supporting multiple instances.

Actions

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

Analyze EML

Use the Analyze EML action to analyze EML files using Vertex AI. This action submits every file individually.

This action doesn't run on Google SecOps entities.

Action inputs

The Analyze EML action requires the following parameters:

Parameter Description
Model ID Optional

The ID of the model to use, such as gemini-1.5-flash-002.

Temperature Optional

The value to control the degree of randomness in a token selection. This parameter accepts float data type values.

For more information about temperature values, see Experiment with the parameter values.

Files To Analyze Required

A comma-separated list of EML files to submit for analysis.

Max Output Tokens Optional

The maximum number of output tokens to generate in every response.

A token is approximately four characters. 100 tokens correspond to roughly 60-80 words. This limit applies to every individual entity.

For more information, see Experiment with parameter values.

The default value is 100.

Action outputs

The Analyze EML 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 output received when using the Analyze EML action:

[{
   "Entity": "file",
   "EntityResult": {
       "raw": "{\"threat_level\": \"High\", \"threats_found\": [{\"threat\": \"Phishing Links\", \"explanation\": \"Multiple links point",
       "extracted_info": {
           "threat_level": "High",
           "threats_found": [
               {
                   "threat": "Phishing Links",
                   "explanation": "Multiple links point to example.com, a suspicious domain likely used for phishing campaigns.",
                   "example": "URL"
               },
               {
                   "threat": "Social Engineering",
                   "explanation": "The email uses urgency and scarcity tactics, pressuring the recipient to click links quickly.",
                   "example": "Register Now and Save $1,000 on all 2-Day Project Management (Fundamentals)"
               },
               {
                   "threat": "Suspicious Domain",
                   "explanation": "The email uses the domain example.com', which is not commonly associated with legitimate businesses or organizations and may be a newly registered domain for malicious purposes. This should be checked for validity and legitimacy. The email also uses the domain pdu-xl.com which may also be suspicious.",
                   "example": "example.com"
               }
           ],
           "verification_steps": [
               "Check the domain reputation of example.com using online tools like VirusTotal or URLVoid.",
               "Analyze email headers to identify the true sender's IP address and location using email analysis tools.",
               "Verify the legitimacy of mentioned products or services by independently contacting the companies mentioned."
           ],
           "protection_measures": [
               "Avoid clicking links in suspicious emails. Hover over links to check the actual URL in a separate tool.",
               "Enable email filtering and anti-phishing features in your email client.",
               "Regularly update your antivirus and anti-malware software.",
               "Educate users about social engineering tactics and phishing schemes."
           ]
       },
       "usageMetadata": {
           "promptTokenCount": 12,
           "candidatesTokenCount": 778,
           "totalTokenCount": 790
       }
   }
}]
Output messages

The Analyze EML action can return the following output messages:

Output message Message description
Successfully analysed the following EML files using Vertex AI: FILE_PATHS The action succeeded.
Error executing action "Analyze EML". 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 Analyze EML action:

Script result name Value
is_success True or False

Describe Entity

Use the Describe Entity action to summarize information about entities using Vertex AI.

This action runs on all Google SecOps entities and submits every entity individually.

Action inputs

The Describe Entity action requires the following parameters:

Parameter Description
Model ID Optional

The ID of the model to use, such as gemini-1.5-flash-002.

Temperature Optional

The value to control the degree of randomness in a token selection. This parameter accepts float data type values.

For more information about temperature values, see Experiment with the parameter values.

Exclude Fields Optional

A comma-separated list of the Google SecOps entity metadata fields to exclude during the entity summary generation.

Force Refresh Optional

If selected, the action ignores the Refresh After (Days) parameter and hash validation and regenerates the entity summary for every action run.

Not selected by default.

Refresh After (Days) Required

The number of days for the action to wait before refreshing the entity summary.

The action generates a hash value that is based on all inputs that are sent Vertex AI excluding values from the Fields To Ignore parameter. If the hash value has changed, the action refreshes the summary after the set number of days. If the hash value didn't change, the action doesn't refresh the summary even if the Refresh After (Days) parameter value is earlier than the latest summary generation time.

The action validates the hash value of the latest actual generated summary and ignores the cached hash value.

The default value is 30.

Max Output Tokens Optional

The maximum number of output tokens to generate in every response.

A token is approximately four characters. 100 tokens correspond to roughly 60-80 words. This limit applies to every individual entity.

For more information, see Experiment with parameter values.

Action outputs

The Describe Entity 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 output received when using the Describe Entity action:

[
    {
        "Entity": "1B16D64CE18772B8F77C74C3D4DC24AA066BB117",
        "EntityResult": {
            "summary": "This is a suspicious, enriched, internal file hash (SHA1: 1B16D64CE18772B8F77C74C3D4DC24AA066BB117) identified as a Microsoft Excel 2007+ file (\"FC090000\") located on a user's desktop.  VirusTotal analysis shows 3 malicious flags out of 65 total engines.  The file contains macros, is potentially obfuscated, and exhibits behaviors like writing to files, running DLLs, and downloading content.  It was last modified on 2024-11-13 and created on 2021-07-07.  The file is linked to a single case (\"potential_apt_doc_files\") which was closed.  The file is flagged as an artifact but not vulnerable or a pivot point.\n",
            "usageMetadata": {
                "promptTokenCount": 12,
                "candidatesTokenCount": 778,
                "totalTokenCount": 790
            }
        }
    }
]
Output messages

The Describe Entity action can return the following output messages:

Output message Message description
Successfully summarized the entity based on the available information using Vertex AI. The action succeeded.
Error executing action "Describe Entity". 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 Describe Entity action:

Script result name Value
is_success True or False

Execute Prompt

Use the Execute Prompt action to execute individual text prompts using Vertex AI.

This action doesn't run on Google SecOps entities.

Action inputs

The Execute Prompt action requires the following parameters:

Parameter Description
Model ID Optional

The ID of the model to use, such as gemini-1.5-flash-002.

Text Prompt Required

The text instructions to include in the prompt.

Temperature Optional

The value to control the degree of randomness in a token selection. This parameter accepts float data type values.

For more information about temperature values, see Experiment with the parameter values.

Candidate Count Optional

The number of response variations to return in every action run.

For every request, the billing applies to an input token once and every output token of all generated candidates.

Response MIME Type Optional

The media (MIME) type of the output response for the generated candidate text.

The response media (MIME) type is available for the following models: gemini-1.5-pro, gemini-1.5-flash.

The possible values are as follows:

  • application/json
  • text/plain
  • text/x.enum
The default value is text/plain.
Response Schema Optional

The schema for the generated candidate text to follow.

To use this parameter, configure the Response MIME Type parameter.

The response schema is available for the following models: gemini-1.5-pro, gemini-1.5-flash.

Max Input Tokens Optional

The maximum number of input tokens to submit.

One token consists of up to four characters. 100 tokens can correspond to 60-80 words.

If you don't set a value, the action executes any prompt. If the number of tokens exceeds the configured maximum number, the action fails.

Max Output Tokens Optional

The maximum number of output tokens to generate in every response.

A token is approximately four characters. 100 tokens correspond to roughly 60-80 words. This limit applies to every individual entity.

For more information, see Experiment with parameter values.

Action outputs

The Execute Prompt 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 output received when using the Execute Prompt action:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Responding to a malicious email requires a layered approach.  Here's a breakdown of remediation steps, prioritizing actions based on urgency:\n\n**Immediate Actions (within minutes):**\n\n1. **Do NOT click any links or open any attachments.** This is paramount.  Malicious links can download malware, and attachments can contain viruses or exploits.\n\n2. **Disconnect from the internet (if possible).** This limits the damage the malware can do if it's already on your system.  Unplug your ethernet cable or turn off Wi-Fi.\n\n3. **Close the email immediately.** Don't even hover over links or attachments; the preview might be enough to trigger some malware.\n\n**Investigative Actions (within hours):**\n\n4. **Check your email account for unauthorized access.**  Look for unfamiliar sent emails, changed settings (like forwarding rules), or new accounts added.\n\n5. **Run a full system scan with your antivirus software.**  Ensure your antivirus definitions are up-to-date before running the scan.  Consider a second opinion scan with a different reputable antivirus program.\n\n6. **Review your computer's processes (Task Manager on Windows, Activity Monitor on macOS).** Look for unfamiliar processes consuming significant resources.  This could indicate malware activity.\n\n7. **Check your network connections.**  See if any unauthorized connections exist.\n\n8. **Change your email password immediately.** Use a strong, unique password.  Consider using a password manager.\n\n9. **If you clicked a link or opened an attachment, consider the potential impact.** Did you enter credentials?  Did you download a file?  The severity of action needed depends on this.\n\n**Remediation Actions (within days):**\n\n10. **Contact your IT department or security professional.**  They can provide expert guidance and assist with more advanced remediation steps.\n\n11. **Consider more advanced malware scanning tools.**  There are specialized tools that can detect malware missed by standard antivirus.\n\n12. **Review your operating system's security settings.**  Ensure firewalls are enabled and that other security features are adequately configured.\n\n13. **Report the malicious email to your email provider.** This helps them remove the email and prevent others from being affected. You can often do this by forwarding the email to an abuse reporting address provided by your provider.  Report it to the appropriate authorities if you suspect the email involves a crime.\n\n14. **Monitor your accounts and financial records for suspicious activity.**  Phishing emails often aim to steal credentials and financial information.\n\n**Preventive Actions (ongoing):**\n\n15. **Implement strong email filtering.** Use spam filters and configure your email provider's security settings to block suspicious emails.\n\n16. **Train yourself and others to identify phishing emails.**  Be wary of emails with unusual addresses, grammatical errors, urgent requests, or suspicious attachments.\n\n17. **Keep your software up to date.** Regularly update your operating system, applications, and antivirus software.\n\n18. **Use strong, unique passwords for all accounts.**  A password manager can assist with this.\n\n19. **Enable two-factor authentication (2FA) wherever possible.** This adds an extra layer of security to your accounts.\n\n\n**If you suspect your personal data or financial information has been compromised:**\n\n* **Contact your bank and credit card companies immediately.**  Report any suspicious transactions and consider placing a fraud alert on your accounts.\n* **Consider credit monitoring services.**  This can help you detect and respond to identity theft.\n\n\nThe severity of the remediation steps depends on the nature of the malicious email and what actions you took in response to it. If you're unsure about any step, err on the side of caution and seek professional help.\n"
          }
        ]
      },
      "finishReason": "STOP",
      "avgLogprobs": -0.4171245741660307
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 778,
    "totalTokenCount": 790
  },
  "modelVersion": "gemini-1.5-flash-002",
"Text_context": ""
"extracted_info": ""
}
Output messages

The Execute Prompt action can return the following output messages:

Output message Message description
Successfully executed a prompt. The action succeeded.
Error executing action "Execute Prompt". 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 Execute Prompt action:

Script result name Value
is_success True or False

Ping

Use the Ping action to test the connectivity to Vertex AI.

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 can return the following output messages:

Output message Message description
Successfully connected to Vertex AI with the provided connection parameters! The action succeeded.

Failed to connect to Vertex AI. The API root that you provided doesn't match the following expected pattern: "https://((\w|-)+)-aiplatform.googleapis.com". Check the spelling.

Failed to connect to Vertex AI! The error is 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 Ping action:

Script result name Value
is_success True or False

Transform Data

Use the Transform Data action to perform data transformations using Vertex AI.

This action doesn't run on Google SecOps entities.

Action inputs

The Transform Data action requires the following parameters:

Parameter Description
Model ID Optional

The ID of the model to use, such as gemini-1.5-flash-002.

Text Prompt Required

The text instructions to include in the prompt.

Temperature Optional

The value to control the degree of randomness in a token selection. This parameter accepts float data type values.

For more information about temperature values, see Experiment with the parameter values.

JSON Object Required

The JSON object to use as an action input.

Max Output Tokens Required

The maximum number of output tokens to generate in every response.

A token is approximately four characters. 100 tokens correspond to roughly 60-80 words. This limit applies to every individual entity.

For more information, see Experiment with parameter values.

The default value is 100.

Action outputs

The Transform Data 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 output received when using the Transform Data action:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Respondo it. If you're unsure about any step, err on the side of caution and seek professional help.\n"
          }
        ]
      },
      "finishReason": "STOP",
      "avgLogprobs": -0.4171245741660307
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 778,
    "totalTokenCount": 790
  },
  "modelVersion": "gemini-1.5-flash-002",
"Text_context": ""
"extracted_info": ""
}
Output messages

The Transform Data action can return the following output messages:

Output message Message description
Successfully transformed provided data. The action succeeded.
Error executing action "Transform Data". 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 Transform Data action:

Script result name Value
is_success True or False

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