MitchellGulledge3/gigamon-sentinel-mcp-demo

# Gigamon Sentinel MCP 演示 本仓库是一个可直接用于 GitHub 的参考实现，面向希望展示端到端 Microsoft Sentinel 自定义 MCP 工具集成演示的 Gigamon 开发人员。 其目的并非推出另一个通用的聊天机器人。目的是展示 ISV（独立软件供应商）如何将聚焦的高价值安全能力，作为 **MCP tools** 暴露在他们已经引入到 Microsoft Sentinel 的数据之上。一旦这些工具存在，终端演示、ISV 产品体验、Copilot 风格的 UI 或其他 agent runtime 就可以调用相同的能力。 ## 一句话概述 Gigamon 在 Sentinel 中拥有丰富的网络可见性；MCP 将这种可见性转化为可重用的 agent 工具，例如“总结安全态势”、“分流横向移动”、“狩猎 DNS 异常”和“总结 TLS 风险”。 ## 架构一览 ``` flowchart LR A["🛰️ Gigamon network telemetry
(CCF / deep observability)"] -->|LogSeeder
DCE + DCR| B[("📊 Microsoft Sentinel
GigamonCcfMcpDemo_CL")] B --> C["📜 KQL tools
mcp-tools/*.kql"] C -->|"scripts/publish-mcp-tools.py
(API)"| D["🧰 Sentinel MCP Collection
Gigamon-Sentinel-MCP-Demo"] D --> E["🤖 VS Code · Copilot Studio
Foundry · Claude · ChatGPT"] D --> F["💻 terminal_demo.py
(local agent)"] style A fill:#1f6feb,stroke:#1f6feb,color:#fff style B fill:#0969da,stroke:#0969da,color:#fff style D fill:#8250df,stroke:#8250df,color:#fff ``` ## 实战工作 session 的推荐路径 如果你正与 Gigamon 开发人员一同进行实战演练，请从这里开始： [`docs/working-session-guide.md`](docs/working-session-guide.md) 该指南是最系统化的路径。它包含了角色分工、可直接复制粘贴的命令、检查点、故障排除指南，以及 Gigamon 针对其自身平台定制该模式的确切位置。 ## 刚接触 Sentinel？请先阅读此内容 | 术语 | 通俗解释 | | --- | --- | | Microsoft Sentinel | 微软的云 SIEM。它帮助安全团队收集日志、检测威胁、调查事件并进行响应。 | | Log Analytics workspace | Sentinel 用于存储日志的 Azure 数据存储库。可以理解为“安全遥测数据的数据库”。 | | 表 (Table) | 工作区中一组带名称的行。此演示将数据写入 `GigamonCcfMcpDemo_CL`。 | | KQL | Kusto 查询语言。这是用于搜索 Sentinel 日志的查询语言。 | | LogSeeder | 一个样本数据工具，用于创建表并插入逼真的演示数据行。 | | DCE | 数据收集端点 (Data Collection Endpoint)。用于发送自定义日志数据的 Azure 数据接入 URL。 | | DCR | 数据收集规则 (Data Collection Rule)。将传入数据映射到正确表和列的 Azure 规则。 | | MCP tool | agent 可以调用的工具。在本仓库中，每个 MCP tool 都会运行一个精心策划的 KQL 查询。 | 简而言之：**LogSeeder 将符合 Gigamon 结构的数据行注入到 Sentinel 中；KQL 负责提出有用的安全问题；MCP 将这些问题封装起来，以便 agent 或应用程序可以调用它们。** ## 此演示证明了什么 Gigamon 开发人员可以： 1. 从官方 Sentinel connector 表的 schema 开始。 2. 使用 Sentinel LogSeeder 创建演示用的自定义表，并注入逼真的遥测数据。 3. 将高价值的 KQL 问题发布为 Sentinel 自定义 MCP 工具。 4. 从简单的终端提示循环或任何未来的 agent runtime 中调用这些工具。 ## 架构 ``` Official Gigamon Sentinel schema | v LogSeeder demo schema + sample value pools | v GigamonCcfMcpDemo_CL in Log Analytics / Sentinel | v KQL-backed custom Sentinel MCP tools | v Interactive terminal demo that routes natural prompts to those tools ``` ## 创建的内容 | 资产 | 创建者 | 存在原因 | | --- | --- | --- | | `GigamonCcfMcpDemo_CL` 表 | LogSeeder | 在 Sentinel 中存储演示用的 Gigamon CCF 风格遥测数据 | | 数据收集端点 (DCE) | LogSeeder/Azure Monitor | 为自定义日志提供接入端点 | | 数据收集规则 (DCR) | LogSeeder/Azure Monitor | 将 JSON 字段映射到自定义表的列中 | | `Gigamon-Sentinel-MCP-Demo` 集合 | `scripts/publish-mcp-tools.py` | 对自定义 MCP 工具进行分组 | | 八个 MCP 工具 | `scripts/publish-mcp-tools.py` | 暴露可重复使用的 Gigamon 调查问题 | | 终端演示 | `terminal_demo.py` | 让演示者可以通过提示符调用工具 | ## 为什么这对 Gigamon 开发人员很重要 开发人员无需猜测 agent 可能需要什么。他们可以围绕 Gigamon 最有能力回答的安全问题，打包一小组具有明确导向的工具： | 开发资产 | 为什么有帮助 | | --- | --- | | 官方表 schema | 确保演示与真实的 Gigamon Sentinel connector 保持一致 | | LogSeeder schema | 让开发人员或销售无需等待实际设备运行即可建立演示数据 | | KQL 文件 | 使安全逻辑可被检查、审查和版本化 | | MCP 发布脚本 | 将 KQL 转换为可调用的自定义工具 | | 终端演示 | 展示端到端的工具调用，而无需经历 Teams、浏览器或管理员同意等繁琐过程 | | 源码注释 | 帮助开发人员理解和自定义每一个核心环节 | ## 演示表 演示表是 `GigamonCcfMcpDemo_CL`。它使用与以下来源中的官方 Sentinel Gigamon CCF 表 schema 相同的列名和类型： ``` https://raw.githubusercontent.com/Azure/Azure-Sentinel/master/Solutions/Gigamon%20Connector/Data%20Connectors/Gigamon_CCF/Gigamon_table.json ``` 该表名特意与 `GigamonV2_CL` 不同，这样演示就永远不会与生产环境的 connector 表发生冲突。 伴随文件 `logseeder/GigamonCcfMcpDemo_CL.annotated.jsonc` 以易于添加注释的格式解释了 schema。请确保 `GigamonCcfMcpDemo_CL.json` 是有效的 JSON 格式以供 LogSeeder 使用。 ## 端到端用例 **用例：** SOC 分析师询问，在怀疑发生入侵期间，Gigamon 网络可见性数据是否显示出横向移动、DNS 异常或 TLS 风险。 MCP 工具将这种调查作为可重用的能力暴露出来： | 工具 | 用途 | | --- | --- | | `Gigamon_Visibility_Posture_Summary` | 主管级别的态势摘要：事件、来源、目的地、应用、协议、字节数 | | `Gigamon_Lateral_Movement_Triage` | 分流 SMB/RDP/SSH 东西向移动候选对象 | | `Gigamon_DNS_Anomaly_Hunt` | 狩猎可疑或缓慢的 DNS 活动 | | `Gigamon_TLS_Risk_Summary` | 总结弱 TLS、弱密钥、即将过期的证书、JA3/JA3S 信号 | | `Gigamon_Top_Talkers_By_App` | 查找最活跃的应用、来源、目的地、字节数、数据包数 | | `Gigamon_JA3_Threat_Match` | ★ 将观察到的 JA3/JA3S 与已知的恶意 C2/RAT/loader 指纹（Cobalt Strike、Sliver、Trickbot、Emotet、Tor、Adwind RAT）进行匹配 | | `Gigamon_Beacon_Periodicity_Hunt` | 通过按 (源, 目的地, 端口) 划分的到达间隔抖动 + IQR 检测 C2 信标 | | `Gigamon_Shadow_IT_App_Discovery` | 发现未经批准的应用（P2P、Tor、消费者 VPN、RMM、个人云、加密挖矿、绕过审查工具） | 最后三个工具是 **DPI 独有**的能力：这些是只有 Gigamon 的深度可观测性架构才能大规模回答的问题。EDR 无法看到 JA3 指纹。单独的 NDR 无法以这种粒度识别应用指纹。CCF 将两者都引入了 Sentinel —— 而 MCP 将它们都转化为了 agent 工具。 有关完整的叙述、价值主张、最新实际输出结果以及每个工具的讲解话术，请参阅 [`docs/tool-use-cases.md`](docs/tool-use-cases.md)。 ## 前置条件 你需要： 1. **一个 Azure 订阅**，包含一个已启用 **Microsoft Sentinel 数据湖**的 **Log Analytics workspace**。 2. **有权在工作区的资源组中创建自定义日志接入资源**（自定义表、DCR、DCE）。 3. **Azure CLI** (`az`) 已通过该订阅的身份验证： brew install azure-cli # 如果你尚未安装 az login az account set --subscription "" 4. **PowerShell 7**（LogSeeder 用于注入数据时需要）： brew install --cask powershell pwsh --version # 应当显示为 7.x 版本 5. **Python 3.9+**，用于发布辅助脚本和终端演示（`python3 --version`）。 6. **`sentinel-logseeder`** —— 微软的样本数据工具。在磁盘上的任意位置将其克隆一次： git clone https://github.com/microsoft/sentinel-logseeder.git 7. **拥有发布 Sentinel 自定义 MCP 工具集合的权限。** 发布辅助脚本会调用 `https://api.securityplatform.microsoft.com/aiprimitives/mcpToolCollections`，并获取资源 ID 为 `4500ebfb-89b6-4b14-a480-7f749797bfcd`（Sentinel 平台服务）的 Azure AD token。必须允许你的身份在目标租户中创建或更新 MCP 工具集合。 ### 获取你的工作区客户 ID 发布脚本和 `.env` 文件需要提供 `` —— 这是 Log Analytics 的**工作区 ID**（一个 GUID），而**不是** Azure 资源 ID。使用以下命令查找你的 ID： ``` az monitor log-analytics workspace show \ --resource-group \ --workspace-name \ --query customerId -o tsv ``` ### 发布脚本的身份验证 `scripts/publish-mcp-tools.py` 使用 `DefaultAzureCredential`。最简单的方法是已经登录了 `az`（即上面的第 3 步）。如果你更愿意使用 service principal，请在运行脚本前设置标准环境变量： ``` export AZURE_TENANT_ID=... export AZURE_CLIENT_ID=... export AZURE_CLIENT_SECRET=... ``` ## 使用 LogSeeder 注入数据 此步骤将创建自定义表并将演示数据行发送到 Sentinel 中。如果你是初次接触 Azure Monitor 数据接入，最重要的部分是 LogSeeder 隐藏了大部分底层细节：它创建或复用 DCE、创建 DCR、映射 schema 并发送样本数据。 将 `logseeder/GigamonCcfMcpDemo_CL.json` 复制到你的 `sentinel-logseeder/schemas/` 文件夹中，然后运行： ``` # 根据你的路径进行调整 export REPO_ROOT=$(pwd) # this repo export LOGSEEDER=/path/to/sentinel-logseeder # where you cloned LogSeeder cp "$REPO_ROOT/logseeder/GigamonCcfMcpDemo_CL.json" "$LOGSEEDER/schemas/" cd "$LOGSEEDER" pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass \ -File ./scripts/Invoke-SampleDataIngestion.ps1 \ -TableName GigamonCcfMcpDemo_CL \ -Schema ./schemas/GigamonCcfMcpDemo_CL.json \ -RowCount 250 \ -TimeWindowMinutes 1440 \ -Deploy -Ingest ``` 验证数据行： ``` GigamonCcfMcpDemo_CL | summarize RowCount=count(), FirstSeen=min(TimeGenerated), LastSeen=max(TimeGenerated) ``` 如果在注入数据后立即查询返回了零行，请等待几分钟后再重新查询。全新的自定义表和 DCR 映射可能需要一些时间才能支持查询。 实用的验证查询： ``` GigamonCcfMcpDemo_CL | summarize Events=count(), Apps=make_set(app_name, 20), Protocols=make_set(protocol, 10) ``` ``` GigamonCcfMcpDemo_CL | where dst_port in ("445", "3389", "22") | summarize Flows=count(), Bytes=sum(tolong(total_bytes)) by dst_port, app_name | order by Bytes desc ``` ``` GigamonCcfMcpDemo_CL | where app_name == "dns" or dst_port == "53" | summarize Queries=count(), Failed=countif(dns_reply_code in ("NXDOMAIN", "SERVFAIL")) by dns_query_type ``` ## 发布自定义 MCP 工具 创建一个 Sentinel 自定义 MCP 集合，然后将 `mcp-tools/` 中的每个文件作为基于 KQL 的工具进行发布。工具输入应包含 `workspaceId`；本仓库中的 KQL 假定该表已经存在于该工作区中。 可以将此步骤视为将保存好的 Sentinel 问题打包成工具。AI 模型无需去编写 KQL，而是由模型或应用程序调用一个已经包含正确查询且受信任的工具。 建议的集合名称： ``` Gigamon-Sentinel-MCP-Demo ``` 本仓库包含一个辅助脚本，用于发布 `mcp-tools/` 中的每一个 KQL 文件： ``` cd "$REPO_ROOT" python3 scripts/publish-mcp-tools.py \ --collection Gigamon-Sentinel-MCP-Demo \ --workspace-id ``` 该脚本将执行以下操作： 1. 通过 Azure CLI 获取 Sentinel 平台服务的 token。 2. 创建或更新 MCP 集合。 3. 读取 `mcp-tools/` 中的每个 `.kql` 文件。 4. 将每个查询封装在自定义 MCP 工具的 payload 结构中。 5. 将每个工具以 `workspaceId` 作为必需的输入进行发布。 ## 终端演示 运行包含的交互式终端演示： ``` cd "$REPO_ROOT" python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt cp .env.example .env ``` 编辑 `.env` 并设置： ``` MCP_DEFAULT_ARGUMENTS={"workspaceId":""} ``` 然后启动应用： ``` python3 terminal_demo.py --show-raw ``` 输入如下提示词： ``` Summarize Gigamon visibility posture Show possible lateral movement Hunt DNS anomalies Summarize TLS risk Show top talkers by app Match observed JA3 fingerprints against known-bad signatures Hunt for beaconing destinations with low jitter Discover unsanctioned shadow IT apps ``` 如果你想要一段可以直接粘贴到演示脚本中的单行命令，请运行： ``` python3 terminal_demo.py --prompt "Show possible lateral movement" --show-raw ``` 终端演示包含一个简单的提示路由器： | 提示包含内容 | 选择的工具 | | --- | --- | | `lateral`, `east-west`, `rdp`, `smb`, `ssh` | `Gigamon_Lateral_Movement_Triage` | | `dns`, `domain`, `lookup`, `nxdomain`, `servfail` | `Gigamon_DNS_Anomaly_Hunt` | | `tls`, `ssl`, `cert`, `certificate`, `weak key` | `Gigamon_TLS_Risk_Summary` | | `top`, `talker`, `app`, `bytes`, `packets` | `Gigamon_Top_Talkers_By_App` | | `ja3`, `fingerprint`, `c2 fingerprint` | `Gigamon_JA3_Threat_Match` | | `beacon`, `beaconing`, `periodicity`, `callback` | `Gigamon_Beacon_Periodicity_Hunt` | | `shadow it`, `tor`, `bittorrent`, `personal vpn`, `crypto miner` | `Gigamon_Shadow_IT_App_Discovery` | | 其他任何内容 | `Gigamon_Visibility_Posture_Summary` | 该路由器特意设计得很简单。在生产的 ISV 应用中，这部分可以使用 LLM planner、工作流引擎或显式的 UI 按钮来替换。 ## 故障排除快速指南 | 症状 | 可能原因 | 解决方法 | | --- | --- | --- | | `az` token 错误 | Azure CLI 未登录或指向了错误的租户/订阅 | 运行 `az login` 和az account set --subscription ` | | 数据接入成功但查询返回 0 行数据 | 表/DCR 传播延迟 | 等待几分钟后重新运行 KQL | | 发布 MCP 时因权限错误失败 | 缺少 Sentinel 自定义 MCP 管理权限 | 使用有权发布工具集合的账户 | | 终端演示提示工作区缺失 | `.env` 未包含 `MCP_DEFAULT_ARGUMENTS` | 设置为 `{"workspaceId":""}` | | 工具未返回数据行 | 演示数据已老化或未被注入 | 使用新的 `TimeWindowMinutes` 重新运行 LogSeeder | ## 演讲话术 ## 源码说明 本仓库包含为希望自定义实现的开发人员准备的详细说明： | 文件 | 用途 | | --- | --- | | `docs/source-line-notes.md` | 对仓库中每个 Python 和 JSON 文件进行逐行解释 | | `logseeder/GigamonCcfMcpDemo_CL.annotated.jsonc` | LogSeeder JSON schema 的注释伴随文件 | JSON 不支持注释，因此可运行的 `.json` 文件会保持有效，而注释内容被放置在 `.jsonc` 或 Markdown 中。 ## 如何将其应用于生产环境 对于由 Gigamon 实际交付的资产，请按如下方式替换演示组件： | 演示组件 | 生产环境方向 | | --- | --- | | `GigamonCcfMcpDemo_CL` | 使用真实的 `GigamonV2_CL` 表或客户指定的表 | | LogSeeder 样本值 | 使用来自 connector 的真实产品遥测数据 | | 静态提示路由器 | 使用明确的产品 UI 操作或 agent planner | | 终端演示 | 将相同的工具调用嵌入到 Gigamon 控制台、类 Copilot 应用或合作伙伴集成中 | | 单一工作区 ID | 让客户配置来选择 Sentinel 工作区 | ## 文件 | 路径 | 用途 | | --- | --- | | `logseeder/GigamonCcfMcpDemo_CL.json` | 源自官方 Gigamon connector schema 的 LogSeeder schema | | `logseeder/GigamonCcfMcpDemo_CL.annotated.jsonc` | 在不破坏有效 JSON 格式的情况下对 schema 进行注释说明 | | `mcp-tools/*.kql` | 自定义 Sentinel MCP 工具的 KQL 定义 | | `scripts/publish-mcp-tools.py` | 将 KQL 文件作为 Sentinel 自定义 MCP 工具发布 | | `terminal_demo.py` | 将提示路由到 Gigamon MCP 工具的交互式终端提示循环 | | `sentinel_mcp_demo/` | 终端演示使用的最小化 Sentinel MCP 客户端 | | `docs/demo-script.md` | 分步演示者脚本 | | `docs/working-session-guide.md` | 面向 Microsoft 和 Gigamon 的系统性实况演练指南 | | `docs/tool-use-cases.md` | 每一个 MCP 工具的详细用例、附加价值和故事指南 | | `docs/source-line-notes.md` | 针对后缀为 Python 和 JSON 文件的详尽逐行源码注释 | ## 实时捕获 — 全部 8 个工具（2026 年 5 月 13 日） 这些是针对演示工作区中实际存在的 `GigamonCcfMcpDemo_CL` 表产生的实际 MCP 工具响应。每一行都是一次 `terminal_demo.py --show-raw --prompt "..."` 的调用。 | 工具 | 核心结果 | | --- | --- | | `Gigamon_Visibility_Posture_Summary` | 1,500 个事件 · 5 个源 · 5 个目的地 · 3.05 GB · 应用包括 `telegram`, `twitch`, `trickbot` | | `Gigamon_Lateral_Movement_Triage` | 目标端口 22 上的 202 个候选流 · 459 MB · 5 个源 / 5 个目的地 | | `Gigamon_DNS_Anomaly_Hunt` | 491 次 A 记录查询 · 345 次失败 · 254 次响应缓慢 · 可疑: `rare-beacon.bad-example.test` | | `Gigamon_TLS_Risk_Summary` | 482 个 TLS 1.0 会话 · 162 次弱密钥观测 · 160 个即将过期的证书 | | `Gigamon_Top_Talkers_By_App` | 基于 TCP 的 `https / remote-admin` — 24 个流 · 69 MB | | ★ `Gigamon_JA3_Threat_Match` | **1,500 次握手 · 9 个唯一的 JA3 · 536 次已知恶意命中**，涵盖 Cobalt Strike, Sliver, Trickbot, Emotet, Tor, Adwind RAT | | `Gigamon_Beacon_Periodicity_Hunt` | 737 个流 · 100 个源/目的地对 · 0 个候选信标（纯净基线） | | `Gigamon_Shadow_IT_App_Discovery` | 331 个影子 IT 流 · 701 MB · 44 台主机 · 9 个类别 · 4 次高风险命中 | ### 为什么 JA3 是旗舰级功能 EDR 无法看到 TLS 握手指纹。只有网络线路上的深度可观测性传感器 (Gigamon) 才能做到。通过一次基于自然语言的 MCP 工具调用，Security Copilot 现在可以回答*“是否有任何 TLS 客户端的指纹显示为 Cobalt Strike？”*这一问题，并给出**跨越六个威胁家族的 536 次命中记录**。 ### 关于“0 个信标”结果的说明 信标狩猎工具在当前数据下返回了 0 个候选信标 —— 这是**预期的纯净状态**。仅当抖动 < 0.25 且 IQR 比率 < 0.3 且中位数间隔 ≥ 15 秒时，该工具才会标记配对。伴随的 Jupyter Notebook [`04-beacon-periodicity-analysis.ipynb`](https://github.com/MitchellGulledge3/gigamon-sentinel-notebooks) 以可视化的方式执行了相同的计算，这样即使 MCP 工具返回“一切正常”，分析人员也可以进行深入调查。

标签：AI合规, Azure Sentinel, IP 地址批量处理, KQL, MCP, PE 加载器, 安全运营, 扫描框架, 网络流量分析, 逆向工具