Use event simulation for detection coverage evaluation

Note: This feature is covered by Pre-GA Offerings Terms of the Google Security Operations Service Specific Terms. Pre-GA features might have limited support, and changes to pre-GA features might not be compatible with other pre-GA versions. For more information, see the Google SecOps Technical Support Service guidelines and the Google SecOps Service Specific Terms.
If this feature isn't visible in your environment, see Manage preview features or contact your system administrator.

This guide is for detection engineering and SOC teams who want to programmatically deliver realistic threat sequences into the live ingestion pipeline using event simulation. Event simulation is a threat simulation and detection coverage evaluation framework embedded directly within Google Security Operations. As a foundational capability of the Detection Engineering Agent (DEA) architecture, event simulation verifies the detection lifecycle from telemetry ingestion and normalization to multi-event correlation and alerting while preserving operational SOC workflows.

By connecting Google SecOps MCP tools with AI assistance (such as Gemini or Claude Code), event simulation automates the detection engineering lifecycle: ingesting raw threat reports, structuring threat tactics into actionable Threat Detection Opportunities (TDOs), synthesizing realistic Unified Data Model (UDM) telemetry, evaluating existing YARA-L 2.0 rule coverage across single-event, multi-event, and composite rules, and drafting new detection rules to close identified security gaps.

Primary use cases

Event simulation and the Detection Engineering Agent (DEA) support the following core workflows:

• Live pipeline ingestion and normalization testing: Programmatically stream synthetic Unified Data Model (UDM) telemetry directly through live ingestion pipelines, context enrichment modules, and entity graphs to achieve complete end-to-end detection readiness.
• Continuous threat coverage and regression validation: Evaluate managed and custom YARA-L 2.0 rules against specific adversary tactics, techniques, and procedures (TTPs), establishing automated unit testing and continuous regression testing across rule sets prior to production deployment.
• Synthetic telemetry generation: Produce schema-valid UDM events simulating complex attack chains (such as web application exploitation, credential access, or lateral movement) to test rules in real production environments.

Key benefits and value proposition

• Proactive posture and threat validation: Test YARA-L 2.0 rules against newly disclosed vulnerabilities and threat actor behaviors before real-world incidents occur.
• Direct synthesis and ingestion assurance: Synthesize schema-valid UDM events directly from threat intelligence text that flow through the live Google SecOps ingestion pipeline (ImportEvents) to undergo complete normalization, field alignment, and context enrichment.
• Isolated telemetry and production safety: Synthetic events generated by event simulation are tagged with simulation metadata (SIMULATION ingestion labels) and result in detections tagged as INCLUDES_SIMULATION_DATA. Detections from simulated data are automatically excluded from production cases, playbooks, risk analytics (RBA) streams, and alert triage dashboards.

Understand event simulation concepts and architecture

The following core components of event simulation and the Detection Engineering Agent (DEA) framework are essential for deployment:

• Threat Detection Opportunity (TDO): A formalized data model acting as a unit test that identifies, prioritizes, and categorizes specific adversary TTPs extracted from threat intelligence reports or natural language descriptions. TDO identifiers follow strict formatting requirements (for example, t01, t02, matching the regular expression ^[a-zA-Z]\d{2}$).
• Synthetic UDM events: Machine-generated log events formatted strictly under the Google SecOps Unified Data Model (UDM) schema. These events simulate specific attacker actions required to test detection rule logic using ImportEvents.
• Simulation labeling and alert tagging: Synthetic events carry an ingestion label (metadata.ingestion_labels["SIMULATION"]). In the Collection proto, detections resulting from simulated data are marked under tags with INCLUDES_SIMULATION_DATA. Detection metadata proto fields include simulated_event_count (total number of simulated events contributing to the detection) and simulated_event_names (the set of SIMULATION label values from contributing events).
• Data visibility and search suppression: Standard Google SecOps UDM searches suppress simulation-labeled events by default. Search queries and UI views can explicitly include simulated data using the simulated_data_visibility configuration parameter or user preferences toggle.
• Long-Running Operations (LROs): An asynchronous backend execution mechanism (evaluate_rule_coverage_long_running) that orchestrates on-demand rule execution batches without encountering API HTTP timeouts.

Before you begin

Event simulation shares the underlying environment prerequisites, IAM permissions, and server setup with the Detection Engineering Agent toolkit. Before you begin, confirm the following prerequisites are met:

• IAM roles: Requires Chronicle API Viewer, Chronicle API Editor, and MCP Tool User roles.
• MCP server and skill setup: For step-by-step guidance on configuring the settings.json MCP server payload, setting up workspace context (Gemini.md), and enabling detection engineering skills, see Use the Detection Engineering Agent to evaluate threat coverage and Use the Google SecOps MCP server.

How synthetic telemetry is injected

Synthetic telemetry is injected into Google SecOps using either the MCP agent toolkit or direct Chronicle API calls:

1. MCP subagent invocation: Call the generate_synthetic_events tool with target Threat Detection Opportunity (TDO) IDs and behavior specifications.
2. Chronicle API endpoint: Programmatically stream synthetic UDM events using the ImportEvents REST API endpoint (POST /v1alpha/projects/{project}/locations/{location}/instances/{instance}/events:import).
3. Simulation labeling: When calling the ImportEvents API directly, callers must manually include metadata.ingestion_labels containing the key "SIMULATION" and a unique simulation or test run identifier as the value in their request payload (for example, "key": "SIMULATION", "value": "TEST123" or "t01"). The API does not autopopulate simulation labels.

Example UDM ingestion call

HTTP request:

POST https://chronicle.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/events:import

Request body:

{
  "events": [
    {
      "metadata": {
        "event_type": "PROCESS_LAUNCH",
        "event_timestamp": "2026-08-05T20:00:00Z",
        "ingestion_labels": [
          {
            "key": "SIMULATION",
            "value": "TEST123"
          }
        ]
      },
      "principal": {
        "user": {
          "userid": "victim_user"
        }
      },
      "target": {
        "process": {
          "command_line": "powershell.exe -ExecutionPolicy Bypass -File dump.ps1"
        }
      }
    }
  ]
}

Event simulation injects synthesized UDM events directly using ImportEvents, evaluating UDM normalization, context enrichment, and rule detection; raw log parsing is tested during synthetic event generation inside the Detection Engineering Agent (DEA) tool.

Note: Synthetic UDM events ingested through event simulation count against both your Google SecOps ingestion quota and detection quota. For information about rate limits, see burst limits.

Configure user preferences for synthetic test data

To view synthetic test events and simulated alerts in Google SecOps across the UI, API, or MCP tools, configure visibility according to your interface:

Google SecOps console

To view synthetic events in the SIEM Search page or UI consoles:

1. In the Google SecOps console, click your profile avatar in the navigation bar, and select User preferences.
2. Navigate to Data Visibility.
3. Set Show synthetic test data to ON.
4. Click Save.

Chronicle API

For programmatic API queries, supply simulated_data_visibility = "SIMULATED_DATA_INCLUDED" when querying UDM Search, rules, or detection endpoints using the Chronicle API:

{
  "query": "metadata.event_type = \"USER_LOGIN\"",
  "simulated_data_visibility": "SIMULATED_DATA_INCLUDED"
}

Supported simulated_data_visibility parameter enum values:

• SIMULATED_DATA_EXCLUDED (Default): Suppresses simulation-labeled events and alerts.
• SIMULATED_DATA_INCLUDED: Returns both production data and synthetic test data in query results.

Google SecOps MCP server

When interacting with Google SecOps using an MCP client (for example, Gemini CLI or AntiGravity), configure tenant-wide simulation visibility in your workspace context file (Gemini.md or settings.json):

When using the GoogleSecOps MCP Server, set simulated_data_visibility = "SIMULATED_DATA_INCLUDED" for all UDM searches, rule evaluation, and detection query tools.

Note: Standard Google SecOps searches suppress simulation-labeled events by default to preserve operational SOC workflows and prevent false-positives in production incident queues.

Understand downstream system isolation

To ensure test data is handled appropriately across Google SecOps, event simulation enforces clean isolation boundaries for downstream components:

System or feature	Synthetic data treatment	Isolation mechanism
Detections and alert store	Isolated and tagged	In the Collection proto, detections resulting from simulated telemetry are marked under tags with INCLUDES_SIMULATION_DATA and include detection metadata proto fields simulated_event_count and simulated_event_names. Suppressed from standard detection read and list APIs unless simulated_data_visibility = "SIMULATED_DATA_INCLUDED" is requested.
UDM search and dashboards	Hidden by default	Filtered unless simulated_data_visibility = "SIMULATED_DATA_INCLUDED" is specified.
Cases and incident triage	Excluded	Detections with simulation tags are bypassed from automated case creation.
Playbooks and SOAR automation	Excluded	Automated SOAR playbooks don't trigger on simulated alerts.
Risk analytics (RBA)	Excluded	Streaming risk score aggregate pipelines drop simulation-labeled events.
Threat Hunting Agent (THA)	Excluded	Threat hunt dataset queries automatically suppress simulation-labeled telemetry.

Agentic suite and tool capabilities

Event simulation leverages the subagent tool capabilities exposed by the Google SecOps MCP server. For detailed information on the available subagent tools (including generate_threat_detection_opportunity, generate_synthetic_events, evaluate_rule_coverage_long_running, get_operation, generate_rules, and create_rule), key inputs, and output schemas, see Use the Detection Engineering Agent to evaluate threat coverage.

Understand the detection engineering lifecycle and workflow

The end-to-end event simulation detection engineering workflow follows a structured multi-stage lifecycle:

1. Intel processing and telemetry ingestion: Pass raw threat intelligence text to generate_threat_detection_opportunity to extract structured TDOs (for example, t01, t02), apply preflight timestamp shifting, and invoke generate_synthetic_events to stream SIMULATION-labeled UDM logs through the live Google SecOps ingestion pipeline (ImportEvents).
2. Asynchronous coverage evaluation: Execute evaluate_rule_coverage_long_running to evaluate YARA-L 2.0 rule coverage across synthetic telemetry, polling get_operation until completion to retrieve the rule match matrix.
3. Gap remediation and rule lifecycle management: Call generate_rules for any uncovered TDOs to produce validated YARA-L 2.0 rule drafts, and deploy reviewed rules to production using create_rule.

For detailed tool invocation payloads and complete code examples across each stage of the detection lifecycle, refer to Use the Detection Engineering Agent to evaluate threat coverage.

Troubleshooting

This section contains some frequently asked troubleshooting questions and answers for them.

Q: Why are synthetic UDM events not appearing in a standard UDM search?

By design, standard Google SecOps UDM searches suppress events carrying the SIMULATION ingestion label to preserve SOC operational hygiene. To view synthetic events in UDM Search or UI consoles, ensure Show synthetic test data is enabled in your User Preferences, or set simulated_data_visibility = "SIMULATED_DATA_INCLUDED" in your query request.

Q: How are detections from simulated data prevented from alerting SOC analysts?

When a rule triggers over synthetic events, the backend compiler tags the resulting detection with INCLUDES_SIMULATION_DATA. Detections with this tag are excluded from production Cases, Playbooks, Risk Analytics (RBA), and alert triage dashboards by default.

Q: Why did evaluate_rule_coverage_long_running return 0 matches for my synthetic events?

Verify that your synthetic event timestamps fall within the rolling 1-hour execution window ([StartTime - 1 hour, StartTime]). Ensure your TDO IDs conform to the required regular expression (^[a-zA-Z]\d{2}$, e.g., t01).

Q: How should atomic indicators (IP addresses, domain names, file hashes) be handled versus behavioral rules?

Manage atomic indicators using Google SecOps IOC Matching or Data Tables rather than hardcoding static IP address or hash values directly into YARA-L 2.0 detection rules. Reserve YARA-L 2.0 for behavioral patterns and TTP correlation.

Q: What is the maximum batch size for TDO coverage evaluation calls?

To optimize performance and comply with API Gateway parameters, batch coverage evaluation requests are limited to a maximum of three TDOs or 40 synthetic events per evaluate_rule_coverage_long_running call.

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