Release: Google SecOps Extension v1.0.0

.github/workflows/release-google-secops.yml

@@ -0,0 +1,26 @@
+name: Release Google SecOps Extension
+
+on:
+  push:
+    tags:
+      - 'google-secops-v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Create Extension Artifact
+        run: |
+          cd extensions
+          zip -r ../google-secops.zip google-secops -x "google-secops/TOOL_MAPPING.md"
+          # Verify zip content
+          unzip -l ../google-secops.zip
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2.5.0
+        with:
+          files: google-secops.zip

.gitignore

@@ -138,6 +138,7 @@ env.bak/
 venv.bak/
 .gemini
 extensions/google-secops/skills/setup-antigravity/.env
+extensions/google-secops-staging/.env
 
 # Spyder project settings
 .spyderproject

docs/google_secops_extension.md

@@ -6,9 +6,11 @@ This folder contains the **Google SecOps Extension**, providing specialized skil
 
 The extension `extensions/google-secops` packages setup and key security workflows into [skills](https://agentskills.io/specification). 
 
-The skills are designed to work seamlessly with:
- * [Gemini CLI](https://geminicli.com) and the Google SecOps Remote MCP Server.
- * [Antigravity](https://antigravity.google/docs/skills)
+These skills are **Adaptive**, designed to work seamlessly with:
+ *   [Google SecOps Remote MCP Server](https://google.github.io/mcp-security/docs/remote_server.html) (Preferred)
+ *   **Local Python Tools** (Fallback)
+
+This allows the skills to function in diverse environments, automatically selecting the best available tool for the job.
 
 The (`.agent`) symlink makes them available as [Antigravity Agent Skills](https://antigravity.google/docs/skills) at the workspace level. You could also install/copy/symlink the skills to `~/.gemini/antigravity/skills/` to make them available globally to all workspaces.
 
@@ -20,7 +22,10 @@ The (`.agent`) symlink makes them available as [Antigravity Agent Skills](https:
     npm install -g @google/gemini-cli@preview
     ```
 
-2.  **Enable Skills**: Ensure your `~/.gemini/settings.json` has `experimental.skills` enabled:
+
+2.  **GUI Login Requirement**: You MUST have logged into the Google SecOps GUI at least once before using the API/MCP server.
+
+3.  **Enable Skills**: Ensure your `~/.gemini/settings.json` has `experimental.skills` enabled:
     ```json
     {
       "security": {
@@ -32,7 +37,8 @@ The (`.agent`) symlink makes them available as [Antigravity Agent Skills](https:
         "previewFeatures": true
       },
       "experimental": {
-        "skills": true
+        "skills": true,
+        "extensionConfig": true
       }
     }
     ```
@@ -52,35 +58,65 @@ To install this extension in your Gemini CLI environment:
     gemini extensions install ./extensions/google-secops
     ```
 
+You will be prompted for environment variables for the MCP configuration:
+
+1. `PROJECT_ID` (GCP Project ID on your SecOps tenant's /settings/profile page)
+2. `CUSTOMER_ID` (Your Chronicle Customer UUID)
+3. `REGION` (Your Chronicle Region, e.g., `us`, `europe-west1`)
+4. `SERVER_URL` (e.g. https://chronicle.northamerica-northeast2.rep.googleapis.com/mcp, https://chronicle.us.rep.googleapis.com/mcp, etc.)
+
+> **Note**: These values are persisted in `~/.gemini/extensions/google-secops/.env` and can be referenced by skills. Also, you can change the values in this file if needed.
+
 ## Available Skills
 
-### 1. Setup Assistant (Gemini CLI) (`secops-setup-gemini-cli`)
-*   **Trigger**: "Help me set up the Gemini CLI", "Configure Gemini CLI for SecOps".
-*   **Function**: checks for `uv` and Google Cloud authentication, then guides you to add the correct `secops-hosted-mcp` configuration to your Gemini settings (`~/.gemini/config.json`).
 
-### 2. Setup Assistant (Antigravity) (`secops-setup-antigravity`)
+### 1. Setup Assistant (Antigravity) (`secops-setup-antigravity`)
 *   **Trigger**: "Help me set up Antigravity", "Configure Antigravity for SecOps".
 *   **Function**: checks for Google Cloud authentication and environment variables, then merges the correct `remote-secops-investigate` and `remote-secops-admin` configuration into your Antigravity settings (`~/.gemini/antigravity/mcp_config.json`).
 
-### 3. Alert Triage (`secops-triage`)
+### 2. Alert Triage (`secops-triage`)
 *   **Trigger**: "Triage alert [ID]", "Analyze case [ID]".
 *   **Function**: Orchestrates a Tier 1 triage workflow by following the `triage_alerts.md` runbook. It checks for duplicates, enriches entities, and provides a classification recommendation (FP/TP).
 
-### 4. Investigation (`secops-investigate`)
+### 3. Investigation (`secops-investigate`)
 *   **Trigger**: "Investigate case [ID]", "Deep dive on [Entity]".
 *   **Function**: Guides deep-dive investigations using specialized runbooks (e.g., Lateral Movement, Malware).
 
-### 5. Threat Hunting (`secops-hunt`)
+### 4. Threat Hunting (`secops-hunt`)
 *   **Trigger**: "Hunt for [Threat]", "Search for TTP [ID]".
 *   **Function**: Assists in proactive threat hunting by generating hypotheses and constructing complex UDM queries for Chronicle.
 
+### 5. Cases (`secops-cases`)
+*   **Trigger**: "List cases", "Show recent cases", "/secops:cases".
+*   **Function**: Lists recent SOAR cases to verify connectivity and view case status.
+
+## Custom Commands
+
+You can use the following slash commands as shortcuts for common tasks:
+
+*   `/secops:triage <ALERT_ID>`: Quickly start triaging an alert.
+*   `/secops:investigate <CASE_ID>`: Start an investigation.
+*   `/secops:hunt <THREAT>`: Start a threat hunt.
+*   `/secops:cases`: List recent cases.
+
 ## How it Works
 
 These skills act as **Driver Agents** that:
 1.  **Read** the standardized Runbooks in `rules_bank/run_books/`.
-2.  **Execute** the steps using the available MCP tools (`secops`, `gti`, `secops-soar`).
+2.  **Execute** the steps using the available MCP tools.
 3.  **Standardize** the output according to SOC best practices.
 
+### Tool Selection
+
+The skills employ an **Adaptive Execution** strategy to ensure robustness:
+
+1.  **Check Environment**: The skill first identifies which tools are available in the current workspace.
+2.  **Prioritize Remote**: If the **Remote MCP Server** is connected, the skill uses remote tools (e.g., `list_cases`, `udm_search`) for maximum capability.
+3.  **Fallback to Local**: If remote tools are unavailable, the skill attempts to use **Local Python Tools**.
+    > **Note**: Local tools are not included in this extension release. To use them, you must clone the [Google SecOps MCP Repository](https://github.com/google/mcp-security) and configure the local server separately.
+
+For a detailed mapping of Remote vs. Local capabilities, see [`TOOL_MAPPING.md`](../extensions/google-secops/TOOL_MAPPING.md).
+
 
 ## Cross-Compatibility
 
@@ -90,14 +126,11 @@ These skills are designed to be compatible with **Claude Code** and other AI age
 *   `personas`: detailed which security personas (e.g., `threat_hunter`) are best suited for the task.
 
 
+## Known Issues
+* If the `SERVER_URL` requires regionalization (i.e. LEP vs REP vs MREP), it can be very difficult for the user to know what value to use.
+
 ## References
 * [Agent Skills Specification](https://agentskills.io/specification)
 * [Gemini CLI Documentation](https://geminicli.com)
 * [Gemini CLI Preview Features](https://geminicli.com/docs/settings/general#previewfeatures)
 * [Antigravity Skills](https://antigravity.google/docs/skills)
-
-
-
-
-
-

extensions/google-secops/.env.example

@@ -0,0 +1,4 @@
+PROJECT_ID=your-project-id-string
+CUSTOMER_ID=12345678-abcd-4321-8765-1234567890ab
+REGION=us
+SERVER_URL=https://chronicle.us.rep.googleapis.com/mcp

extensions/google-secops/.env.secops-lab

@@ -0,0 +1,4 @@
+PROJECT_ID=secops-demo-env
+CUSTOMER_ID=a13f6726-efed-452e-9008-8fe0d3cb0f75
+REGION=us
+SERVER_URL=https://chronicle.us.rep.googleapis.com/mcp

extensions/google-secops/.env.staging

@@ -0,0 +1,4 @@
+PROJECT_ID=secops-ai-staging
+CUSTOMER_ID=eb3b937b-3ab6-47e5-8185-24837b826691
+REGION=us
+SERVER_URL=https://staging-chronicle.sandbox.googleapis.com/mcp

extensions/google-secops/GEMINI.md

@@ -0,0 +1,161 @@
+# Google SecOps Extension
+
+This folder contains the **Google SecOps Extension**, providing specialized skills for security operations.
+
+## Overview
+
+The extension `extensions/google-secops` packages setup and key security workflows into [skills](https://agentskills.io/specification). 
+
+These skills are **Adaptive**, designed to work seamlessly with:
+ *   [Google SecOps Remote MCP Server](https://google.github.io/mcp-security/docs/remote_server.html) (Preferred)
+ *   **Local Python Tools** (Fallback)
+
+This allows the skills to function in diverse environments, automatically selecting the best available tool for the job.
+
+The (`.agent`) symlink makes them available as [Antigravity Agent Skills](https://antigravity.google/docs/skills) at the workspace level. You could also install/copy/symlink the skills to `~/.gemini/antigravity/skills/` to make them available globally to all workspaces.
+
+
+## Prerequisites
+
+1.  **Install Gemini CLI (Preview)**:
+    ```bash
+    npm install -g @google/gemini-cli@preview
+    ```
+
+
+2.  **GUI Login Requirement**: You MUST have logged into the Google SecOps GUI at least once before using the API/MCP server.
+
+3.  **Enable Skills**: Ensure your `~/.gemini/settings.json` has `experimental.skills` enabled:
+    ```json
+    {
+      "security": {
+        "auth": {
+          "selectedType": "gemini-api-key"
+        }
+      },
+      "general": {
+        "previewFeatures": true
+      },
+      "experimental": {
+        "skills": true,
+        "extensionConfig": true
+      }
+    }
+    ```
+
+Verify skills are enabled from the Gemini CLI prompt:
+```
+/skills list
+```
+
+## Installation
+
+To install this extension in your Gemini CLI environment:
+
+1.  **Navigate** to the project root.
+2.  **Run**:
+    ```bash
+    gemini extensions install ./extensions/google-secops
+    ```
+
+You will be prompted for environment variables for the MCP configuration:
+
+1. `PROJECT_ID` (GCP Project ID on your SecOps tenant's /settings/profile page)
+2. `CUSTOMER_ID` (Your Chronicle Customer UUID)
+3. `REGION` (Your Chronicle Region, e.g., `us`, `europe-west1`)
+4. `SERVER_URL` (e.g. https://chronicle.northamerica-northeast2.rep.googleapis.com/mcp, https://chronicle.us.rep.googleapis.com/mcp, etc.)
+
+> **Note**: These values are persisted in `~/.gemini/extensions/google-secops/.env` and can be referenced by skills. Also, you can change the values in this file if needed.
+
+When using the secops-hosted-mcp MCP Server, use these parameters from the `.env` file (located at `~/.gemini/extensions/google-secops/.env`) for EVERY request:
+Customer ID: ${CUSTOMER_ID}
+Region: ${REGION}
+Project ID: ${PROJECT_ID}
+
+## Available Skills
+
+
+### 1. Setup Assistant (Antigravity) (`secops-setup-antigravity`)
+*   **Trigger**: "Help me set up Antigravity", "Configure Antigravity for SecOps".
+*   **Function**: checks for Google Cloud authentication and environment variables, then merges the correct `remote-secops-investigate` and `remote-secops-admin` configuration into your Antigravity settings (`~/.gemini/antigravity/mcp_config.json`).
+
+### 2. Alert Triage (`secops-triage`)
+*   **Trigger**: "Triage alert [ID]", "Analyze case [ID]".
+*   **Function**: Orchestrates a Tier 1 triage workflow by following the `triage_alerts.md` runbook. It checks for duplicates, enriches entities, and provides a classification recommendation (FP/TP).
+
+### 3. Investigation (`secops-investigate`)
+*   **Trigger**: "Investigate case [ID]", "Deep dive on [Entity]".
+*   **Function**: Guides deep-dive investigations using specialized runbooks (e.g., Lateral Movement, Malware).
+
+### 4. Threat Hunting (`secops-hunt`)
+*   **Trigger**: "Hunt for [Threat]", "Search for TTP [ID]".
+*   **Function**: Assists in proactive threat hunting by generating hypotheses and constructing complex UDM queries for Chronicle.
+
+### 5. Cases (`secops-cases`)
+*   **Trigger**: "List cases", "Show recent cases", "/secops:cases".
+*   **Function**: Lists recent SOAR cases to verify connectivity and view case status.
+
+## Custom Commands
+
+You can use the following slash commands as shortcuts for common tasks:
+
+*   `/secops:triage <ALERT_ID>`: Quickly start triaging an alert.
+*   `/secops:investigate <CASE_ID>`: Start an investigation.
+*   `/secops:hunt <THREAT>`: Start a threat hunt.
+*   `/secops:cases`: List recent cases.
+
+## How it Works
+
+These skills act as **Driver Agents** that:
+1.  **Read** the standardized Runbooks in `rules_bank/run_books/`.
+2.  **Execute** the steps using the available MCP tools.
+3.  **Standardize** the output according to SOC best practices.
+
+### Tool Selection
+
+The skills employ an **Adaptive Execution** strategy to ensure robustness:
+
+1.  **Check Environment**: The skill first identifies which tools are available in the current workspace.
+2.  **Prioritize Remote**: If the **Remote MCP Server** is connected, the skill uses remote tools (e.g., `list_cases`, `udm_search`) for maximum capability.
+3.  **Fallback to Local**: If remote tools are unavailable, the skill attempts to use **Local Python Tools**.
+    > **Note**: Local tools are not included in this extension release. To use them, you must clone the [Google SecOps MCP Repository](https://github.com/google/mcp-security) and configure the local server separately.
+
+For a detailed mapping of Remote vs. Local capabilities, see [`TOOL_MAPPING.md`](https://github.com/google/mcp-security/blob/main/extensions/google-secops/TOOL_MAPPING.md).
+
+
+## Cross-Compatibility
+
+These skills are designed to be compatible with **Claude Code** and other AI agents. The `slash_command` and `personas` metadata in the YAML frontmatter allow other tools to index and trigger these skills effectively.
+
+*   `slash_command`: Defines the equivalent command pattern (e.g., `/security:triage`).
+*   `personas`: detailed which security personas (e.g., `threat_hunter`) are best suited for the task.
+
+
+## Known Issues
+* If the `SERVER_URL` requires regionalization (i.e. LEP vs REP vs MREP), it can be very difficult for the user to know what value to use.
+
+Documentation says:
+> Server URL or Endpoint: Select the regional endpoint and add /mcp at the end. For example, https://chronicle.us.rep.googleapis.com/mcp
+
+Known-good values for Regional Endpoints (REP):
+* https://chronicle.us-east1.rep.googleapis.com/mcp
+* https://chronicle.africa-south1.rep.googleapis.com/mcp
+* https://chronicle.asia-northeast1.rep.googleapis.com/mcp
+* https://chronicle.me-central1.rep.googleapis.com/mcp
+* https://chronicle.europe-west1.rep.googleapis.com/mcp
+* https://chronicle.northamerica-northeast2.rep.googleapis.com/mcp
+* https://chronicle.southamerica-east1.rep.googleapis.com/mcp
+* https://chronicle.europe-west2.rep.googleapis.com/mcp
+* ...
+
+Known-good values for Multi-Regional Endpoints (MREP):
+* https://chronicle.us.rep.googleapis.com/mcp
+
+
+## References
+* [Agent Skills Specification](https://agentskills.io/specification)
+* [Gemini CLI Documentation](https://geminicli.com)
+* [Gemini CLI Preview Features](https://geminicli.com/docs/settings/general#previewfeatures)
+* [Antigravity Skills](https://antigravity.google/docs/skills)
+* [Use the Google SecOps MCP server](https://docs.cloud.google.com/chronicle/docs/secops/use-google-secops-mcp)
+* [Chronicle API - Regional service endpoint](https://docs.cloud.google.com/chronicle/docs/reference/rest?rep_location=us)

extensions/google-secops/commands/secops/cases.toml

@@ -0,0 +1 @@
+prompt = """Run the secops-cases skill."""

extensions/google-secops/commands/secops/hunt.toml

@@ -0,0 +1 @@
+prompt = """Run the secops-hunt skill for `{{args}}`."""

extensions/google-secops/commands/secops/investigate.toml

@@ -0,0 +1 @@
+prompt = """Run the secops-investigate skill on case `{{args}}`."""

extensions/google-secops/commands/secops/triage.toml

@@ -0,0 +1 @@
+prompt = """Run the secops-triage skill on alert `{{args}}`."""

extensions/google-secops/endpoint_constants.py

@@ -0,0 +1,14 @@
+
+VALID_REPS = [
+  "https://chronicle.us-east1.rep.googleapis.com/mcp",
+  "https://chronicle.africa-south1.rep.googleapis.com/mcp",
+  "https://chronicle.asia-northeast1.rep.googleapis.com/mcp",
+  "https://chronicle.me-central1.rep.googleapis.com/mcp",
+  "https://chronicle.europe-west1.rep.googleapis.com/mcp",
+  "https://chronicle.northamerica-northeast2.rep.googleapis.com/mcp",
+  "https://chronicle.southamerica-east1.rep.googleapis.com/mcp",
+  "https://chronicle.europe-west2.rep.googleapis.com/mcp",
+]
+VALID_MREPS = [
+  "https://chronicle.us.rep.googleapis.com/mcp",
+]