googleSandy/ge-secops-agent
GitHub: googleSandy/ge-secops-agent
一个面向 Gemini Enterprise 的智能 SOC 代理，通过 MCP 协议集成 SecOps 工具链以实现安全运营的自动化与智能化。
Stars: 0 | Forks: 0
# GE SecOps Agent
部署专注于安全的 AI agent 到 Gemini Enterprise，通过 Model Context Protocol (MCP) 集成对 SecOps SIEM、SOAR、Google Threat Intelligence 和 Security Command Center 的访问。
基于 [Google ADK](https://google.github.io/adk-docs/) (Agent Development Kit) 构建，并通过 Vertex AI Reasoning Engine 部署。
## 目录
- [快速开始](#quick-start)
- [架构](#architecture)
- [安装](#installation)
- [配置](#configuration)
- [用法](#usage)
- [RAG Corpus 管理](#rag-corpus-management)
- [Gemini Enterprise 集成](#gemini-enterprise-integration)
- [CLI 参考](#cli-reference)
- [本地开发](#local-development)
- [故障排除](#troubleshooting)
- [常见问题解答](#faq)
## 快速开始
### 本地开发（推荐入门使用）
```
# Clone 和 setup
git clone --recurse-submodules https://github.com/googleSandy/ge-secops-agent.git
cd ge-secops-agent
# 配置环境
cp .env.example .env
# 使用你的 Google Cloud 凭证编辑 .env
# 安装 dependencies
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# 使用 ADK Web 在本地运行
cd soc_agent
GOOGLE_GENAI_USE_VERTEXAI=True \
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json \
GOOGLE_CLOUD_PROJECT=your-project-id \
GOOGLE_CLOUD_LOCATION=us-central1 \
adk web
```
这将在 `http://localhost:8000` 打开一个交互式 Web UI，您可以立即测试所有功能。
### 生产环境部署
```
# 1. 验证 setup 并配置 IAM（一次性）
python manage.py vertex verify
python manage.py iam setup
# 2. 部署到 Reasoning Engine
make agent-engine-deploy
# 3. 注册到 Gemini Enterprise
make agentspace-register
```
运行 `make help` 查看所有可用命令。
## 架构
```
flowchart TB
subgraph GE["Gemini Enterprise"]
UI["User Interface
Conversational UI"] end subgraph RE["Vertex AI Reasoning Engine (us-central1)"] subgraph Orch["SOC Agent Orchestrator"] Model["gemini-3.1-pro-preview
via global endpoint"] subgraph RAG["Direct Tool Access"] RAGTool["VertexAiRagRetrieval
us-east4"] Runbooks["170+ SOC Runbooks
IR Procedures
Security Docs"] end subgraph Specialists["Sub-Agents"] CTI["CTI Researcher
gemini-3-flash-preview
• Threat Intel
• IOC Analysis
• Threat Actors
• Campaigns"] T1["Tier 1 Analyst
gemini-3-flash-preview
• Alert Triage
• Case Mgmt
• Investigation
• Escalation"] end end end subgraph MCP["MCP Security Servers"] SIEM["SecOps SIEM
UDM Search, Entity Timeline
IOC Prevalence, Alerts"] SOAR["SecOps SOAR
Case Management
Findings, Collaboration"] GTI["GTI
IOC Lookup, Threat Actors
Campaigns, MITRE ATT&CK"] SCC["SCC
Findings, Assets
Compliance"] end subgraph Cache["GTI Response Cache"] CacheTTL["File: 24h | IP: 12h
Domain: 30m | URL: 30m"] end UI --> Orch RAGTool --> Runbooks Model --> RAG Model --> Specialists CTI --> SIEM & SOAR & GTI & SCC T1 --> SIEM & SOAR & GTI GTI --> Cache style GE fill:#4285f4,color:#fff style RE fill:#34a853,color:#fff style Orch fill:#fbbc04,color:#000 style RAG fill:#ea4335,color:#fff style Specialists fill:#9334e6,color:#fff style MCP fill:#185abc,color:#fff style Cache fill:#137333,color:#fff ``` **核心设计决策：** - **Orchestrator + Specialists**：单一面向用户的 agent 委派给基于角色设定的 specialists - **RAG 隔离**：VertexAiRagRetrieval 仅在 orchestrator 上使用（ADK 限制 - 无法与 function tool 共存） - **MCP 集成**：通过 Model Context Protocol server 访问安全工具 - **响应缓存**：GTI 查询会被缓存，其 TTL 根据数据波动性进行了优化 ## 安装 ### 前置条件 - Python 3.10+ - 已配置 Google Cloud SDK - 已启用结算功能的 GCP 项目 ### 所需 API ``` gcloud services enable aiplatform.googleapis.com storage.googleapis.com \ cloudbuild.googleapis.com compute.googleapis.com discoveryengine.googleapis.com ``` ### 设置步骤 1. **克隆并配置：** git clone --recurse-submodules https://github.com/googleSandy/ge-secops-agent.git cd ge-secops-agent cp .env.example .env # 编辑 .env 填入您的配置 2. **安装依赖项：** pip install -r requirements.txt 3. **验证设置并配置 IAM：** python manage.py vertex verify python manage.py iam setup 4. **部署：** make agent-engine-deploy # 将 AGENT_ENGINE_RESOURCE_NAME 保存到 .env 5. **注册到 Gemini Enterprise：** make agentspace-register ## 配置 有关所有环境变量，请参见 [.env.example](.env.example)。关键变量： | 变量 | 描述 | |----------|-------------| | `GCP_PROJECT_ID` | Google Cloud Project ID | | `GCP_PROJECT_NUMBER` | 项目编号（数字） | | `GCP_LOCATION` | 部署区域（例如，us-central1） | | `GCP_STAGING_BUCKET` | 用于暂存的 GCS bucket (gs://...) | | `CHRONICLE_PROJECT_ID` | SecOps SIEM 项目 | | `CHRONICLE_CUSTOMER_ID` | SecOps 客户 ID | | `SOAR_URL` | SOAR 平台 URL | | `SOAR_API_KEY` | SOAR API 密钥 | | `GTI_API_KEY` | Google Threat Intelligence API 密钥 | | `RAG_CORPUS_ID` | RAG corpus 资源名称 | ## 用法 ### 示例查询 ``` "What's the procedure for handling a ransomware incident?" "Analyze the APT29 threat actor and their recent campaigns" "Triage this phishing alert for user john.doe@company.com" "Hunt for lateral movement using SMB in the last 7 days" "Check IP 198.51.100.42 reputation and search for related activity" ``` ### 常用命令 ``` make agent-engine-deploy # Deploy agent make agent-engine-redeploy # Redeploy existing agent make agentspace-register # Register with Gemini Enterprise make agentspace-update # Update registration make warmup # Pre-warm MCP connections make status # Check system status ``` ## RAG Corpus 管理 ``` make rag-list # List all RAG corpora make rag-create NAME="Security Runbooks" make rag-info RAG_CORPUS_ID=projects/.../ragCorpora/... make rag-delete RAG_CORPUS_ID=projects/.../ragCorpora/... ``` ## Gemini Enterprise 集成 **通过控制台创建（推荐）：** 1. 导航到 Vertex AI > Search & Conversation > Apps 2. 点击 **Create App** > 选择 **Agent** 类型 3. 将 App ID 复制到 `.env` 作为 `AGENTSPACE_APP_ID` 4. 运行 `make agentspace-register` ## CLI 参考 | Makefile | Python CLI | |----------|------------| | `make agent-engine-list` | `python manage.py agent-engine list` | | `make agentspace-register` | `python manage.py agentspace register` | | `make rag-list` | `python manage.py rag list` | | `make status` | `python manage.py workflow status` | 运行 `python manage.py --help` 查看所有命令。 ## 本地开发 ### ADK Web（推荐） ``` cd soc_agent GOOGLE_GENAI_USE_VERTEXAI=True \ GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json \ GOOGLE_CLOUD_PROJECT=your-project-id \ GOOGLE_CLOUD_LOCATION=us-central1 \ adk web ``` 打开 `http://localhost:8000`，您可以体验： - 与 agent 实时聊天 - 实时查看工具调用可视化 - 无需部署即可立即迭代 ### 测试 MCP Server ``` cd mcp-security/server/secops-soar/secops_soar_mcp uv run server.py ``` ## 故障排除 | 问题 | 解决方案 | |-------|----------| | **403/401 认证错误** | `gcloud auth application-default login` | | **API 未启用** | `gcloud services enable aiplatform.googleapis.com` | | **缺少 MCP 模块** | `git submodule update --init --recursive` | | **Agent 不在 Gemini Enterprise 中** | `make agentspace-verify` 然后 `make agentspace-link-agent` | | **Agent 无响应** | `gcloud logging tail "resource.type=aiplatform.googleapis.com/ReasoningEngine"` | ## 常见问题解答 **我可以在没有 SOAR 的情况下使用它吗？** 可以。所有安全工具集成都是可选的。 **支持哪些 AI 模型？** orchestrator 默认使用 `gemini-3.1-pro-preview`，sub-agents 默认使用 `gemini-3-flash-preview`。可在 agent.py 中配置。 **如何更新 agent？** ``` git pull && make agent-engine-redeploy && make agentspace-update ``` **成本是多少？** Vertex AI 按每次 API 调用收费。安全产品需要单独的许可。 ## 最佳实践 - **安全**：使用 Secret Manager 管理凭证，启用审计日志 - **开发**：分离开发/测试/生产项目 - **运营**：设置预算提醒，监控配额 ## 资源 - [Google ADK 文档](https://google.github.io/adk-docs/) - Agent Development Kit - [Vertex AI 文档](https://cloud.google.com/vertex-ai/docs) - 平台文档 - [MCP 协议](https://modelcontextprotocol.io/) - Model Context Protocol - [SecOps 文档](https://cloud.google.com/chronicle/docs) - SIEM 文档 - [Security Command Center](https://cloud.google.com/security-command-center/docs) ## 支持 - [GitHub Issues](https://github.com/googleSandy/ge-secops-agent/issues) - 报告 bug 或请求功能 - [Google Cloud Support](https://console.cloud.google.com/support) - 生产环境问题
Conversational UI"] end subgraph RE["Vertex AI Reasoning Engine (us-central1)"] subgraph Orch["SOC Agent Orchestrator"] Model["gemini-3.1-pro-preview
via global endpoint"] subgraph RAG["Direct Tool Access"] RAGTool["VertexAiRagRetrieval
us-east4"] Runbooks["170+ SOC Runbooks
IR Procedures
Security Docs"] end subgraph Specialists["Sub-Agents"] CTI["CTI Researcher
gemini-3-flash-preview
• Threat Intel
• IOC Analysis
• Threat Actors
• Campaigns"] T1["Tier 1 Analyst
gemini-3-flash-preview
• Alert Triage
• Case Mgmt
• Investigation
• Escalation"] end end end subgraph MCP["MCP Security Servers"] SIEM["SecOps SIEM
UDM Search, Entity Timeline
IOC Prevalence, Alerts"] SOAR["SecOps SOAR
Case Management
Findings, Collaboration"] GTI["GTI
IOC Lookup, Threat Actors
Campaigns, MITRE ATT&CK"] SCC["SCC
Findings, Assets
Compliance"] end subgraph Cache["GTI Response Cache"] CacheTTL["File: 24h | IP: 12h
Domain: 30m | URL: 30m"] end UI --> Orch RAGTool --> Runbooks Model --> RAG Model --> Specialists CTI --> SIEM & SOAR & GTI & SCC T1 --> SIEM & SOAR & GTI GTI --> Cache style GE fill:#4285f4,color:#fff style RE fill:#34a853,color:#fff style Orch fill:#fbbc04,color:#000 style RAG fill:#ea4335,color:#fff style Specialists fill:#9334e6,color:#fff style MCP fill:#185abc,color:#fff style Cache fill:#137333,color:#fff ``` **核心设计决策：** - **Orchestrator + Specialists**：单一面向用户的 agent 委派给基于角色设定的 specialists - **RAG 隔离**：VertexAiRagRetrieval 仅在 orchestrator 上使用（ADK 限制 - 无法与 function tool 共存） - **MCP 集成**：通过 Model Context Protocol server 访问安全工具 - **响应缓存**：GTI 查询会被缓存，其 TTL 根据数据波动性进行了优化 ## 安装 ### 前置条件 - Python 3.10+ - 已配置 Google Cloud SDK - 已启用结算功能的 GCP 项目 ### 所需 API ``` gcloud services enable aiplatform.googleapis.com storage.googleapis.com \ cloudbuild.googleapis.com compute.googleapis.com discoveryengine.googleapis.com ``` ### 设置步骤 1. **克隆并配置：** git clone --recurse-submodules https://github.com/googleSandy/ge-secops-agent.git cd ge-secops-agent cp .env.example .env # 编辑 .env 填入您的配置 2. **安装依赖项：** pip install -r requirements.txt 3. **验证设置并配置 IAM：** python manage.py vertex verify python manage.py iam setup 4. **部署：** make agent-engine-deploy # 将 AGENT_ENGINE_RESOURCE_NAME 保存到 .env 5. **注册到 Gemini Enterprise：** make agentspace-register ## 配置 有关所有环境变量，请参见 [.env.example](.env.example)。关键变量： | 变量 | 描述 | |----------|-------------| | `GCP_PROJECT_ID` | Google Cloud Project ID | | `GCP_PROJECT_NUMBER` | 项目编号（数字） | | `GCP_LOCATION` | 部署区域（例如，us-central1） | | `GCP_STAGING_BUCKET` | 用于暂存的 GCS bucket (gs://...) | | `CHRONICLE_PROJECT_ID` | SecOps SIEM 项目 | | `CHRONICLE_CUSTOMER_ID` | SecOps 客户 ID | | `SOAR_URL` | SOAR 平台 URL | | `SOAR_API_KEY` | SOAR API 密钥 | | `GTI_API_KEY` | Google Threat Intelligence API 密钥 | | `RAG_CORPUS_ID` | RAG corpus 资源名称 | ## 用法 ### 示例查询 ``` "What's the procedure for handling a ransomware incident?" "Analyze the APT29 threat actor and their recent campaigns" "Triage this phishing alert for user john.doe@company.com" "Hunt for lateral movement using SMB in the last 7 days" "Check IP 198.51.100.42 reputation and search for related activity" ``` ### 常用命令 ``` make agent-engine-deploy # Deploy agent make agent-engine-redeploy # Redeploy existing agent make agentspace-register # Register with Gemini Enterprise make agentspace-update # Update registration make warmup # Pre-warm MCP connections make status # Check system status ``` ## RAG Corpus 管理 ``` make rag-list # List all RAG corpora make rag-create NAME="Security Runbooks" make rag-info RAG_CORPUS_ID=projects/.../ragCorpora/... make rag-delete RAG_CORPUS_ID=projects/.../ragCorpora/... ``` ## Gemini Enterprise 集成 **通过控制台创建（推荐）：** 1. 导航到 Vertex AI > Search & Conversation > Apps 2. 点击 **Create App** > 选择 **Agent** 类型 3. 将 App ID 复制到 `.env` 作为 `AGENTSPACE_APP_ID` 4. 运行 `make agentspace-register` ## CLI 参考 | Makefile | Python CLI | |----------|------------| | `make agent-engine-list` | `python manage.py agent-engine list` | | `make agentspace-register` | `python manage.py agentspace register` | | `make rag-list` | `python manage.py rag list` | | `make status` | `python manage.py workflow status` | 运行 `python manage.py --help` 查看所有命令。 ## 本地开发 ### ADK Web（推荐） ``` cd soc_agent GOOGLE_GENAI_USE_VERTEXAI=True \ GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json \ GOOGLE_CLOUD_PROJECT=your-project-id \ GOOGLE_CLOUD_LOCATION=us-central1 \ adk web ``` 打开 `http://localhost:8000`，您可以体验： - 与 agent 实时聊天 - 实时查看工具调用可视化 - 无需部署即可立即迭代 ### 测试 MCP Server ``` cd mcp-security/server/secops-soar/secops_soar_mcp uv run server.py ``` ## 故障排除 | 问题 | 解决方案 | |-------|----------| | **403/401 认证错误** | `gcloud auth application-default login` | | **API 未启用** | `gcloud services enable aiplatform.googleapis.com` | | **缺少 MCP 模块** | `git submodule update --init --recursive` | | **Agent 不在 Gemini Enterprise 中** | `make agentspace-verify` 然后 `make agentspace-link-agent` | | **Agent 无响应** | `gcloud logging tail "resource.type=aiplatform.googleapis.com/ReasoningEngine"` | ## 常见问题解答 **我可以在没有 SOAR 的情况下使用它吗？** 可以。所有安全工具集成都是可选的。 **支持哪些 AI 模型？** orchestrator 默认使用 `gemini-3.1-pro-preview`，sub-agents 默认使用 `gemini-3-flash-preview`。可在 agent.py 中配置。 **如何更新 agent？** ``` git pull && make agent-engine-redeploy && make agentspace-update ``` **成本是多少？** Vertex AI 按每次 API 调用收费。安全产品需要单独的许可。 ## 最佳实践 - **安全**：使用 Secret Manager 管理凭证，启用审计日志 - **开发**：分离开发/测试/生产项目 - **运营**：设置预算提醒，监控配额 ## 资源 - [Google ADK 文档](https://google.github.io/adk-docs/) - Agent Development Kit - [Vertex AI 文档](https://cloud.google.com/vertex-ai/docs) - 平台文档 - [MCP 协议](https://modelcontextprotocol.io/) - Model Context Protocol - [SecOps 文档](https://cloud.google.com/chronicle/docs) - SIEM 文档 - [Security Command Center](https://cloud.google.com/security-command-center/docs) ## 支持 - [GitHub Issues](https://github.com/googleSandy/ge-secops-agent/issues) - 报告 bug 或请求功能 - [Google Cloud Support](https://console.cloud.google.com/support) - 生产环境问题
标签：AI智能体, Gemini, Google Cloud, MCP, SOAR, 安全运营, 扫描框架, 构建工具, 逆向工具