|
| 1 | +# Google SecOps Extension |
| 2 | + |
| 3 | +This folder contains the **Google SecOps Extension**, providing specialized skills for security operations. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The extension `extensions/google-secops-staging` packages setup and key security workflows into [skills](https://agentskills.io/specification). |
| 8 | + |
| 9 | +These skills are **Adaptive**, designed to work seamlessly with: |
| 10 | + * [Google SecOps Remote MCP Server](https://google.github.io/mcp-security/docs/remote_server.html) (Preferred) |
| 11 | + * **Local Python Tools** (Fallback) |
| 12 | + |
| 13 | +This allows the skills to function in diverse environments, automatically selecting the best available tool for the job. |
| 14 | + |
| 15 | +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. |
| 16 | + |
| 17 | + |
| 18 | +## Prerequisites |
| 19 | + |
| 20 | +1. **Install Gemini CLI (Preview)**: |
| 21 | + ```bash |
| 22 | + npm install -g @google/gemini-cli@preview |
| 23 | + ``` |
| 24 | + |
| 25 | + |
| 26 | +2. **GUI Login Requirement**: You MUST have logged into the Google SecOps GUI at least once before using the API/MCP server. |
| 27 | + |
| 28 | +3. **Enable Skills**: Ensure your `~/.gemini/settings.json` has `experimental.skills` enabled: |
| 29 | + ```json |
| 30 | + { |
| 31 | + "security": { |
| 32 | + "auth": { |
| 33 | + "selectedType": "gemini-api-key" |
| 34 | + } |
| 35 | + }, |
| 36 | + "general": { |
| 37 | + "previewFeatures": true |
| 38 | + }, |
| 39 | + "experimental": { |
| 40 | + "skills": true, |
| 41 | + "extensionConfig": true |
| 42 | + } |
| 43 | + } |
| 44 | + ``` |
| 45 | + |
| 46 | +Verify skills are enabled from the Gemini CLI prompt: |
| 47 | +``` |
| 48 | +/skills list |
| 49 | +``` |
| 50 | +
|
| 51 | +## Installation |
| 52 | +
|
| 53 | +To install this extension in your Gemini CLI environment: |
| 54 | +
|
| 55 | +1. **Navigate** to the project root. |
| 56 | +2. **Run**: |
| 57 | + ```bash |
| 58 | + gemini extensions install ./extensions/google-secops |
| 59 | + ``` |
| 60 | +
|
| 61 | +You will be prompted for environment variables for the MCP configuration: |
| 62 | +
|
| 63 | +1. `PROJECT_ID` (GCP Project ID on your SecOps tenant's /settings/profile page) |
| 64 | +2. `CUSTOMER_ID` (Your Chronicle Customer UUID) |
| 65 | +3. `REGION` (Your Chronicle Region, e.g., `us`, `europe-west1`) |
| 66 | +4. `SERVER_URL` (e.g. https://chronicle.northamerica-northeast2.rep.googleapis.com/mcp, https://chronicle.us.rep.googleapis.com/mcp, etc.) |
| 67 | +
|
| 68 | +> **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. |
| 69 | +
|
| 70 | +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: |
| 71 | +Customer ID: ${CUSTOMER_ID} |
| 72 | +Region: ${REGION} |
| 73 | +Project ID: ${PROJECT_ID} |
| 74 | +
|
| 75 | +## Available Skills |
| 76 | +
|
| 77 | +
|
| 78 | +### 1. Setup Assistant (Antigravity) (`secops-setup-antigravity`) |
| 79 | +* **Trigger**: "Help me set up Antigravity", "Configure Antigravity for SecOps". |
| 80 | +* **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`). |
| 81 | +
|
| 82 | +### 2. Alert Triage (`secops-triage`) |
| 83 | +* **Trigger**: "Triage alert [ID]", "Analyze case [ID]". |
| 84 | +* **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). |
| 85 | +
|
| 86 | +### 3. Investigation (`secops-investigate`) |
| 87 | +* **Trigger**: "Investigate case [ID]", "Deep dive on [Entity]". |
| 88 | +* **Function**: Guides deep-dive investigations using specialized runbooks (e.g., Lateral Movement, Malware). |
| 89 | +
|
| 90 | +### 4. Threat Hunting (`secops-hunt`) |
| 91 | +* **Trigger**: "Hunt for [Threat]", "Search for TTP [ID]". |
| 92 | +* **Function**: Assists in proactive threat hunting by generating hypotheses and constructing complex UDM queries for Chronicle. |
| 93 | +
|
| 94 | +### 5. Cases (`secops-cases`) |
| 95 | +* **Trigger**: "List cases", "Show recent cases", "/secops:cases". |
| 96 | +* **Function**: Lists recent SOAR cases to verify connectivity and view case status. |
| 97 | +
|
| 98 | +## Custom Commands |
| 99 | +
|
| 100 | +You can use the following slash commands as shortcuts for common tasks: |
| 101 | +
|
| 102 | +* `/secops:triage <ALERT_ID>`: Quickly start triaging an alert. |
| 103 | +* `/secops:investigate <CASE_ID>`: Start an investigation. |
| 104 | +* `/secops:hunt <THREAT>`: Start a threat hunt. |
| 105 | +* `/secops:cases`: List recent cases. |
| 106 | +
|
| 107 | +## How it Works |
| 108 | +
|
| 109 | +These skills act as **Driver Agents** that: |
| 110 | +1. **Read** the standardized Runbooks in `rules_bank/run_books/`. |
| 111 | +2. **Execute** the steps using the available MCP tools. |
| 112 | +3. **Standardize** the output according to SOC best practices. |
| 113 | +
|
| 114 | +### Tool Selection |
| 115 | +
|
| 116 | +The skills employ an **Adaptive Execution** strategy to ensure robustness: |
| 117 | +
|
| 118 | +1. **Check Environment**: The skill first identifies which tools are available in the current workspace. |
| 119 | +2. **Prioritize Remote**: If the **Remote MCP Server** is connected, the skill uses remote tools (e.g., `list_cases`, `udm_search`) for maximum capability. |
| 120 | +3. **Fallback to Local**: If remote tools are unavailable, the skill attempts to use **Local Python Tools**. |
| 121 | + > **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. |
| 122 | +
|
| 123 | +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). |
| 124 | +
|
| 125 | +
|
| 126 | +## Cross-Compatibility |
| 127 | +
|
| 128 | +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. |
| 129 | +
|
| 130 | +* `slash_command`: Defines the equivalent command pattern (e.g., `/security:triage`). |
| 131 | +* `personas`: detailed which security personas (e.g., `threat_hunter`) are best suited for the task. |
| 132 | +
|
| 133 | +
|
| 134 | +## Known Issues |
| 135 | +* 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. |
| 136 | +
|
| 137 | +## References |
| 138 | +* [Agent Skills Specification](https://agentskills.io/specification) |
| 139 | +* [Gemini CLI Documentation](https://geminicli.com) |
| 140 | +* [Gemini CLI Preview Features](https://geminicli.com/docs/settings/general#previewfeatures) |
| 141 | +* [Antigravity Skills](https://antigravity.google/docs/skills) |
0 commit comments