MarketingDotLimited/mcp-sentinel
GitHub: MarketingDotLimited/mcp-sentinel
一个安全加固的 MCP 服务器，允许 AI 云服务在多层认证、审计和审批机制保护下远程管控 Linux 服务器。
Stars: 0 | Forks: 0
# MCP Sentinel 🛡️
[](LICENSE)
[](https://github.com/MarketingDotLimited/mcp-sentinel/actions/workflows/ci.yml)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
[](CONTRIBUTING.md)
一个**经过安全加固的 MCP (Model Context Protocol) 服务器**，允许 AI 云服务（Claude、ChatGPT、Gemini、Cursor 等）通过 Streamable HTTP 安全地控制和管理您的 Linux 服务器。
## ✨ 功能
- **32 个 MCP 工具** — 检查和管理文件、服务、用户、数据库、仓库、沙盒代码和警报
- **多层安全** — API key + JWT token + IP 白名单 + 速率限制 + 审计日志 + 路径沙盒化 + scope 强制执行 + HTTPS + Helmet + CORS
- **基于角色的访问** — `admin` 拥有完全控制权；`user` 被限制在其 home 目录下的沙盒中
- **按用户划分的 API key** — 为不同的用户/服务签发指定 scope 的 key
- **审计日志** — 记录每次工具调用的用户、IP、持续时间和结果（每日轮换的 JSON）
- **审批控制平面** — 可选地要求人类管理员在执行确切的高风险 AI 操作之前进行审批
- **引导式工作流** — 为任何兼容 MCP 的 AI 提供用于诊断、安全审查、备份和部署的自然语言提示
- **项目注册表** — 注册已批准的仓库，并为开发者和 AI 编程代理生成安全的部署计划
- **systemd 就绪** — 开机自启动
## 🚀 快速开始
```
# 1. Clone
git clone https://github.com/MarketingDotLimited/mcp-sentinel.git
cd mcp-sentinel
# 2. 安装依赖
npm install
# 3. 设置（生成 secrets、.env、可选 TLS cert）
node setup.js
# 4. 启动
npm start
# 5. 或作为 system service 运行
cp mcp-server.service /etc/systemd/system/
systemctl enable --now mcp-server
```
## 🔗 连接您的 AI 客户端
Web 仪表板现在包含 **Connect AI** 功能，可提供当前的 endpoint 和平台无关的配置代码片段。为每个 AI 客户端创建指定 scope 的 key，并为能够进行更改的代理启用审批模式。
### Claude Desktop
```
{
"mcpServers": {
"server-control": {
"type": "sse",
"url": "https://YOUR_SERVER_IP:4444/mcp",
"headers": { "X-API-Key": "YOUR_ADMIN_KEY" }
}
}
}
```
### Cursor / VS Code
```
{
"mcpServers": {
"server-control": {
"url": "https://YOUR_SERVER_IP:4444/mcp",
"type": "sse",
"headers": { "X-API-Key": "YOUR_ADMIN_KEY" }
}
}
}
```
## 🛠️ 可用工具
| 类别 | 工具 |
|---|---|
| **System** | `get_system_info`, `get_processes`, `kill_process` |
| **Files** | `read_file`, `write_file`, `delete_file`, `list_directory`, `move_file`, `copy_file`, `get_file_info`, `search_files` |
| **Services** | `manage_service`, `get_service_status`, `list_services`, `get_journal_logs`, `manage_firewall` |
| **Users** | `list_users`, `get_user_info`, `create_user`, `delete_user`, `set_user_password`, `modify_user`, `manage_ssh_keys` |
## 🔐 安全架构
```
AI Client → HTTPS → IP Whitelist → API Key/JWT → Rate Limit → Scope Check → Sandbox → Tool
```
| 层级 | 详情 |
|---|---|
| **HTTPS/TLS** | TLS 1.2+ 及强加密套件 |
| **权限分离** | 工具以映射的 Unix 用户 UID/GID 运行（对于普通用户绝不以 root 运行） |
| **IP 白名单** | 基于 key 或全局的 CIDR 限制（IPv4 和 IPv6） |
| **API Key** | 持久化存储，SHA-256 哈希加密 |
| **JWT Token** | HS256 签名，绑定 IP，短期的 bearer token |
| **速率与会话限制** | 全局限制、认证限制以及并发会话上限 |
| **Scope 强制执行** | 基于 key 的工具访问控制 |
| **路径沙盒** | 防范 symlink，用户被限制在 `/home/{username}` 和私有临时目录中 |
| **审计日志** | 防篡改的结构化 JSON，并进行密钥脱敏 |
## 📁 项目结构
```
├── server.js # Main MCP server (Express + Streamable HTTP)
├── security.js # All auth & security middleware
├── audit.js # Structured audit logging
├── keygen.js # API key generator
├── setup.js # First-time setup wizard
├── mcp-server.service # generated by setup.js when needed
├── .env # generated by setup.js; never commit this file
└── tools/
├── system.js # Shell commands, processes, system info
├── files.js # File system CRUD
├── services.js # systemd & firewall management
└── users.js # User & SSH key management
```
## ⚙️ 配置
运行 `node setup.js` 以创建 `.env`，然后根据需要进行配置：
```
PORT=4444
USE_HTTPS=true
JWT_SECRET=<64-byte random hex>
ADMIN_API_KEY=
ALLOWED_IPS=203.0.113.10,192.168.1.0/24 # optional
RATE_LIMIT_MAX_REQUESTS=60
AUDIT_LOG_KEEP_DAYS=30
# 可选 Authelia/OIDC bearer-token 支持。两者必须同时设置，并且
# JWKS endpoint 必须提供受 Node.js 信任的证书。
AUTHELIA_ISSUER=https://auth.example.com
AUTHELIA_JWKS_URL=https://auth.example.com/jwks.json
OAUTH_RESOURCE_URL=https://mcp.example.com
# 可选 control-plane 存储和 project allow-list
CONTROL_PLANE_STATE_FILE=./data/control-plane.json
GIT_ALLOWED_REPOS=/srv/my-app,/srv/another-app
PUBLIC_URL=https://mcp.example.com
MCP_POLICY_FILE=./policy.json
# 企业运维：在配置每个功能之前，这些是强制性的。
# 使用以下命令生成 CONTROL_PLANE_ENCRYPTION_KEY：openssl rand -hex 32
CONTROL_PLANE_ENCRYPTION_KEY=<64-hex-character-secret>
MCP_FLEET_ALLOWED_HOSTS=sentinel-1.example.com,sentinel-2.example.com
BACKUP_ALLOWED_PATHS=/etc/my-app,/srv/my-app/config
BACKUP_ALLOWED_ROOTS=/var/lib/mcp-sentinel/backups
S3_ALLOWED_HOSTS=s3.example.com
WEBHOOK_ALLOWED_HOSTS=hooks.example.com
PROJECT_HEALTH_ALLOWED_HOSTS=app.example.com
```
对于企业级的 policy-as-code（策略即代码），请将 [policy.example.json](policy.example.json) 复制到仓库之外或受保护的配置路径中，设置 `MCP_POLICY_FILE`，并通过您常规的配置管理流程审查更改。即使 key 本身允许某项操作，策略也可以拒绝该角色的工具，或者要求进行审批。
## 企业级运维
MCP Sentinel 维护一个小型、加密的控制平面状态文件（模式为 `0600`），用于记录已注册的 fleet 服务器、备份目标、webhook、审批、项目和计划。请勿将其置于版本控制之下。
- **Fleet：** 注册每个 Sentinel 的健康检查 endpoint。Sentinel 仅对 `MCP_FLEET_ALLOWED_HOSTS` 中明确列出的主机执行定时的 `GET` 请求；它不会通过 fleet 清单公开远程 shell 访问权限。
- **备份：** 备份目标可以是本地白名单目录或兼容 S3 的 endpoint。仅接受最大为 25 MiB 的白名单常规文件。每个备份在到达目标之前都会进行 AES-256-GCM 加密；S3 凭证在静态状态下加密，且绝不会通过 API 返回。
- **Webhook：** 事件仅发送至 `WEBHOOK_ALLOWED_HOSTS`，禁用重定向，具有十秒的超时时间，并附带 `X-MCP-Sentinel-Signature-256: sha256=` 标头。请仅在 Sentinel 中保留密钥，并在接收方验证此 HMAC。
- **部署：** 创建一个包含白名单仓库和服务的已注册项目。`deploy_project` 仅执行 `git pull --ff-only`，重启那个确切的已注册 systemd 服务，然后检查其 host 位于 `PROJECT_HEALTH_ALLOWED_HOSTS` 中的健康状态 URL。它需要 `confirm: true`、管理员身份，并且在启用审批模式时需要 key 级别的审批。
对于非技术操作员，仪表板的 Guided Help、Approvals、Projects、Automations、Connect AI、Teams 和 Security 页面是首选的起始点。对于 AI 客户端，请首先调用 `list_guided_workflows`，在部署之前使用 `plan_project_deployment`，并使用 `request_change_approval` 提交确切的高风险请求。
## 🔑 生成 API Key
```
# 生成 admin key
node keygen.js admin admin
# 生成 scoped user key
node keygen.js alice user run_command,read_file,write_file
```
## 📊 监控
```
# 实时审计日志
tail -f logs/audit-$(date +%Y-%m-%d).log | jq
# 查看活动会话
curl -k https://localhost:4444/admin/sessions -H "X-API-Key: YOUR_KEY"
# 健康检查
curl -k https://localhost:4444/health
```
## 要求
- Node.js 18+
- Linux（基于 systemd）
- `openssl`（用于 HTTPS）
- Root 或 sudo 权限（以使用完整的管理工具）
## 测试
```
npm test # unit and security tests
npm run test:ui # Playwright browser flow (uses an isolated local Sentinel)
npm run test:live # creates and removes one temporary no-login OS user; run only on a disposable or approved host
```
实时测试验证了低权限的 MCP 身份可以读取系统健康状况，但不能读取 `/etc/shadow` 或创建用户。两个集成测试套件均使用临时的状态、密钥、日志和端口。
## 安全
发现漏洞？请阅读 [SECURITY.md](SECURITY.md) 并私下报告 —— 请勿公开提出 issue。
## 许可证
[MIT](LICENSE) © 2026 [MarketingDotLimited](https://github.com/MarketingDotLimited)
标签：AI集成, GNU通用公共许可证, Linux服务器管理, MCP服务, MITM代理, Node.js, 安全测试工具, 权限控制, 特征检测, 自定义脚本