feat(secops): add Detection Engineering Agent MCP tools and coverage evaluation skill

[dandye]

Summary

Implements support for the newly launched Google SecOps Agentic Detection Engineering (ADE) APIs in secops-mcp, introduces the canonical detection-engineering-coverage-evaluation skill for Antigravity and Gemini CLI agents, and adds a comprehensive end-to-end documentation guide and tool reference.

This enables security teams and autonomous agents to automate the end-to-end detection engineering lifecycle: ingesting threat intelligence, generating Threat Detection Opportunities (TDOs), simulating attacker behavior with synthetic UDM events, running isolated rule coverage evaluations via Chronicle Long-Running Operations (LRO), synthesizing candidate YARA-L 2.0 rules for identified coverage gaps, and deploying verified detections with explicit human-in-the-loop authorization.

Reference documentation: Agentic Detection Engineering in Google SecOps

---

Changes

1. Detection Engineering MCP Tools (server/secops/secops_mcp/tools/detection_agent.py & security_rules.py)

Adds 5 new tools to the SecOps FastMCP toolset, plus tool aliases for Remote OneMCP parity:

• generate_threat_detection_opportunity: Generates structured Threat Detection Opportunities (TDOs) from natural-language threat intel descriptions and target log types.
• generate_synthetic_events: Simulates attacker activity by synthesizing realistic raw logs, UDM event records, and JSON-encoded UDM strings for specific TDOs. Automatically synthesizes the threat_detection_opportunity_events wrapper in both single- and multi-TDO flows to ensure seamless chaining into rule coverage evaluation without KeyError exceptions. Supports multi-TDO batching.
• evaluate_rule_coverage_long_running: Initiates a Chronicle LRO (:evaluateRuleCoverageLongRunning) to evaluate synthetic events against active rulesets in a safe sandbox simulation without writing mock data to production storage. Defaults exclude_composite_coverage=True to avoid false coverage signals from multi-event composite/correlation rules.
• get_operation: Polls standard Google Long-Running Operations (LRO) until completion, surfacing progress metadata and final evaluation responses. Automatically normalizes operation name prefixes.
• generate_rules: Synthesizes production-ready candidate YARA-L 2.0 detection rules specifically tailored to close uncovered TDOs and coverage gaps. Supports multi-TDO batching.
• get_rule (security_rules.py): Added as a FastMCP tool alias alongside get_security_rule to ensure 1:1 compatibility with Remote OneMCP servers.
• Robust Parameter Aliasing & Input Flexibility: Added comprehensive alias support across all ADE tools (threat_description/threatDescription, log_types/logTypes with automatic comma-separated string to list coercion, tdo/threat_detection_opportunities/tdo_events/opportunity_events, operation_name/operationName, background_context/backgroundContext). Unwraps nested wrapper dictionaries automatically.

2. Comprehensive Agentic Detection Engineering Documentation (Merged PR #306)

• docs/agentic_detection_engineering.md: New end-to-end guide detailing the ADE architecture, Mermaid lifecycle diagram, SecOps Web UI synthetic test data visibility configuration, step-by-step python script walkthroughs, and troubleshooting tips.
• docs/img/synthetic_data_visibility.png: UI screenshot illustrating the SecOps "Show synthetic data in search and rules" setting.
• docs/servers/secops_mcp.md: Expanded reference table for all 5 ADE tools with parameter descriptions, exclude_composite_coverage=True default explanation, and complete end-to-end Example 9 walkthrough.
• docs/index.md & docs/toc.md: Added global quick links and Table of Contents entries.
• docs/google_secops_extension.md: Documented Skill 6 (detection-engineering-coverage-evaluation).

3. Detection Engineering Coverage Evaluation Skill (extensions/google-secops/skills/detection-coverage/)

Adds the detection-engineering-coverage-evaluation skill (available via .agent/skills/detection-coverage/SKILL.md):

• Lifecycle Runbook: Structured 8-stage detection pipeline (Intel Ingestion $\rightarrow$ TDO Generation $\rightarrow$ Synthetic Simulation $\rightarrow$ Rule Coverage Evaluation $\rightarrow$ Gap Analysis $\rightarrow$ YARA-L 2.0 Rule Generation $\rightarrow$ Verification $\rightarrow$ Deployment).
• Prompt Injection Defense: Enforces strict demarcation when parsing untrusted external threat reports, blog posts, and markdown feeds.
• Safety Gate: Requires explicit user confirmation with full rule preview before creating or enabling rules in production.

4. Persona & Extension Tool Mapping Documentation

• docs/personas/detection_engineer.md: Updated Detection Engineer persona documentation to detail ADE tools, workflows, and sample execution flows.
• extensions/google-secops/TOOL_MAPPING.md: Added the Detection Engineering tool category mapping.
• extensions/google-secops/GEMINI.md: Added Skill 6 (detection-engineering-coverage-evaluation) to the extensions registry.

5. Git Hygiene & Secret Isolation

• Added .envrc and .gcloud/ to .gitignore to prevent credential and local configuration leakage when using direnv and local Application Default Credentials (ADC).

---

Verification & Testing

Unit Tests

• Expanded server/secops/tests/test_secops_detection_agent_unit.py to 19 async unit tests.
• Tests cover endpoint routing, request body structure, parameter aliases, string log-type coercion, single and multi-TDO synthesis/batching, nested response unwrapping, operation prefix normalization, and get_rule alias.
• All 19 detection agent unit tests pass:

  uv run --directory server/secops --with pytest --with pytest-asyncio pytest tests/test_secops_detection_agent_unit.py
  # 19 passed in 0.81s

• Linting verified clean:

  uv run --directory server/secops --with ruff ruff check secops_mcp/tools/detection_agent.py tests/test_secops_detection_agent_unit.py
  # All checks passed!

• Documentation build verified clean:

  uv run --with-requirements docs/requirements.txt make -C docs html
  # build succeeded, copying images... [100%] img/synthetic_data_visibility.png

Live Tenant Verification

Verified end-to-end execution against a live Google SecOps tenant using ADC:

1. generate_threat_detection_opportunity: Successfully extracted TDOs (t01, t02) for PowerShell-based C2 communication.
2. generate_synthetic_events: Successfully generated 8 synthetic UDM events simulating suspicious PowerShell process launches and outbound network connections.
3. evaluate_rule_coverage_long_running: Initiated LRO (operations/dea-bkFXS0...) with synthetic events.
4. get_operation: Polled operation status to retrieve coverage results.
5. generate_rules: Successfully synthesized candidate YARA-L 2.0 rule (ttp_suspicious_powershell_network_connection) closing the identified gap.

TAG=agy
CONV=b434fecb-6fd3-4841-b909-49d23ef70fa3