nickvd7/vaultrun
GitHub: nickvd7/vaultrun
一个自托管的 AI Agent 安全运行时，通过隔离 Docker 沙箱让大语言模型在自有基础设施上安全地执行代码和操作资源。
Stars: 1 | Forks: 0
# VaultRun
[](https://github.com/nickvd7/vaultrun/actions/workflows/ci.yml)
[](https://pypi.org/project/vaultrun-sdk/)
[](https://github.com/nickvd7/vaultrun/pulls)
**面向 AI agent 的自托管安全 runtime。** — [vaultrun.dev](https://vaultrun.dev) · [llms.txt](https://vaultrun.dev/llms.txt) · [PyPI](https://pypi.org/project/vaultrun-sdk/)
VaultRun 让 AI agent 能够安全地执行代码、查询数据库、调用云 API，并管理运行在你自有基础设施上的独立 Docker 沙箱内的文件。无需外部 SaaS。数据不会离开你的网络。
```
┌──────────────────────────────────────────────────────────────┐
│ Your AI Agent (Claude, GPT-4o, custom, …) │
│ │
│ result = client.run(session_id, │
│ command="python", args=["analyze.py"]) │
└────────────────────────┬─────────────────────────────────────┘
│ API key
▼
┌──────────────────────────────────────────────────────────────┐
│ VaultRun API (your server, your infra) │
│ │
│ • Isolated Docker container per session │
│ • exec API only — no shell injection │
│ • Path traversal prevention in workspace │
│ • HMAC-signed audit trail │
│ • CPU / memory / timeout limits per session │
│ • Network disabled by default │
└──────────────────────────────────────────────────────────────┘
```
## 快速开始
**前置条件：** Docker、Docker Compose、Go 1.25+
```
git clone https://github.com/nickvd7/vaultrun
cd vaultrun
cp .env.example .env # set MASTER_API_KEY to something strong
make up # start API + Postgres + Redis + dashboard
make bootstrap-key # prints your first vr_... API key
curl http://localhost:8080/health
```
打开 `http://localhost:3000` 访问仪表板。
## 包含的内容
| 组件 | 描述 |
|---|---|
| **API 服务器** (`cmd/api`) | 基于 Gin 的 REST API — 会话、运行、文件、审计 |
| **CLI** (`cmd/cli`) | `vaultrun` 命令行工具 |
| **MCP 服务器** (`sdk/mcp`) | 包含 53 个工具的 MCP 服务器 (stdio + HTTP) |
| **CI runner** (`cmd/ci-runner`) | GitHub webhook → 沙箱 CI + Slack/Teams 通知 |
| **仪表板** (`apps/frontend`) | 基于 Next.js 的管理 UI |
| **Go SDK** (`sdk/go`) | 强类型的 Go 客户端 |
| **Python SDK** (`sdk/python`) | Python 客户端 — [`pip install vaultrun-sdk`](https://pypi.org/project/vaultrun-sdk/) |
## 架构
```
vaultrun/
├── cmd/
│ ├── api/ Go API server (Gin)
│ ├── cli/ Go CLI (vaultrun)
│ └── ci-runner/ GitHub webhook CI runner
├── internal/
│ ├── auth/ API key hashing + validation
│ ├── audit/ HMAC-signed event logger
│ ├── docker/ Container + exec management
│ ├── workspace/ File vault, path traversal prevention
│ ├── runner/ Command execution orchestration
│ ├── db/ Postgres queries (sqlx)
│ ├── policy/ Pluggable policy hook (OPA-ready)
│ └── config/ Environment-based configuration
├── apps/
│ └── frontend/ Next.js dashboard (React + Tailwind)
├── sdk/
│ ├── go/ Go SDK
│ ├── python/ Python SDK
│ └── mcp/ MCP server (53 tools)
├── migrations/ SQL migrations (golang-migrate)
├── deployments/ Docker Compose + Dockerfiles
├── docs/ Architecture, security, API reference
└── examples/ Usage examples
```
## MCP 服务器（53 个工具）
MCP 服务器将每一项 VaultRun 功能作为 Model Context Protocol 工具公开。
只需几秒钟，即可将其添加到 Claude Desktop、Claude Code 或任何兼容 MCP 的平台。
### Stdio 传输 (Claude Desktop / Claude Code)
```
{
"mcpServers": {
"vaultrun": {
"command": "/path/to/vaultrun-mcp",
"env": {
"VAULTRUN_BASE_URL": "http://localhost:8080",
"VAULTRUN_API_KEY": "vr_your_key"
}
}
}
}
```
构建二进制文件：`go build -o vaultrun-mcp ./sdk/mcp/`
### HTTP 传输 (OpenAI / OpenRouter / 自定义)
```
MCP_TRANSPORT=http \
MCP_AUTH_TOKEN=your-secret-token \
VAULTRUN_BASE_URL=http://localhost:8080 \
VAULTRUN_API_KEY=vr_your_key \
./vaultrun-mcp
# POST /mcp — JSON-RPC 2.0, Authorization: Bearer your-secret-token
```
### 工具类别
| 类别 | 工具 |
|---|---|
| **沙箱** | `create_session`, `list_sessions`, `get_session`, `delete_session`, `run_command`, `upload_file`, `read_file`, `list_files`, `delete_file`, `get_run`, `list_runs`, `get_session_stats`, `get_session_logs` |
| **镜像** | `list_images`, `pull_image` |
| **快照** | `create_snapshot`, `list_snapshots` |
| **产物** | `create_artifact`, `list_artifacts`, `list_audit_logs` |
| **GitHub** | `run_github_repo`, `github_post_comment` |
| **文件系统** | `fs_read_file`, `fs_write_file`, `fs_list_dir`, `fs_delete_file` |
| **S3** | `s3_list_buckets`, `s3_list_objects`, `s3_get_object`, `s3_put_object`, `s3_delete_object`, `s3_head_object` |
| **SSM** | `ssm_get_parameter`, `ssm_put_parameter`, `ssm_delete_parameter`, `ssm_list_parameters` |
| **Secrets Manager** | `sm_get_secret`, `sm_list_secrets` |
| **Lambda** | `lambda_list_functions`, `lambda_invoke` |
| **SQLite** | `sqlite_query`, `sqlite_execute`, `sqlite_schema` |
| **PostgreSQL** | `pg_query`, `pg_execute`, `pg_schema` |
| **MongoDB** | `mongo_find`, `mongo_insert_one`, `mongo_update`, `mongo_delete`, `mongo_aggregate`, `mongo_collections`, `mongo_generate_mongoose` |
完整文档：[sdk/mcp/README.md](sdk/mcp/README.md)
## GitHub CI Runner
由 GitHub webhook 触发，在 VaultRun 沙箱内运行 PR 测试套件。
```
GITHUB_TOKEN=ghp_... \
GITHUB_WEBHOOK_SECRET=your-secret \
VAULTRUN_BASE_URL=http://vaultrun \
VAULTRUN_API_KEY=vr_... \
SLACK_WEBHOOK_URL=https://... \ # optional
TEAMS_WEBHOOK_URL=https://... \ # optional
NOTIFY_ON_SUCCESS=false \ # suppress green noise
CI_TEST_COMMANDS='[["make","test"]]' \ # default
./ci-runner
```
- **Webhook endpoint：** `POST /webhook` (通过 HMAC-SHA256 验证)
- **健康检查：** `GET /healthz`
- 将结果作为 PR 评论 + 提交状态 (`vaultrun-ci`) 发布
- 支持 Slack Block Kit 和 Teams Adaptive Card 1.4 payload
## REST API 参考
所有 endpoint 都需要 `X-API-Key` 或 `Authorization: Bearer `。
### 会话
```
POST /api/v1/sessions Create a new session
GET /api/v1/sessions List active sessions
GET /api/v1/sessions/:id Get session details
DELETE /api/v1/sessions/:id Delete session + container + workspace
```
**创建会话的 body：**
```
{
"name": "my-session",
"image": "python:3.12-slim",
"network_enabled": false,
"cpu_limit": 1.0,
"memory_limit_mb": 512,
"timeout_seconds": 300
}
```
### 命令执行
```
POST /api/v1/sessions/:id/run Execute a command
GET /api/v1/sessions/:id/runs List runs for a session
GET /api/v1/runs/:id Get run details
```
**执行命令的 body：**
```
{ "command": "python", "args": ["script.py"], "timeout_seconds": 30 }
```
**响应：**
```
{
"id": "uuid",
"status": "completed",
"exit_code": 0,
"stdout": "...",
"stderr": "",
"duration_ms": 412
}
```
### 文件保险库
```
POST /api/v1/sessions/:id/files Upload file (multipart)
GET /api/v1/sessions/:id/files List files
GET /api/v1/sessions/:id/files/*path Download file
```
### 审计日志
```
GET /api/v1/audit?session_id=... List audit logs
```
### 密钥管理
```
POST /api/v1/keys Create API key (requires master key)
GET /api/v1/keys List API keys
```
完整的 OpenAPI 规范：[docs/openapi.yaml](docs/openapi.yaml)
## CLI
```
export VAULTRUN_API_URL=http://localhost:8080
export VAULTRUN_API_KEY=vr_...
vaultrun session create --image python:3.12-slim --cpu 0.5 --mem 256
vaultrun session list
vaultrun file upload ./script.py
vaultrun run -- python script.py
vaultrun logs
vaultrun session delete
```
## Python SDK
```
from sandbox_sdk import Client
client = Client("http://localhost:8080", api_key="vr_...")
session = client.create_session(image="python:3.12-slim", memory_limit_mb=256)
client.upload_file(session.id, "script.py", open("script.py", "rb"))
result = client.run(session.id, command="python", args=["script.py"])
print(result.stdout)
client.delete_session(session.id)
```
安装：[`pip install vaultrun-sdk`](https://pypi.org/project/vaultrun-sdk/)
## Go SDK
```
import vaultrun "github.com/nickvd7/vaultrun/sdk/go"
client := vaultrun.New("http://localhost:8080", "vr_...")
session, _ := client.CreateSession(ctx, vaultrun.CreateSessionOptions{Image: "python:3.12-slim"})
client.UploadFile(ctx, session.ID, "script.py", scriptContent)
run, _ := client.Run(ctx, session.ID, vaultrun.RunOptions{Command: "python", Args: []string{"script.py"}})
fmt.Println(*run.Stdout)
```
## SSO / 身份验证
VaultRun 支持三种身份验证方法：
| 方法 | 方式 | 用例 | 版本 |
|---|---|---|---|
| **API 密钥** | `X-API-Key: vr_…` header | Agent、SDK、CI | 核心版 (Apache 2.0) |
| **OIDC** | 浏览器重定向至 IdP → 会话 cookie | 通过 Okta/Azure AD/Google 访问的仪表板用户 | 企业版 |
| **SAML 2.0** | 浏览器重定向至 IdP → 会话 cookie | 企业 IdP (Okta, AD FS, OneLogin) | 企业版 |
SSO 登录会自动配置一个 VaultRun API 密钥并颁发一个签名的会话 cookie。OIDC 和 SAML 不会授予 master-key 权限。
SSO 作为 **VaultRun Enterprise** 位于独立的存储库中，并作为 overlay 编译进 API 服务器 (`go build -tags enterprise`)。当设置了 `OIDC_*`/`SAML_*` 环境变量时，核心版本的构建会拒绝启动，因此配置错误的部署会显式报错。
### 如何获取企业版
在 [vaultrun.dev/#enterprise](https://vaultrun.dev/#enterprise) 上选择一个路径 — 每个请求都会发送邮件至 **mail@030.dev**：
1. **评估** — 免费用于开发和测试；申请评估访问权限
2. **许可证** — 用于生产的 SSO；包括组织、IdP、实例/席位数和时间表
3. **联系我们** — 采购、支持或自定义条款
请参阅 [docs/sso-setup.md](docs/sso-setup.md) 获取分步设置指南（IdP 注册、证书、测试、故障排除），或参阅 [docs/configuration.md](docs/configuration.md#sso--oidc--openid-connect) 获取环境变量参考。
## 安全性
请参阅 [docs/security.md](docs/security.md) 了解完整的安全模型。
- 无 shell 执行 — 命令通过 Docker exec API 执行
- 非 root 容器，并且丢弃所有权限
- 默认禁用网络；启用时使用基于会话的 iptables 白名单
- 在工作区层级进行路径遍历防护
- API 密钥存储为 SHA-256 哈希值，绝不使用明文
- 对每个操作进行 HMAC 签名的审计跟踪
- 在 MCP HTTP 传输上进行速率限制 + 安全标头
- `MCP_AWS_ENABLED=true` 显式选择加入，防止激活环境 IAM 凭据
- OIDC：PKCE + 状态验证；SAML：XMLDSig 签名验证
- 会话 cookie：`HttpOnly`、`Secure`、HS256 签名
## 配置
所有配置均通过环境变量进行。请参阅 [.env.example](.env.example) 和 [docs/configuration.md](docs/configuration.md)。
**API 服务器（必需）：**
| 变量 | 默认值 | 描述 |
|---|---|---|
| `PORT` | `8080` | API 服务器端口 |
| `DATABASE_URL` | — | Postgres DSN（必需）|
| `MASTER_API_KEY` | — | 引导密钥（使用一次后禁用）|
**SSO（可选）：**
| 变量 | 描述 |
|---|---|
| `OIDC_ISSUER_URL` | 启用 OIDC — 例如 `https://accounts.google.com` |
| `SAML_IDP_METADATA_URL` | 启用 SAML — IdP 的 metadata XML 的 URL |
| `SSO_SESSION_SECRET` | 启用 SSO 时必需 — `openssl rand -hex 32` |
**多区域（可选）：**
| 变量 | 描述 |
|---|---|
| `REGION` | 包含在 `/health` 响应中的区域标签 |
| `DATABASE_READ_URL` | 用于 list/get 查询的只读副本 DSN |
**MCP 服务器**（`MCP_TRANSPORT=http` 额外配置）：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `MCP_TRANSPORT` | `stdio` | `stdio` 或 `http` |
| `MCP_AUTH_TOKEN` | — | Bearer token（HTTP 必需）|
| `MCP_PORT` | `:8090` | HTTP 传输的监听地址 |
| `MCP_SQLITE_PATH` | — | SQLite 数据库文件的路径 |
| `MCP_PG_DSN` | — | PostgreSQL 连接字符串 |
| `MCP_MONGO_URI` | — | MongoDB 连接 URI |
## 开发
```
make test # unit tests
make test-integration # integration tests (requires running stack)
make fmt vet # format + vet
make build # build API + CLI binaries
make lint # golangci-lint
# MCP server
go test ./sdk/mcp/...
go build -o vaultrun-mcp ./sdk/mcp/
# CI runner
go test ./cmd/ci-runner/...
go build -o ci-runner ./cmd/ci-runner/
```
## 更新日志
请参阅 [CHANGELOG.md](CHANGELOG.md) 了解版本历史。
## 许可证
VaultRun 是 open core 模式：
- 本存储库中的所有内容均基于 **Apache 2.0** 许可 — 请参阅 [LICENSE](LICENSE)。
- **VaultRun Enterprise** (SSO: OIDC + SAML 2.0) 位于独立的存储库中，基于 VaultRun Enterprise 许可证。
企业许可与支持：**[vaultrun.dev/#enterprise](https://vaultrun.dev/#enterprise)** → 发送邮件至 **mail@030.dev**
标签：AI代理, Docker隔离, EVTX分析, Go, MCP服务, Ruby工具, 人工智能, 搜索引擎查询, 日志审计, 测试用例, 用户模式Hook绕过, 自托管, 请求拦截, 运行时沙箱, 逆向工具