安全的Ubuntu MCP服务器
🔒 安全第一 用于安全Ubuntu系统操作的模型上下文协议服务器
已硬化，可生产 模型上下文协议（MCP） 为AI助手提供以下功能的服务器 安全、受控的访问 Ubuntu系统操作。构建了全面的安全控制、审计日志和深度防御原则。
   
✨ 主要特点
🛡️ 安全第一架构
- 路径遍历保护 -具有allowlist/denylist控件的Symlink解析
- 命令清理 -通过安全参数解析防止外壳注入
- 资源限制 -文件大小、执行超时和输出大小控制
- 全面的审计日志记录 -所有记录有用户归因的操作
- 纵深防御 -具有故障安全默认值的多个安全层
🎯 核心能力
- 文件操作 -通过权限验证读取、写入和列出目录
- 命令执行 -使用白名单/黑名单过滤执行安全shell命令
- 系统信息 -操作系统详细信息、内存和磁盘使用情况监控
- 包管理 -APT包搜索和列表（安装需要显式配置）
🏗️ 生产就绪
- 模块化设计 明确分离关注点
- 全面的错误处理 带有有意义的错误信息
- 广泛的测试套件 包括安全验证测试
- 可配置策略 适用于不同的用例和环境
- 零依赖安全 -核心安全不依赖于外部包
🚀 快速开始
先决条件
- Ubuntu 18.04+（在20.04、22.04、24.04上测试）
- Python 3.9或更高版本
- 标准Unix实用程序（ls、cat、echo等）
安装
# Clone the repository
git clone https://github.com/yourusername/secure-ubuntu-mcp.git
cd secure-ubuntu-mcp
# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Verify installation with built-in tests
python main.py --test基本用法
# Start with secure policy (recommended)
python main.py --policy secure
# Start with development policy (more permissive)
python main.py --policy dev
# Test security measures
python main.py --security-test🔧 整合
克劳德桌面
在Linux上安装Claude Desktop
官方支持：Claude Desktop没有正式支持Linux，但社区已经创建了解决方案！
推荐方法：使用社区Debian软件包@aaddrick：
# Download and install Claude Desktop for Linux
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 # Fix any dependency issues有关其他方法和故障排除，请参阅：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的客户端一起工作：
# Example with mcp Python client
import asyncio
from mcp.client import ClientSession
async def example():
# Connect to the server
# Implementation depends on your MCP client
pass🛡️ 安全策略
安全策略（默认）
建议用于生产环境和不受信任的环境：
- 允许的路径:
~/,/tmp,/var/tmp - 禁止的路径:
/etc,/root,/boot,/sys,/proc,/dev,/usr,/bin,/sbin - 命令白名单:
ls,cat,echo,pwd,whoami,date,find,grep,apt（仅搜索） - 资源限制：1MB文件，15秒超时，256KB输出
- 南：已禁用
- 壳牌执行：禁用（使用安全直接执行）
发展政策
对开发环境更加宽容：
- 其他允许的路径:
/opt,/usr/local - 更少的限制：访问更多系统区域
- 更大的限制：10MB文件，60秒超时，1MB输出
- 更多命令：允许使用大多数开发工具
- 南：默认情况下仍禁用（可以启用）
自定义策略
创建自己的安全策略：
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, # Use with extreme caution
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)-检查套餐可用性（仅列出）
🔒 安全功能
防止常见攻击
路径穿越预防:
# These are all blocked:
../../../etc/passwd
/etc/passwd
/tmp/../etc/passwd
symlinks_to_sensitive_files命令注入预防:
# These are all blocked:
echo hello; rm -rf /
echo `cat /etc/passwd`
echo $(whoami)
ls | rm -rf /资源枯竭保护:
- 文件大小限制可防止内存耗尽
- 执行超时可防止挂起进程
- 输出大小限制可防止日志泛滥
- 目录列表限制可防止枚举攻击
审计跟踪
所有操作都记录在：
- 用户归因
- 时间戳和操作类型
- 全路径分辨率
- 成功/失败状态
- 安全违规详细信息
🧪 测试
功能测试
# Test core functionality
python main.py --test安全验证
# Run comprehensive security tests
python main.py --security-test手动测试
# Test MCP protocol directly
python test_client.py --simple📊 示例用法
一旦与AI助手集成：
系统监控:
“检查我的系统状态和磁盘空间”
文件管理:
“列出主目录中的文件，并显示最大的文件”
开发任务:
“检查是否安装了Python并显示版本”
日志分析:
“在我的项目目录中查找任何错误文件”
⚙️ 配置
环境变量
MCP_LOG_LEVEL-日志记录级别（调试、信息、警告、错误）MCP_POLICY-安全策略（安全、开发）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:
"""Tool description for AI assistant"""
try:
# Use controller methods for safe operations
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:
"""Create a custom security policy"""
return SecurityPolicy(
allowed_paths=["/your/paths"],
forbidden_commands=["dangerous", "commands"],
# ... other settings
)🔧 故障排除
常见问题
“服务器似乎挂起”
- 这很正常！MCP服务器持续运行，并通过stdio进行通信
- 服务器正在等待MCP协议消息
“ModuleNotFoundError:没有名为'mcp'的模块”
- 确保您使用的是虚拟环境Python解释器
- 检查您的Claude Desktop配置是否使用了完整路径
.venv/bin/python3
“安全违规”错误
- 检查您的安全策略是否允许路径/命令
- 在以下网址查看审计日志
/tmp/ubuntu_mcp_audit.log - 考虑使用开发策略进行测试
“权限被拒绝”错误
- 验证您的用户是否可以访问请求的路径
- 检查文件/目录权限
ls -la
调试模式
# Enable verbose logging
python main.py --log-level DEBUG --policy secure
# Check audit logs
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许可证获得许可-请参阅 许可证 文件以获取详细信息。
🔐 安全披露
如果您发现安全漏洞，请发送电子邮件至\[radjackbartok@proton.me\]而不是制造公共问题。我们认真对待安全问题，并将迅速作出回应。
🙏 致谢
- 模型上下文协议 优秀协议团队
- 安全研究人员和信息安全社区的最佳实践
- Python安全社区提供持续指导
📈 路线图
- \[ \] 增强日志记录 -具有更多上下文的结构化JSON日志记录
- \[ \] 容器支持 -Docker集成和容器感知策略
- \[ \] 网络工具 -安全网络工具（ping、traceroute等）
- \[ \] 流程管理 -安全过程监控
- \[ \] 配置UI -用于策略管理的Web界面
- \[ \] 集成测试 -全面的端到端测试
- \[ \] 性能优化 -缓存和性能改进
- \[ \] 多用户支持 -基于角色的访问控制
______________________________________________________________________
专为注重安全的人工智能社区打造
💡 专业提示：从安全策略开始，根据需要逐步增加权限。添加权限比从安全事件中恢复更容易！