Use the Detection Engineering Agent

This guide is for security engineers and SOC analysts who want to evaluate and strengthen their Google Security Operations security posture against new and existing threats, using the AI-powered Detection Engineering Agent in Google SecOps.

You can access the agent using Model Context Protocol (MCP) tools operated by compatible AI clients (for example, Google Antigravity or Claude Code). Using the Detection Engineering Agent, you can extract threat intelligence and automatically draft YARA-L rules, which improves time-to-value for custom security automation and accelerates risk mitigation.

Key terminology

  • Detection Engineering Agent: An AI-powered engineering assistant embedded in Google SecOps, operated by AI clients (for example, Antigravity or Claude Code) using MCP tools.
  • Model Context Protocol (MCP): An open-source standard for connecting AI applications to external systems, which is used across Google Cloud services to securely connect AI agents and applications to various data sources and infrastructure tools.
  • Threat Detection Opportunity (TDO): A formalized data model designed to identify, track, and prioritize potential new detection rules or analytics.
  • Synthetic events: Unified Data Model (UDM) logs generated to simulate an input TDO.

Before you begin

Before you begin, confirm the following prerequisites are met:

Environment check — AI client

You must operate an AI client (such as Antigravity or Claude Code) capable of interfacing with MCP tools.

Required roles and permissions

This section lists the required Identity and Access Management (IAM) permissions and recommended predefined roles for both human users and service accounts.

Required roles for all principal users

Every principal calling the Detection Engineering Agent must have the following roles: MCP Tool User and Chronicle API Viewer. Ensure that a system administrator updates these roles for all principal users.

For more information, see Configure MCP.

Required core permissions

The following permissions are required to run the Detection Engineering Agent:

  • chronicle.ade.generateThreatDetectionOpportunity
  • chronicle.ade.generateSyntheticEvents
  • chronicle.ade.evaluateRuleCoverage
  • chronicle.ade.generateRules
  • chronicle.operations.get

Required rule management and parser permissions

The following permissions are required to manage rules and parsers:

  • chronicle.rules.list
  • chronicle.rules.get
  • chronicle.rules.verify
  • chronicle.rules.create
  • chronicle.rules.update
  • chronicle.ruleDeployments.get
  • chronicle.ruleDeployments.update
  • chronicle.parsers.list
  • chronicle.parsers.get
  • chronicle.logTypes.list

Required remote MCP server and project service usage permissions

The following permissions are required to call the remote MCP server and use project services for MCP tools:

  • mcp.tools.call (granted by the roles/mcp.toolUser role)
  • serviceusage.services.use (granted by the roles/serviceusage.serviceUsageConsumer role)

The following predefined roles provide the necessary permissions for both human users and service accounts:

  • roles/chronicle.admin (or roles/chronicle.editor)
  • roles/mcp.toolUser
  • roles/serviceusage.serviceUsageConsumer

Set up the MCP server

To create your settings.json file, see Configure MCP. After you collect the required values, make sure that the contents of your settings.json file look like the following:

{
  "name": "my_extension_name",
  "version": "1.0.0",
  "mcpServers": {
    "GoogleSecOps": {
      "httpUrl": "https://us-chronicle.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": [
          "https://www.googleapis.com/auth/cloud-platform",
          "https://www.googleapis.com/auth/chronicle"
        ]
      },
      "timeout": 300000,
      "headers": {
        "x-goog-user-project": "my-cloud-project-name"
      }
    }
  }
}

Set up a context file

To get started, set up a context file to ensure that Gemini targets the correct Google SecOps instance for every request.

To keep everything lightweight, Google recommends starting with the following content in your GEMINI.md file and then building from there. Replace the placeholder values with the correct information for your Google SecOps instance and environment:

When using the Google SecOps MCP server, use these parameters for EVERY request: Customer ID: aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa Region: us Project ID: my-cloud-project-name

Set up the skill to interact with the tools

Google highly recommends using the detection-engineering-coverage-evaluation skill to interact with the tools. This skill prevents the AI from summarizing or abbreviating critical tool outputs.

This skill is built-in as detection-engineering-coverage-evaluation and is hosted publicly in the Google Agent Skills GitHub repository.

Key capabilities

This section describes key capabilities for threat analysis and rule generation that the Detection Engineering Agent provides.

Generate Threat Detection Opportunities

The generate_threat_detection_opportunity tool extracts and enriches raw threat intelligence from sources (for example, security blogs and internal findings) to create prioritized TDOs for analysis. The TDOs produced in this step inform the subsequent detection engineering agent steps to evaluate existing rule coverage or generate new rules.

  • To use the generate_threat_detection_opportunity tool, instruct Gemini to use curl to extract the text, or copy and paste raw text from a threat report into the tool.

Generate synthetic events

To generate synthetic events for a TDO, your Google SecOps instance must have ingested raw logs and an active parser for at least one of the supported log types in that TDO.

Supported log types

Synthetic event generation supports the following eight log types:

Category Vendor or product Log type
Endpoint detection and response (EDR) CrowdStrike Falcon CS_EDR
Endpoint detection and response (EDR) Microsoft Defender for Endpoint MICROSOFT_DEFENDER_ENDPOINT
Endpoint detection and response (EDR) SentinelOne EDR SENTINEL_EDR
Antivirus and endpoint Windows Defender ATP WINDOWS_DEFENDER_ATP
DNS Zscaler DNS ZSCALER_DNS
Google Cloud Google Workspace Activities WORKSPACE_ACTIVITY
Identity and access management Okta OKTA
SaaS applications Microsoft 365 (Office 365) OFFICE_365

Evaluate coverage

The Detection Engineering Agent checks whether existing rules in your Google SecOps instance trigger on simulated events ingested through event simulation. If any rules match the simulated events, the tool returns the matching rule identifiers and coverage result metadata. If no rules match, an empty result is returned, signaling a coverage gap.

Generate draft rules

The Detection Engineering Agent codifies detection logic by creating draft YARA-L rules from user input or natural language to address gaps identified during coverage evaluation. When you use the detection-engineering-coverage-evaluation skill, the agent generates draft rules only for TDOs that no existing rule matches, and only after coverage evaluation finishes for all TDOs. This prevents duplicate rules for threats that existing rules already cover.

The generate_rules tool doesn't automatically add the draft rules to your Google SecOps instance. After you review the draft rules, you can add them in either of the following ways:

  • Use your AI client: The detection-engineering-coverage-evaluation skill prompts you to approve or reject each draft rule. For each rule that you approve, the AI client calls the create_rule tool on the Google SecOps MCP server to create the rule in your instance.
  • Create the rule manually: Copy the rule text from the tool output and create the rule in the Rules Editor.

Troubleshooting

Use the following table to self-remediate common issues during the evaluation process:

Issue Description Fix
Tool failure The generate_synthetic_events tool repeatedly fails. Verify that the TDO includes at least one of the supported log types and that your Google SecOps instance has ingested raw logs and an active parser for that log type. Otherwise, skip synthetic event generation for that TDO and continue with the remaining TDOs.
Summarization error The AI abbreviates log types or takes shortcuts during execution. Ensure the detection-engineering-coverage-evaluation skill is actively being used to interface with the system.

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