jmaciasc-google/google-security-agent

# Google Security 多 Agent 部署指南 这是一个基于 **Google Agent Development Kit (ADK)** 构建的企业级、轻量级多 Agent 安全编排器，可以通过 **Model Context Protocol (MCP)** 与 Google Security 套件集成。该 Agent 能够协调 **Google Security Command Center (SCC)**、**Google SecOps (Chronicle)** 和 **Google Threat Intelligence (GTI)** 之间的情报和操作。 该编排器设计为**高度可移植、完全可重用，并且无需客户修改任何代码**。本指南为任何人（即使是零编程基础的用户）提供了循序渐进的操作演练，指导如何在 **Gemini Enterprise** 中安全地部署和注册此 Agent。 ## 🏗️ 架构流程 该编排器采用 **多 Agent 架构**： * **Google Security Agent（中心）：** 处理用户意图，展示透明的多步编排计划，并动态协调任务。 * **子 Agent：** `scc_agent`、`secops_agent` 和 `gti_agent` 根据可用性连接到独立的、由客户管理或由 Google 管理的基于 HTTP 的 MCP 服务器。 * **安全边界：** 允许以编程方式过滤不需要的工具，并利用 Cloud Run 的服务身份按需动态生成短期的安全 OIDC ID Token。 ``` graph TD GE[Gemini Enterprise UI] -->|IAM OIDC Bearer Token| GSA[Google Security Agent Hub] subgraph "Multi-Agent Container (Cloud Run)" GSA -->|Dynamic Coordination| SCC[SCC Agent Spoke] GSA -->|Dynamic Coordination| SecOps[SecOps Agent Spoke] GSA -->|Dynamic Coordination| GTI[GTI Agent Spoke] end GSA -->|OIDC Identity Handshake| metaserv[GCP Metadata Server] SCC -->|OIDC Token| scc_mcp[SCC MCP Server] SecOps -->|OIDC Token| secops_mcp[SecOps MCP Server] GTI -->|OIDC Token| gti_mcp[GTI MCP Server] ``` ## 📋 阶段 1：前置条件 在开始之前，请确保您满足以下云架构前置条件： 1. **有效的 GCP 项目：** 您必须拥有一个已激活结算功能的 Google Cloud Platform (GCP) 项目。 2. **Google Cloud Shell（强烈推荐）：** 您无需安装本地命令行工具，直接在浏览器中使用 **Google Cloud Shell** 即可。它预装了 Google Cloud SDK、Git，并且已经获得授权可以管理您的 GCP 资源！ 3. **活跃的 MCP 服务器：** 您应该已经启动并运行了目标 MCP 服务器。请参阅以下设置资源： * **Google SecOps (Chronicle)：** 按照 [Google SecOps MCP 服务器文档](https://docs.cloud.google.com/chronicle/docs/secops/use-google-secops-mcp) 进行设置并部署您的 SecOps 引擎。 * **Google Threat Intelligence (GTI)：** 使用 [GTI MCP 服务器代码库](https://github.com/jmaciasc-google/gti-mcp-server) 进行部署。 * **Security Command Center (SCC)：** 此 MCP 服务器尚未作为单独的代码库提供，请保持关注。 4. **Gemini Enterprise 许可证：** 确保您的 Google Cloud 组织拥有有效的 **Gemini Enterprise 许可证**。您的项目中需要有活跃的 Gemini Enterprise 应用引擎才能连接并使用自定义 Agent。 ## 💻 阶段 2：本地工作区设置 打开 Google Cloud Shell（或您的本地终端）并执行以下命令以克隆代码库并准备工作区： ``` # 1. 克隆此仓库 git clone # 2. 进入项目目录 cd google-security-agent ``` ## ⚙️ 阶段 3：定义部署环境变量 请在下方填入您的 GCP 项目 ID，并在您的终端中运行此代码块： ``` export PROJECT_ID="" # Your Google Cloud Project ID export REGION="us-east1" # Google Cloud deployment region export SEC_AGENT_NAME="google-security-agent" # Name of your new Cloud Run service export SEC_AGENT_SERVICE_ACCOUNT_NAME="google-security-agent-runner" # Name of your new Service Account export SEC_AGENT_REPO="security-agent-repo" # Artifact Registry repository name export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") gcloud config set project $PROJECT_ID ``` ## ⚙️ 阶段 4：配置 Agent 环境变量 您**无需**编辑任何 Python 代码。代码库完全是通用的，可以直接执行。您无需编辑文件，而是可以直接在终端中使用 `export` 命令定义 Agent 的功能和端点。这使得复制、粘贴和部署变得极其简单。 ### 1. 配置参数参考表 | 变量名 | 默认值 | 描述 / 参考链接 | |---|---|---| | `GEMINI_MODEL` | `gemini-2.5-flash` | 用于根 Agent 和子 Agent 的 Google Gemini 模型。请参阅 [Vertex AI Gemini 模型文档](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models) 查看可用模型。 | | `ENABLE_SCC_AGENT` | `true` | 切换（`true`/`false`）以启用/禁用 Security Command Center 子 Agent。 | | `ENABLE_SECOPS_AGENT` | `true` | 切换（`true`/`false`）以启用/禁用 Google SecOps (Chronicle) 子 Agent。 | | `ENABLE_GTI_AGENT` | `true` | 切换（`true`/`false`）以启用/禁用 Google Threat Intelligence 子 Agent。 | | `EXCLUDED_TOOLS` | `""` | 要排除的以逗号分隔的工具名称列表。请查看下方工具目录中各项服务的可用工具。 | | `SCC_MCP_URL` | `https://scc-mcp-server.run.app/sse` | SCC MCP 服务器的端点 URL。 | | `SECOPS_MCP_URL` | `https://secops-mcp-server.run.app/sse` | SecOps MCP 服务器的端点 URL。 | | `GTI_MCP_URL` | `https://gti-mcp-server.run.app/sse` | GTI MCP 服务器的端点 URL。 | ### 2. 导出配置变量 在您的 Cloud Shell 或终端中运行以下导出命令。请确保将占位符 URL 替换为您实际部署的 MCP 服务器端点： ``` export GEMINI_MODEL="gemini-2.5-flash" export ENABLE_SCC_AGENT="true" export ENABLE_SECOPS_AGENT="true" export ENABLE_GTI_AGENT="true" # Security Tool Filter：列出任何工具名称（例如：scc:delete_finding）以完全禁用它 # 有关所有工具的列表，请参阅上方链接的 MCP 工具目录。 export EXCLUDED_TOOLS="scc:delete_finding" # 指向你的目标 MCP server endpoint 的 URL： export SCC_MCP_URL="https://your-scc-mcp-server-endpoint.run.app/sse" export SECOPS_MCP_URL="https://your-secops-mcp-server-endpoint.run.app/sse" export GTI_MCP_URL="https://your-gti-mcp-server-endpoint.run.app/sse" ``` ## 🛡️ 阶段 5：配置 GCP 基础设施 运行这些命令以准备您的 GCP 项目的 API 和安全权限。 ### 1. 启用所需的 Cloud API ``` gcloud services enable run.googleapis.com \ aiplatform.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ discoveryengine.googleapis.com ``` ### 2. 为编排器创建自定义服务账号 ``` gcloud iam service-accounts create $SEC_AGENT_SERVICE_ACCOUNT_NAME \ --display-name="Google Security Agent Runner" \ --project=$PROJECT_ID ``` ### 3. 向服务账号授予 IAM 安全角色 ``` # 授权该服务账号通过 Vertex AI API 调用 Gemini LLM gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:$SEC_AGENT_SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/aiplatform.user" ``` ## 🚢 阶段 6：构建并部署到 Cloud Run ### 1. 创建 Artifact Registry 代码库 我们使用之前定义的 `$SEC_AGENT_REPO` 环境变量来创建 Docker 代码库： ``` gcloud artifacts repositories create $SEC_AGENT_REPO \ --repository-format=docker \ --location=$REGION \ --project=$PROJECT_ID ``` ### 2. 使用 `agents-cli` 构建和部署（推荐流程） 我们在 Cloud Build 中安全地编译并部署容器，并使用 `agents-cli deploy` 实用工具将其启动到 Cloud Run 上。 由于我们使用终端环境变量配置了 Agent 的配置变量，因此我们使用 `--update-env-vars` 标志将它们传递给 Cloud Run： ``` agents-cli deploy \ --no-confirm-project \ --project $PROJECT_ID \ --region $REGION \ --service-name $SEC_AGENT_NAME \ --service-account $SEC_AGENT_SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com \ --update-env-vars "GEMINI_MODEL=$GEMINI_MODEL,ENABLE_SCC_AGENT=$ENABLE_SCC_AGENT,ENABLE_SECOPS_AGENT=$ENABLE_SECOPS_AGENT,ENABLE_GTI_AGENT=$ENABLE_GTI_AGENT,EXCLUDED_TOOLS=$EXCLUDED_TOOLS,SCC_MCP_URL=$SCC_MCP_URL,SECOPS_MCP_URL=$SECOPS_MCP_URL,GTI_MCP_URL=$GTI_MCP_URL" ``` ## 🤝 阶段 7：连接到 Gemini Enterprise (A2A) 部署完成后，我们专门向 Gemini Enterprise 授予调用权限，并通过 **Agent-to-Agent (A2A)** 协议注册 Google Security Agent。 ### 1. 授权 Gemini Enterprise 调用您的 Cloud Run 服务 为了允许 Gemini Enterprise 调用您的私有 Cloud Run 服务，我们将 **`roles/run.servicesInvoker`** 角色授予您 Discovery Engine 的系统服务账号。 ``` gcloud run services add-iam-policy-binding $SEC_AGENT_NAME \ --region=$REGION \ --member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com" \ --role="roles/run.servicesInvoker" \ --project=$PROJECT_ID ``` ### 2. 以编程方式注册 Agent 我们检索已部署的 Cloud Run 服务 URL，并将其作为 **Agent-to-Agent (A2A)** 提供者注册到您的 Gemini Enterprise 应用中。 #### 步骤 A：导出已部署的服务 URL ``` export SERVICE_URL=$(gcloud run services describe $SEC_AGENT_NAME --region=$REGION --project=$PROJECT_ID --format="value(status.url)") ``` #### 步骤 B：发现并导出 Gemini Enterprise 应用 ID 根据您项目的配置，选择以下两种情况中的**一种**来导出您的 `GE_APP_ID`： ##### 选项 A：您只有一个应用（自动提取） 如果您的项目中只配置了一个应用，请运行此自动命令以立即查找并导出您的 App ID： ``` export GE_APP_ID=$(agents-cli publish gemini-enterprise --list --project-id $PROJECT_ID | grep -o "projects/.*default_collection/engines/[^[:space:]]*" | head -n 1) ``` ##### 选项 B：您有多个应用（手动选择） 如果您有多个应用，请首先列出它们： ``` agents-cli publish gemini-enterprise --list --project-id $PROJECT_ID ``` 从命令输出中识别出正确的应用路径，并手动将其导出： ``` export GE_APP_ID="projects/$PROJECT_NUMBER/locations/global/collections/default_collection/engines/YOUR_CHOSEN_APP_NAME" ``` #### 步骤 C：发布并注册您的 Agent 在导出变量后，运行以下命令以完成注册： ``` agents-cli publish gemini-enterprise \ --agent-card-url "$SERVICE_URL/a2a/app/.well-known/agent-card.json" \ --gemini-enterprise-app-id "$GE_APP_ID" \ --project-id "$PROJECT_ID" \ --display-name "Google Security Agent" \ --description "An enterprise security orchestrator that coordinates actions and insights across Google Threat Intelligence (GTI), Google SecOps, and Security Command Center (SCC)." ``` ✅ **大功告成！** 您的 **`Google Security Agent`** 现已完全注册并在您的 Gemini Enterprise 应用中激活！

标签：AI智能体, FTP漏洞扫描, MCP协议, 企业安全, 多智能体, 安全编排, 网络调试, 网络资产管理, 自动化, 请求拦截, 逆向工具