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:
Grant the necessary Identity and Access Management roles to your service account.
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
In the Google Cloud console, go to IAM & Admin > Service Accounts.
Click addCreate service account.
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.
In the Google Cloud console, go to IAM.
Find your service account and click Edit principal (edit).
Click Add another role and select Vertex AI User (
roles/aiplatform.user).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.
In Google SecOps, go to Content Hub > Response Integrations.
Select the Vertex AI integration and enter your service account email in Workload Identity Email.
Click Save > Test. The test is expected to fail.
Click close_small next to the Test button and locate the identity email beginning with
gke-init-python@...orsoar-python@....Copy this unique email address.
Authorize the instance identity in Google Cloud
In the Google Cloud console, go to IAM & Admin > Service Accounts.
Select the target service account and go to Permissions > Grant Access.
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.
In the Google Cloud console, go to IAM & Admin > Service Accounts and select your service account.
Go to the Keys tab and click Add key > Create new key.
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
|
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 |
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 |
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
|
Temperature |
Optional The value to control the degree of randomness in a
token selection. This parameter accepts 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 |
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
|
Temperature |
Optional The value to control the degree of randomness in a
token selection. This parameter accepts 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 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 The action validates the hash value of the latest actual generated summary and ignores the cached hash value. The default value is |
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
|
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 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: The possible values are as follows:
text/plain. |
Response Schema |
Optional The schema for the generated candidate text to follow. To use this parameter, configure the The response schema is available for the
following models: |
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. |
|
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
|
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 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 |
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.