🔒 安全调查自动化系统
由Microsoft Sentinel、Defender XDR、Graph API和威胁情报提供的全面、自动化的安全调查,具有25种专门的代理技能
📺 视频演练: 查看此项目的实际情况-- 在 YouTube 上观看 (从安全调查员演示开始)。涵盖了端到端的工作流程:自然语言调查、MCP服务器集成、KQL查询执行、威胁情报丰富和自动报告生成。
一个结合了以下功能的调查自动化框架 GitHub Copilot, VS代码代理技能,以及 模型上下文协议(MCP)服务器 以实现自然语言安全调查。问以下问题 *“调查此用户过去7天的情况”* 或 *“这个IP是恶意的吗?”* 通过KQL查询、威胁情报关联和专业报告进行全面分析。
快速入门(TL;DR)
# 1. Clone and open in VS Code
git clone https://github.com/SCStelz/security-investigator.git
code security-investigator
# 2. Set up Python environment
python -m venv .venv
.venv\Scripts\Activate.ps1 # Windows
# source .venv/bin/activate # macOS/Linux
pip install --require-hashes -r requirements.lock # Hash-verified (recommended)
# pip install -r requirements.txt # Without hash verification
# 3. Configure environment
copy config.json.template config.json
# Edit config.json → add your Sentinel workspace ID, tenant ID
copy .env.template .env
# Edit .env → add your API tokens (ipinfo, AbuseIPDB, vpnapi, Shodan)
# 4. Configure MCP servers
copy .vscode\mcp.json.template .vscode\mcp.json
# All platform servers are pre-configured — just needs a GitHub PAT on first use
# 5. Open Copilot Chat (Ctrl+Shift+I) in Agent mode and start with:
# "Run a threat pulse scan"🚀 建议首次运行: 这 威胁脉冲 技能是最好的起点。它对9个安全域(事件、身份、端点、暴露、电子邮件、UEBA、身份验证喷雾、特权操作、CVE)进行广谱扫描,并产生带有颜色编码的优先结果(🔴 升级/🟠 调查/🟡 监视器/✅ 清除)。每个发现都包括一个指向特定技能的深入建议,因此在扫描后,您将确切地知道要关注的位置以及要运行的后续命令。
其他示例提示:
"Investigate user@domain.com for the last 7 days" → user-investigation
"Analyze incident 12345" → incident-investigation
"Is this IP malicious? 203.0.113.42" → ioc-investigation
"What skills do you have access to?" → lists all 25 skills有关详细的工作流程和KQL查询: → (通用模式、技能检测) → (25个专业调查工作流程) → 查询/ (已验证的KQL查询库)
______________________________________________________________________
架构概述
┌────────────────────────────────────────────────────────────────────┐
│ GitHub Copilot (VS Code) │
├────────────────────────────────────────────────────────────────────┤
│ .github/copilot-instructions.md │
│ (Skill detection, universal patterns, routing) │
├────────────────────────────────────────────────────────────────────┤
│ .github/skills/*.md │
│ (25 specialized workflows with KQL, risk assessment) │
├────────────────────────────────────────────────────────────────────┤
│ MCP Servers (Platform) │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────────────────┐ │
│ │ Sentinel │ │ Graph API │ │ Sentinel Triage (XDR) │ │
│ │ Data Lake │ │ (Identity) │ │ (Advanced Hunting) │ │
│ └─────────────┘ └──────────────┘ └───────────────────────────┘ │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────────────────┐ │
│ │ KQL Search │ │ Microsoft │ │ Azure MCP Server │ │
│ │ (Schema) │ │ Learn (Docs) │ │ (ARM + Monitor) │ │
│ └─────────────┘ └──────────────┘ └───────────────────────────┘ │
│ ┌─────────────┐ │
│ │ Sentinel │ │
│ │ Graph (Rel) │ │
│ └─────────────┘ │
├────────────────────────────────────────────────────────────────────┤
│ MCP Apps (Local Custom Servers) │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────────────────┐ │
│ │ Geomap │ │ Heatmap │ │ Incident Comment │ │
│ │ (Attack Map)│ │ (Patterns) │ │ (Sentinel Integration) │ │
│ └─────────────┘ └──────────────┘ └───────────────────────────┘ │
├────────────────────────────────────────────────────────────────────┤
│ Python Utilities │
│ generate_report_from_json.py │ enrich_ips.py │ report_generator│
└────────────────────────────────────────────────────────────────────┘关键部件:
- 25代理技能 --针对事件、用户、设备、IoC、身份验证、范围漂移(SPN/用户/设备)、MCP监控、暴露管理、AI代理姿态、应用程序注册姿态、身份姿态、数据安全分析、电子邮件威胁姿态、MITRE ATT&CK覆盖范围、摄入分析、检测编写、威胁脉冲扫描、SVG仪表板等的模块化调查工作流程
- 7 MCP服务器集成 -Sentinel Data Lake、Graph API、Defender XDR Triage、KQL Search、Microsoft Learn、Azure MCP Server、Sentinel Graph(私人预览)
- 3个本地MCP应用程序 --交互式热图、地理攻击图、事件评论
- Python实用程序 --使用IP丰富功能生成HTML报告(地理位置、VPN检测、滥用分数、Shodan端口/服务/CVE情报)
______________________________________________________________________
🤖 代理技能
该系统使用 VS代码代理技能 提供模块化、特定领域的调查工作流程。技能会根据提示中的关键字自动检测。
可用技能(25)
| 类别 | 技能 | 描述 | 触发关键字 |
|---|---|---|---|
| ⚡ 快速扫描 | 威胁脉冲 | 跨7个域的快速广谱安全扫描:活动事件、身份(人+NHI)、端点、电子邮件威胁、管理和云操作、暴露。带有颜色编码的判断和深入建议的优先威胁脉冲调查结果 | “威胁脉冲”、“快速扫描”、“安全脉冲”、《晨间狩猎》、“你能做什么”、“我从哪里开始”、“发生了什么” |
| 🔍 核心调查 | 计算机调查 | Entra加入、混合加入和Entra注册设备的设备安全分析:Defender警报、合规性、登录用户、漏洞、进程/网络/文件事件 | “调查计算机”、“调查设备”、“研究端点”、“检查机器”、主机名 |
| 🔍 核心调查 | 蜜罐调查 | 蜜罐安全分析:攻击模式、威胁情报、漏洞、高管报告 | “蜜罐”、“攻击分析”、“威胁行为者” |
| 🔍 核心调查 | 事故调查 | Defender XDR和Sentinel事件的综合事件分析:关键性评估、实体提取、过滤、递归实体调查 | “调查事件”、“事件ID”、“分析事件”、 |
| 🔍 核心调查 | 国际奥委会调查 | 入侵分析指标:IP地址、域、URL、文件哈希。包括Defender威胁情报、Sentinel TI表、CVE相关性、组织暴露 | “调查IP”、“调查域”、“研究URL”、“分析哈希”、“IoC”、“这是恶意的吗” |
| 🔍 核心调查 | 用户调查 | Entra ID用户安全分析:登录、异常、MFA、设备、审计日志、事件、身份保护、HTML报告 | “调查用户”、“安全调查”、“检查用户活动”、UPN/电子邮件 |
| 🔐 身份验证和访问 | 身份验证跟踪 | Entra ID认证链取证:SessionId分析、令牌重用与交互式MFA、地理异常 | “跟踪认证”、“SessionId分析”、“令牌重用”、“地理异常” |
| 🔐 身份验证和访问 | ca政策调查 | 条件访问策略取证:登录失败关联、策略状态更改、安全绕过检测 | “条件访问”、“CA策略”、“设备合规性”、“策略绕过” |
| 📈 行为分析 | 瞄准镜漂移检测/装置 | 设备进程漂移:可配置的窗口基线、5维漂移分数(数量/进程/账户/链/签名)、全机队或单个设备、心跳正常运行时间确证 | “设备漂移”、“端点漂移”、”进程基线“、”设备行为变化“ |
| 📈 行为分析 | 示波器漂移检测/spn | SPN范围漂移:90天基线与7天比较,5维漂移评分,与AuditLogs、SecurityAlert、DeviceNetworkEvents | “范围漂移”、“服务主体漂移”、”SPN行为变化“、”SPN漂移“相关 |
| 📈 行为分析 | 范围漂移检测/用户 | 用户范围漂移:90天基线与7天比较,双漂移分数(7-dim交互式+6-m非交互式),与AuditLogs、SecurityAlert、身份保护、CloudAppEvents、EmailEvents | “用户漂移”、“用户范围漂移”、”用户行为变化“、”UPN漂移“相关 |
| 🛡️ 姿势和曝光 | 暴露调查 | 漏洞和暴露管理报告:利用漏洞/CVSS数据进行CVE评估、安全配置合规性、支持终止软件、ExposureGraph关键资产、攻击路径、Defender健康状况、证书状态 | “漏洞报告”、“暴露报告”、”CVE评估“、”安全态势“、”TVM“ |
| 🛡️ 姿势和曝光 | 人工智能代理姿势 | Copilot Studio和M365 Copilot代理的AI代理安全态势审计:代理库存、身份验证漏洞、访问控制配置错误、MCP工具激增、知识源暴露、XPIA风险、凭证检测、代理安全评分 | “AI代理态势”、“代理安全审计”、“Copilot工作室代理”、“代理人库存”、“未经身份验证的代理”、 |
| 🛡️ 姿势和曝光 | 应用程序注册姿势 | 应用注册和服务主体安全态势:图形API权限清单(危险授予、权限集中)、应用所有权风险、凭据卫生(陈旧机密、多凭据应用)、跨租户SPN暴露、KQL攻击链检测(AuditLogs、AADServicePrincipalSignInLogs、MicrosoftGraphActivityLogs)、5维应用权限风险评分 | “应用注册态势”、“应用注册滥用”、“服务主体权限”、“危险应用权限”、 |
| 🛡️ 姿势和曝光 | 电子邮件威胁态势 | Microsoft Defender for Office 365的电子邮件威胁防护态势报告:入站邮件流概述、威胁构成(网络钓鱼/垃圾邮件/恶意软件)、电子邮件身份验证(DMARC/DKIM/SPF/CompAuth)、ZAP交付后补救、安全链接点击保护、附件分析、检测方法细分、MDO安全事件、5维电子邮件保护评分。内联聊天、markdown文件和SVG仪表板输出 | “电子邮件威胁报告”、“电子邮件安全态势”、“网络钓鱼报告”、”MDO报告“、”Office 365防御者报告“、“ZAP有效性”、“安全链接报告”“、”DMARC报告“ |
| 🛡️ 姿势和曝光 | 身份姿态 | 使用IdentityAccountInfo(MDI/高级狩猎)的身份安全态势报告:多提供商帐户清单(Entra ID、AD、Okta、SailPoint、CyberArk、Ping)、具有角色分配的特权帐户审计、过时/禁用/删除的帐户卫生、密码态势、风险分布、多提供商身份链接、MDI标签分析、5维身份态势评分。内联聊天和markdown文件输出 | “身份状态”、“身份安全报告”、“帐户卫生”、“过时帐户”、“特权帐户”、”密码状态“、”身份提供者“、”honeytoken“ |
| 🔒 数据安全 | 数据安全分析 | DataSecurityEvents(权限/IRM)分析:SIT访问故障、用户风险排名、文件清单、DLP策略相关性、复制副本SIT暴露、SIT GUID到名称解析、异常检测。专为10万+用户环境设计 | “数据安全”、“敏感信息类型”、“SIT访问”、“DLP事件”、“DataSecurityEvents”、“EDM访问”,“内部风险活动”、“权限数据安全” |
| 📊 可视化 | geomap可视化 | Sentinel数据的交互式世界地图可视化:攻击源地图、地理威胁分布、IP地理定位以及丰富的向下钻取 | “geomap”、“世界地图”、“地理”、“攻击图”、“袭击源” |
| 📊 可视化 | 热图可视化 | Sentinel数据的交互式热图可视化:按时间、活动网格、IP与小时矩阵、威胁情报钻取 | “热图”、“显示热图”,“可视化模式”、“活动网格”划分的攻击模式 |
| 📊 可视化 | svg仪表板 | SVG数据可视化仪表板:双模式渲染器,支持清单驱动的结构化仪表板(来自技能报告)和来自特别调查数据的自由形式自适应可视化。14小部件组件库 | “生成SVG仪表板”、“创建可视化仪表板”,“可视化此报告”,“从此数据生成SVG” |
| 🔧 工具和监控 | 检测编辑 | 通过Graph API创建、部署、更新和管理Defender XDR自定义检测规则。从Sentinel KQL进行查询自适应,通过PowerShell进行清单驱动的批量部署,生命周期管理 | “创建自定义检测”、“部署检测”、 |
| 🔧 工具和监控 | kql查询编写 | 使用模式验证创建KQL查询、社区示例、Microsoft Learn | “编写KQL”、“创建KQL询问”、“KQL帮助”、“查询\[表\]” |
| 🔧 工具和监控 | mcp使用监控 | MCP服务器使用情况监控和审计:图表MCP端点分析、Sentinel MCP身份验证事件、Azure MCP ARM操作、工作区查询治理、MCP使用情况评分,包括5个健康/风险维度 | “MCP使用情况”、“MCP服务器监控”、“MCP-活动”、“MVP审计”、“图表MCP”、“Sentinel MCP”和“Azure MCP” |
| 🔧 工具和监控 | 哨兵摄入报告 | Sentinel工作区摄入和成本分析:表级容量细分、层分类(Analytics/Basic/Data Lake)、SecurityEvent/Syslog/CommonSecurityLog深入分析、摄入异常检测、通过REST API的分析规则清单、通过Graph API的自定义检测清单、通过SentinelHealth的规则健康状况、数据湖层迁移候选、许可证利益分析(DfS P2,M365 E5) | “摄入报告”、“使用报告”、《数据量》、“成本分析”、“表细分”、“数据湖层”、“摄入异常”、“成本优化” |
| 🔧 工具和监控 | mitre报道 | MITRE ATT&CK覆盖率分析:YAML驱动的PowerShell管道收集分析规则MITRE标签、自定义检测技术、SOC优化建议、警报/事件操作数据。战术级覆盖矩阵、技术级钻取规则映射、覆盖差距识别、SOC优化威胁场景对齐、未标记规则补救、MITRE覆盖评分(5个加权维度)。内联聊天和标记文件输出 | “MITRE覆盖率”、“ATT&CK覆盖率”,“MITRE报告”、“战术覆盖率”和“技术覆盖率”。“覆盖差距”、“MITRE评分”、“检测覆盖率报告”和“MITRE矩阵” |
技能如何发挥作用
- 你问副驾驶一个问题(例如,“调查user@domain.com过去7天”)
- Copilot检测关键字并从中加载相应的技能
.github/skills//SKILL.md - 该技能提供专门的工作流程、KQL查询和风险评估标准
- 通用模式来自
.github/copilot-instructions.md自动继承
自然语言触发技巧
您无需提及技能名称——关键字会自动检测:
| 你说什么 | 技能触发 |
|---|---|
| “调查user@domain.com过去7天“ | 用户调查 |
| “分析事件12345” | 事件调查 |
| “此IP是恶意的吗?203.0.113.42” | ioc调查 |
| “检查设备WORKSTATION-01是否存在威胁” | 计算机调查 |
| “在热图上显示攻击模式” | 热图可视化 |
| “从报告生成SVG仪表板” | SVG仪表板 |
| “绘制这些攻击的地理起源图” | 地理地图可视化 |
| “编写KQL查询以查找失败的登录” | KQL查询编写 |
| “将此身份验证追溯到原始MFA” | 身份验证跟踪 |
| “检测服务主体中的作用域漂移” | 作用域漂移检测/spn |
| “检查用户行为漂移user@domain.com“ | 范围漂移检测/用户 |
| “分析整个机队的设备过程漂移” | 范围漂移检测/设备 |
| “显示过去30天的MCP服务器使用情况” | MCP使用情况监控 |
| “生成哨兵摄入报告” | 哨兵摄入报告 |
| “为事件ID 4799创建自定义检测” | 检测编写 |
| “审计AI代理安全态势” | AI代理态势 |
| “谁访问了带有信用卡号的文件?” | 数据安全分析 |
| “生成电子邮件威胁防护报告” | 电子邮件威胁态势 |
| “运行身份姿势报告” | 身份姿势 |
| “生成MITRE ATT&CK覆盖率报告” | MITRE覆盖率报告 |
| “运行威胁脉冲扫描” | 威胁脉冲 |
| “审核我们的应用程序注册安全状态” | 应用程序注册状态 |
跟进和链接
进行调查后,在不重新运行整个工作流程的情况下提出后续问题:
Is that IP a VPN?
Trace authentication for that suspicious location
Was MFA used for those sign-ins?技能可以链接起来进行综合分析:
1. "Investigate incident 12345" → incident-investigation extracts entities
2. "Now investigate the user from that incident" → user-investigation runs on extracted UPN
3. "Check if that IP is malicious" → ioc-investigation analyzes the suspicious IP
4. "Show me a heatmap of the attack patterns" → heatmap-visualizationCopilot使用来自以下来源的现有调查数据 temp/investigation_*.json 如果可用。
发现技能
What investigation skills do you have access to?
Explain the high-level workflow of the user-investigation skill
What data sources does the ioc-investigation skill use?📖 参考:
从调查中创作新技能和疑问
临时调查自然会演变为可重复使用的资产。完成调查后,请Copilot将经过验证的查询、模式陷阱和分析逻辑打包到新的SKILL.md或查询文件中。
"Based on the investigation we just completed, create a new reusable skill"
"Read this threat intel article: — extract TTPs and IOCs, then write, test, and tune a queries file for reusable threat hunts"______________________________________________________________________
📁 项目结构
security-investigator/
├── enrich_ips.py # Standalone IP enrichment utility
├── config.json # Configuration (workspace IDs, mappings)
├── config.json.template # Config template (committed to Git)
├── .env # API tokens (gitignored, auto-loaded by python-dotenv)
├── .env.template # Token template (committed to Git)
├── requirements.txt # Python dependencies
├── requirements.lock # Hash-verified dependency lockfile
├── .vscode/
│ └── mcp.json.template # MCP server config template (copy to mcp.json)
├── .github/
│ ├── copilot-instructions.md # Skill detection, universal patterns, routing
│ ├── manifests/ # Auto-generated discovery indexes
│ │ ├── discovery-manifest.yaml # Query file + skill index (domains, MITRE, prompts)
│ │ └── build_manifest.py # Manifest generator script
│ └── skills/ # 25 Agent Skills (modular investigation workflows)
│ ├── ai-agent-posture/
│ ├── app-registration-posture/
│ ├── authentication-tracing/
│ ├── ca-policy-investigation/
│ ├── computer-investigation/
│ ├── data-security-analysis/
│ ├── detection-authoring/
│ ├── email-threat-posture/
│ ├── exposure-investigation/
│ ├── geomap-visualization/
│ ├── heatmap-visualization/
│ ├── honeypot-investigation/
│ ├── identity-posture/
│ ├── incident-investigation/
│ ├── ioc-investigation/
│ ├── kql-query-authoring/
│ ├── mcp-usage-monitoring/
│ ├── mitre-coverage-report/
│ ├── scope-drift-detection/
│ │ ├── spn/ # Service principal drift (5 dimensions)
│ │ ├── user/ # User account drift (7+6 dimensions)
│ │ └── device/ # Device process drift (5 dimensions)
│ ├── sentinel-ingestion-report/
│ ├── svg-dashboard/
│ ├── threat-pulse/
│ └── user-investigation/
├── queries/ # Verified KQL query library (grep-searchable, by data domain)
│ ├── cloud/ # Cloud app & exposure management queries
│ ├── email/ # Defender for Office 365 email queries
│ ├── endpoint/ # Defender for Endpoint device queries
│ ├── identity/ # Entra ID / Azure AD identity queries
│ ├── incidents/ # SecurityIncident & SecurityAlert queries
│ └── network/ # Network telemetry queries
├── scripts/ # Python utilities
│ ├── generate_report_from_json.py # Report generator (main entry point)
│ ├── report_generator.py # HTML report builder class
│ ├── investigator.py # Data models and core types
│ ├── cleanup_old_investigations.py # Automated cleanup (3+ days old)
│ └── generate_tocs.py # Auto-generate query file TOCs
├── mcp-apps/ # Local MCP servers (visualization, automation)
│ ├── sentinel-geomap-server/
│ ├── sentinel-heatmap-server/
│ └── sentinel-incident-comment/
├── docs/ # Setup guides and reference documentation
├── authoring/ # Blog drafts, writing guides, and marketing content
├── reports/ # Generated investigation reports (organized by type)
│ ├── ai-agent-posture/ # AI agent security posture reports
│ ├── app-registration-posture/ # App registration posture reports
│ ├── computer-investigations/ # Device security investigation reports
│ ├── data-security/ # Data security SIT analysis reports
│ ├── email-threat-posture/ # Email threat protection posture reports
│ ├── exposure/ # Exposure management reports
│ ├── honeypot/ # Honeypot executive reports
│ ├── identity-posture/ # Identity security posture reports
│ ├── mcp-usage/ # MCP usage monitoring reports
│ ├── scope-drift/ # Scope drift analysis reports
│ ├── sentinel/ # Sentinel ingestion & cost analysis reports
│ ├── threat-pulse/ # Threat Pulse scan reports
│ └── user-investigations/ # HTML user investigation reports
├── temp/ # Investigation JSON files (auto-cleaned after 3 days)
└── archive/ # Legacy code and design docs查询库(queries/)
这 queries/ 文件夹包含 经过验证、实战测试的KQL查询集合 按检测场景组织。这些是 优先级2查找源 在 KQL飞行前检查表 --Copilot在编写任何ad-hoc KQL之前会搜索它们。
每个文件都使用标准化的元数据头,以提高效率 grep_search 发现:
#
**Tables:**
**Keywords:**
**MITRE:**
**Domains:** 发现清单(.github/manifests/)
这 发现清单 提供所有查询文件和技能的机器可读索引,支持通过域和MITRE技术进行确定性交叉引用。Threat Pulse技能加载此清单,以将发现与下游查询文件相匹配,并自动深入技能。
discovery-manifest.yaml--紧凑型索引(~500行)title,path,domains,mitre,以及prompt每个查询文件和技能的字段build_manifest.py--扫描的生成器脚本queries/元数据头和技能YAML frontmatter来生成清单
它是如何工作的:
- 查询文件声明
**Domains:**元数据标头中的标签(有效标签:incidents,identity,spn,endpoint,email,admin,cloud,exposure) - 技能声明
threat_pulse_domains:和drill_down_prompt:在他们的YAML frontmatter中 python .github/manifests/build_manifest.py扫描两者并发出清单- 威胁脉冲技能读取清单以匹配非-✅ 发现→ 域标记和MITRE技术重叠的相关查询文件和技巧
再生后 创建或重命名查询文件/技能,或更改 Domains:/threat_pulse_domains: 值:
python .github/manifests/build_manifest.py______________________________________________________________________
🚀 设置
先决条件
| 要求 | 详细信息 |
|---|---|
| VS Code | 建议使用1.99+版本(代理模式+MCP支持)。 |
| GitHub Copilot | 主动订阅-- Copilot Pro+商业或企业。必须启用代理模式。 |
| Python 3.8+ | 用于IP丰富实用程序和报告生成。 下载 |
| Azure命令行界面 | Azure MCP服务器(底层身份验证)和 sentinel-ingestion-report 技能(az monitor log-analytics query 对于所有KQL查询, az rest 对于分析规则清单, az monitor log-analytics workspace table list 用于层级分类)。 安装.身份验证: az login --tenant 那么 az account set --subscription 。需要 日志分析阅读器 (KQL查询+表列表)和 微软哨兵阅读器 (分析规则清单)。 |
log-analytics CLI扩展 | 要求由 sentinel-ingestion-report 技能为 az monitor log-analytics query (第1-5阶段中的所有KQL查询)。安装: az extension add --name log-analytics.验证: az extension list --query "[?name=='log-analytics']". |
| PowerShell 7.0+ | 需要 sentinel-ingestion-report 技能(通过并行查询执行 ForEach-Object -Parallel). 安装.验证: $PSVersionTable.PSVersion. |
| Node.js 18+ | KQL搜索MCP所需(npx)以及构建本地MCP应用程序。 下载 或通过安装 winget install OpenJS.NodeJS.LTS (Windows)/ brew install node (macOS)。 |
| 微软哨兵 | 带有数据的日志分析工作区。您需要工作区GUID和租户ID |
| 参赛者ID权限 | 如果您可以在Azure门户中查询Sentinel,那么您可能有足够的访问权限。这 Graph MCP服务器 需要 一次性租户配置 由管理员。看 MCP服务器设置 了解每台服务器的详细要求。 |
| 微软。图形PowerShell | 需要 detection-authoring 技能(CustomDetection.ReadWrite.All -通过Graph API创建/更新/删除自定义检测规则)。也被使用 sentinel-ingestion-report 规则盘点技能(CustomDetection.Read.All --只读、如果不安装则优雅降级)。 Install-Module Microsoft.Graph.Authentication -Scope CurrentUser. |
| GitHub PAT | public_repo 范围-- 在此处创建一个。由KQL搜索MCP使用。 |
1.安装依赖项
验证先决条件:
python --version # Requires 3.8+
node --version # Requires 18+ (needed for KQL Search MCP)
az --version # Azure CLI (needed for Azure MCP Server, ingestion report skill)
pwsh --version # Requires 7.0+ (needed for sentinel-ingestion-report skill)如果缺少Node.js: 下载 或奔跑 winget install OpenJS.NodeJS.LTS (Windows)/ brew install node (macOS)。 如果缺少Azure CLI: 安装那么 az login --tenant 和 az account set --subscription . 如果 log-analytics 缺少扩展名: az extension add --name log-analytics (需要 sentinel-ingestion-report 技能)。
设置Python环境:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt2.配置环境
复制 config.json.template 到 config.json 并填写您的工作区详细信息:
{
"sentinel_workspace_id": "YOUR_WORKSPACE_ID_HERE",
"tenant_id": "YOUR_TENANT_ID_HERE",
"subscription_id": "YOUR_SUBSCRIPTION_ID_HERE",
"azure_mcp": {
"resource_group": "YOUR_LOG_ANALYTICS_RESOURCE_GROUP",
"workspace_name": "YOUR_LOG_ANALYTICS_WORKSPACE_NAME",
"tenant": "YOUR_TENANT_ID_HERE",
"subscription": "YOUR_SUBSCRIPTION_ID_HERE"
},
"output_dir": "reports"
}| 设置 | 必填 | 说明 |
|---|---|---|
sentinel_workspace_id | 是 | Microsoft Sentinel(日志分析)工作区GUID |
tenant_id | 是 | Sentinel工作区的Entra ID(Azure AD)租户ID |
subscription_id | 是 | 包含Sentinel工作区的Azure订阅ID |
azure_mcp.* | 是 | Azure MCP服务器参数--资源组、工作区名称、租户、订阅。需要避免跨租户身份验证错误。 |
output_dir | 否 | HTML报告目录(默认: reports) |
API令牌(.env 文件)
用于IP丰富的API令牌存储在 .env 文件(gitignored)而不是 config.json 为了安全。复制模板并添加密钥:
copy .env.template .env
# Edit .env with your token valuesIPINFO_TOKEN=your_token_here
ABUSEIPDB_TOKEN=your_token_here
VPNAPI_TOKEN=your_token_here
SHODAN_TOKEN=your_token_here这些是由自动加载的 enrich_ips.py 通过 python-dotenv --不需要人工采购。
| 令牌 | 必填 | 描述 |
|---|---|---|
IPINFO_TOKEN | 推荐 | Fo.io API代币-地理位置,ASN,组织。免费:1K/天;代币:50K/月;付费计划包括VPN检测 |
ABUSEIPDB_TOKEN | 推荐 | 滥用IPDB API代币-IP信誉评分(0-100置信度)。免费:1K/天 |
VPNAPI_TOKEN | 可选 | Vpnapi。 API令牌-VPN/代理/Tor检测。如果ipinfo.io是付费计划,则不需要 |
SHODAN_TOKEN | 可选 | 肖丹 API密钥-开放端口,服务,CVE,操作系统检测,标签。如果没有密钥或信用耗尽,则免费InternetDB回退 |
3.配置MCP服务器
复制MCP服务器模板(所有平台服务器+3个可选的MCP应用程序已预先配置):
copy .vscode/mcp.json.template .vscode/mcp.json该模板包括每个服务器的内联文档。首次使用时,VS Code将提示:
- Entra ID登录 --Sentinel Data Lake、Graph、Triage和Sentinel Graph服务器的基于浏览器的身份验证
- **** --用于KQL搜索MCP(模式智能和查询发现)。需要
public_repo范围。
看 MCP服务器设置 下面是每台服务器的权限和安装指南。
4.构建MCP应用程序(可选——可视化技能)
PowerShell(Windows):
cd mcp-apps/sentinel-geomap-server; npm install; npm run build; cd ../..
cd mcp-apps/sentinel-heatmap-server; npm install; npm run build; cd ../..
cd mcp-apps/sentinel-incident-comment; npm install; npm run build; cd ../..Bash(macOS/Linux):
cd mcp-apps/sentinel-geomap-server && npm install && npm run build && cd ../..
cd mcp-apps/sentinel-heatmap-server && npm install && npm run build && cd ../..
cd mcp-apps/sentinel-incident-comment && npm install && npm run build && cd ../..______________________________________________________________________
🔌 MCP服务器设置
该系统使用多个模型上下文协议(MCP)服务器。都是 预配置 在 .vcode/mcp.模板 --复制到 .vscode/mcp.json 开始(参见 上述步骤3).以下部分记录了每台服务器的权限、工具和安装指南。
概览
| # | 服务器 | MCP URL/传输 | 设置指南 | 密钥权限 |
|---|---|---|---|---|
| 1 | 哨兵数据湖 | https://sentinel.microsoft.com/mcp/data-exploration | 设置 | 日志分析阅读器 |
| 2 | 微软图形 | https://mcp.svc.cloud.microsoft/enterprise | 设置 | 用户。读。全部,设备。读。全部 |
| 3 | 哨兵分类 | https://sentinel.microsoft.com/mcp/triage | 设置 | 安全阅读器 |
| 4 | KQL搜索 | npx -y kql-search-mcp (stdio) 设置 | (public_repo) | |
| 5 | 微软学习 | https://learn.microsoft.com/api/mcp | 设置 | 无(免费) |
| 6 | Azure MCP服务器 | VS代码扩展(stdio) | 设置 | 订阅时的贡献者或读者 |
| 7 | 哨兵图 ⚠️ | https://sentinel.microsoft.com/mcp/graph | 博客 | 哨兵阅读器-- *内测* |
1.微软哨兵MCP服务器
📖 安装指南
工具: query_lake, search_tables, list_sentinel_workspaces
权限:
- 日志分析阅读器 (最小)--查询工作区数据
- 哨兵阅读器 (推荐)--全面的调查能力
- 哨兵贡献者 --监视列表管理(可选)
2.微软Graph的MCP服务器
📖 安装指南
工具: microsoft_graph_suggest_queries, microsoft_graph_get, microsoft_graph_list_properties
⚡ 一次性租户配置 (要求 应用程序管理员 或 云应用管理员 角色):
# 1. Install the Entra Beta PowerShell module (v1.0.13+)
Install-Module Microsoft.Entra.Beta -Force -AllowClobber
# 2. Authenticate to your tenant
Connect-Entra -Scopes 'Application.ReadWrite.All', 'Directory.Read.All', 'DelegatedPermissionGrant.ReadWrite.All'
# 3. Register the MCP Server and grant permissions to VS Code
Grant-EntraBetaMCPServerPermission -ApplicationName VisualStudioCode这只需要做 每位租户一次配置后,租户中的所有用户都可以通过使用自己的帐户登录来使用Graph MCP服务器。
权限(委派,每个用户):
- 用户。读。全部 --用户配置文件和身份验证方法
- 用户身份验证方法。读。全部 --MFA方法
- 设备。读。全部 --设备合规性和注册
- 身份风险事件。读。全部 --身份保护风险检测
3.微软哨兵分类MCP服务器
📖 安装指南
工具(30+): RunAdvancedHuntingQuery, ListIncidents, GetAlertById, GetDefenderMachine, GetDefenderFileInfo, GetDefenderIpAlerts, ListUserRelatedMachines, GetDefenderMachineVulnerabilities以及更多。
权限:
- 用于Endpoint API的Microsoft Defender --SecurityReader角色最小值
- 高级狩猎 --读取Defender XDR数据
4.KQL搜索MCP服务器
📖 安装指南
选项A:VS代码扩展(推荐)
- 扩展面板→ 搜索“KQL搜索MCP”→ 安装
- 命令面板→
KQL Search MCP: Set GitHub Token
选项B:NPX --已在中配置 .vscode/mcp.json.template只需要一个 和 public_repo 范围(首次使用时提示)。
工具(34): 模式智能、查询验证、GitHub搜索、支持331+个表的ASIM。
5.微软学习MCP服务器
📖 安装指南
单击一下: 在VS代码中安装 --或已在中配置 .vscode/mcp.json.template.
工具: microsoft_docs_search, microsoft_docs_fetch, microsoft_code_sample_search
无需API密钥-免费,微软云托管。
6.Azure MCP服务器
📖 安装指南
通过VS代码扩展安装:在扩展中搜索“Azure MCP服务器”,或从 市场。该扩展自动注册为stdio MCP服务器。
工具: monitor_workspace_log_query, monitor_activitylog_list, group_list, subscription_list以及40多个命名空间,涵盖人工智能、身份、安全、数据库、存储、计算和网络。
权限:
- 读者 (最低)--对Azure资源的只读访问
- 日志分析阅读器 --for
workspace_log_query(KQL反对日志分析) - 贡献者 --用于写入/修改操作(可选)
配置: 需要 azure_mcp 参数在 config.json (租户、订阅、资源组、工作区名称)以避免跨租户身份验证错误。看 配置环境.
7.哨兵图MCP服务器⚠️ 内测
注: Sentinel Graph当前处于 内测 并非所有客户都可以使用。如果您的租户没有访问权限,此服务器将无法连接——您可以安全地将其从 .vscode/mcp.json。请参阅 公告博客文章 了解详情和报名。工具: 实体图探索和关系查询。
权限:
- 哨兵阅读器 (最小值)
在中预先配置 .vscode/mcp.json.template首次使用时基于浏览器的Entra ID登录。
验证设置
打开 副驾驶聊天 (Ctrl+Shift+I)in 代理模式 并尝试以下提示:
| 测试 | 提示输入副驾驶聊天 |
|---|---|
| 哨兵数据湖 | List my Sentinel workspaces |
| 微软图形 | Look up my user profile in Graph |
| 哨兵分类 | List recent security incidents |
| KQL搜索 | What columns does the SigninLogs table have? |
| 微软学习 | Search Microsoft docs for KQL query language |
| 所有技能 | What investigation skills do you have access to? |
如果任何服务器发生故障,请检查 MCP服务器 VS Code中的面板(单击 {} 底部状态栏中的图标),以验证每个服务器是否显示绿色连接状态。
______________________________________________________________________
⚙️ 配置详情
API速率限制(IP富集)
| 提供商 | 免费等级 | 带令牌 |
|---|---|---|
| Fo.io | 1000/天(地理、组织、ASN) | 50000/月;付费计划包括VPN检测 |
| 滥用IPDB | 1000美元/天 | 10000美元/天(每月20美元) |
| Vpnapi。 | 1000美元/月 | 10000美元/月(9.99美元/月) |
| 肖丹 | InternetDB(无限制,端口/漏洞/标签) | 49美元一次性会员费:每月100次查询(添加服务、横幅、SSL、操作系统) |
令牌优先级: 如果 ipinfo_token 是付费计划,包括VPN检测 vpnapi_token 是可选的。当付费密钥可用时,Shodan使用完整的API;在403/429上,它自动回退到免费的InternetDB。
IP富集发生在 报告生成 (不是数据收集),因此您可以在不重新查询Sentinel/Graph的情况下重新生成报告。
依赖项
pip install -r requirements.txt核心包: 请求: (用于丰富API的HTTP客户端), python日期工具 (KQL时间范围的日期解析)。
______________________________________________________________________
🔒 安全考虑
- 机密数据 --报告包含PII和敏感的安全数据。标记为机密,并遵循组织数据分类政策。
- 访问控制 --限制SOC授权人员进入。将Azure RBAC用于Sentinel,将PIM用于Graph API权限。
- 审计跟踪 --所有调查都有时间戳。JSON文件
temp/保存快照;HTML报告包括生成元数据。 - 数据保留 --超过3天的调查将自动删除(可配置)。在清理之前,将重要调查归档。
- API代币安全 --永不承诺
config.json带有令牌(已在.gitignore).使用环境变量或Azure密钥库进行生产。 - 调查JSON文件 --存储在
temp/(未提交到Git)。包含完整的数据,包括IP丰富。无需重新查询即可重新分析。
______________________________________________________________________
🛠️ 故障排除
| 问题 | 解决方案 | |
|---|---|---|
| “未发现异常” | Signinlogs_Anomalies_KQL_CL 表不存在或没有数据。请参阅用户调查技能文档。等待24小时,等待初始种群。 | |
| “IP富集失败” | ipinfo.io费率限制(1K/天免费)。将令牌添加到 config.json 每月5万。 | |
| “MCP服务器不可用” | 检查VS Code MCP服务器配置。验证身份验证令牌是否有效。 | |
| “找不到用户ID”(图表) | 验证UPN是否正确。检查图形权限:用户。读。全部。 | |
| “哨兵查询超时” | 缩小日期范围。添加 `\ | take 10` 以限制结果。 |
| 报告生成失败 | 验证JSON: python -m json.tool temp/investigation_*.json。检查必填字段。 | |
| SecurityIncident返回0个结果 | 两者都用 targetUPN 和 targetUserId (对象ID)。某些事件使用对象ID | |
| 危险登录404 | 必须使用 /beta 端点,不是 /v1.0. |
验证连接性
在 副驾驶聊天 (代理模式):
"List my Sentinel workspaces"--验证Sentinel数据湖MCP"Look up user@domain.com in Graph"--验证Graph MCP"List recent incidents"--验证哨兵分类MCP
在 终端:
python enrich_ips.py 8.8.8.8 # Verifies IP enrichment API tokens______________________________________________________________________
🧠 (可选)持久租户上下文
GitHub Copilot Chat in VS Code为代理提供了 memory 工具 --内置文件系统(/memories/)用于在对话中持续记录笔记。Copilot已经在内部使用了它;您可以使用租户特定的上下文(已知的基础设施IP、经过验证的人员、假阳性模式、实验室自动化签名)对其进行扩展,这样调查就不会反复将记录的活动错误分类为🔴 关键。
两个内存层是相关的:
| 层 | 路径 | 自动加载? | 用于 |
|---|---|---|---|
| 用户内存 | /memories/*.md | ✅ 是(约200行) | 短触发规则(“当你看到租户X时,读取回购文件Y”) |
| 回购存储器 | /memories/repo/*.md | ❌ 仅文件名 | 富租户上下文(IP、人员、FP模式)——由触发规则引入 |
内存工具是一种内部代理功能——VS Code不会为其发布专门的文档页面 自定义指令 和 代理技能,它们服务于不同的目的(分别始终应用约定和专门的工作流程)。
此工作区附带了:
- 模板 在
notes/memory/examples/--复制并适应您的租户(一个用户层示例,两个仓库层示例) - 同步脚本
scripts/sync-repo-memory.ps1--备份工作区范围(repo)内存从VS Code AppData转移到工作区文件夹中,在重新安装VS Code和重命名工作区后幸存下来。连接到工作区(OneDrive、Dropbox、iCloud等)的任何云同步都会在机器之间镜像备份。默认为单向导出(ToBackup);恢复模式(FromBackup)要求-Force因为它会写入Copilot的可信内存存储。 - 安装指南
notes/memory/README.md--完整的演练、同步使用、安全模型和触发规则模式,使Copilot实际查询存储库内存
快速入门: 从打开模板 notes/memory/examples/,然后在聊天中询问Copilot *“在以下位置将其创建为内存文件 /memories/...,将占位符替换为我的租户值。"* Copilot使用其 memory 直接编写它的工具——不需要AppData路径导航。
⚠️ 内存=可信输入。 任何东西notes/memory/repo/成为未来每次聊天中Copilot的权威指令(使用MCP工具访问Sentinel、Graph、Azure)。在还原之前,请检查分叉/PR的差异,切勿粘贴机密,如果您的工作区是云同步的,请确认目标是否符合安全上下文。看notes/memory/README.md对于完整的威胁模型。
______________________________________________________________________
📄 许可证
该项目根据 MIT许可证.使用它,分叉它,使其适应你的SOC——只需保留版权声明。
______________________________________________________________________
🙏 致谢
微软安全平台
- 微软哨兵 --SIEM/SOAR平台为所有KQL查询和事件管理提供支持
- Microsoft Defender XDR --高级狩猎、设备遥测、漏洞管理
- Microsoft Graph API --Entra ID身份数据、用户/组管理、角色分配
- Microsoft Entra ID保护 --风险检测、风险登录、用户风险状态
MCP服务器
- 哨兵数据湖MCP --对Sentinel工作区执行KQL查询
- 哨兵分类MCP --事件分类、高级狩猎、防御实体API
- Microsoft Graph的MCP服务器 -图形API端点发现和执行
- KQL搜索MCP --模式智能、GitHub KQL查询发现、ASIM验证
- 微软学习 MCP --官方文档搜索和代码示例检索
威胁情报API
- Fo.io --IP地理定位、ISP/ASN识别、主机提供商检测
- Vpnapi。 --VPN、代理、Tor出口节点和中继检测
- 滥用IPDB --社区来源的IP滥用评分和最近的攻击报告
- 肖丹 --开放端口枚举、服务/横幅检测、CVE识别、基础设施标记
开发工具
- **** --AI编码助手为自然语言调查界面提供动力
- VS代码代理技能 --专门调查工作流程的模块化技能框架
- 模型上下文协议(MCP) --将LLM连接到外部数据源和工具的开放协议
特别感谢Microsoft Security社区分享KQL查询和检测逻辑,以及 斯蒂芬 针对Sentinel事件评论MCP模式。
