GetSetPOx

<div align="center"> # GetSetPOx 中转服务器 ### 通过 AI 代理驱动 Microsoft Entra、Global Secure Access、Intune 和 IGA 概念验证。 一个模型上下文协议（MCP）服务器，暴露由 **Microsoft Graph** 驱动的工具，用于 **Entra ID**、**Global Secure Access（互联网访问）**、**Identity Governance（IGA）** 和 **Intune**，以便 AI 代理可以通过自然语言建立和操作 Microsoft 身份和安全概念验证。 [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io/) [](#configuration-for-vs-code) [](https://github.com/psf/black) [](LICENSE) [概述](#-overview) · [工具目录](#-tool--service-catalog) · [快速入门](#-getting-started) · [VS Code 设置](#configuration-for-vs-code) · [配置](#️-configuration) · [开发](#-development) </div> --- ## 🎯 概述 **GetSetPOx** 是一个基于 Python 的 MCP 服务器，旨在 **快速交付 Microsoft 概念验证**。将其连接到任何与 MCP 兼容的客户端（VS Code、Claude 或您自己的代理），并驱动真正的 Microsoft Graph 操作 — 列出和创建 Entra 用户/组/设备，配置 Global Secure Access 网络内容过滤，管理 Intune 设备和应用部署，构建 Identity Governance 访问包 — 所有这些都通过工具调用而不是点击门户。 **亮点：** - ✨ 清洁、模块化的 **每域服务** 架构 — 轻松扩展新的工具 - 🔄 双重传输：**STDIO** （默认）和 **HTTP** - 🛡️ 完整的 **OAuth2 / MSAL** 身份验证，用于 Microsoft Graph（应用程序和委托模式） - 🧪 内置 **权限诊断**，测试 19 个关键 Graph 权限，并通过实时 API 调用返回可行的成功/失败报告 - 📦 作为源代码 **或** 独立可执行文件发布（无需安装 Python） - 📝 结构化日志记录和环境变量配置 > **用途：** 将多步骤的 Microsoft 身份/安全概念验证转换为少数代理指令 — 可重复，具有相同的 Graph 调用。 --- ## 适用对象 | 您是… | 使用 GetSetPOx 来… | |---|---| | **身份/安全预销售工程师** | 从您的代理快速启动 Entra + GSA + Intune 演示环境。 | | **Microsoft 365 / Entra 管理员** | 在没有定制代码的情况下，脚本化可重复的 Graph 操作（用户、组、设备、策略）。 | | **AI 代理 / MCP 构建者** | 通过标准协议将经过战斗测试的 Microsoft Graph 工具集插入您的代理。 | | **概念验证 / 实验室作者** | 在一次调用中自动化端到端的 Web 内容过滤和访问包设置。 | --- ## 目录 - [🎯 概述](#-overview) - [🧰 工具和服务目录](#-tool--service-catalog) - [🔐 身份验证和安全](#-authentication--security) - [🚀 快速入门](#-getting-started) - [VS Code 配置](#configuration-for-vs-code) - [⚙️ 配置](#️-configuration) - [🧪 测试](#-testing) - [🔧 开发](#-development) - [📋 示例用法](#-example-usage) - [🤝 贡献](#-contributing) - [📄 许可证](#-license) --- ## 🧰 工具和服务目录 ### 🧪 测试和诊断 - **hello_world** — 用于测试 MCP 连接的简单问候服务 - **echo** — 带有元数据的回声服务，用于验证和调试 - **check_token_permissions** — 全面的 Microsoft Graph 权限诊断；测试 19 个关键权限，并通过实时 API 调用返回可行的成功/失败报告 ### 👤 Entra ID（EID）管理 - **EID_listUsers** — 列出 Microsoft Entra ID 中的所有用户 - **EID_getUser** — 按 ID 或 userPrincipalName 获取特定用户 - **EID_searchUsers** — 按显示名称或电子邮件搜索用户 - **EID_listDevices** — 列出所有设备（Entra 加入、混合加入、注册、合规） - **EID_getDevice** — 按 ID 获取特定设备详细信息 - **EID_getGroups** / **EID_getGroup** — 列出组（分页）或按 ID 获取组 - **EID_getGroupMembers** — 获取特定组的成员 - **EID_searchGroups** — 按显示名称搜索组 - **EID_createUserGroups** — 创建和管理具有用户和嵌套组的 安全组 ### 🛂 身份治理和管理（IGA） - **IGA_listAccessPackages** — 列出 Entitlement Management 中的所有访问包 - **IGA_createAccessCatalog** — 创建新的访问包目录 - **IGA_createAccessPackage** — 创建新的访问包 - **IGA_addResourceGrouptoPackage** — 将 Entra 组作为资源添加到访问包 ### 💻 Intune 设备管理 - **IN_listIntuneManagedDevices** — 列出所有 Intune 管理的设备 - **IN_getManagedDeviceDetails** — 详细的设备信息（合规性、注册、同步状态） - **IN_listDeviceCompliancePolicies** — 列出所有设备合规性策略 - **IN_listDeviceConfigurationProfiles** — 列出所有配置配置文件 - **IN_syncManagedDevice** — 触发设备与 Intune 的同步 - **IN_prepGSAWinClient** — 准备 Global Secure Access Windows 客户端进行部署 - **IN_intuneAppAssignment** — 将 Win32 应用分配到设备组，并设置部署 ### 🌐 Global Secure Access — 互联网访问（IA） - **IA_checkInternetAccessForwardingProfile** — 检查转发配置文件状态 - **IA_enableInternetAccessForwardingProfile** — 启用/禁用转发配置文件 - **IA_createFilteringPolicy** — 创建网页分类过滤策略 - **IA_createFilteringProfile** — 创建过滤配置文件 - **IA_linkPolicyToFilteringProfile** — 将策略链接到配置文件，并记录 - **IA_createConditionalAccessPolicy** — 为过滤配置文件创建 CA 策略 - **IA_TLSPOCV2** — 用于检查的先进 TLS 证书工作流程 - **IA_internetAccessPoc** — 自动化端到端 Web 内容过滤概念验证设置 --- ## 🔐 身份验证和安全 - **Entra ID（Azure AD）OAuth2** — Microsoft Graph 的完整身份验证 - **多种身份验证模式** — 应用程序（守护进程）使用客户端凭证，或通过设备代码流委托（用户） - **令牌管理** — 自动刷新、安全缓存和到期检查 - **MSAL 集成** — 使用 Python 的 Microsoft 身份验证库 - **非阻塞身份验证** — 后台身份验证保持服务器启动快速 - **安全存储** — 令牌缓存写入具有限制的文件权限 完整设置： **[docs/authentication.md](docs/authentication.md)** · 安全策略： **[SECURITY.md](SECURITY.md)** --- ## 🚀 快速入门 ### 先决条件 - Python 3.10+ 和 `pip`（或 `uv`）— *如果使用独立可执行文件，则不需要* ### 选项 1 — 独立可执行文件（最快） 无需安装 Python。 **Windows：** 从发行版下载 `getset-pox-mcp.exe` → 创建 `.env`（参见 [`.env.example`](.env.example)）→ 运行 `getset-pox-mcp.exe`。 **Linux/macOS：** 下载 `getset-pox-mcp` → `chmod +x getset-pox-mcp` → 创建 `.env` → 运行 `./getset-pox-mcp`。 自行构建： **[BUILD_INSTRUCTIONS.md](BUILD_INSTRUCTIONS.md)**。 ### 选项 2 — 从源代码安装 ```bash git clone https://github.com/jeevanbisht/GetSetPOx.git cd GetSetPOx python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -e ".[dev]" ``` ### 选项 3 — 使用 uv ```bash uv venv source .venv/bin/activate # Windows: .venv\Scripts\activate uv pip install -e ".[dev]" ``` --- ## VS Code 配置 将服务器添加到 VS Code 的 `settings.json` 或 `mcp.json` 中。 ### STDIO 模式（默认） ```json { "mcp": { "servers": { "getset-pox-mcp": { "command": "python", "args": ["-m", "getset_pox_mcp.server"], "env": { "LOG_LEVEL": "INFO" } } } } } ``` ### HTTP 模式 ```json { "mcp": { "servers": { "getset-pox-mcp": { "command": "python", "args": ["-m", "getset_pox_mcp.server"], "env": { "TRANSPORT": "http", "HTTP_HOST": "127.0.0.1", "HTTP_PORT": "3000", "HTTP_PATH": "/mcp", "LOG_LEVEL": "INFO" } } } } } ``` --- ## ⚙️ 配置 通过环境变量（例如，在 `.env` 文件中）配置服务器。 ### 服务器 | 变量 | 描述 | 默认值 | 示例 | |----------|-------------|---------|---------| | `TRANSPORT` | 传输模式（`stdio` 或 `http`） | `stdio` | `http` | | `HTTP_HOST` | HTTP 主机（HTTP 模式） | `127.0.0.1` | `0.0.0.0` | | `HTTP_PORT` | HTTP 端口（HTTP 模式） | `3000` | `8080` | | `HTTP_PATH` | HTTP 端点路径（HTTP 模式） | `/mcp` | `/api/mcp` | | `STATELESS_HTTP` | 使用无状态 HTTP 模式 | `false` | `true` | | `LOG_LEVEL` | 日志级别 | `INFO` | `DEBUG` | | `LOG_FILE` | 日志文件路径 | 无 | `logs/server.log` | ### 身份验证（Entra ID） | 变量 | 必需 | 默认值 | 描述 | |----------|----------|---------|-------------| | `ENTRA_ENABLE_AUTH` | 否 | `false` | 启用身份验证 | | `ENTRA_TENANT_ID` | 是\* | – | Azure AD 租户 ID | | `ENTRA_CLIENT_ID` | 是\* | – | 应用程序（客户端）ID | | `ENTRA_CLIENT_SECRET` | 是\*\* | – | 客户端密钥 | | `ENTRA_AUTH_MODE` | 否 | `application` | `application` 或 `delegated` | | `ENTRA_SCOPES` | 否 | `https://graph.microsoft.com/.default` | 以逗号分隔的作用域 | \* 启用身份验证时需要 \*\* 应用程序模式下需要 完整说明： **[docs/authentication.md](docs/authentication.md)**。 --- ## 🧪 测试 ```bash pytest tests/ # 运行测试套件 pytest --cov=getset_pox_mcp tests/ # 带有覆盖率 ``` --- ## 🔧 开发 ### 项目结构 ``` GetSetPOx/ ├── getset_pox_mcp/ # 主包 │ ├── server.py # 服务器入口点 + 工具注册 │ ├── config.py # 配置管理 │ ├── logging_config.py # 日志设置 │ ├── authentication/ # OAuth2 提供者、中间件、令牌管理器 │ ├── transport/ # 传输层实现 │ └── services/ # MCP 服务和工具（每个域一个文件夹） │ ├── diagnostics/ # Graph 权限诊断 │ ├── eid/ # Entra ID 管理 │ ├── iga/ # 身份治理 │ ├── intune/ # Intune 设备管理 │ ├── internetAccess/ # Global Secure Access — 互联网访问 │ ├── poc/ # 概念验证编排实用程序 │ └── Test/ # hello_world, echo ├── docs/authentication.md # 身份验证设置指南 ├── scripts/ # setup.bat / setup.sh ├── tests/ # 测试套件 ├── BUILD_INSTRUCTIONS.md # PyInstaller 构建指南 ├── ENV_PACKAGING_GUIDE.md # 配置打包指南 ├── getset-pox-mcp.spec # PyInstaller 规范 ├── pyproject.toml # 项目配置 ├── CHANGELOG.md · CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md └── LICENSE ``` ### 构建独立可执行文件 ```bash # 快速构建（嵌入 .env） prepare_env_for_build.bat # Windows ./prepare_env_for_build.sh # Linux/macOS # 手动构建 pip install pyinstaller pyinstaller getset-pox-mcp.spec # 输出在 dist/ (~24 MB) ``` 参见 **[BUILD_INSTRUCTIONS.md](BUILD_INSTRUCTIONS.md)** 和 **[ENV_PACKAGING_GUIDE.md](ENV_PACKAGING_GUIDE.md)**。 ### 添加新服务 1. 在 `getset_pox_mcp/services/<domain>/` 中创建工具： ```python from typing import Any async def my_tool(param1: str, param2: int) -> dict[str, Any]: """您的工具描述。 参数： param1: param1 描述 param2: param2 描述 返回： 结果字典 """ return {"result": "success"} ``` 2. 在 `getset_pox_mcp/server.py` 中注册它： ```python from .services.<domain>.my_tools import my_tool # 在 register_tools() 中： @mcp.tool() async def my_tool_handler(param1: str, param2: int) -> dict[str, Any]: """工具描述""" return await my_tool(param1, param2) ``` ### 在开发环境中运行 ```bash python -m getset_pox_mcp.server # STDIO 传输 TRANSPORT=http python -m getset_pox_mcp.server # HTTP 传输 ``` --- ## 📋 示例用法 配置完成后，通过任何与 MCP 兼容的客户端进行交互： ``` 用户： 调用具有名称“Alice”的 hello_world 工具 代理： [调用 hello_world] 服务器： {"message": "Hello, Alice! Welcome to getset-pox-mcp."} 用户： 回声 “test message” 代理： [调用 echo] 服务器： { "original": "test message", "echoed": "test message", "timestamp": "2025-01-16T19:40:00.000Z", "length": 12 } ``` --- ## 🤝 贡献 欢迎贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。 1. 复刻仓库并创建功能分支 2. 使用适当的测试进行更改 3. 确保 `pytest` 通过 4. 提交拉取请求 --- ## 📄 许可证 [MIT](LICENSE) — 请参阅 LICENSE 文件了解详情。 ## 🔗 资源 - [模型上下文协议规范](https://modelcontextprotocol.io/) - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - [fabric-rti-mcp 参考](https://github.com/microsoft/fabric-rti-mcp) ## 📝 更新日志 请参阅 [CHANGELOG.md](CHANGELOG.md) 获取版本历史。