Use event simulation for detection coverage evaluation

Use event simulation for detection coverage evaluation

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 full-funnel 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 entire detection lifecycle from initial log parsing 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 full 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 Agentic Detection Engineering toolkit support the following core workflows:

  • Full-Funnel Ingestion and Parsing Validation: Programmatically verify that raw log data and synthetic UDM telemetry successfully navigate live ingestion pipelines, custom parsers, and context enrichment modules 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.
  • Rule Tuning and Precision Improvement: Identify false-positive vectors, evaluate rule logic over synthetic and historical data, and optimize rule precision.

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.
  • Full-Funnel 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.
  • Scalable Asynchronous Evaluation: Evaluate extensive threat behaviors across large YARA-L 2.0 rule sets (including single-event, multi-event, and composite rules) using asynchronous Long-Running Operations (LROs) driven by CreateOnDemandRuleExecutions.

Understand event simulation concepts and architecture

Understand event simulation concepts and architecture: the following core components of event simulation and the Agentic Detection Engineering 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 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.
  • On-demand rule execution: The execution engine (CreateOnDemandRuleExecutions) that evaluates active and archived YARA-L 2.0 rules against synthetic UDM events within a specified historical or real-time window.
  • Simulation labeling and alert tagging: Synthetic events carry an ingestion label (metadata.ingestion_labels["SIMULATION"]). When rules execute over simulated data, the resulting detections are tagged with INCLUDES_SIMULATION_DATA, and rule outcomes track $simulated_event_count, $non_simulated_event_count, and $all_simulations.
  • 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 = "SIMULATED_DATA_INCLUDED" parameter or UI 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 Agentic Detection Engineering toolkit. Before you begin, confirm the following prerequisites are met:

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 "SIMULATION" and a unique simulation or test run identifier in their request payload (for example, "key": "SIMULATION", "value": "TEST123"). The API does not autopopulate simulation labels.

Example UDM ingestion payload

{
  "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 streams synthesized UDM events into live ingestion and context enrichment pipelines (testing UDM normalization, context enrichment, and rule execution), while raw log parsing is validated during synthetic event generation within the Detection Engineering Agent (DEA).

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, click your user avatar, select User Preferences > Synthetic Data Visibility, and then select the Show synthetic test data checkbox, or set simulated_data_visibility = "SIMULATED_DATA_INCLUDED" in your query request.

Chronicle API

For programmatic API queries, customers supply simulated_data_visibility = "SIMULATED_DATA_INCLUDED" (or specific parameter enum values depending on the API endpoint being invoked) 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.
  • SIMULATED_DATA_ONLY: Restricts results exclusively to synthetic test data.

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 Search, rule evaluation, and detection query tools.

Understand downstream system isolation

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

System / Feature Synthetic Data Treatment Isolation Mechanism
Detections and Alert Store Isolated and Tagged Detections resulting from simulated telemetry are tagged with INCLUDES_SIMULATION_DATA and outcome counts ($simulated_event_count). Suppressed from standard detection read/list APIs unless explicitly requested (include_simulated_detections = true).
UDM Search and Dashboards Hidden by default Filtered unless simulated_data_visibility = "SIMULATED_DATA_INCLUDED" is requested
Alert Triage Dashboards Excluded Detections with simulation tags are excluded from production alert triage dashboards
Cases and Incident Triage Excluded Detections with simulation tags are bypassed from case creation
Playbooks and Automation Excluded Automated SOAR playbooks do not 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 Agentic suite and tool capabilities.

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.

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?

Atomic indicators should be managed using Google SecOps IOC Matching or Reference Lists 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 3 TDOs or 40 synthetic events per evaluate_rule_coverage_long_running call.

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