Ubuntu_mcp_server

安全 Python

🚀 安全的Ubuntu MCP服务器

🔒 这是一款以安全为首要考量的模型上下文协议（MCP）服务器，专为保障Ubuntu系统的安全操作而设计。它为AI助手提供对Ubuntu系统操作的安全、可控访问，具备全面的安全控制、审计日志记录和纵深防御原则。

✨ 主要特性

🛡️ 安全优先架构

路径遍历保护：通过允许列表/拒绝列表控制进行符号链接解析。
命令清理：通过安全的参数解析防止shell注入。
资源限制：对文件大小、执行超时时间和输出大小进行控制。
全面的审计日志记录：记录所有操作并关联用户信息。
纵深防御：具备多个安全层，并采用故障安全默认设置。

🎯 核心功能

文件操作：在验证权限的前提下，进行文件的读取、写入和目录列表操作。
命令执行：通过白名单/黑名单过滤，安全地执行shell命令。
系统信息：监控操作系统细节、内存和磁盘使用情况。
软件包管理：搜索和列出APT软件包（安装需要明确配置）。

🏗️ 生产就绪

模块化设计：各功能模块职责明确。
全面的错误处理：提供有意义的错误信息。
广泛的测试套件：包括安全验证测试。
可配置策略：适用于不同的用例和环境。
零依赖安全机制：核心安全功能不依赖外部软件包。

🚀 快速开始

前提条件

Ubuntu 18.04及以上版本（已在20.04、22.04、24.04版本上测试）。
Python 3.9或更高版本。
标准Unix实用工具（如ls、cat、echo等）。

安装

# 克隆仓库
git clone https://github.com/yourusername/secure-ubuntu-mcp.git
cd secure-ubuntu-mcp

# 创建并激活虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 使用内置测试验证安装
python main.py --test

基本用法

# 使用安全策略启动（推荐）
python main.py --policy secure

# 使用开发策略启动（更宽松）
python main.py --policy dev

# 测试安全措施
python main.py --security-test

💻 使用示例

基础用法

# 使用安全策略启动服务器
python main.py --policy secure

高级用法

# 在调试模式下启动服务器，并使用安全策略
python main.py --log-level DEBUG --policy secure

📚 详细文档

🔧 集成

Claude Desktop

在Linux上获取Claude Desktop

官方支持情况：Claude Desktop官方不支持Linux，但社区已经提供了解决方案！ 推荐方法：使用@aaddrick提供的社区Debian软件包：

# 下载并安装适用于Linux的Claude Desktop
wget https://github.com/aaddrick/claude-desktop-debian/releases/latest/download/claude-desktop_latest_amd64.deb
sudo dpkg -i claude-desktop_latest_amd64.deb
sudo apt-get install -f  # 修复任何依赖问题

如需了解其他方法和故障排除信息，请参阅：https://github.com/aaddrick/claude-desktop-debian

配置

Claude Desktop安装完成后，将以下内容添加到配置文件（~/.config/claude-desktop/claude_desktop_config.json）中：

{
"mcpServers": {
"secure-ubuntu": {
"command": "/path/to/secure-ubuntu-mcp/.venv/bin/python3",
"args": ["/path/to/secure-ubuntu-mcp/main.py", "--policy", "secure"],
"env": {
"MCP_LOG_LEVEL": "INFO"
}
}
}
}

⚠️ 重要提示：请使用绝对路径和虚拟环境的Python解释器。

验证：重启Claude Desktop后，你应该会看到“secure-ubuntu”作为已连接的服务器列出，并且Claude将可以访问系统控制工具。

其他MCP客户端

该服务器实现了标准的MCP协议，可与任何兼容MCP的客户端配合使用：

# 使用mcp Python客户端的示例
import asyncio
from mcp.client import ClientSession

async def example():
# 连接到服务器
# 具体实现取决于你的MCP客户端
pass

🛡️ 安全策略

安全策略（默认）

推荐用于生产环境和不可信环境：

允许路径：~/, /tmp, /var/tmp
禁止路径：/etc, /root, /boot, /sys, /proc, /dev, /usr, /bin, /sbin
命令白名单：ls, cat, echo, pwd, whoami, date, find, grep, apt（仅搜索）
资源限制：1MB文件，15s超时时间，256KB输出
sudo权限：禁用
shell执行：禁用（使用安全的直接执行方式）

开发策略

适用于开发环境，限制更宽松：

额外允许路径：/opt, /usr/local
更少限制：可访问更多系统区域
更大限制：10MB文件，60s超时时间，1MB输出
更多命令：允许使用大多数开发工具
sudo权限：默认仍禁用（可启用）

自定义策略

创建自己的安全策略：

from main import SecurityPolicy

custom_policy = SecurityPolicy(
allowed_paths=["/your/custom/paths"],
forbidden_paths=["/sensitive/areas"],
allowed_commands=["safe", "commands"],
forbidden_commands=["dangerous", "commands"],
max_command_timeout=30,
allow_sudo=False,  # 谨慎使用
audit_actions=True
)

🔍 可用工具

文件操作

list_directory(path)：列出目录内容并包含元数据。
read_file(file_path)：读取文件内容并进行大小验证。
write_file(file_path, content, create_dirs=False)：使用原子操作进行文件写入。

系统操作

execute_command(command, working_dir=None)：安全地执行shell命令。
get_system_info()：获取操作系统、内存和磁盘信息。

软件包管理

search_packages(query)：搜索APT软件包仓库。
install_package(package_name)：检查软件包可用性（仅列出）。

🔒 安全特性

防范常见攻击

路径遍历防范：

# 以下路径均会被阻止：
../../../etc/passwd
/etc/passwd
/tmp/../etc/passwd
symlinks_to_sensitive_files

命令注入防范：

# 以下命令均会被阻止：
echo hello; rm -rf /
echo `cat /etc/passwd`
echo $(whoami)
ls | rm -rf /

资源耗尽防范：

文件大小限制防止内存耗尽。
执行超时时间防止进程挂起。
输出大小限制防止日志泛滥。
目录列表限制防止枚举攻击。

审计跟踪

所有操作都会记录以下信息：

用户信息
时间戳和操作类型
完整路径解析
成功/失败状态
安全违规详情

🧪 测试

功能测试

# 测试核心功能
python main.py --test

安全验证

# 运行全面的安全测试
python main.py --security-test

手动测试

# 直接测试MCP协议
python test_client.py --simple

📊 示例用法

与AI助手集成后：

系统监控：

"检查我的系统状态和磁盘空间"

文件管理：

"列出我主目录中的文件，并显示最大的文件"

开发任务：

"检查是否安装了Python，并显示版本信息"

日志分析：

"查找我项目目录中的所有错误文件"

⚙️ 配置

环境变量

MCP_LOG_LEVEL：日志级别（DEBUG, INFO, WARNING, ERROR）
MCP_POLICY：安全策略（secure, dev）
MCP_CONFIG_PATH：自定义配置文件的路径

配置文件

创建config.json进行自定义设置：

{
"server": {
"name": "secure-ubuntu-controller",
"version": "1.0.0",
"log_level": "INFO"
},
"security": {
"policy_name": "secure",
"allowed_paths": ["~/", "/tmp"],
"max_command_timeout": 30,
"allow_sudo": false,
"audit_actions": true
}
}

🛠️ 开发

添加新工具

@mcp.tool("your_tool_name")
async def your_tool(param: str) -> str:
"""AI助手使用的工具描述"""
try:
# 使用控制器方法进行安全操作
result = controller.safe_operation(param)
return json.dumps(result, indent=2)
except Exception as e:
return json.dumps({"error": str(e)}, indent=2)

扩展安全机制

def create_custom_policy() -> SecurityPolicy:
"""创建自定义安全策略"""
return SecurityPolicy(
allowed_paths=["/your/paths"],
forbidden_commands=["dangerous", "commands"],
# ... 其他设置
)

🔧 故障排除

常见问题

“服务器似乎挂起”

这是正常现象！MCP服务器会持续运行，并通过标准输入输出进行通信。
服务器正在等待MCP协议消息。

“ModuleNotFoundError: No module named 'mcp'”

确保你使用的是虚拟环境的Python解释器。
检查Claude Desktop配置是否使用了.venv/bin/python3的完整路径。

“SecurityViolation”错误

检查路径/命令是否被你的安全策略允许。
查看/tmp/ubuntu_mcp_audit.log中的审计日志。
考虑使用开发策略进行测试。

“Permission denied”错误

验证你的用户是否有权限访问请求的路径。
使用ls -la检查文件/目录权限。

调试模式

# 启用详细日志记录
python main.py --log-level DEBUG --policy secure

# 查看审计日志
tail -f /tmp/ubuntu_mcp_audit.log

🤝 贡献

我们欢迎贡献！请参阅我们的贡献指南以获取详细信息。

开发设置

分叉仓库。
创建功能分支：git checkout -b feature/amazing-feature。
进行更改并编写测试。
确保所有测试通过：python main.py --test && python main.py --security-test。
提交拉取请求。

代码标准

遵循PEP 8风格指南。
为所有公共函数添加类型提示。
包含全面的文档字符串。
为新功能编写测试。
坚持安全优先原则。

📄 许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件。

🔐 安全披露

如果您发现安全漏洞，请发送电子邮件至 [radjackbartok@proton.me]，而不是创建公开问题。我们非常重视安全问题，并将及时响应。

🙏 致谢

模型上下文协议团队提供了优秀的协议。
安全研究人员和信息安全社区分享了最佳实践。
Python安全社区提供了持续的指导。

📈 路线图

[ ] 增强日志记录：提供结构化的JSON日志，并包含更多上下文信息。
[ ] 容器支持：集成Docker，并支持容器感知策略。
[ ] 网络工具：提供安全的网络实用工具（如ping、traceroute等）。
[ ] 进程管理：安全地监控和控制进程。
[ ] 配置用户界面：提供用于策略管理的Web界面。
[ ] 集成测试：进行全面的端到端测试。
[ ] 性能优化：通过缓存和其他方式提高性能。
[ ] 多用户支持：实现基于角色的访问控制。

为注重安全的AI社区打造

💡 使用建议：从安全策略开始，根据需要逐步增加权限。添加权限比从安全事件中恢复要容易得多！

0 条评论
分类：安全