From 85290c7c6f682a85983c546502a9a5af0bb04d17 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Wed, 14 Jan 2026 22:06:47 -0500 Subject: [PATCH 01/20] Update docs to describe Adaptive Execution --- docs/google_secops_extension.md | 25 +++++++++++++--- .../google-secops/gemini-extension.json | 29 ++++++++++++++++++- 2 files changed, 49 insertions(+), 5 deletions(-) diff --git a/docs/google_secops_extension.md b/docs/google_secops_extension.md index 3516a77d..7b9c6807 100644 --- a/docs/google_secops_extension.md +++ b/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. @@ -52,6 +54,11 @@ To install this extension in your Gemini CLI environment: gemini extensions install ./extensions/google-secops ``` +You will be prompted for two environment variables for the MCP configuration: + +1. `PROJECT_ID` +2. `SERVER_URL` + ## Available Skills ### 1. Setup Assistant (Gemini CLI) (`secops-setup-gemini-cli`) @@ -78,9 +85,19 @@ To install this extension in your Gemini CLI environment: 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 automatically falls back to **Local Python Tools** (e.g., `search_security_events`). + +For a detailed mapping of Remote vs. Local capabilities, see [`TOOL_MAPPING.md`](../TOOL_MAPPING.md). + ## Cross-Compatibility diff --git a/extensions/google-secops/gemini-extension.json b/extensions/google-secops/gemini-extension.json index 5f66cdab..b38d0e1c 100644 --- a/extensions/google-secops/gemini-extension.json +++ b/extensions/google-secops/gemini-extension.json @@ -8,5 +8,32 @@ "skills/triage", "skills/investigate", "skills/hunt" - ] + ], + "settings": [ + { + "name": "PROJECT_ID", + "description": "Your Google Cloud Project ID.", + "envVar": "PROJECT_ID" + }, + { + "name": "SERVER_URL", + "defaultValue": "https://staging-chronicle.sandbox.googleapis.com/mcp", + "description": "The URL of the remote MCP server.", + "envVar": "SERVER_URL" + } + ], + "mcpServers": { + "remote-mcp-secops": { + "httpUrl": "${SERVER_URL}", + "authProviderType": "google_credentials", + "oauth": { + "scopes": [ + "https://www.googleapis.com/auth/cloud-platform" + ] + }, + "headers": { + "x-goog-user-project": "${PROJECT_ID}" + } + } + } } \ No newline at end of file From efe8d4d3e0ada1d16bfc11686ebd7ec749834063 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Wed, 14 Jan 2026 23:06:08 -0500 Subject: [PATCH 02/20] Populate GEMINI.md for extension spec --- extensions/google-secops/GEMINI.md | 114 +++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 extensions/google-secops/GEMINI.md diff --git a/extensions/google-secops/GEMINI.md b/extensions/google-secops/GEMINI.md new file mode 100644 index 00000000..6acc8d1d --- /dev/null +++ b/extensions/google-secops/GEMINI.md @@ -0,0 +1,114 @@ +# 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. **Enable Skills**: Ensure your `~/.gemini/settings.json` has `experimental.skills` enabled: + ```json + { + "security": { + "auth": { + "selectedType": "gemini-api-key" + } + }, + "general": { + "previewFeatures": true + }, + "experimental": { + "skills": 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 two environment variables for the MCP configuration: + +1. `PROJECT_ID` +2. `SERVER_URL` + +## 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`) +* **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`) +* **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`) +* **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`) +* **Trigger**: "Hunt for [Threat]", "Search for TTP [ID]". +* **Function**: Assists in proactive threat hunting by generating hypotheses and constructing complex UDM queries for Chronicle. + +## 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 automatically falls back to **Local Python Tools** (e.g., `search_security_events`). + +For a detailed mapping of Remote vs. Local capabilities, see [`TOOL_MAPPING.md`](../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. + + +## 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) From 412542891e90e3ff2a458c7fb1a298250ce8a8c0 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Thu, 5 Feb 2026 07:46:18 -0500 Subject: [PATCH 03/20] use MREP insted of staging as defaultValue --- extensions/google-secops/gemini-extension.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/google-secops/gemini-extension.json b/extensions/google-secops/gemini-extension.json index b38d0e1c..60924a06 100644 --- a/extensions/google-secops/gemini-extension.json +++ b/extensions/google-secops/gemini-extension.json @@ -17,8 +17,8 @@ }, { "name": "SERVER_URL", - "defaultValue": "https://staging-chronicle.sandbox.googleapis.com/mcp", - "description": "The URL of the remote MCP server.", + "defaultValue": "https://chronicle.us.rep.googleapis.com/mcp", + "description": "The URL of the remote MCP server See https://docs.cloud.google.com/chronicle/docs/secops/use-google-secops-mcp.", "envVar": "SERVER_URL" } ], From 2616d5b44fb86cc71ab3bb2f05a2cb7a83a91e34 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Thu, 5 Feb 2026 08:35:39 -0500 Subject: [PATCH 04/20] chore: prepare google-secops extension v1.0.0 release --- .github/workflows/release-google-secops.yml | 22 +++++++++++++++++++ .../google-secops/gemini-extension.json | 11 +++++++++- 2 files changed, 32 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/release-google-secops.yml diff --git a/.github/workflows/release-google-secops.yml b/.github/workflows/release-google-secops.yml new file mode 100644 index 00000000..4920fcae --- /dev/null +++ b/.github/workflows/release-google-secops.yml @@ -0,0 +1,22 @@ +name: Release Google SecOps Extension + +on: + push: + tags: + - 'google-secops-v*' + +jobs: + release: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Create Extension Artifact + run: | + cd extensions/google-secops + zip -r ../../google-secops.zip . + + - name: Create GitHub Release + uses: softprops/action-gh-release@v1 + with: + files: google-secops.zip diff --git a/extensions/google-secops/gemini-extension.json b/extensions/google-secops/gemini-extension.json index 60924a06..8c0c2116 100644 --- a/extensions/google-secops/gemini-extension.json +++ b/extensions/google-secops/gemini-extension.json @@ -33,7 +33,16 @@ }, "headers": { "x-goog-user-project": "${PROJECT_ID}" - } + }, + "disabledTools": [ + "list_log_types", + "list_parsers", + "list_integrations", + "list_integration_actions", + "execute_manual_action", + "create_reference_list", + "get_reference_list" + ] } } } \ No newline at end of file From 494d8055ff9f21f616ee77a9b398238d4b02190b Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Thu, 5 Feb 2026 08:53:20 -0500 Subject: [PATCH 05/20] fix: exclude TOOL_MAPPING.md and update local tools docs for release --- .github/workflows/release-google-secops.yml | 2 +- extensions/google-secops/GEMINI.md | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/release-google-secops.yml b/.github/workflows/release-google-secops.yml index 4920fcae..aa41fa97 100644 --- a/.github/workflows/release-google-secops.yml +++ b/.github/workflows/release-google-secops.yml @@ -14,7 +14,7 @@ jobs: - name: Create Extension Artifact run: | cd extensions/google-secops - zip -r ../../google-secops.zip . + zip -r ../../google-secops.zip . -x "TOOL_MAPPING.md" - name: Create GitHub Release uses: softprops/action-gh-release@v1 diff --git a/extensions/google-secops/GEMINI.md b/extensions/google-secops/GEMINI.md index 6acc8d1d..68dbee08 100644 --- a/extensions/google-secops/GEMINI.md +++ b/extensions/google-secops/GEMINI.md @@ -94,9 +94,10 @@ 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 automatically falls back to **Local Python Tools** (e.g., `search_security_events`). +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`](../TOOL_MAPPING.md). +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 From c34a1212a0910a050901c82e252b8e04bfc8ef81 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Thu, 5 Feb 2026 08:57:02 -0500 Subject: [PATCH 06/20] fix: sanitize internal staging URL --- .../skills/setup-antigravity/mcp_config.template.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/google-secops/skills/setup-antigravity/mcp_config.template.json b/extensions/google-secops/skills/setup-antigravity/mcp_config.template.json index 89eb33ec..c7074eb6 100644 --- a/extensions/google-secops/skills/setup-antigravity/mcp_config.template.json +++ b/extensions/google-secops/skills/setup-antigravity/mcp_config.template.json @@ -1,7 +1,7 @@ { "mcpServers": { "remote-secops-investigate": { - "serverUrl": "{{ server_url | default('https://staging-chronicle.sandbox.googleapis.com/mcp') }}", + "serverUrl": "{{ server_url | default('https://chronicle.us.googleapis.com/mcp') }}", "headers": { "Content-Type": "application/json", "x-goog-user-project": "{{ project_id }}", @@ -41,7 +41,7 @@ ] }, "remote-secops-admin": { - "serverUrl": "{{ server_url | default('https://staging-chronicle.sandbox.googleapis.com/mcp') }}", + "serverUrl": "{{ server_url | default('https://chronicle.us.googleapis.com/mcp') }}", "headers": { "Content-Type": "application/json", "x-goog-user-project": "{{ project_id }}", From 00a10bf555c9fb4543d568d3ac63e9a738f4bbf9 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Thu, 5 Feb 2026 09:06:55 -0500 Subject: [PATCH 07/20] security: pin release action to v2.5.0 strict SHA --- .github/workflows/release-google-secops.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release-google-secops.yml b/.github/workflows/release-google-secops.yml index aa41fa97..fb49d5d8 100644 --- a/.github/workflows/release-google-secops.yml +++ b/.github/workflows/release-google-secops.yml @@ -17,6 +17,6 @@ jobs: zip -r ../../google-secops.zip . -x "TOOL_MAPPING.md" - name: Create GitHub Release - uses: softprops/action-gh-release@v1 + uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2.5.0 with: files: google-secops.zip From 5ad31400edddcff56f11fcd5224652d9c5dbb718 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Thu, 5 Feb 2026 09:14:01 -0500 Subject: [PATCH 08/20] fix: remove redundant setup-gemini-cli skill --- extensions/google-secops/GEMINI.md | 7 +-- .../google-secops/gemini-extension.json | 2 +- .../skills/setup-gemini-cli/SKILL.md | 58 ------------------- 3 files changed, 3 insertions(+), 64 deletions(-) delete mode 100644 extensions/google-secops/skills/setup-gemini-cli/SKILL.md diff --git a/extensions/google-secops/GEMINI.md b/extensions/google-secops/GEMINI.md index 68dbee08..0d94132f 100644 --- a/extensions/google-secops/GEMINI.md +++ b/extensions/google-secops/GEMINI.md @@ -56,14 +56,11 @@ To install this extension in your Gemini CLI environment: You will be prompted for two environment variables for the MCP configuration: -1. `PROJECT_ID` -2. `SERVER_URL` +1. `PROJECT_ID` (GCP Project ID on your SecOps tenant's /settings/profile page) +2. `SERVER_URL` (e.g. https://chronicle.northamerica-northeast2.rep.googleapis.com/mcp, https://chronicle.us.rep.googleapis.com/mcp, etc.) ## 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`) * **Trigger**: "Help me set up Antigravity", "Configure Antigravity for SecOps". diff --git a/extensions/google-secops/gemini-extension.json b/extensions/google-secops/gemini-extension.json index 8c0c2116..62319a66 100644 --- a/extensions/google-secops/gemini-extension.json +++ b/extensions/google-secops/gemini-extension.json @@ -3,7 +3,7 @@ "description": "Essential Security Operations skills for Triage, Investigation, and Hunting.", "version": "1.0.0", "skills": [ - "skills/setup-gemini-cli", + "skills/setup-antigravity", "skills/triage", "skills/investigate", diff --git a/extensions/google-secops/skills/setup-gemini-cli/SKILL.md b/extensions/google-secops/skills/setup-gemini-cli/SKILL.md deleted file mode 100644 index 23ef18ed..00000000 --- a/extensions/google-secops/skills/setup-gemini-cli/SKILL.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -name: secops-setup-gemini -description: Helps the user configure the Google SecOps Remote MCP Server for Gemini CLI. Use this when the user asks to "set up" or "configure" the security tools for Gemini CLI. -slash_command: /security:setup-gemini -category: configuration -personas: - - security_engineer ---- - -# Google SecOps Setup Assistant (Gemini CLI) - -You are an expert in configuring the Google SecOps Remote MCP Server for Gemini CLI users. - -## Prerequisite Checks - -1. **Check for `uv`**: The user needs `uv` installed. - * Ask if `uv` is installed. - * If not, guide: `curl -LsSf https://astral.sh/uv/install.sh | sh` - -2. **Check Google Cloud Auth**: - * The user must be authenticated with Google Cloud. - * Ask: "Have you run `gcloud auth application-default login`?" - * If not, instruct: - ```bash - gcloud auth application-default login - gcloud auth application-default set-quota-project - ``` - -3. **Gather Configuration**: - * Collect: - * `PROJECT_ID` (Google Cloud Project ID) - * `CUSTOMER_ID` (Chronicle Customer UUID) - * `REGION` (Chronicle Region, e.g., `us`, `europe-west1`) - -## Configuration Steps - -Guide the user to update their Gemini CLI configuration at `~/.gemini/config.json`. - -Instruct the user to add the following under `mcpServers`: - -```json -"remote-mcp-secops": { - "httpUrl": "https://chronicle.googleapis.com/mcp", - "authProviderType": "google_credentials", - "oauth": { - "scopes": ["https://www.googleapis.com/auth/cloud-platform"] - }, - "timeout": 30000, - "headers": { - "x-goog-user-project": "" - } -} -``` - -## Verification - -After configuration, ask the user to test: -`gemini prompt "list 3 soar cases"` From 872e65ba0d6780b6ad4a54f43843f2b1c1747211 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Thu, 5 Feb 2026 09:21:40 -0500 Subject: [PATCH 09/20] fix: add permissions for release creation and document known issues --- .github/workflows/release-google-secops.yml | 2 ++ extensions/google-secops/GEMINI.md | 3 +++ 2 files changed, 5 insertions(+) diff --git a/.github/workflows/release-google-secops.yml b/.github/workflows/release-google-secops.yml index fb49d5d8..d266a0cd 100644 --- a/.github/workflows/release-google-secops.yml +++ b/.github/workflows/release-google-secops.yml @@ -8,6 +8,8 @@ on: jobs: release: runs-on: ubuntu-latest + permissions: + contents: write steps: - uses: actions/checkout@v3 diff --git a/extensions/google-secops/GEMINI.md b/extensions/google-secops/GEMINI.md index 0d94132f..952b3d84 100644 --- a/extensions/google-secops/GEMINI.md +++ b/extensions/google-secops/GEMINI.md @@ -105,6 +105,9 @@ 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) From 47975b0809f69412682f9eb0c1ee72b8dee9857d Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Thu, 5 Feb 2026 11:49:42 -0500 Subject: [PATCH 10/20] fix: zip google-secops directory instead of contents --- .github/workflows/release-google-secops.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release-google-secops.yml b/.github/workflows/release-google-secops.yml index d266a0cd..c841b4c5 100644 --- a/.github/workflows/release-google-secops.yml +++ b/.github/workflows/release-google-secops.yml @@ -15,8 +15,8 @@ jobs: - name: Create Extension Artifact run: | - cd extensions/google-secops - zip -r ../../google-secops.zip . -x "TOOL_MAPPING.md" + cd extensions + zip -r ../google-secops.zip google-secops -x "google-secops/TOOL_MAPPING.md" - name: Create GitHub Release uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2.5.0 From 0ecc1aec9356671de9d38acd08893dc538fb40b1 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Thu, 5 Feb 2026 13:59:24 -0500 Subject: [PATCH 11/20] Update extension config to include CUSTOMER_ID and REGION --- docs/google_secops_extension.md | 38 +++++++++---------- extensions/google-secops/GEMINI.md | 24 ++++++++---- .../google-secops/gemini-extension.json | 21 ++++++++-- 3 files changed, 53 insertions(+), 30 deletions(-) diff --git a/docs/google_secops_extension.md b/docs/google_secops_extension.md index 7b9c6807..1769c8cb 100644 --- a/docs/google_secops_extension.md +++ b/docs/google_secops_extension.md @@ -34,7 +34,8 @@ The (`.agent`) symlink makes them available as [Antigravity Agent Skills](https: "previewFeatures": true }, "experimental": { - "skills": true + "skills": true, + "extensionConfig": true } } ``` @@ -54,30 +55,31 @@ To install this extension in your Gemini CLI environment: gemini extensions install ./extensions/google-secops ``` -You will be prompted for two environment variables for the MCP configuration: +You will be prompted for environment variables for the MCP configuration: -1. `PROJECT_ID` -2. `SERVER_URL` +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. ## 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. @@ -94,9 +96,10 @@ 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 automatically falls back to **Local Python Tools** (e.g., `search_security_events`). +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`](../TOOL_MAPPING.md). +For a detailed mapping of Remote vs. Local capabilities, see [`TOOL_MAPPING.md`](../extensions/google-secops/TOOL_MAPPING.md). ## Cross-Compatibility @@ -107,14 +110,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) - - - - - - diff --git a/extensions/google-secops/GEMINI.md b/extensions/google-secops/GEMINI.md index 952b3d84..df65e44c 100644 --- a/extensions/google-secops/GEMINI.md +++ b/extensions/google-secops/GEMINI.md @@ -34,7 +34,8 @@ The (`.agent`) symlink makes them available as [Antigravity Agent Skills](https: "previewFeatures": true }, "experimental": { - "skills": true + "skills": true, + "extensionConfig": true } } ``` @@ -54,27 +55,36 @@ To install this extension in your Gemini CLI environment: gemini extensions install ./extensions/google-secops ``` -You will be prompted for two environment variables for the MCP configuration: +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. `SERVER_URL` (e.g. https://chronicle.northamerica-northeast2.rep.googleapis.com/mcp, https://chronicle.us.rep.googleapis.com/mcp, etc.) +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. + +When using the secops-hosted-mcp MCP Server, use these parameters from the .env for EVERY request: +Customer ID: ${CUSTOMER_ID} +Region: ${REGION} +Project ID: ${PROJECT_ID} ## Available Skills -### 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. diff --git a/extensions/google-secops/gemini-extension.json b/extensions/google-secops/gemini-extension.json index 62319a66..86e9e8ce 100644 --- a/extensions/google-secops/gemini-extension.json +++ b/extensions/google-secops/gemini-extension.json @@ -3,7 +3,6 @@ "description": "Essential Security Operations skills for Triage, Investigation, and Hunting.", "version": "1.0.0", "skills": [ - "skills/setup-antigravity", "skills/triage", "skills/investigate", @@ -12,14 +11,28 @@ "settings": [ { "name": "PROJECT_ID", - "description": "Your Google Cloud Project ID.", - "envVar": "PROJECT_ID" + "description": "Your Google Cloud Project ID (from /settings/profile).", + "envVar": "PROJECT_ID", + "sensitive": false + }, + { + "name": "CUSTOMER_ID", + "description": "Your Chronicle Customer UUID (from /settings/profile).", + "envVar": "CUSTOMER_ID", + "sensitive": false + }, + { + "name": "REGION", + "description": "Your Chronicle Region (e.g. 'us', 'europe-west1').", + "envVar": "REGION", + "sensitive": false }, { "name": "SERVER_URL", "defaultValue": "https://chronicle.us.rep.googleapis.com/mcp", "description": "The URL of the remote MCP server See https://docs.cloud.google.com/chronicle/docs/secops/use-google-secops-mcp.", - "envVar": "SERVER_URL" + "envVar": "SERVER_URL", + "sensitive": false } ], "mcpServers": { From 9147735d5990c400b1d44b86b4260957678d80a1 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Thu, 5 Feb 2026 14:01:00 -0500 Subject: [PATCH 12/20] Add default values for PROJECT_ID, CUSTOMER_ID, and REGION --- extensions/google-secops/gemini-extension.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/extensions/google-secops/gemini-extension.json b/extensions/google-secops/gemini-extension.json index 86e9e8ce..4beadb33 100644 --- a/extensions/google-secops/gemini-extension.json +++ b/extensions/google-secops/gemini-extension.json @@ -11,18 +11,21 @@ "settings": [ { "name": "PROJECT_ID", + "defaultValue": "secops-demo-env", "description": "Your Google Cloud Project ID (from /settings/profile).", "envVar": "PROJECT_ID", "sensitive": false }, { "name": "CUSTOMER_ID", + "defaultValue": "a13f6726-efed-452e-9008-8fe0d3cb0f75", "description": "Your Chronicle Customer UUID (from /settings/profile).", "envVar": "CUSTOMER_ID", "sensitive": false }, { "name": "REGION", + "defaultValue": "us", "description": "Your Chronicle Region (e.g. 'us', 'europe-west1').", "envVar": "REGION", "sensitive": false From 854cf9ae6ec1f1b02071f3496e74c218504ade48 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Thu, 5 Feb 2026 14:55:50 -0500 Subject: [PATCH 13/20] Add GUI login requirement to prerequisites --- docs/google_secops_extension.md | 5 ++++- extensions/google-secops/GEMINI.md | 5 ++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/google_secops_extension.md b/docs/google_secops_extension.md index 1769c8cb..87e8be4d 100644 --- a/docs/google_secops_extension.md +++ b/docs/google_secops_extension.md @@ -22,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": { diff --git a/extensions/google-secops/GEMINI.md b/extensions/google-secops/GEMINI.md index df65e44c..0cc12e45 100644 --- a/extensions/google-secops/GEMINI.md +++ b/extensions/google-secops/GEMINI.md @@ -22,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": { From d983ca4356a0b3a67096c33999f84bbd1037ed95 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Thu, 5 Feb 2026 15:06:58 -0500 Subject: [PATCH 14/20] Add env block to remote-mcp-secops config --- extensions/google-secops/gemini-extension.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/extensions/google-secops/gemini-extension.json b/extensions/google-secops/gemini-extension.json index 4beadb33..612ddd56 100644 --- a/extensions/google-secops/gemini-extension.json +++ b/extensions/google-secops/gemini-extension.json @@ -50,6 +50,11 @@ "headers": { "x-goog-user-project": "${PROJECT_ID}" }, + "env": { + "PROJECT_ID": "${PROJECT_ID}", + "CUSTOMER_ID": "${CUSTOMER_ID}", + "REGION": "${REGION}" + }, "disabledTools": [ "list_log_types", "list_parsers", From e38f3dd079ec6bc6a5d0dcd4169243a2b1e7a975 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Thu, 5 Feb 2026 15:56:31 -0500 Subject: [PATCH 15/20] Clarify .env file path in documentation --- docs/google_secops_extension.md | 2 +- extensions/google-secops/GEMINI.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/google_secops_extension.md b/docs/google_secops_extension.md index 87e8be4d..f92a694d 100644 --- a/docs/google_secops_extension.md +++ b/docs/google_secops_extension.md @@ -65,7 +65,7 @@ You will be prompted for environment variables for the MCP configuration: 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. +> **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 diff --git a/extensions/google-secops/GEMINI.md b/extensions/google-secops/GEMINI.md index 0cc12e45..34b95b28 100644 --- a/extensions/google-secops/GEMINI.md +++ b/extensions/google-secops/GEMINI.md @@ -65,9 +65,9 @@ You will be prompted for environment variables for the MCP configuration: 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. +> **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 for EVERY request: +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} From d877c232924149db763052364a72e82da33946ec Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Thu, 5 Feb 2026 16:39:09 -0500 Subject: [PATCH 16/20] feat(secops): add cases skill, custom commands, and contextFileName config --- docs/google_secops_extension.md | 13 +++++++++++ extensions/google-secops/GEMINI.md | 13 +++++++++++ .../google-secops/commands/secops/cases.toml | 1 + .../google-secops/commands/secops/hunt.toml | 1 + .../commands/secops/investigate.toml | 1 + .../google-secops/commands/secops/triage.toml | 1 + .../google-secops/gemini-extension.json | 4 +++- .../google-secops/skills/cases/SKILL.md | 23 +++++++++++++++++++ extensions/google-secops/skills/hunt/SKILL.md | 2 +- .../google-secops/skills/investigate/SKILL.md | 2 +- .../google-secops/skills/triage/SKILL.md | 2 +- 11 files changed, 59 insertions(+), 4 deletions(-) create mode 100644 extensions/google-secops/commands/secops/cases.toml create mode 100644 extensions/google-secops/commands/secops/hunt.toml create mode 100644 extensions/google-secops/commands/secops/investigate.toml create mode 100644 extensions/google-secops/commands/secops/triage.toml create mode 100644 extensions/google-secops/skills/cases/SKILL.md diff --git a/docs/google_secops_extension.md b/docs/google_secops_extension.md index f92a694d..5dda5c50 100644 --- a/docs/google_secops_extension.md +++ b/docs/google_secops_extension.md @@ -86,6 +86,19 @@ You will be prompted for environment variables for the MCP configuration: * **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 `: Quickly start triaging an alert. +* `/secops:investigate `: Start an investigation. +* `/secops:hunt `: Start a threat hunt. +* `/secops:cases`: List recent cases. + ## How it Works These skills act as **Driver Agents** that: diff --git a/extensions/google-secops/GEMINI.md b/extensions/google-secops/GEMINI.md index 34b95b28..39e0dd00 100644 --- a/extensions/google-secops/GEMINI.md +++ b/extensions/google-secops/GEMINI.md @@ -91,6 +91,19 @@ Project ID: ${PROJECT_ID} * **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 `: Quickly start triaging an alert. +* `/secops:investigate `: Start an investigation. +* `/secops:hunt `: Start a threat hunt. +* `/secops:cases`: List recent cases. + ## How it Works These skills act as **Driver Agents** that: diff --git a/extensions/google-secops/commands/secops/cases.toml b/extensions/google-secops/commands/secops/cases.toml new file mode 100644 index 00000000..44e47b1f --- /dev/null +++ b/extensions/google-secops/commands/secops/cases.toml @@ -0,0 +1 @@ +prompt = """Run the secops-cases skill.""" diff --git a/extensions/google-secops/commands/secops/hunt.toml b/extensions/google-secops/commands/secops/hunt.toml new file mode 100644 index 00000000..6cbd0f97 --- /dev/null +++ b/extensions/google-secops/commands/secops/hunt.toml @@ -0,0 +1 @@ +prompt = """Run the secops-hunt skill for `{{args}}`.""" diff --git a/extensions/google-secops/commands/secops/investigate.toml b/extensions/google-secops/commands/secops/investigate.toml new file mode 100644 index 00000000..981015f3 --- /dev/null +++ b/extensions/google-secops/commands/secops/investigate.toml @@ -0,0 +1 @@ +prompt = """Run the secops-investigate skill on case `{{args}}`.""" diff --git a/extensions/google-secops/commands/secops/triage.toml b/extensions/google-secops/commands/secops/triage.toml new file mode 100644 index 00000000..49327458 --- /dev/null +++ b/extensions/google-secops/commands/secops/triage.toml @@ -0,0 +1 @@ +prompt = """Run the secops-triage skill on alert `{{args}}`.""" diff --git a/extensions/google-secops/gemini-extension.json b/extensions/google-secops/gemini-extension.json index 612ddd56..d1428af3 100644 --- a/extensions/google-secops/gemini-extension.json +++ b/extensions/google-secops/gemini-extension.json @@ -1,12 +1,14 @@ { "name": "google-secops", + "contextFileName": "GEMINI.md", "description": "Essential Security Operations skills for Triage, Investigation, and Hunting.", "version": "1.0.0", "skills": [ "skills/setup-antigravity", "skills/triage", "skills/investigate", - "skills/hunt" + "skills/hunt", + "skills/cases" ], "settings": [ { diff --git a/extensions/google-secops/skills/cases/SKILL.md b/extensions/google-secops/skills/cases/SKILL.md new file mode 100644 index 00000000..ef44a3cb --- /dev/null +++ b/extensions/google-secops/skills/cases/SKILL.md @@ -0,0 +1,23 @@ +--- +name: secops-cases +description: List recent SOAR cases. Use this for "list cases" or "show cases". +slash_command: /secops:cases +category: security_operations +personas: + - tier1_soc_analyst +--- + +# Security Cases Specialist + +You are a specialist in retrieving SOAR case information. + +## Tool Selection + +1. **Check Availability**: Prefer `list_cases` (Remote). +2. **Fallback**: Use `list_cases` from Local tools if Remote is unavailable. + +## Workflow + +1. **List Cases**: + * Call `list_cases` to retrieve the most recent cases. + * Display them in a table with ID, Title, Priority, and Status. diff --git a/extensions/google-secops/skills/hunt/SKILL.md b/extensions/google-secops/skills/hunt/SKILL.md index 0038d752..33112afd 100644 --- a/extensions/google-secops/skills/hunt/SKILL.md +++ b/extensions/google-secops/skills/hunt/SKILL.md @@ -1,7 +1,7 @@ --- name: secops-hunt description: Expert guidance for proactive threat hunting. Use this when the user asks to "hunt" for threads, IOCs, or specific TTPs. -slash_command: /security:hunt +slash_command: /secops:hunt category: security_operations personas: - threat_hunter diff --git a/extensions/google-secops/skills/investigate/SKILL.md b/extensions/google-secops/skills/investigate/SKILL.md index de008d25..6c22f67a 100644 --- a/extensions/google-secops/skills/investigate/SKILL.md +++ b/extensions/google-secops/skills/investigate/SKILL.md @@ -1,7 +1,7 @@ --- name: secops-investigate description: Expert guidance for deep security investigations. Use this when the user asks to "investigate" a case, entity, or incident. -slash_command: /security:investigate +slash_command: /secops:investigate category: security_operations personas: - incident_responder diff --git a/extensions/google-secops/skills/triage/SKILL.md b/extensions/google-secops/skills/triage/SKILL.md index 613a92f3..3b291be3 100644 --- a/extensions/google-secops/skills/triage/SKILL.md +++ b/extensions/google-secops/skills/triage/SKILL.md @@ -1,7 +1,7 @@ --- name: secops-triage description: Expert guidance for security alert triage. Use this when the user asks to "triage" an alert or case. -slash_command: /security:triage +slash_command: /secops:triage category: security_operations personas: - tier1_soc_analyst From 03bb90f7f1dd7dede37bab48eb158d41ec763974 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Fri, 6 Feb 2026 10:58:09 -0500 Subject: [PATCH 17/20] Update extension configuration and prepare for release --- .gitignore | 1 + extensions/google-secops-staging/.env.example | 4 + .../google-secops-staging/.env.secops-lab | 4 + extensions/google-secops-staging/.env.staging | 4 + extensions/google-secops-staging/GEMINI.md | 141 ++++++++++++++++++ .../google-secops-staging/TOOL_MAPPING.md | 36 +++++ .../commands/secops/cases.toml | 1 + .../commands/secops/hunt.toml | 1 + .../commands/secops/investigate.toml | 1 + .../commands/secops/triage.toml | 1 + .../endpoint_constants.py | 0 .../gemini-extension.json | 71 +++++++++ .../rewrite_json_w_env.py | 45 ++++++ .../skills/cases/SKILL.md | 23 +++ .../skills/hunt/SKILL.md | 88 +++++++++++ .../skills/investigate/SKILL.md | 121 +++++++++++++++ .../skills/setup-antigravity/.env.example | 3 + .../skills/setup-antigravity/SKILL.md | 51 +++++++ .../mcp_config.template.json | 75 ++++++++++ .../skills/triage/SKILL.md | 98 ++++++++++++ 20 files changed, 769 insertions(+) create mode 100644 extensions/google-secops-staging/.env.example create mode 100644 extensions/google-secops-staging/.env.secops-lab create mode 100644 extensions/google-secops-staging/.env.staging create mode 100644 extensions/google-secops-staging/GEMINI.md create mode 100644 extensions/google-secops-staging/TOOL_MAPPING.md create mode 100644 extensions/google-secops-staging/commands/secops/cases.toml create mode 100644 extensions/google-secops-staging/commands/secops/hunt.toml create mode 100644 extensions/google-secops-staging/commands/secops/investigate.toml create mode 100644 extensions/google-secops-staging/commands/secops/triage.toml create mode 100644 extensions/google-secops-staging/endpoint_constants.py create mode 100644 extensions/google-secops-staging/gemini-extension.json create mode 100644 extensions/google-secops-staging/rewrite_json_w_env.py create mode 100644 extensions/google-secops-staging/skills/cases/SKILL.md create mode 100644 extensions/google-secops-staging/skills/hunt/SKILL.md create mode 100644 extensions/google-secops-staging/skills/investigate/SKILL.md create mode 100644 extensions/google-secops-staging/skills/setup-antigravity/.env.example create mode 100644 extensions/google-secops-staging/skills/setup-antigravity/SKILL.md create mode 100644 extensions/google-secops-staging/skills/setup-antigravity/mcp_config.template.json create mode 100644 extensions/google-secops-staging/skills/triage/SKILL.md diff --git a/.gitignore b/.gitignore index a614800b..81e761d9 100644 --- a/.gitignore +++ b/.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 diff --git a/extensions/google-secops-staging/.env.example b/extensions/google-secops-staging/.env.example new file mode 100644 index 00000000..81c4c3e9 --- /dev/null +++ b/extensions/google-secops-staging/.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 diff --git a/extensions/google-secops-staging/.env.secops-lab b/extensions/google-secops-staging/.env.secops-lab new file mode 100644 index 00000000..f3cb4aef --- /dev/null +++ b/extensions/google-secops-staging/.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 diff --git a/extensions/google-secops-staging/.env.staging b/extensions/google-secops-staging/.env.staging new file mode 100644 index 00000000..ed6fe539 --- /dev/null +++ b/extensions/google-secops-staging/.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 diff --git a/extensions/google-secops-staging/GEMINI.md b/extensions/google-secops-staging/GEMINI.md new file mode 100644 index 00000000..dd4ede80 --- /dev/null +++ b/extensions/google-secops-staging/GEMINI.md @@ -0,0 +1,141 @@ +# Google SecOps Extension + +This folder contains the **Google SecOps Extension**, providing specialized skills for security operations. + +## Overview + +The extension `extensions/google-secops-staging` 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 `: Quickly start triaging an alert. +* `/secops:investigate `: Start an investigation. +* `/secops:hunt `: 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. + +## 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) diff --git a/extensions/google-secops-staging/TOOL_MAPPING.md b/extensions/google-secops-staging/TOOL_MAPPING.md new file mode 100644 index 00000000..6158e6e3 --- /dev/null +++ b/extensions/google-secops-staging/TOOL_MAPPING.md @@ -0,0 +1,36 @@ +# Tool Mapping: Local vs. Remote + +This document maps the tools defined in the local MCP server implementation (`server/secops` and `server/secops-soar`) to the tools available in the remote Google SecOps MCP server. + +**Configuration & Selection Strategy:** +When executing a skill, the agent should first check which tools are available in the current environment. +1. **Prioritize Remote Tools**: If a remote tool is available, use it. +2. **Fallback to Local Tools**: If the remote tool is unavailable, use the corresponding local tool. +3. **Adapt Workflow**: Some operations (like Natural Language Search) require a multi-step workflow in Remote (Translate -> Search) but a single step in Local. + +| Category | Capability | Remote Tool (MCP Server) | Local Tool (Python) | Notes | +| :--- | :--- | :--- | :--- | :--- | +| **Case Management** | List Cases | `list_cases` | `list_cases` | | +| | Get Case Details | `get_case` | `get_case_full_details` | Local `get_case_full_details` aggregates alerts/comments. Remote `get_case` fetches the case object; use `expand='tasks,tags,products'` or call `list_case_alerts`/`list_case_comments` for full context. | +| | Comment on Case | `create_case_comment` | `post_case_comment` | | +| | Update Case | `update_case` | `change_case_priority` | Remote tool is general (priority, status, assignee). Local tool is specific to priority. | +| | Close Case | `execute_bulk_close_case` | *(No local tool)* | Only remote tool can close cases. | +| **Alerts (SOAR)** | List Alerts for Case | `list_case_alerts` | `list_alerts_by_case` | | +| | List Events for Alert | `list_connector_events` | `list_events_by_alert` | Remote tool lists "connector events". | +| | List Alert Groups | *(No direct equivalent)* | `list_alert_group_identifiers_by_case` | Remote `list_case_alerts` returns alert objects which may contain grouping info. | +| **Entities (SOAR)** | Search Entities | `search_entity` | `search_entity` | | +| | Get Involved Entities | `list_involved_entities` | `get_entities_by_alert_group_identifiers` | Remote tool lists involved entities for a specific case alert. | +| | Get Entity Details | *(No direct equivalent)* | `get_entity_details` | | +| **SIEM / UDM** | UDM Search (Query) | `udm_search` | `search_udm` | | +| | UDM Search (Nat. Lang.) | `translate_udm_query` -> `udm_search` | `search_security_events` | **Critical:** Remote requires 2 steps (Translate then Search). Local does both in one call. | +| | Entity Summary | `summarize_entity` | `lookup_entity` | Both provide a summary of entity activity in SIEM. | +| | IoC Matching | `get_ioc_match` | `get_ioc_matches` | | +| | Export Results | *(No direct equivalent)* | `export_udm_search_csv` | | +| **Alerts (SIEM)** | List SIEM Alerts | `list_security_alerts` | `list_security_alerts` | Lists alerts directly from SIEM (not SOAR cases). | +| | Get SIEM Alert | `get_security_alert` | `get_security_alert` | | +| | Update SIEM Alert | `update_security_alert` | `update_security_alert` | | +| **Rules** | List Rules | `list_rules` | `list_rules` | | +| | Get Rule | `get_rule` | `get_rule` | | +| | Create Rule | `create_rule` | `create_rule` | | +| | Validate Rule | `validate_rule` | `validate_rule` | | +| | Test/Run Rule | `list_rule_detections` | `list_rule_detections` | Use to see historical detections. | \ No newline at end of file diff --git a/extensions/google-secops-staging/commands/secops/cases.toml b/extensions/google-secops-staging/commands/secops/cases.toml new file mode 100644 index 00000000..44e47b1f --- /dev/null +++ b/extensions/google-secops-staging/commands/secops/cases.toml @@ -0,0 +1 @@ +prompt = """Run the secops-cases skill.""" diff --git a/extensions/google-secops-staging/commands/secops/hunt.toml b/extensions/google-secops-staging/commands/secops/hunt.toml new file mode 100644 index 00000000..6cbd0f97 --- /dev/null +++ b/extensions/google-secops-staging/commands/secops/hunt.toml @@ -0,0 +1 @@ +prompt = """Run the secops-hunt skill for `{{args}}`.""" diff --git a/extensions/google-secops-staging/commands/secops/investigate.toml b/extensions/google-secops-staging/commands/secops/investigate.toml new file mode 100644 index 00000000..981015f3 --- /dev/null +++ b/extensions/google-secops-staging/commands/secops/investigate.toml @@ -0,0 +1 @@ +prompt = """Run the secops-investigate skill on case `{{args}}`.""" diff --git a/extensions/google-secops-staging/commands/secops/triage.toml b/extensions/google-secops-staging/commands/secops/triage.toml new file mode 100644 index 00000000..49327458 --- /dev/null +++ b/extensions/google-secops-staging/commands/secops/triage.toml @@ -0,0 +1 @@ +prompt = """Run the secops-triage skill on alert `{{args}}`.""" diff --git a/extensions/google-secops-staging/endpoint_constants.py b/extensions/google-secops-staging/endpoint_constants.py new file mode 100644 index 00000000..e69de29b diff --git a/extensions/google-secops-staging/gemini-extension.json b/extensions/google-secops-staging/gemini-extension.json new file mode 100644 index 00000000..b96382b2 --- /dev/null +++ b/extensions/google-secops-staging/gemini-extension.json @@ -0,0 +1,71 @@ +{ + "name": "google-secops", + "contextFileName": "GEMINI.md", + "description": "Essential Security Operations skills for Triage, Investigation, and Hunting.", + "version": "1.0.0", + "skills": [ + "skills/setup-antigravity", + "skills/triage", + "skills/investigate", + "skills/hunt", + "skills/cases" + ], + "settings": [ + { + "name": "PROJECT_ID", + "defaultValue": "secops-ai-staging", + "description": "Your Google Cloud Project ID (from /settings/profile).", + "envVar": "PROJECT_ID", + "sensitive": false + }, + { + "name": "CUSTOMER_ID", + "defaultValue": "eb3b937b-3ab6-47e5-8185-24837b826691", + "description": "Your Chronicle Customer UUID (from /settings/profile).", + "envVar": "CUSTOMER_ID", + "sensitive": false + }, + { + "name": "REGION", + "defaultValue": "us", + "description": "Your Chronicle Region (e.g. 'us', 'europe-west1').", + "envVar": "REGION", + "sensitive": false + }, + { + "name": "SERVER_URL", + "defaultValue": "https://staging-chronicle.sandbox.googleapis.com/mcp", + "description": "The URL of the remote MCP server See https://docs.cloud.google.com/chronicle/docs/secops/use-google-secops-mcp.", + "envVar": "SERVER_URL", + "sensitive": false + } + ], + "mcpServers": { + "remote-mcp-secops": { + "httpUrl": "${SERVER_URL}", + "authProviderType": "google_credentials", + "oauth": { + "scopes": [ + "https://www.googleapis.com/auth/cloud-platform" + ] + }, + "headers": { + "x-goog-user-project": "${PROJECT_ID}" + }, + "env": { + "PROJECT_ID": "${PROJECT_ID}", + "CUSTOMER_ID": "${CUSTOMER_ID}", + "REGION": "${REGION}" + }, + "disabledTools": [ + "list_log_types", + "list_parsers", + "list_integrations", + "list_integration_actions", + "execute_manual_action", + "create_reference_list", + "get_reference_list" + ] + } + } +} diff --git a/extensions/google-secops-staging/rewrite_json_w_env.py b/extensions/google-secops-staging/rewrite_json_w_env.py new file mode 100644 index 00000000..db2a47b2 --- /dev/null +++ b/extensions/google-secops-staging/rewrite_json_w_env.py @@ -0,0 +1,45 @@ +import json +import os + +def main(): + env_file = '.env' + json_file = 'gemini-extension.json' + + if not os.path.exists(env_file): + print(f"Error: {env_file} not found.") + return + + if not os.path.exists(json_file): + print(f"Error: {json_file} not found.") + return + + # Read .env file + env_vars = {} + with open(env_file, 'r') as f: + for line in f: + line = line.strip() + if line and not line.startswith('#'): + key, value = line.split('=', 1) + env_vars[key.strip()] = value.strip() + + # Read gemini-extension.json + with open(json_file, 'r') as f: + data = json.load(f) + + # Update defaultValue in settings + if 'settings' in data: + for setting in data['settings']: + env_var_name = setting.get('envVar') + if env_var_name and env_var_name in env_vars: + setting['defaultValue'] = env_vars[env_var_name] + print(f"Updated {env_var_name} to {env_vars[env_var_name]}") + + # Write back to gemini-extension.json + with open(json_file, 'w') as f: + json.dump(data, f, indent=2) + f.write('\n') # Add trailing newline + + print("Successfully updated gemini-extension.json") + +if __name__ == "__main__": + main() diff --git a/extensions/google-secops-staging/skills/cases/SKILL.md b/extensions/google-secops-staging/skills/cases/SKILL.md new file mode 100644 index 00000000..ef44a3cb --- /dev/null +++ b/extensions/google-secops-staging/skills/cases/SKILL.md @@ -0,0 +1,23 @@ +--- +name: secops-cases +description: List recent SOAR cases. Use this for "list cases" or "show cases". +slash_command: /secops:cases +category: security_operations +personas: + - tier1_soc_analyst +--- + +# Security Cases Specialist + +You are a specialist in retrieving SOAR case information. + +## Tool Selection + +1. **Check Availability**: Prefer `list_cases` (Remote). +2. **Fallback**: Use `list_cases` from Local tools if Remote is unavailable. + +## Workflow + +1. **List Cases**: + * Call `list_cases` to retrieve the most recent cases. + * Display them in a table with ID, Title, Priority, and Status. diff --git a/extensions/google-secops-staging/skills/hunt/SKILL.md b/extensions/google-secops-staging/skills/hunt/SKILL.md new file mode 100644 index 00000000..33112afd --- /dev/null +++ b/extensions/google-secops-staging/skills/hunt/SKILL.md @@ -0,0 +1,88 @@ +--- +name: secops-hunt +description: Expert guidance for proactive threat hunting. Use this when the user asks to "hunt" for threads, IOCs, or specific TTPs. +slash_command: /secops:hunt +category: security_operations +personas: + - threat_hunter +--- + +# Threat Hunter + +You are an expert Threat Hunter. Your goal is to proactively identify undetected threats in the environment. + +## Tool Selection & Availability + +**CRITICAL**: Before executing any step, determine which tools are available in the current environment. +1. **Check Availability**: Look for Remote tools (e.g., `udm_search`, `get_ioc_match`) first. If unavailable, use Local tools (e.g., `search_security_events`, `get_ioc_matches`). +2. **Reference Mapping**: Use `extensions/google-secops/TOOL_MAPPING.md` to find the correct tool for each capability. +3. **Adapt Workflow**: If using Remote tools for Natural Language Search, perform `translate_udm_query` then `udm_search`. If using Local tools, use `search_security_events` directly. + +## Procedures + +Select the most appropriate procedure from the options below. + +### Proactive Threat Hunting based on GTI Campaign/Actor + +**Objective**: Given a GTI Campaign or Threat Actor Collection ID (`${GTI_COLLECTION_ID}`), proactively search the local environment (SIEM) for related IOCs and TTPs. + +**Workflow**: + +1. **Analyst Input**: Hunt for Campaign/Actor: `${GTI_COLLECTION_ID}` +2. **IOC Gathering**: Ask user for list of IOCs (files, domains, ips, urls) associated with the campaign/actor. +3. **Initial Scan**: + * **Action**: Check for recent hits against these indicators. + * **Remote**: `get_ioc_match`. + * **Local**: `get_ioc_matches`. +4. **Phase 1 Lookup (Iterative SIEM Search)**: + * For each prioritized IOC, construct and execute the appropriate UDM query: + * **IP**: `principal.ip = "IOC" OR target.ip = "IOC" OR network.ip = "IOC"` + * **Domain**: `principal.hostname = "IOC" OR target.hostname = "IOC" OR network.dns.questions.name = "IOC"` + * **Hash**: `target.file.sha256 = "IOC" OR target.file.md5 = "IOC" OR target.file.sha1 = "IOC"` + * **URL**: `target.url = "IOC"` + * **Tool**: `udm_search` (Remote/Local). +5. **Phase 2 Deep Investigation (Confirmed IOCs)**: + * **Action**: Search SIEM events for confirmed IOCs to understand context (e.g. process execution, network connections). + * **Action**: Check for related cases (`list_cases`). +6. **Synthesis**: Synthesize all findings. +7. **Output**: Ask user to Create Case, Update Case, or Generate Report. + * If **Report**: Generate a markdown report file using `write_file`. + * If **Case**: Post a comment to SOAR. + +### Guided TTP Hunt (Example: Credential Access) + +**Objective**: Proactively hunt for evidence of specific MITRE ATT&CK Credential Access techniques (e.g., OS Credential Dumping T1003, Credentials from Password Stores T1555). + +**Inputs**: +* `${TECHNIQUE_IDS}`: List of MITRE IDs (e.g., "T1003.001"). +* `${TIME_FRAME_HOURS}`: Lookback (default 72). +* `${TARGET_SCOPE_QUERY}`: Optional scope filter. + +**Workflow**: + +1. **Research**: Review MITRE ATT&CK techniques or ask user for TTP details. +2. **Hunt Loop**: + * **Develop Queries**: Formulate UDM queries for `udm_search` (e.g., specific process names, command lines). + * **Execute**: Run the searches using `udm_search`. + * **Analyze**: Review for anomalies. Does this match the hypothesis? Is it noise? + * **Refine**: If too noisy, add filters. If no results, broaden query. + * **Repeat**: Iterate until exhausted or leads found. +3. **Enrich**: Lookup suspicious entities found during the loop. + * **Remote**: `summarize_entity`. + * **Local**: `lookup_entity`. +4. **Document**: Post findings to a SOAR case or create a report. +5. **Escalate**: Identify if a new incident needs to be raised. + +## Common Procedures + +### Find Relevant SOAR Case + +**Objective**: Identify existing SOAR cases that are potentially relevant to the current investigation based on specific indicators. + +**Inputs**: +* `${SEARCH_TERMS}`: List of values to search (IOCs, etc.). + +**Steps**: +1. **Search**: Use `list_cases` with a filter for the search terms. +2. **Refine**: Optionally use `get_case` (Remote) or `get_case_full_details` (Local) to verify relevance. +3. **Output**: Return list of relevant `${RELEVANT_CASE_IDS}`. \ No newline at end of file diff --git a/extensions/google-secops-staging/skills/investigate/SKILL.md b/extensions/google-secops-staging/skills/investigate/SKILL.md new file mode 100644 index 00000000..6c22f67a --- /dev/null +++ b/extensions/google-secops-staging/skills/investigate/SKILL.md @@ -0,0 +1,121 @@ +--- +name: secops-investigate +description: Expert guidance for deep security investigations. Use this when the user asks to "investigate" a case, entity, or incident. +slash_command: /secops:investigate +category: security_operations +personas: + - incident_responder + - tier2_soc_analyst +--- + +# Security Investigator + +You are a Tier 2/3 SOC Analyst and Incident Responder. Your goal is to investigate security incidents thoroughly. + +## Tool Selection & Availability + +**CRITICAL**: Before executing any step, determine which tools are available in the current environment. +1. **Check Availability**: Look for Remote tools (e.g., `list_cases`, `udm_search`) first. If unavailable, use Local tools (e.g., `list_cases`, `search_security_events`). +2. **Reference Mapping**: Use `extensions/google-secops/TOOL_MAPPING.md` to find the correct tool for each capability. +3. **Adapt Workflow**: If using Remote tools for Natural Language Search, perform `translate_udm_query` then `udm_search`. If using Local tools, use `search_security_events` directly. + +## Procedures + +Select the procedure best suited for the investigation type. + +### Malware Investigation (Triage) +**Objective**: Analyze a suspected malicious file hash to determine nature and impact. +**Inputs**: `${FILE_HASH}`, `${CASE_ID}`. +**Steps**: +1. **Context**: + * **Remote**: `get_case` + `list_case_alerts`. + * **Local**: `get_case_full_details`. +2. **SIEM Prevalence**: + * **Remote**: `summarize_entity` (hash). + * **Local**: `lookup_entity` (hash). +3. **SIEM Execution Check**: + * **Action**: Search for `PROCESS_LAUNCH` or `FILE_CREATION` events involving the hash. + * **Query**: `target.file.sha256 = "FILE_HASH" OR target.file.md5 = "FILE_HASH"` + * **Remote**: `udm_search` (using UDM query). + * **Local**: `search_udm` (using UDM query). + * Identify `${AFFECTED_HOSTS}`. +4. **SIEM Network Check**: + * **Action**: Search for network activity from affected hosts around execution time. + * **Query**: `principal.process.file.sha256 = "FILE_HASH"` + * **Remote**: `udm_search`. + * **Local**: `search_udm`. + * Identify `${NETWORK_IOCS}`. +5. **Enrichment**: **Execute Common Procedure: Enrich IOC** for network IOCs. +6. **Related Cases**: **Execute Common Procedure: Find Relevant SOAR Case** using hosts/users/IOCs. +7. **Synthesize**: Assess severity using the matrix below. + + **Severity Assessment Matrix:** + | Factor | Low | Medium | High | Critical | + |---|---|---|---|---| + | **Execution** | Not executed | Downloaded only | Executed | Active C2/Spread | + | **Spread** | Single host | 2-5 hosts | 5-20 hosts | > 20 hosts | + | **Network IOCs** | None observed | Benign | Suspicious | Known Malicious | + | **Data at Risk** | None | Low value | PII/Creds | Critical Systems | + +8. **Document**: **Execute Common Procedure: Document in SOAR**. +9. **Report**: Optionally **Execute Common Procedure: Generate Report File**. + +### Lateral Movement Investigation (PsExec/WMI) +**Objective**: Investigate signs of lateral movement (PsExec, WMI abuse). +**Inputs**: `${TIME_FRAME_HOURS}`, `${TARGET_SCOPE}`. +**Steps**: +1. **Technique Research**: Review MITRE ATT&CK techniques T1021.002 (SMB/Windows Admin Shares) and T1047 (WMI). +2. **SIEM Queries**: + * **PsExec Service Installation**: + * `metadata.product_event_type = "ServiceInstalled" AND target.process.file.full_path CONTAINS "PSEXESVC.exe"` + * **PsExec Execution**: + * `target.process.file.full_path CONTAINS "PSEXESVC.exe"` + * **WMI Process Creation**: + * `metadata.event_type = "PROCESS_LAUNCH" AND principal.process.file.full_path = "C:\\Windows\\System32\\wbem\\WmiPrvSE.exe" AND target.process.file.full_path IN ("cmd.exe", "powershell.exe")` + * **WMI Remote Execution**: + * `principal.process.command_line CONTAINS "wmic" AND principal.process.command_line CONTAINS "/node:" AND principal.process.command_line CONTAINS "process call create"` +3. **Execute**: + * **Remote**: `udm_search`. + * **Local**: `search_udm`. +4. **Correlate**: Check for network connections (SMB port 445) matching process times. +5. **Enrich**: **Execute Common Procedure: Enrich IOC** for involved IPs/Hosts. +6. **Document**: **Execute Common Procedure: Document in SOAR**. + +### Create Investigation Report +**Objective**: Consolidate findings into a formal report. +**Inputs**: `${CASE_ID}`. +**Steps**: +1. **Gather Context**: + * **Remote**: `get_case` + `list_case_comments`. + * **Local**: `get_case_full_details`. + * Identify key entities. +2. **Synthesize**: Combine findings from SIEM, IOC matches, and case history. +3. **Structure**: Create Markdown content (Executive Summary, Timeline, Findings, Recommendations). +4. **Diagram**: Generate a Mermaid sequence diagram of the investigation. +5. **Redaction**: **CRITICAL**: Confirm no sensitive PII/Secrets in report. +6. **Generate File**: **Execute Common Procedure: Generate Report File**. +7. **Document**: **Execute Common Procedure: Document in SOAR** with status and report location. + +## Common Procedures + +### Enrich IOC (SIEM Prevalence) +**Steps**: +1. **SIEM Summary**: `summarize_entity` (Remote) or `lookup_entity` (Local). +2. **IOC Match**: `get_ioc_match` (Remote) or `get_ioc_matches` (Local). +3. Return combined findings. + +### Find Relevant SOAR Case +**Steps**: +1. **Search**: `list_cases` with filters for entity values. +2. Return list of `${RELEVANT_CASE_IDS}`. + +### Document in SOAR +**Steps**: +1. **Post**: `create_case_comment` (Remote) or `post_case_comment` (Local). + +### Generate Report File +**Tool**: `write_file` (Agent Capability) +**Steps**: +1. Construct filename: `reports/${REPORT_TYPE}_${SUFFIX}_${TIMESTAMP}.md`. +2. Write content to file using `write_file`. +3. Return path. \ No newline at end of file diff --git a/extensions/google-secops-staging/skills/setup-antigravity/.env.example b/extensions/google-secops-staging/skills/setup-antigravity/.env.example new file mode 100644 index 00000000..aa95328a --- /dev/null +++ b/extensions/google-secops-staging/skills/setup-antigravity/.env.example @@ -0,0 +1,3 @@ +PROJECT_ID=your-project-id +# Optional: Override the server URL +# SERVER_URL=https://chronicle.googleapis.com/mcp diff --git a/extensions/google-secops-staging/skills/setup-antigravity/SKILL.md b/extensions/google-secops-staging/skills/setup-antigravity/SKILL.md new file mode 100644 index 00000000..3c846f55 --- /dev/null +++ b/extensions/google-secops-staging/skills/setup-antigravity/SKILL.md @@ -0,0 +1,51 @@ +--- +name: secops-setup-antigravity +description: Helps the user configure the Google SecOps Remote MCP Server for Antigravity. Use this when the user asks to "set up" or "configure" the security tools for Antigravity. +slash_command: /security:setup-antigravity +category: configuration +personas: + - security_engineer +--- + +# Google SecOps Setup Assistant (Antigravity) + +You are an expert in configuring the Google SecOps Remote MCP Server for Antigravity. + +## Prerequisite Checks + +1. **Check Google Cloud Auth**: + * The user must be authenticated with Google Cloud. + * Ask: "Have you run `gcloud auth application-default login`?" + * If not, instruct: + ```bash + gcloud auth application-default login + gcloud auth application-default set-quota-project + ``` + +2. **Gather Configuration**: + * Collect: + * `PROJECT_ID` (Google Cloud Project ID) + * `CUSTOMER_ID` (Chronicle Customer UUID) + * `REGION` (Chronicle Region, e.g., `us`, `europe-west1`) + +## Configuration Steps + +Guide the user to update their Antigravity configuration at `~/.gemini/antigravity/mcp_config.json` using the provided template. + +1. **Read Template**: Read the `mcp_config.template.json` file located in the same directory as this skill. +3. **Prepare Variables**: + * **Option A (Recommended)**: reading from `.env`. + * Ask the user to create a `.env` file in this directory based on `.env.example`. + * Read the `PROJECT_ID` and optional `SERVER_URL` from `.env`. + * **Option B (Manual)**: Ask the user directly for their `PROJECT_ID`. +4. **Generate and Merge Config**: + * Read `mcp_config.template.json`. + * Generate `auth_token` using: `$(gcloud auth print-access-token)`. *Note: Warn the user that this token is temporary.* + * Replace `{{ project_id }}`, `{{ server_url }}`, and `{{ auth_token }}` in the template to create the new config object. + * Read the existing `~/.gemini/antigravity/mcp_config.json`. + * Merge the new `remote-mcp-secops` config into the existing `mcpServers` object. **Do not overwrite other servers.** + * Write the merged JSON back to `~/.gemini/antigravity/mcp_config.json`. + +## Verification + +After configuration, ask the user to verify by creating a new conversation and asking to "list 3 soar cases". diff --git a/extensions/google-secops-staging/skills/setup-antigravity/mcp_config.template.json b/extensions/google-secops-staging/skills/setup-antigravity/mcp_config.template.json new file mode 100644 index 00000000..c7074eb6 --- /dev/null +++ b/extensions/google-secops-staging/skills/setup-antigravity/mcp_config.template.json @@ -0,0 +1,75 @@ +{ + "mcpServers": { + "remote-secops-investigate": { + "serverUrl": "{{ server_url | default('https://chronicle.us.googleapis.com/mcp') }}", + "headers": { + "Content-Type": "application/json", + "x-goog-user-project": "{{ project_id }}", + "Authorization": "Bearer {{ auth_token }}" + }, + "disabled": false, + "disabledTools": [ + "list_feeds", + "get_feed", + "create_feed", + "update_feed", + "enable_feed", + "disable_feed", + "delete_feed", + "generate_feed_secret", + "list_parsers", + "get_parser", + "run_parser", + "create_parser", + "activate_parser", + "deactivate_parser", + "import_logs", + "list_log_types", + "list_data_tables", + "create_data_table", + "list_data_table_rows", + "add_rows_to_data_table", + "delete_data_table_row", + "create_reference_list", + "get_reference_list", + "update_reference_list", + "list_playbooks", + "list_playbook_instances", + "create_rule", + "validate_rule", + "list_rule_errors" + ] + }, + "remote-secops-admin": { + "serverUrl": "{{ server_url | default('https://chronicle.us.googleapis.com/mcp') }}", + "headers": { + "Content-Type": "application/json", + "x-goog-user-project": "{{ project_id }}", + "Authorization": "Bearer {{ auth_token }}" + }, + "disabled": true, + "disabledTools": [ + "list_cases", + "get_case", + "update_case", + "create_case_comment", + "list_case_comments", + "execute_bulk_close_case", + "execute_manual_action", + "list_security_alerts", + "get_security_alert", + "update_security_alert", + "list_case_alerts", + "get_case_alert", + "update_case_alert", + "search_entity", + "summarize_entity", + "get_involved_entity", + "list_involved_entities", + "list_connector_events", + "get_connector_event", + "get_ioc_match" + ] + } + } +} \ No newline at end of file diff --git a/extensions/google-secops-staging/skills/triage/SKILL.md b/extensions/google-secops-staging/skills/triage/SKILL.md new file mode 100644 index 00000000..3b291be3 --- /dev/null +++ b/extensions/google-secops-staging/skills/triage/SKILL.md @@ -0,0 +1,98 @@ +--- +name: secops-triage +description: Expert guidance for security alert triage. Use this when the user asks to "triage" an alert or case. +slash_command: /secops:triage +category: security_operations +personas: + - tier1_soc_analyst +--- + +# Security Alert Triage Specialist + +You are a Tier 1 SOC Analyst expert. When asked to triage an alert, you strictly follow the **Alert Triage Protocol**. + +## Tool Selection & Availability + +**CRITICAL**: Before executing any step, determine which tools are available in the current environment. +1. **Check Availability**: Look for Remote tools (e.g., `list_cases`, `udm_search`) first. If unavailable, use Local tools (e.g., `list_cases`, `search_security_events`). +2. **Reference Mapping**: Use `extensions/google-secops/TOOL_MAPPING.md` to find the correct tool for each capability. +3. **Adapt Workflow**: If using Remote tools for Natural Language Search, perform `translate_udm_query` then `udm_search`. If using Local tools, use `search_security_events` directly. + +## Alert Triage Protocol + +**Objective**: Standardized assessment of incoming security alerts to determine if they are False Positives (FP), Benign True Positives (BTP), or True Positives (TP) requiring investigation. + +**Inputs**: `${ALERT_ID}` or `${CASE_ID}`. + +**Workflow**: + +1. **Gather Context**: + * **Action**: Get Case Details. + * **Remote**: `get_case` (expand='tasks,tags,products') + `list_case_alerts`. + * **Local**: `get_case_full_details`. + * Identify alert type, severity, `${KEY_ENTITIES}`, and triggering events. + +2. **Check for Duplicates**: + * **Action**: List Cases with filter. + * **Tool**: `list_cases` (Remote or Local). + * **Query**: Filter by `displayName` or `tags` or description containing `${KEY_ENTITIES}`. + * **Decision**: If `${SIMILAR_CASE_IDS}` found and confirmed as duplicate: + * **Action**: Document & Close. + * **Remote**: `create_case_comment` -> `execute_bulk_close_case`. + * **Local**: `post_case_comment` -> *(Close not supported locally, advise user)*. + * **STOP**. + +3. **Find Related Cases**: + * **Action**: Search for open cases involving entities. + * **Tool**: `list_cases` (Remote or Local). + * **Filter**: `description="*ENTITY_VALUE*"` AND `status="OPENED"`. + * Store `${ENTITY_RELATED_CASES}`. + +4. **Alert-Specific SIEM Search**: + * **Action**: Search SIEM events for context (e.g., login events around alert time). + * **Remote**: `udm_search` (using UDM query) or `translate_udm_query` -> `udm_search` (for natural language). + * **Local**: `search_udm` or `search_security_events`. + * **Specific Focus**: + * *Suspicious Login*: Search login events (success/failure) for user/source IP around alert time. + * *Malware*: Search process execution, file mods, network events for the hash/endpoint. + * *Network*: Search network flows, DNS lookups for source/destination IPs/domains. + * Store `${INITIAL_SIEM_CONTEXT}`. + +5. **Enrichment**: + * For each `${KEY_ENTITY}`, **Execute Common Procedure: Enrich IOC**. + * Store findings in `${ENRICHMENT_RESULTS}`. + +6. **Assessment**: + * Analyze `${ENRICHMENT_RESULTS}`, `${ENTITY_RELATED_CASES}`, and `${INITIAL_SIEM_CONTEXT}`. + * **Classify** based on the following criteria: + + | Classification | Criteria | Action | + |---|---|---| + | **False Positive (FP)** | No malicious indicators, known benign activity. | Close | + | **Benign True Positive (BTP)** | Real detection but authorized/expected activity (e.g., admin task). | Close | + | **True Positive (TP)** | Confirmed malicious indicators or suspicious behavior. | Escalate | + | **Suspicious** | Inconclusive but warrants investigation. | Escalate | + +7. **Final Action**: + * **If FP/BTP**: + * **Action**: Document reasoning. + * **Tool**: `create_case_comment` (Remote) / `post_case_comment` (Local). + * **Action**: Close Case (Remote only). + * **Tool**: `execute_bulk_close_case` (Reason="NOT_MALICIOUS", RootCause="Legit action/Normal behavior"). + * **If TP/Suspicious**: + * **(Optional)** Update priority (`update_case` Remote / `change_case_priority` Local). + * **Action**: Document findings. + * **Escalate**: Prepare for lateral movement or specific hunt (refer to relevant Skills). + +## Common Procedures + +### Enrich IOC (SIEM Prevalence) +**Capability**: Entity Summary / IoC Match +**Steps**: +1. **SIEM Summary**: + * **Remote**: `summarize_entity`. + * **Local**: `lookup_entity`. +2. **IOC Match**: + * **Remote**: `get_ioc_match`. + * **Local**: `get_ioc_matches`. +3. Return combined `${ENRICHMENT_ABSTRACT}`. \ No newline at end of file From 4568a9c466895cf21011fa678504731cf7206de1 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Fri, 6 Feb 2026 11:31:02 -0500 Subject: [PATCH 18/20] Update google-secops extension: fix defaults, add endpoint constants --- extensions/google-secops-staging/.env.example | 4 - .../google-secops-staging/.env.secops-lab | 4 - extensions/google-secops-staging/.env.staging | 4 - extensions/google-secops-staging/GEMINI.md | 141 ------------------ .../google-secops-staging/TOOL_MAPPING.md | 36 ----- .../commands/secops/cases.toml | 1 - .../commands/secops/hunt.toml | 1 - .../commands/secops/investigate.toml | 1 - .../commands/secops/triage.toml | 1 - .../endpoint_constants.py | 0 .../gemini-extension.json | 71 --------- .../skills/cases/SKILL.md | 23 --- .../skills/hunt/SKILL.md | 88 ----------- .../skills/investigate/SKILL.md | 121 --------------- .../skills/setup-antigravity/.env.example | 3 - .../skills/setup-antigravity/SKILL.md | 51 ------- .../mcp_config.template.json | 75 ---------- .../skills/triage/SKILL.md | 98 ------------ extensions/google-secops/GEMINI.md | 20 +++ .../google-secops/endpoint_constants.py | 14 ++ .../google-secops/gemini-extension.json | 2 +- .../rewrite_json_w_env.py | 0 22 files changed, 35 insertions(+), 724 deletions(-) delete mode 100644 extensions/google-secops-staging/.env.example delete mode 100644 extensions/google-secops-staging/.env.secops-lab delete mode 100644 extensions/google-secops-staging/.env.staging delete mode 100644 extensions/google-secops-staging/GEMINI.md delete mode 100644 extensions/google-secops-staging/TOOL_MAPPING.md delete mode 100644 extensions/google-secops-staging/commands/secops/cases.toml delete mode 100644 extensions/google-secops-staging/commands/secops/hunt.toml delete mode 100644 extensions/google-secops-staging/commands/secops/investigate.toml delete mode 100644 extensions/google-secops-staging/commands/secops/triage.toml delete mode 100644 extensions/google-secops-staging/endpoint_constants.py delete mode 100644 extensions/google-secops-staging/gemini-extension.json delete mode 100644 extensions/google-secops-staging/skills/cases/SKILL.md delete mode 100644 extensions/google-secops-staging/skills/hunt/SKILL.md delete mode 100644 extensions/google-secops-staging/skills/investigate/SKILL.md delete mode 100644 extensions/google-secops-staging/skills/setup-antigravity/.env.example delete mode 100644 extensions/google-secops-staging/skills/setup-antigravity/SKILL.md delete mode 100644 extensions/google-secops-staging/skills/setup-antigravity/mcp_config.template.json delete mode 100644 extensions/google-secops-staging/skills/triage/SKILL.md create mode 100644 extensions/google-secops/endpoint_constants.py rename extensions/{google-secops-staging => google-secops}/rewrite_json_w_env.py (100%) diff --git a/extensions/google-secops-staging/.env.example b/extensions/google-secops-staging/.env.example deleted file mode 100644 index 81c4c3e9..00000000 --- a/extensions/google-secops-staging/.env.example +++ /dev/null @@ -1,4 +0,0 @@ -PROJECT_ID=your-project-id-string -CUSTOMER_ID=12345678-abcd-4321-8765-1234567890ab -REGION=us -SERVER_URL=https://chronicle.us.rep.googleapis.com/mcp diff --git a/extensions/google-secops-staging/.env.secops-lab b/extensions/google-secops-staging/.env.secops-lab deleted file mode 100644 index f3cb4aef..00000000 --- a/extensions/google-secops-staging/.env.secops-lab +++ /dev/null @@ -1,4 +0,0 @@ -PROJECT_ID=secops-demo-env -CUSTOMER_ID=a13f6726-efed-452e-9008-8fe0d3cb0f75 -REGION=us -SERVER_URL=https://chronicle.us.rep.googleapis.com/mcp diff --git a/extensions/google-secops-staging/.env.staging b/extensions/google-secops-staging/.env.staging deleted file mode 100644 index ed6fe539..00000000 --- a/extensions/google-secops-staging/.env.staging +++ /dev/null @@ -1,4 +0,0 @@ -PROJECT_ID=secops-ai-staging -CUSTOMER_ID=eb3b937b-3ab6-47e5-8185-24837b826691 -REGION=us -SERVER_URL=https://staging-chronicle.sandbox.googleapis.com/mcp diff --git a/extensions/google-secops-staging/GEMINI.md b/extensions/google-secops-staging/GEMINI.md deleted file mode 100644 index dd4ede80..00000000 --- a/extensions/google-secops-staging/GEMINI.md +++ /dev/null @@ -1,141 +0,0 @@ -# Google SecOps Extension - -This folder contains the **Google SecOps Extension**, providing specialized skills for security operations. - -## Overview - -The extension `extensions/google-secops-staging` 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 `: Quickly start triaging an alert. -* `/secops:investigate `: Start an investigation. -* `/secops:hunt `: 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. - -## 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) diff --git a/extensions/google-secops-staging/TOOL_MAPPING.md b/extensions/google-secops-staging/TOOL_MAPPING.md deleted file mode 100644 index 6158e6e3..00000000 --- a/extensions/google-secops-staging/TOOL_MAPPING.md +++ /dev/null @@ -1,36 +0,0 @@ -# Tool Mapping: Local vs. Remote - -This document maps the tools defined in the local MCP server implementation (`server/secops` and `server/secops-soar`) to the tools available in the remote Google SecOps MCP server. - -**Configuration & Selection Strategy:** -When executing a skill, the agent should first check which tools are available in the current environment. -1. **Prioritize Remote Tools**: If a remote tool is available, use it. -2. **Fallback to Local Tools**: If the remote tool is unavailable, use the corresponding local tool. -3. **Adapt Workflow**: Some operations (like Natural Language Search) require a multi-step workflow in Remote (Translate -> Search) but a single step in Local. - -| Category | Capability | Remote Tool (MCP Server) | Local Tool (Python) | Notes | -| :--- | :--- | :--- | :--- | :--- | -| **Case Management** | List Cases | `list_cases` | `list_cases` | | -| | Get Case Details | `get_case` | `get_case_full_details` | Local `get_case_full_details` aggregates alerts/comments. Remote `get_case` fetches the case object; use `expand='tasks,tags,products'` or call `list_case_alerts`/`list_case_comments` for full context. | -| | Comment on Case | `create_case_comment` | `post_case_comment` | | -| | Update Case | `update_case` | `change_case_priority` | Remote tool is general (priority, status, assignee). Local tool is specific to priority. | -| | Close Case | `execute_bulk_close_case` | *(No local tool)* | Only remote tool can close cases. | -| **Alerts (SOAR)** | List Alerts for Case | `list_case_alerts` | `list_alerts_by_case` | | -| | List Events for Alert | `list_connector_events` | `list_events_by_alert` | Remote tool lists "connector events". | -| | List Alert Groups | *(No direct equivalent)* | `list_alert_group_identifiers_by_case` | Remote `list_case_alerts` returns alert objects which may contain grouping info. | -| **Entities (SOAR)** | Search Entities | `search_entity` | `search_entity` | | -| | Get Involved Entities | `list_involved_entities` | `get_entities_by_alert_group_identifiers` | Remote tool lists involved entities for a specific case alert. | -| | Get Entity Details | *(No direct equivalent)* | `get_entity_details` | | -| **SIEM / UDM** | UDM Search (Query) | `udm_search` | `search_udm` | | -| | UDM Search (Nat. Lang.) | `translate_udm_query` -> `udm_search` | `search_security_events` | **Critical:** Remote requires 2 steps (Translate then Search). Local does both in one call. | -| | Entity Summary | `summarize_entity` | `lookup_entity` | Both provide a summary of entity activity in SIEM. | -| | IoC Matching | `get_ioc_match` | `get_ioc_matches` | | -| | Export Results | *(No direct equivalent)* | `export_udm_search_csv` | | -| **Alerts (SIEM)** | List SIEM Alerts | `list_security_alerts` | `list_security_alerts` | Lists alerts directly from SIEM (not SOAR cases). | -| | Get SIEM Alert | `get_security_alert` | `get_security_alert` | | -| | Update SIEM Alert | `update_security_alert` | `update_security_alert` | | -| **Rules** | List Rules | `list_rules` | `list_rules` | | -| | Get Rule | `get_rule` | `get_rule` | | -| | Create Rule | `create_rule` | `create_rule` | | -| | Validate Rule | `validate_rule` | `validate_rule` | | -| | Test/Run Rule | `list_rule_detections` | `list_rule_detections` | Use to see historical detections. | \ No newline at end of file diff --git a/extensions/google-secops-staging/commands/secops/cases.toml b/extensions/google-secops-staging/commands/secops/cases.toml deleted file mode 100644 index 44e47b1f..00000000 --- a/extensions/google-secops-staging/commands/secops/cases.toml +++ /dev/null @@ -1 +0,0 @@ -prompt = """Run the secops-cases skill.""" diff --git a/extensions/google-secops-staging/commands/secops/hunt.toml b/extensions/google-secops-staging/commands/secops/hunt.toml deleted file mode 100644 index 6cbd0f97..00000000 --- a/extensions/google-secops-staging/commands/secops/hunt.toml +++ /dev/null @@ -1 +0,0 @@ -prompt = """Run the secops-hunt skill for `{{args}}`.""" diff --git a/extensions/google-secops-staging/commands/secops/investigate.toml b/extensions/google-secops-staging/commands/secops/investigate.toml deleted file mode 100644 index 981015f3..00000000 --- a/extensions/google-secops-staging/commands/secops/investigate.toml +++ /dev/null @@ -1 +0,0 @@ -prompt = """Run the secops-investigate skill on case `{{args}}`.""" diff --git a/extensions/google-secops-staging/commands/secops/triage.toml b/extensions/google-secops-staging/commands/secops/triage.toml deleted file mode 100644 index 49327458..00000000 --- a/extensions/google-secops-staging/commands/secops/triage.toml +++ /dev/null @@ -1 +0,0 @@ -prompt = """Run the secops-triage skill on alert `{{args}}`.""" diff --git a/extensions/google-secops-staging/endpoint_constants.py b/extensions/google-secops-staging/endpoint_constants.py deleted file mode 100644 index e69de29b..00000000 diff --git a/extensions/google-secops-staging/gemini-extension.json b/extensions/google-secops-staging/gemini-extension.json deleted file mode 100644 index b96382b2..00000000 --- a/extensions/google-secops-staging/gemini-extension.json +++ /dev/null @@ -1,71 +0,0 @@ -{ - "name": "google-secops", - "contextFileName": "GEMINI.md", - "description": "Essential Security Operations skills for Triage, Investigation, and Hunting.", - "version": "1.0.0", - "skills": [ - "skills/setup-antigravity", - "skills/triage", - "skills/investigate", - "skills/hunt", - "skills/cases" - ], - "settings": [ - { - "name": "PROJECT_ID", - "defaultValue": "secops-ai-staging", - "description": "Your Google Cloud Project ID (from /settings/profile).", - "envVar": "PROJECT_ID", - "sensitive": false - }, - { - "name": "CUSTOMER_ID", - "defaultValue": "eb3b937b-3ab6-47e5-8185-24837b826691", - "description": "Your Chronicle Customer UUID (from /settings/profile).", - "envVar": "CUSTOMER_ID", - "sensitive": false - }, - { - "name": "REGION", - "defaultValue": "us", - "description": "Your Chronicle Region (e.g. 'us', 'europe-west1').", - "envVar": "REGION", - "sensitive": false - }, - { - "name": "SERVER_URL", - "defaultValue": "https://staging-chronicle.sandbox.googleapis.com/mcp", - "description": "The URL of the remote MCP server See https://docs.cloud.google.com/chronicle/docs/secops/use-google-secops-mcp.", - "envVar": "SERVER_URL", - "sensitive": false - } - ], - "mcpServers": { - "remote-mcp-secops": { - "httpUrl": "${SERVER_URL}", - "authProviderType": "google_credentials", - "oauth": { - "scopes": [ - "https://www.googleapis.com/auth/cloud-platform" - ] - }, - "headers": { - "x-goog-user-project": "${PROJECT_ID}" - }, - "env": { - "PROJECT_ID": "${PROJECT_ID}", - "CUSTOMER_ID": "${CUSTOMER_ID}", - "REGION": "${REGION}" - }, - "disabledTools": [ - "list_log_types", - "list_parsers", - "list_integrations", - "list_integration_actions", - "execute_manual_action", - "create_reference_list", - "get_reference_list" - ] - } - } -} diff --git a/extensions/google-secops-staging/skills/cases/SKILL.md b/extensions/google-secops-staging/skills/cases/SKILL.md deleted file mode 100644 index ef44a3cb..00000000 --- a/extensions/google-secops-staging/skills/cases/SKILL.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -name: secops-cases -description: List recent SOAR cases. Use this for "list cases" or "show cases". -slash_command: /secops:cases -category: security_operations -personas: - - tier1_soc_analyst ---- - -# Security Cases Specialist - -You are a specialist in retrieving SOAR case information. - -## Tool Selection - -1. **Check Availability**: Prefer `list_cases` (Remote). -2. **Fallback**: Use `list_cases` from Local tools if Remote is unavailable. - -## Workflow - -1. **List Cases**: - * Call `list_cases` to retrieve the most recent cases. - * Display them in a table with ID, Title, Priority, and Status. diff --git a/extensions/google-secops-staging/skills/hunt/SKILL.md b/extensions/google-secops-staging/skills/hunt/SKILL.md deleted file mode 100644 index 33112afd..00000000 --- a/extensions/google-secops-staging/skills/hunt/SKILL.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -name: secops-hunt -description: Expert guidance for proactive threat hunting. Use this when the user asks to "hunt" for threads, IOCs, or specific TTPs. -slash_command: /secops:hunt -category: security_operations -personas: - - threat_hunter ---- - -# Threat Hunter - -You are an expert Threat Hunter. Your goal is to proactively identify undetected threats in the environment. - -## Tool Selection & Availability - -**CRITICAL**: Before executing any step, determine which tools are available in the current environment. -1. **Check Availability**: Look for Remote tools (e.g., `udm_search`, `get_ioc_match`) first. If unavailable, use Local tools (e.g., `search_security_events`, `get_ioc_matches`). -2. **Reference Mapping**: Use `extensions/google-secops/TOOL_MAPPING.md` to find the correct tool for each capability. -3. **Adapt Workflow**: If using Remote tools for Natural Language Search, perform `translate_udm_query` then `udm_search`. If using Local tools, use `search_security_events` directly. - -## Procedures - -Select the most appropriate procedure from the options below. - -### Proactive Threat Hunting based on GTI Campaign/Actor - -**Objective**: Given a GTI Campaign or Threat Actor Collection ID (`${GTI_COLLECTION_ID}`), proactively search the local environment (SIEM) for related IOCs and TTPs. - -**Workflow**: - -1. **Analyst Input**: Hunt for Campaign/Actor: `${GTI_COLLECTION_ID}` -2. **IOC Gathering**: Ask user for list of IOCs (files, domains, ips, urls) associated with the campaign/actor. -3. **Initial Scan**: - * **Action**: Check for recent hits against these indicators. - * **Remote**: `get_ioc_match`. - * **Local**: `get_ioc_matches`. -4. **Phase 1 Lookup (Iterative SIEM Search)**: - * For each prioritized IOC, construct and execute the appropriate UDM query: - * **IP**: `principal.ip = "IOC" OR target.ip = "IOC" OR network.ip = "IOC"` - * **Domain**: `principal.hostname = "IOC" OR target.hostname = "IOC" OR network.dns.questions.name = "IOC"` - * **Hash**: `target.file.sha256 = "IOC" OR target.file.md5 = "IOC" OR target.file.sha1 = "IOC"` - * **URL**: `target.url = "IOC"` - * **Tool**: `udm_search` (Remote/Local). -5. **Phase 2 Deep Investigation (Confirmed IOCs)**: - * **Action**: Search SIEM events for confirmed IOCs to understand context (e.g. process execution, network connections). - * **Action**: Check for related cases (`list_cases`). -6. **Synthesis**: Synthesize all findings. -7. **Output**: Ask user to Create Case, Update Case, or Generate Report. - * If **Report**: Generate a markdown report file using `write_file`. - * If **Case**: Post a comment to SOAR. - -### Guided TTP Hunt (Example: Credential Access) - -**Objective**: Proactively hunt for evidence of specific MITRE ATT&CK Credential Access techniques (e.g., OS Credential Dumping T1003, Credentials from Password Stores T1555). - -**Inputs**: -* `${TECHNIQUE_IDS}`: List of MITRE IDs (e.g., "T1003.001"). -* `${TIME_FRAME_HOURS}`: Lookback (default 72). -* `${TARGET_SCOPE_QUERY}`: Optional scope filter. - -**Workflow**: - -1. **Research**: Review MITRE ATT&CK techniques or ask user for TTP details. -2. **Hunt Loop**: - * **Develop Queries**: Formulate UDM queries for `udm_search` (e.g., specific process names, command lines). - * **Execute**: Run the searches using `udm_search`. - * **Analyze**: Review for anomalies. Does this match the hypothesis? Is it noise? - * **Refine**: If too noisy, add filters. If no results, broaden query. - * **Repeat**: Iterate until exhausted or leads found. -3. **Enrich**: Lookup suspicious entities found during the loop. - * **Remote**: `summarize_entity`. - * **Local**: `lookup_entity`. -4. **Document**: Post findings to a SOAR case or create a report. -5. **Escalate**: Identify if a new incident needs to be raised. - -## Common Procedures - -### Find Relevant SOAR Case - -**Objective**: Identify existing SOAR cases that are potentially relevant to the current investigation based on specific indicators. - -**Inputs**: -* `${SEARCH_TERMS}`: List of values to search (IOCs, etc.). - -**Steps**: -1. **Search**: Use `list_cases` with a filter for the search terms. -2. **Refine**: Optionally use `get_case` (Remote) or `get_case_full_details` (Local) to verify relevance. -3. **Output**: Return list of relevant `${RELEVANT_CASE_IDS}`. \ No newline at end of file diff --git a/extensions/google-secops-staging/skills/investigate/SKILL.md b/extensions/google-secops-staging/skills/investigate/SKILL.md deleted file mode 100644 index 6c22f67a..00000000 --- a/extensions/google-secops-staging/skills/investigate/SKILL.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -name: secops-investigate -description: Expert guidance for deep security investigations. Use this when the user asks to "investigate" a case, entity, or incident. -slash_command: /secops:investigate -category: security_operations -personas: - - incident_responder - - tier2_soc_analyst ---- - -# Security Investigator - -You are a Tier 2/3 SOC Analyst and Incident Responder. Your goal is to investigate security incidents thoroughly. - -## Tool Selection & Availability - -**CRITICAL**: Before executing any step, determine which tools are available in the current environment. -1. **Check Availability**: Look for Remote tools (e.g., `list_cases`, `udm_search`) first. If unavailable, use Local tools (e.g., `list_cases`, `search_security_events`). -2. **Reference Mapping**: Use `extensions/google-secops/TOOL_MAPPING.md` to find the correct tool for each capability. -3. **Adapt Workflow**: If using Remote tools for Natural Language Search, perform `translate_udm_query` then `udm_search`. If using Local tools, use `search_security_events` directly. - -## Procedures - -Select the procedure best suited for the investigation type. - -### Malware Investigation (Triage) -**Objective**: Analyze a suspected malicious file hash to determine nature and impact. -**Inputs**: `${FILE_HASH}`, `${CASE_ID}`. -**Steps**: -1. **Context**: - * **Remote**: `get_case` + `list_case_alerts`. - * **Local**: `get_case_full_details`. -2. **SIEM Prevalence**: - * **Remote**: `summarize_entity` (hash). - * **Local**: `lookup_entity` (hash). -3. **SIEM Execution Check**: - * **Action**: Search for `PROCESS_LAUNCH` or `FILE_CREATION` events involving the hash. - * **Query**: `target.file.sha256 = "FILE_HASH" OR target.file.md5 = "FILE_HASH"` - * **Remote**: `udm_search` (using UDM query). - * **Local**: `search_udm` (using UDM query). - * Identify `${AFFECTED_HOSTS}`. -4. **SIEM Network Check**: - * **Action**: Search for network activity from affected hosts around execution time. - * **Query**: `principal.process.file.sha256 = "FILE_HASH"` - * **Remote**: `udm_search`. - * **Local**: `search_udm`. - * Identify `${NETWORK_IOCS}`. -5. **Enrichment**: **Execute Common Procedure: Enrich IOC** for network IOCs. -6. **Related Cases**: **Execute Common Procedure: Find Relevant SOAR Case** using hosts/users/IOCs. -7. **Synthesize**: Assess severity using the matrix below. - - **Severity Assessment Matrix:** - | Factor | Low | Medium | High | Critical | - |---|---|---|---|---| - | **Execution** | Not executed | Downloaded only | Executed | Active C2/Spread | - | **Spread** | Single host | 2-5 hosts | 5-20 hosts | > 20 hosts | - | **Network IOCs** | None observed | Benign | Suspicious | Known Malicious | - | **Data at Risk** | None | Low value | PII/Creds | Critical Systems | - -8. **Document**: **Execute Common Procedure: Document in SOAR**. -9. **Report**: Optionally **Execute Common Procedure: Generate Report File**. - -### Lateral Movement Investigation (PsExec/WMI) -**Objective**: Investigate signs of lateral movement (PsExec, WMI abuse). -**Inputs**: `${TIME_FRAME_HOURS}`, `${TARGET_SCOPE}`. -**Steps**: -1. **Technique Research**: Review MITRE ATT&CK techniques T1021.002 (SMB/Windows Admin Shares) and T1047 (WMI). -2. **SIEM Queries**: - * **PsExec Service Installation**: - * `metadata.product_event_type = "ServiceInstalled" AND target.process.file.full_path CONTAINS "PSEXESVC.exe"` - * **PsExec Execution**: - * `target.process.file.full_path CONTAINS "PSEXESVC.exe"` - * **WMI Process Creation**: - * `metadata.event_type = "PROCESS_LAUNCH" AND principal.process.file.full_path = "C:\\Windows\\System32\\wbem\\WmiPrvSE.exe" AND target.process.file.full_path IN ("cmd.exe", "powershell.exe")` - * **WMI Remote Execution**: - * `principal.process.command_line CONTAINS "wmic" AND principal.process.command_line CONTAINS "/node:" AND principal.process.command_line CONTAINS "process call create"` -3. **Execute**: - * **Remote**: `udm_search`. - * **Local**: `search_udm`. -4. **Correlate**: Check for network connections (SMB port 445) matching process times. -5. **Enrich**: **Execute Common Procedure: Enrich IOC** for involved IPs/Hosts. -6. **Document**: **Execute Common Procedure: Document in SOAR**. - -### Create Investigation Report -**Objective**: Consolidate findings into a formal report. -**Inputs**: `${CASE_ID}`. -**Steps**: -1. **Gather Context**: - * **Remote**: `get_case` + `list_case_comments`. - * **Local**: `get_case_full_details`. - * Identify key entities. -2. **Synthesize**: Combine findings from SIEM, IOC matches, and case history. -3. **Structure**: Create Markdown content (Executive Summary, Timeline, Findings, Recommendations). -4. **Diagram**: Generate a Mermaid sequence diagram of the investigation. -5. **Redaction**: **CRITICAL**: Confirm no sensitive PII/Secrets in report. -6. **Generate File**: **Execute Common Procedure: Generate Report File**. -7. **Document**: **Execute Common Procedure: Document in SOAR** with status and report location. - -## Common Procedures - -### Enrich IOC (SIEM Prevalence) -**Steps**: -1. **SIEM Summary**: `summarize_entity` (Remote) or `lookup_entity` (Local). -2. **IOC Match**: `get_ioc_match` (Remote) or `get_ioc_matches` (Local). -3. Return combined findings. - -### Find Relevant SOAR Case -**Steps**: -1. **Search**: `list_cases` with filters for entity values. -2. Return list of `${RELEVANT_CASE_IDS}`. - -### Document in SOAR -**Steps**: -1. **Post**: `create_case_comment` (Remote) or `post_case_comment` (Local). - -### Generate Report File -**Tool**: `write_file` (Agent Capability) -**Steps**: -1. Construct filename: `reports/${REPORT_TYPE}_${SUFFIX}_${TIMESTAMP}.md`. -2. Write content to file using `write_file`. -3. Return path. \ No newline at end of file diff --git a/extensions/google-secops-staging/skills/setup-antigravity/.env.example b/extensions/google-secops-staging/skills/setup-antigravity/.env.example deleted file mode 100644 index aa95328a..00000000 --- a/extensions/google-secops-staging/skills/setup-antigravity/.env.example +++ /dev/null @@ -1,3 +0,0 @@ -PROJECT_ID=your-project-id -# Optional: Override the server URL -# SERVER_URL=https://chronicle.googleapis.com/mcp diff --git a/extensions/google-secops-staging/skills/setup-antigravity/SKILL.md b/extensions/google-secops-staging/skills/setup-antigravity/SKILL.md deleted file mode 100644 index 3c846f55..00000000 --- a/extensions/google-secops-staging/skills/setup-antigravity/SKILL.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -name: secops-setup-antigravity -description: Helps the user configure the Google SecOps Remote MCP Server for Antigravity. Use this when the user asks to "set up" or "configure" the security tools for Antigravity. -slash_command: /security:setup-antigravity -category: configuration -personas: - - security_engineer ---- - -# Google SecOps Setup Assistant (Antigravity) - -You are an expert in configuring the Google SecOps Remote MCP Server for Antigravity. - -## Prerequisite Checks - -1. **Check Google Cloud Auth**: - * The user must be authenticated with Google Cloud. - * Ask: "Have you run `gcloud auth application-default login`?" - * If not, instruct: - ```bash - gcloud auth application-default login - gcloud auth application-default set-quota-project - ``` - -2. **Gather Configuration**: - * Collect: - * `PROJECT_ID` (Google Cloud Project ID) - * `CUSTOMER_ID` (Chronicle Customer UUID) - * `REGION` (Chronicle Region, e.g., `us`, `europe-west1`) - -## Configuration Steps - -Guide the user to update their Antigravity configuration at `~/.gemini/antigravity/mcp_config.json` using the provided template. - -1. **Read Template**: Read the `mcp_config.template.json` file located in the same directory as this skill. -3. **Prepare Variables**: - * **Option A (Recommended)**: reading from `.env`. - * Ask the user to create a `.env` file in this directory based on `.env.example`. - * Read the `PROJECT_ID` and optional `SERVER_URL` from `.env`. - * **Option B (Manual)**: Ask the user directly for their `PROJECT_ID`. -4. **Generate and Merge Config**: - * Read `mcp_config.template.json`. - * Generate `auth_token` using: `$(gcloud auth print-access-token)`. *Note: Warn the user that this token is temporary.* - * Replace `{{ project_id }}`, `{{ server_url }}`, and `{{ auth_token }}` in the template to create the new config object. - * Read the existing `~/.gemini/antigravity/mcp_config.json`. - * Merge the new `remote-mcp-secops` config into the existing `mcpServers` object. **Do not overwrite other servers.** - * Write the merged JSON back to `~/.gemini/antigravity/mcp_config.json`. - -## Verification - -After configuration, ask the user to verify by creating a new conversation and asking to "list 3 soar cases". diff --git a/extensions/google-secops-staging/skills/setup-antigravity/mcp_config.template.json b/extensions/google-secops-staging/skills/setup-antigravity/mcp_config.template.json deleted file mode 100644 index c7074eb6..00000000 --- a/extensions/google-secops-staging/skills/setup-antigravity/mcp_config.template.json +++ /dev/null @@ -1,75 +0,0 @@ -{ - "mcpServers": { - "remote-secops-investigate": { - "serverUrl": "{{ server_url | default('https://chronicle.us.googleapis.com/mcp') }}", - "headers": { - "Content-Type": "application/json", - "x-goog-user-project": "{{ project_id }}", - "Authorization": "Bearer {{ auth_token }}" - }, - "disabled": false, - "disabledTools": [ - "list_feeds", - "get_feed", - "create_feed", - "update_feed", - "enable_feed", - "disable_feed", - "delete_feed", - "generate_feed_secret", - "list_parsers", - "get_parser", - "run_parser", - "create_parser", - "activate_parser", - "deactivate_parser", - "import_logs", - "list_log_types", - "list_data_tables", - "create_data_table", - "list_data_table_rows", - "add_rows_to_data_table", - "delete_data_table_row", - "create_reference_list", - "get_reference_list", - "update_reference_list", - "list_playbooks", - "list_playbook_instances", - "create_rule", - "validate_rule", - "list_rule_errors" - ] - }, - "remote-secops-admin": { - "serverUrl": "{{ server_url | default('https://chronicle.us.googleapis.com/mcp') }}", - "headers": { - "Content-Type": "application/json", - "x-goog-user-project": "{{ project_id }}", - "Authorization": "Bearer {{ auth_token }}" - }, - "disabled": true, - "disabledTools": [ - "list_cases", - "get_case", - "update_case", - "create_case_comment", - "list_case_comments", - "execute_bulk_close_case", - "execute_manual_action", - "list_security_alerts", - "get_security_alert", - "update_security_alert", - "list_case_alerts", - "get_case_alert", - "update_case_alert", - "search_entity", - "summarize_entity", - "get_involved_entity", - "list_involved_entities", - "list_connector_events", - "get_connector_event", - "get_ioc_match" - ] - } - } -} \ No newline at end of file diff --git a/extensions/google-secops-staging/skills/triage/SKILL.md b/extensions/google-secops-staging/skills/triage/SKILL.md deleted file mode 100644 index 3b291be3..00000000 --- a/extensions/google-secops-staging/skills/triage/SKILL.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -name: secops-triage -description: Expert guidance for security alert triage. Use this when the user asks to "triage" an alert or case. -slash_command: /secops:triage -category: security_operations -personas: - - tier1_soc_analyst ---- - -# Security Alert Triage Specialist - -You are a Tier 1 SOC Analyst expert. When asked to triage an alert, you strictly follow the **Alert Triage Protocol**. - -## Tool Selection & Availability - -**CRITICAL**: Before executing any step, determine which tools are available in the current environment. -1. **Check Availability**: Look for Remote tools (e.g., `list_cases`, `udm_search`) first. If unavailable, use Local tools (e.g., `list_cases`, `search_security_events`). -2. **Reference Mapping**: Use `extensions/google-secops/TOOL_MAPPING.md` to find the correct tool for each capability. -3. **Adapt Workflow**: If using Remote tools for Natural Language Search, perform `translate_udm_query` then `udm_search`. If using Local tools, use `search_security_events` directly. - -## Alert Triage Protocol - -**Objective**: Standardized assessment of incoming security alerts to determine if they are False Positives (FP), Benign True Positives (BTP), or True Positives (TP) requiring investigation. - -**Inputs**: `${ALERT_ID}` or `${CASE_ID}`. - -**Workflow**: - -1. **Gather Context**: - * **Action**: Get Case Details. - * **Remote**: `get_case` (expand='tasks,tags,products') + `list_case_alerts`. - * **Local**: `get_case_full_details`. - * Identify alert type, severity, `${KEY_ENTITIES}`, and triggering events. - -2. **Check for Duplicates**: - * **Action**: List Cases with filter. - * **Tool**: `list_cases` (Remote or Local). - * **Query**: Filter by `displayName` or `tags` or description containing `${KEY_ENTITIES}`. - * **Decision**: If `${SIMILAR_CASE_IDS}` found and confirmed as duplicate: - * **Action**: Document & Close. - * **Remote**: `create_case_comment` -> `execute_bulk_close_case`. - * **Local**: `post_case_comment` -> *(Close not supported locally, advise user)*. - * **STOP**. - -3. **Find Related Cases**: - * **Action**: Search for open cases involving entities. - * **Tool**: `list_cases` (Remote or Local). - * **Filter**: `description="*ENTITY_VALUE*"` AND `status="OPENED"`. - * Store `${ENTITY_RELATED_CASES}`. - -4. **Alert-Specific SIEM Search**: - * **Action**: Search SIEM events for context (e.g., login events around alert time). - * **Remote**: `udm_search` (using UDM query) or `translate_udm_query` -> `udm_search` (for natural language). - * **Local**: `search_udm` or `search_security_events`. - * **Specific Focus**: - * *Suspicious Login*: Search login events (success/failure) for user/source IP around alert time. - * *Malware*: Search process execution, file mods, network events for the hash/endpoint. - * *Network*: Search network flows, DNS lookups for source/destination IPs/domains. - * Store `${INITIAL_SIEM_CONTEXT}`. - -5. **Enrichment**: - * For each `${KEY_ENTITY}`, **Execute Common Procedure: Enrich IOC**. - * Store findings in `${ENRICHMENT_RESULTS}`. - -6. **Assessment**: - * Analyze `${ENRICHMENT_RESULTS}`, `${ENTITY_RELATED_CASES}`, and `${INITIAL_SIEM_CONTEXT}`. - * **Classify** based on the following criteria: - - | Classification | Criteria | Action | - |---|---|---| - | **False Positive (FP)** | No malicious indicators, known benign activity. | Close | - | **Benign True Positive (BTP)** | Real detection but authorized/expected activity (e.g., admin task). | Close | - | **True Positive (TP)** | Confirmed malicious indicators or suspicious behavior. | Escalate | - | **Suspicious** | Inconclusive but warrants investigation. | Escalate | - -7. **Final Action**: - * **If FP/BTP**: - * **Action**: Document reasoning. - * **Tool**: `create_case_comment` (Remote) / `post_case_comment` (Local). - * **Action**: Close Case (Remote only). - * **Tool**: `execute_bulk_close_case` (Reason="NOT_MALICIOUS", RootCause="Legit action/Normal behavior"). - * **If TP/Suspicious**: - * **(Optional)** Update priority (`update_case` Remote / `change_case_priority` Local). - * **Action**: Document findings. - * **Escalate**: Prepare for lateral movement or specific hunt (refer to relevant Skills). - -## Common Procedures - -### Enrich IOC (SIEM Prevalence) -**Capability**: Entity Summary / IoC Match -**Steps**: -1. **SIEM Summary**: - * **Remote**: `summarize_entity`. - * **Local**: `lookup_entity`. -2. **IOC Match**: - * **Remote**: `get_ioc_match`. - * **Local**: `get_ioc_matches`. -3. Return combined `${ENRICHMENT_ABSTRACT}`. \ No newline at end of file diff --git a/extensions/google-secops/GEMINI.md b/extensions/google-secops/GEMINI.md index 39e0dd00..b8462338 100644 --- a/extensions/google-secops/GEMINI.md +++ b/extensions/google-secops/GEMINI.md @@ -134,8 +134,28 @@ These skills are designed to be compatible with **Claude Code** and other AI age ## 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) \ No newline at end of file diff --git a/extensions/google-secops/endpoint_constants.py b/extensions/google-secops/endpoint_constants.py new file mode 100644 index 00000000..95c0b502 --- /dev/null +++ b/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", +] \ No newline at end of file diff --git a/extensions/google-secops/gemini-extension.json b/extensions/google-secops/gemini-extension.json index d1428af3..5f77f4d2 100644 --- a/extensions/google-secops/gemini-extension.json +++ b/extensions/google-secops/gemini-extension.json @@ -68,4 +68,4 @@ ] } } -} \ No newline at end of file +} diff --git a/extensions/google-secops-staging/rewrite_json_w_env.py b/extensions/google-secops/rewrite_json_w_env.py similarity index 100% rename from extensions/google-secops-staging/rewrite_json_w_env.py rename to extensions/google-secops/rewrite_json_w_env.py From 9f3382bed6c532ea6df4ce6ceb51b3f4e633f13d Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Fri, 6 Feb 2026 11:36:56 -0500 Subject: [PATCH 19/20] Debug release zip: add unzip -l to verify content --- .github/workflows/release-google-secops.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/release-google-secops.yml b/.github/workflows/release-google-secops.yml index c841b4c5..c61bb2b2 100644 --- a/.github/workflows/release-google-secops.yml +++ b/.github/workflows/release-google-secops.yml @@ -17,6 +17,8 @@ jobs: 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 From 9d9610eb23f32e1c81cc5ecf5e7478f53531a3a5 Mon Sep 17 00:00:00 2001 From: Dan Dye Date: Fri, 6 Feb 2026 11:37:12 -0500 Subject: [PATCH 20/20] Include sample env files for release --- extensions/google-secops/.env.example | 4 ++++ extensions/google-secops/.env.secops-lab | 4 ++++ extensions/google-secops/.env.staging | 4 ++++ 3 files changed, 12 insertions(+) create mode 100644 extensions/google-secops/.env.example create mode 100644 extensions/google-secops/.env.secops-lab create mode 100644 extensions/google-secops/.env.staging diff --git a/extensions/google-secops/.env.example b/extensions/google-secops/.env.example new file mode 100644 index 00000000..81c4c3e9 --- /dev/null +++ b/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 diff --git a/extensions/google-secops/.env.secops-lab b/extensions/google-secops/.env.secops-lab new file mode 100644 index 00000000..f3cb4aef --- /dev/null +++ b/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 diff --git a/extensions/google-secops/.env.staging b/extensions/google-secops/.env.staging new file mode 100644 index 00000000..ed6fe539 --- /dev/null +++ b/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