btepmmcp (Wesharris222)

BeyondTrust EPM MCP服务器

模型上下文协议（MCP）服务器，用于通过Claude Desktop和其他MCP客户端管理BeyondTrust端点特权管理（EPM）。

特性

• 🔐 策略管理：创建、读取和管理EPM策略和应用程序
• 📋 计算机管理：列出、授权和组织受管端点
• 👥 用户和组管理：管理EPM用户、角色和计算机组
• 🔍 文件检查：安全提取文件元数据以创建策略（Windows PE文件）
• 📊 审计与监控：访问活动审核、事件和授权请求
• ✅ 管理员访问请求：创建、批准和拒绝管理员访问请求

🚀 快速开始

先决条件

• Python 3.14或更高版本
• 紫外线 包管理器
• 克劳德桌面 （或另一个MCP客户端）
• BeyondTrust具有API凭据的EPM实例

安装

1.克隆存储库

git clone https://github.com/wesharris222/btepmmcp.git
cd btepmmcp

2.安装依赖项

uv sync

这将安装：

• httpx -用于EPM API的HTTP客户端
• mcp -模型上下文协议SDK
• pefile -用于文件检查的PE文件解析器

3.获取您的EPM API证书

从您的BeyondTrust EPM控制台：

1. 引导到 配置 → API注册
2. 创建新的API客户端
3. 复制以下值：

- 基础URL: https://[your-subdomain]-services.pm.beyondtrustcloud.com - 客户端ID：您的API客户端ID（GUID） - 客户端密钥：您的API客户机密

4.配置克劳德桌面

窗户： 编辑 %APPDATA%\Claude\claude_desktop_config.json

macOS： 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json

Linux： 编辑 ~/.config/Claude/claude_desktop_config.json

添加此配置：

{
  "mcpServers": {
    "beyondtrust-epm": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/path/to/btepmmcp",
        "run",
        "bt_epm_mcpv1.py"
      ],
      "env": {
        "BT_EPM_BASE_URL": "https://YOUR-SUBDOMAIN-services.pm.beyondtrustcloud.com",
        "BT_EPM_CLIENT_ID": "your-client-id-here",
        "BT_EPM_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

重要提示： 替换以下内容：

• C:/path/to/btepmmcp → 克隆仓库的实际路径
• YOUR-SUBDOMAIN → 您的EPM子域
• your-client-id-here → 您的API客户端ID
• your-client-secret-here → 您的API客户机密

5.重新启动克劳德桌面

关闭并重新打开Claude Desktop以加载MCP服务器。

6.验证安装

在Claude Desktop中，尝试：

List all EPM policies

如果配置正确，Claude将使用MCP服务器检索您的策略！

______________________________________________________________________

📖 用法示例

策略管理

List all policies

Show me the details for policy ID 063caa3a-a1fe-4f41-a1d3-994ad5cb0d7a

List applications in policy 063caa3a-a1fe-4f41-a1d3-994ad5cb0d7a

文件检查（安全-不执行）

Inspect the file at C:\Program Files\7-Zip\7zFM.exe

返回如下文件属性：

• 文件名、大小、哈希值（SHA256、SHA1）
• 出版商、产品名称、版本
• 不执行文件的所有元数据

创建策略应用程序

Create a policy application:
- Policy ID: 063caa3a-a1fe-4f41-a1d3-994ad5cb0d7a
- Application Group ID: 5c28a0a9-c133-4f19-9378-0b12f5fe7b77
- Type: exe
- Description: 7-Zip File Manager
- Publisher: Igor Pavlov
- Product Name: 7-Zip

计算机管理

List all computers

Show unauthorized computers

Authorize computer IDs [id1, id2] and assign to group [group-id]

用户管理

List all EPM users

Create a user with email john.doe@company.com and role ID [role-id]

管理员访问请求

Create an admin access request for computer [computer-id]

Approve admin access request [request-id] by user john.doe@company.com

______________________________________________________________________

🛠️ 可用工具

MCP服务器提供以下工具（由Claude自动使用）：

策略管理

• list_policies -列出所有政策
• get_policy_details -获取详细的政策信息
• list_policy_application_groups -在策略中列出应用程序
• create_policy_application -将应用程序添加到策略中

文件检查

• inspect_file_for_policy -安全提取文件元数据

计算机管理

• list_computers -列出受管理的计算机
• get_computer_details -获取计算机详细信息
• authorize_computers -授权计算机
• assign_computers_to_group -将计算机分配给组

组管理

• list_groups -列出计算机组
• create_group -创建新组

用户管理

• list_users -列出EPM用户
• create_user -创建新用户

监控与审计

• get_activity_audits -获取审核日志
• search_events -搜索EPM事件
• list_authorization_requests -列出授权请求
• get_authorization_request_details -获取请求详细信息

管理员访问请求

• list_admin_access_requests -列出管理员访问请求
• get_admin_access_request_details -获取请求详细信息
• create_admin_access_request -创建新请求
• approve_admin_access_request -批准请求
• deny_admin_access_request -拒绝请求

______________________________________________________________________

🔒 安全与安保

文件检查安全

这 inspect_file_for_policy 工具是 100%安全:

✅ 从不执行文件 -仅读取元数据\ ✅ 只读操作 -无文件修改\ ✅ 仅进行静态分析 -解析PE结构而不运行代码\ ✅ 行业标准库 -使用受信任的 pefile 图书馆\ ✅ 跨平台 -适用于Windows、Linux、macOS

看 FILE_Inspecting_README.md 了解详情。

API安全

• 使用OAuth 2.0客户端凭据流
• 存储在Claude Desktop配置中的凭据（仅限本地）
• 与BeyondTrust EPM API的HTTPS通信
• 带有过期处理的令牌自动刷新

______________________________________________________________________

📁 文件结构

btepmmcp/
├── bt_epm_mcpv1.py              # Main MCP server
├── pyproject.toml               # Python dependencies
├── README.md                    # This file
├── FILE_INSPECTION_README.md    # File inspection guide
├── IMPLEMENTATION_SUMMARY.md    # Technical details
├── QUICK_START.md              # Quick reference
├── test_file_inspection.py     # Safety tests
└── mcp_output/                 # Query results (auto-created)

______________________________________________________________________

🧪 测试

测试文件检查

uv run python test_file_inspection.py

这验证了：

• 文件未执行
• 元数据已正确提取
• 哈希值已计算
• PE解析工作

手动测试

# Test file inspection
uv run python -c "from bt_epm_mcpv1 import inspect_file_properties; import json; print(json.dumps(inspect_file_properties('C:\\Windows\\System32\\notepad.exe'), indent=2))"

______________________________________________________________________

🌐 与跨平台支持

视窗

• 全部功能
• PE文件元数据提取
• 原生路径支持

Linux

• API完整功能
• 可以检查Windows PE文件（.exe、.dll）
• 使用Linux路径： /usr/bin/app

macOS

• API完整功能
• 可以检查Windows PE文件
• 使用macOS路径： /Applications/App.app/Contents/MacOS/app

______________________________________________________________________

📊 输出文件

所有查询结果都保存到 mcp_output/:

• latest.json -上次查询结果（始终被覆盖）
• _.json -每个查询的存档结果

例子：

mcp_output/
├── latest.json
├── list_policies_2025-11-13T10-30-45-123456.json
├── inspect_file_for_policy_2025-11-13T10-35-22-789012.json
└── create_policy_application_2025-11-13T10-40-15-345678.json

______________________________________________________________________

⚙️ 配置选项

环境变量

必填项（在Claude Desktop配置中设置）：

• BT_EPM_BASE_URL -您的EPM实例URL
• BT_EPM_CLIENT_ID -API客户端ID
• BT_EPM_CLIENT_SECRET -API客户端机密

定制

编辑 bt_epm_mcpv1.py 自定义：

• OUTPUT_DIR （第17行）-更改输出目录
• timeout=30.0 （第146行）-调整HTTP超时
• 工具说明和参数

______________________________________________________________________

🐛 故障排除

“缺少必需的环境变量”

问题： 服务器找不到API凭据

解决方案： 检查你的 claude_desktop_config.json:

1. 验证路径是否正确
2. 确保设置了所有三个环境变量
3. 变量名中没有拼写错误
4. 更改后重新启动Claude Desktop

“无法解析导入文件”

问题： 未安装依赖项

解决方案：

cd /path/to/btepmmcp
uv sync

检查文件时“找不到文件”

问题： 相对路径或路径格式不正确

解决方案： 使用绝对路径：

• 窗户： C:\\Program Files\\App\\app.exe （双反斜杠）
• Linux/Mac： /usr/bin/app

“HTTP错误401未经授权”

问题： API凭据无效

解决方案：

1. 在EPM控制台中验证凭据
2. 检查基本URL格式（必须包括 https://)
3. 确保客户端具有适当的权限

“HTTP错误405方法不允许”

问题： API端点不正确（在v1中修复）

解决方案： 更新到最新版本：

git pull origin main

MCP服务器未加载

问题： Claude Desktop找不到服务器

解决方案：

1. 检查配置中的绝对路径是否正确
2. 验证 uv 在你的路径中
3. 检查克劳德桌面日志：

- 窗户： %APPDATA%\Claude\logs\ - macOS： ~/Library/Logs/Claude/ - Linux： ~/.config/Claude/logs/

______________________________________________________________________

📚 其他资源

• BeyondTrust EPM API文档
• 模型上下文协议规范
• Claude桌面文档

______________________________________________________________________

🤝 贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 测试您的更改
4. 提交拉取请求

______________________________________________________________________

📝 许可证

\[在此处添加您的许可证\]

______________________________________________________________________

💡 提示和最佳实践

政策制定

1. 先检查文件：使用 inspect_file_for_policy 获取准确的元数据
2. 使用发布者匹配：更新时比哈希匹配更灵活
3. 小组测试：在广泛部署之前验证策略

文件检查

1. 始终使用绝对路径：避免路径解析问题
2. 查看提取的属性：并非所有文件都具有所有元数据
3. 合并标准：使用发布者+产品名称可获得最佳效果

安全

1. 保护API凭据：切勿提交具有真实凭据的配置文件
2. 使用最小权限：使用所需的最低权限创建API客户端
3. 查看审核日志：监视EPM审核日志中的MCP服务器操作

______________________________________________________________________

🆘 支持

对于问题或疑问：

1. 检查 故障排除 章节
2. 查看此存储库中的文档文件
3. 查看BeyondTrust EPM API文档
4. 在GitHub上打开一个问题

______________________________________________________________________

✨ 最新动态

v1.0（当前）

• ✅ 修复了405错误 create_policy_application
• ✅ 增加了跨平台文件检查
• ✅ PE元数据提取（发布者、版本、哈希）
• ✅ 全面的文件
• ✅ 安全测试套件

______________________________________________________________________

🎯 路线图

未来的增强功能：

• \[\]批量文件检查
• \[\]目录扫描
• \[\]证书验证
• \[\]策略模板
• \[\]版本比较工具
• \[\]用于配置的Web UI

______________________________________________________________________

准备好自动化您的EPM管理了吗？现在就开始吧！ 🚀