shellgate-legacy

# Shellgate [](https://github.com/matthiastjong/shellgate/stargazers) [](https://opensource.org/licenses/MIT) [](https://ghcr.io/matthiastjong/shellgate) [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io/) **停止向AI代理提供API密钥。** Shellgate位于您的AI代理和基础设施之间。代理获得限定范围的令牌 - 它们永远不会看到真实的凭证、SSH密钥或密码。您可以控制运行的内容，记录所有内容，危险命令在执行前需要您的批准。 ``` 代理 → sg_token → Shellgate → 您的API / SSH服务器 / 工具 │ ├─ 注入凭证（代理从未看到它们） ├─ 拦截危险命令 → 需要批准 └─ 记录每个请求 ``` ## 为什么使用Shellgate？ **没有Shellgate：** - 代理持有您的真实API密钥和SSH凭证 - 撤销访问意味着在所有地方轮换密钥 - 对代理正在执行的操作没有任何可见性 - 一个提示注入 = 您的生产服务器被入侵 **使用Shellgate：** - 代理仅持有限定范围、可撤销的`sg_`令牌 - 撤销一个令牌而不影响其他任何内容 - 每个请求都被记录并可审计 - 危险命令在执行前被拦截 --- > **🔒 安全注意：** 在与AI代理不同的机器上运行Shellgate。像OpenClaw这样的代理可以访问主机文件系统。如果Shellgate在同一台机器上运行，代理可以直接访问数据库，绕过所有访问控制。您只需要一个廉价的VPS（Hetzner、Railway等），或者使用[Shellgate Cloud](https://shellgate.cloud)进行完全托管的设置。 --- ## Shellgate 云 Shellgate 云为您提供一个安全的代理网关，分钟级即可开通 - 无需Docker，无需设置。 **[Shellgate 云](https://app.shellgate.cloud)** 是托管版本。注册，获取专用实例，即可立即连接您的代理。 - 完全托管 - 无需Docker，无需服务器 - 一分钟内即可开通 - 包含每日备份 - 14天免费试用，无需信用卡 [**免费试用Shellgate 云**](https://app.shellgate.cloud) 更喜欢完全控制？继续阅读以了解如何自行托管。 --- ## 快速入门 ### 1. 运行Shellgate **Docker镜像：** ```bash docker run -d \ -p 3000:3000 \ -e DATABASE_URL=postgres://user:pass@host:5432/shellgate \ -e SESSION_SECRET=$(openssl rand -hex 32) \ ghcr.io/matthiastjong/shellgate:latest ``` 这假设您已经有一个正在运行的PostgreSQL数据库。将`DATABASE_URL`指向您现有的实例。 **Docker Compose：** ```yaml services: shellgate: image: ghcr.io/matthiastjong/shellgate:latest ports: - "3000:3000" environment: DATABASE_URL: postgres://postgres:postgres@db:5432/shellgate SESSION_SECRET: change-me-to-a-random-string depends_on: - db db: image: postgres:16-alpine environment: POSTGRES_DB: shellgate POSTGRES_PASSWORD: postgres volumes: - pgdata:/var/lib/postgresql/data volumes: pgdata: ``` ```bash docker compose up -d ``` ### 2. 设置您的账户 打开`http://localhost:3000` → 在设置屏幕上创建您的管理员账户。 ### 3. 添加目标 **目标** 是您希望代理访问的任何上游API（OpenAI、Anthropic、Stripe、您的内部服务等）。 前往 **目标** → **添加目标**： - **名称：** `openai` - **基准URL：** `https://api.openai.com` - **身份验证：** 添加您的OpenAI API密钥作为Bearer令牌 ### 4. 创建API密钥 前往 **API密钥** → **创建密钥**： - 给它一个名称（例如`my-agent`） - 授予它对`openai`目标的权限 - 复制`sg_...`令牌 ### 5. 使用它 您的代理现在与Shellgate对话，而不是直接与OpenAI： ```bash # 之前：代理拥有您的真实API密钥 curl https://api.openai.com/v1/chat/completions \ -H "Authorization: Bearer sk-your-real-key" \ -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}' # 之后：代理仅拥有Shellgate令牌 curl http://localhost:3000/gateway/openai/v1/chat/completions \ -H "Authorization: Bearer sg_your-shellgate-token" \ -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}' ``` 相同的请求，相同的响应。但现在，您可以控制访问，立即撤销令牌，并拥有完整的审计跟踪。 **SSH目标** 的工作原理类似 - 将服务器添加为目标，给予您的代理一个令牌，它可以在不查看您的SSH密钥的情况下运行命令： ```bash curl -X POST http://localhost:3000/ssh/prod-server/exec \ -H "Authorization: Bearer sg_your-shellgate-token" \ -H "Content-Type: application/json" \ -d '{"command": "docker ps", "timeout": 30}' ``` 如果命令被标记为危险（例如`rm -rf`，`systemctl stop`），Shellgate返回`202 approval_required`响应而不是执行 - 您的代理会向您请求批准。 --- ## 部署 Shellgate可以在任何运行Docker的平台上运行。您可以在本地开发环境中运行它，但在生产环境中，我们建议使用远程服务器，以便您的代理拥有一个稳定的端点。 | 平台 | 操作方法 | |---|---| | **任何VPS** (Hetzner, DigitalOcean等) | `docker compose up -d` | | **Railway** | 从GitHub部署，设置环境变量 | | **Render** | Docker部署，设置环境变量 | | **Coolify / Dokploy** | 从Git仓库添加，自动检测 | | **Fly.io** | `fly launch`，附加Postgres | **要求：** - PostgreSQL 14+ - Node.js 22+（如果不使用Docker） **环境变量：** | 变量 | 必需 | 描述 | |---|---|---| | `DATABASE_URL` | ✅ | PostgreSQL连接字符串 | | `SESSION_SECRET` | ✅ | 会话加密的随机字符串 | --- ## 功能 ### 网关代理 将代理请求路由到任何上游API。Shellgate注入真实凭证，以便代理永远不会看到它们。 ### 令牌管理 从仪表板创建、撤销和轮换`sg_`令牌。每个令牌都可以限定特定目标的范围。 ### 按令牌划分权限 控制每个代理可以访问哪些API。代理A获得OpenAI，代理B获得Anthropic。您可以决定。 ### 仪表板 用于管理目标、令牌和权限的Web界面。不需要CLI。 ### 代理集成 **Claude Code**、**OpenClaw**和**Hermes**的内置安装脚本。从仪表板一键连接您的代理。 ### SSH执行 通过Shellgate运行远程服务器上的命令。相同的令牌，相同的审计跟踪。 ### 人机交互守护 Shellgate在执行危险命令之前会拦截它们并请求您的批准。内置保护开箱即用 - 无需配置。 **工作原理：** 1. 代理发送命令（例如`rm -rf /var/backups/2024`） 2. Shellgate将其与内置规则集进行匹配 3. 而不是执行，它返回`approval_required` 4. 您的代理将此信息通知您 - 您批准或拒绝 5. 代理重新发送带有`X-Shellgate-Approved: true`标头的内容 → 执行 ```json { "status": "approval_required", "reason": "Command contains 'rm -r'", "matched": "rm -r", "request": { "type": "ssh", "command": "rm -rf /var/backups/2024" } } ``` 适用于SSH命令和API调用（例如`DELETE`请求）。像`rm -r`、`DROP TABLE`、`systemctl stop`和`DELETE FROM`这样的破坏性模式默认触发批准。像`/etc/shadow`和`curl | bash`这样的阻止模式始终被拒绝，无论是否批准。 这也充当**提示注入防御** - 即使恶意提示欺骗您的代理发送危险命令，Shellgate也会在命令到达您的基础设施之前捕获它。 ### MCP 服务器 Shellgate通过[MCP（模型上下文协议）](https://modelcontextprotocol.io/)服务器公开所有面向代理的功能。Claude Code和其他兼容MCP的代理直接连接 - 不需要REST调用。 **内置工具：** | 工具 | 描述 | |---|---| | `discover` | 列出可访问的目标、Webhook和组织技能 | | `api_request` | 代理HTTP请求并自动注入凭证 | | `api_download` | 下载身份验证的图像响应作为临时MCP资源，并检查内容类型和大小 | | `ssh_exec` | 执行具有保护措施的SSH命令 | | `webhook_poll` | 轮询传入的Webhook事件 | | `webhook_ack` | 确认已处理的Webhook事件 | | `vault_search` | 在凭证保险库中搜索盲填充句柄 | | `memory_list` / `memory_read` / `memory_add` / `memory_delete` | 管理代理内存 | | `org_skill_list` / `org_skill_read` / `org_skill_upsert` / `org_skill_delete` | 管理共享的组织技能 | | `wiki_list_pages` / `wiki_read_page` / `wiki_upsert_page` / `wiki_delete_page` / `wiki_lint_page` | 组织知识库 | 通过`mcpServers`配置连接到`POST /mcp`并使用您的`sg_`令牌作为Bearer标头。 ### Webhook 接收来自外部服务（Stripe、GitHub、Slack等）的Webhook并将它们路由到您的代理。 1. 在仪表板中创建Webhook端点 - 您获得一个唯一的URL 2. 将外部服务指向该URL 3. 您的代理轮询新事件并在处理后确认它们 每个端点支持可选的**处理说明** - 普通文本指导，告诉代理在收到事件时该怎么做。 ### 凭证库 安全地存储和管理凭证。代理永远不会看到原始机密 - 它们获得Shellgate在请求时解析的盲填充句柄。 - 将凭证组织成多个保险库 - 按令牌划分保险库权限 - 敏感字段被加密，代理永远不会暴露 - `vault_search` MCP工具允许代理按域发现可用的凭证 ### 组织技能 共享的、可重用的程序，任何代理都可以访问。技能是带有结构化指令的Markdown文档 - 类似于代理可以遵循的运行手册。 - 从仪表板或通过MCP创建和版本化技能 - 代理调用`org_skill_list`以发现可用的技能 - 调用`org_skill_read`以在执行前加载技能的完整指令 ### 记忆 在会话之间为您的代理提供持久性内存。记忆可以限定在组织、特定用户或特定令牌的范围内。 - 代理在对话之间存储和回忆上下文 - 三个可见性级别：`org`、`user`、`token` - 通过MCP工具完全的CRUD操作 ### 知识库 用于编译组织知识的内置知识库。存储研究、文档和参考资料，代理可以查询。 - 多命名空间支持 - 状态跟踪（草稿、活动、存档） - 来源属性 - 标签和搜索 - 内置linting/validation ### 审计日志 每个网关请求、SSH命令和防护操作都会记录下完整的上下文 - 方法、路径、状态码、持续时间、客户端IP和防护决策。从仪表板可搜索。 --- ## 从源码运行 ```bash git clone https://github.com/matthiastjong/shellgate.git cd shellgate npm install cp .env.example .env # 编辑DATABASE_URL和SESSION_SECRET npm run dev ``` 打开`http://localhost:5173`。 --- ## API 参考 所有管理端点都需要管理员身份验证（来自仪表板登录的会话cookie）。 代理端点使用Bearer令牌身份验证（`sg_`令牌）。 ### 网关 ``` ANY /gateway/:target/* ``` 将请求代理到目标的基本URL，并注入身份验证。需要有效的`sg_`Bearer令牌，并具有目标权限。 ### 令牌 ``` POST /api/tokens # 创建令牌 GET /api/tokens # 列出令牌 DELETE /api/tokens/:id # 撤销令牌 POST /api/tokens/:id/regenerate # 重新生成令牌 ``` ### 目标 ``` POST /api/targets # 创建目标 GET /api/targets # 列出目标 PATCH /api/targets/:id # 更新目标 DELETE /api/targets/:id # 删除目标 ``` ### 权限 ``` POST /api/tokens/:id/permissions # 授予目标访问权限 DELETE /api/tokens/:id/permissions/:targetId # 撤销目标访问权限 ``` ### SSH ``` POST /ssh/:target/exec # 在SSH目标上执行命令 ``` 正文：`{ "command": "string", "timeout": 30 }`（超时可选，最大60s） 响应：`{ "exitCode": 0, "stdout": "...", "stderr": "...", "durationMs": 123 }` 如果命令被防护拦截：`{ "status": "approval_required", "reason": "...", "matched": "...", "request": {...} }`（HTTP 202） 重新提交时添加`X-Shellgate-Approved: true`标头以执行获得人为批准后的操作。 ### MCP ``` POST /mcp # MCP服务器（流式HTTP传输） ``` Bearer令牌身份验证。 [MCP服务器](#mcp-server)中列出的所有工具均可用。 ### Webhook ``` POST /webhooks/incoming/:slug # 接收来自外部服务的Webhook GET /webhooks/poll # 轮询待处理事件（Bearer令牌） POST /webhooks/ack # 确认事件（Bearer令牌） ``` ### 发现 ``` GET /discovery # 列出此令牌可访问的目标、Webhook和技能 ``` ### 健康检查 ``` GET /health # 返回 { status: "ok" } ``` --- ## 许可证 MIT