chenxin/hunjing

0 Fork 0

Files

T

History

chenxin 887c1f449e 初始化提交

2026-08-21 16:00:13 +08:00

src

初始化提交

2026-08-21 16:00:13 +08:00

Cargo.lock

初始化提交

2026-08-21 16:00:13 +08:00

Cargo.toml

初始化提交

2026-08-21 16:00:13 +08:00

README.md

初始化提交

2026-08-21 16:00:13 +08:00

README.md

乾坤 · 魂镜安全沙箱服务（hunjing-sandbox / Sandbox Engine）

文化命名「乾坤」（Sandbox Engine），百工枢的隔离执行后端——为器用百工提供一个自成天地、越界即止的封闭执行世界。命名登记见 docs/contracts/contract-glossary.md §2.1。

Rust + axum 实现的 HTTP 微服务，为「百工 Tool Runtime」提供本地隔离的命令执行层。在系统中的定位：

flowchart LR
    Backend["后端 FastAPI"] -->|POST /v1/exec| Sandbox["hunjing-sandbox (Rust)"]
    Sandbox --> Child["受限子进程<br/>进程组 / 临时工作目录 / 超时"]
    Child --> System["shell / python / 外部命令"]
    Sandbox -->|SIGKILL 进程组| Cleanup["超时或取消时清理子进程"]

安全边界：沙箱只执行已授权任务，不做风险判定（由司命 Safety 负责）；调用方应在发起前完成权限与风险审核。设计依据见 docs/architecture/service-boundaries.md 与 docs/architecture/service-boundaries.md。

司命授权

/v1/exec 受 HMAC 授权中间件保护（/healthz 不受保护）。调用方（后端百工客户端）需经司命审核后签发短期凭证，沙箱端验签通过才执行。

凭证格式：<payload_b64url>.<sig_b64url>，payload 含 exp / trace_id / risk_level / tool / character_id / run_id / body_hash / rlimit_overrides / file_op_hash，sig 为 HMAC-SHA256(SANDBOX_AUTH_SECRET, payload_b64url)。
rlimit_overrides：司命按 tool policy 授予的资源配额上限（key: fsize/as/cpu/nproc/nofile），随 HMAC 不可伪造；sandbox 验签后 clamp 到全局天花板 SANDBOX_RLIMIT_*_MAX。属授权属性，不进 body_hash。
凭证轮换：SANDBOX_AUTH_SECRET_PREVIOUS（逗号分隔旧 secret）支持多 secret 并存的无中断轮换——sandbox 先加 previous 认新旧 → backend 切新 secret → TTL 后清 previous。metric sandbox_auth_secret_used{slot=primary|previous} 指示轮换进度。
body_hash 为 SHA256(canonical JSON {argv, stdin})，把凭证绑死到具体执行内容——凭证在 TTL 内无法被重放去执行任意其他命令；两端字节级一致（共享固定向量回归测试守护，见 sandbox/src/auth.rs 与 backend/.../sandbox/auth.py）。
file_op_hash 为 SHA256(canonical JSON {op, path})，把文件 IO 凭证绑死到具体操作（read/write/list/stat）与路径——TTL 内无法重放去读写任意其他文件；与 body_hash 互斥（exec 凭证此字段为 null），两端字节级一致（同样由固定向量回归守护）。
HTTP 头：Authorization: Bearer <token>。
校验失败统一返回 401 {"error":{"code":"sandbox_unauthorized", ...}}。
SANDBOX_AUTH_ENABLED=false 时跳过校验（仅本地联调，生产禁用）。

后端客户端实现见 backend/app/integrations/sandbox/（签发 + 调用 + 一炁事件回写，两端 HMAC 字节级一致，已通过跨语言闭环验证）。

隔离措施

维度	措施
进程	独立进程组（`process_group(0)`），超时/取消对整组 `SIGKILL`，清理派生子进程
环境	默认 `env_clear`，仅注入 `SANDBOX_ALLOWED_ENV` 白名单 + 请求指定变量
工作目录	默认每次执行用 base 下临时目录（执行后回收）；可指定 base 内子目录，拒绝路径逃逸；文件类工具由百工 runtime 按 run/trace 隔离为 `workspace/<run_key>`（key 经 sanitize，防路径注入）
超时	`min(请求 timeout_ms, 全局 SANDBOX_MAX_TIMEOUT_MS)`，到点强制结束
客户端断开	流式执行（`/v1/exec/stream`）感知接收端关闭（rx drop / SSE 断连）后主动对进程组 `SIGKILL` 取消并收尸，避免已离开用户的长任务（如 `sleep 30`）占满并发闸；覆盖无输出命令（`capture_streaming` 的 send-err 检测对无输出命令失效）
输出	stdout / stderr 各自截断至 `max_output_bytes`，超出标记 `truncated` 并继续 drain 防管道阻塞
残留清理	启动时清理 base 下 `.tmp*` 临时目录（tempfile 异常退出残留），不触及 `workspace/` 持久目录
资源（进程）	fork 后、exec 前 `setrlimit` 限制单文件写入 / 虚拟内存 / CPU / 子进程数 / 打开文件数（软=硬），与容器限额形成纵深；配额分层（全局天花板 → 凭证授予 → 请求收紧）见下文
资源（容器）	Docker 侧 `deploy.resources.limits` 约束 memory / cpus / pids，`/tmp` 走 tmpfs 限大小
网络（容器）	sandbox 仅接入 internal 专属网络 `hunjing-sandbox-net`，无公网出站，防数据外泄；后端经该网络以服务名访问
权限（容器）	只读根文件系统（仅 `/tmp` tmpfs 与 `sandbox-work` bind mount 可写）、`no-new-privileges`、`cap_drop: ALL`、Docker 默认 seccomp profile

HTTP API

`GET /healthz`

{ "status": "ok", "service": "hunjing-sandbox", "version": "0.1.0" }

`GET /metrics`

Prometheus 指标（text/plain; version=0.0.4），不鉴权，供抓取：

指标	类型	含义
`sandbox_exec_total{outcome}`	counter	同步执行次数（completed/timeout/cancelled/failed）
`sandbox_exec_duration_seconds`	histogram	同步执行耗时分布（含 `_bucket/_sum/_count`）
`sandbox_concurrent`	gauge	当前并发执行数
`sandbox_concurrent_limit`	gauge	并发上限（`SANDBOX_MAX_CONCURRENT`）
`sandbox_stream_total{outcome}`	counter	流式执行次数
`sandbox_auth_secret_used{slot}`	counter	验签命中 secret 分布（primary/previous），指示轮换进度
`sandbox_auth_enabled`	gauge	鉴权是否开启（1/0）；值为 0 时应告警（生产环境鉴权被关）

`POST /v1/exec`

请求体：

{
  "argv": ["python3", "-c", "print(1 + 1)"],
  "stdin": "可选标准输入",
  "timeout_ms": 5000,
  "workdir": "可选，base 内的相对子目录",
  "env": { "GREETING": "hi" },
  "max_output_bytes": 1048576,
  "trace_id": "可选，透传用"
}

响应体：

{
  "ok": true,
  "exit_code": 0,
  "stdout": "2\n",
  "stderr": "",
  "duration_ms": 42,
  "timeout": false,
  "cancelled": false,
  "truncated": false,
  "trace_id": "sbx_18f3a1...",
  "isolation_mode": "process"
}

支持两种互斥的执行形态：

命令模式：argv（首个元素为可执行文件）。
代码模式：code + language（默认 python，P0 仅支持 python）。沙箱转译为 argv（写临时脚本文件 + interpreter）后走执行路径；凭证 body_hash 按 SHA256(canonical JSON {language, code, stdin}) 绑定。

argv 与 code 同时或都不给出返回 400。响应体 isolation_mode 字段（process / container）回显实际生效的隔离模式：P0 期间凭证下发 container 一律降级 process 并 warn（L3-L4 真正走容器留待 P1）。

错误统一格式（见跨语言契约）：

{ "error": { "code": "exec_timeout", "message": "执行超时" } }

超时不计入错误码：响应 HTTP 200 且 timeout: true（执行被 SIGKILL 中止，exit_code 为 null），调用方据 timeout 字段判断。

code	HTTP	含义
`bad_request`	400	argv/code 互斥冲突、argv 为空、language 不支持等参数错误
`sandbox_unauthorized`	401	授权凭证缺失 / 过期 / 签名无效 / body_hash 不匹配
`not_found`	404	cancel 的 trace_id 不存在或已完成
`service_unavailable`	503	并发闸耗尽
`exec_failed`	500	spawn / 等待失败等

`POST /v1/cancel`

按 trace_id 取消运行中的任务（对进程组 SIGKILL）。请求体 { "trace_id": "..." }，命中返回 { "cancelled": true, "trace_id": "..." }；任务不存在或已完成返回 404 not_found。被取消的 /v1/exec 调用会以 cancelled: true、ok: false 返回。

安全权衡：cancel 仅中止任务、不执行新命令，危害有限，故凭证验签 + 过期即可，不绑定 trace_id（与 exec 的 body_hash 强绑定不同）。调用方需自行记录 trace_id——exec 未传 trace_id 时由沙箱生成，客户端无从获知，无法取消。

`POST /v1/exec/stream`

流式执行（SSE）：请求体同 /v1/exec，响应为 text/event-stream，实时推送：

event: stdout / event: stderr：data 为 base64(urlsafe-no-pad) 编码的原始字节增量（保真，前端解码为 UTF-8）
event: done：data 为 JSON {exit_code, duration_ms, timeout, cancelled, truncated, trace_id}，标志执行结束
心跳：每 15s 一个注释行（KeepAlive），防代理空闲断开

后端 POST /tools/{name}/invoke/stream（sse-starlette）转发为 tool.stdout / tool.stderr / tool.completed / tool.requires_confirmation / tool.failed 事件；前端用 fetch+ReadableStream 消费（EventSource 不支持 POST body）。started/completed 落一炁事件存储，stdout/stderr 增量只透传不落库。

文件 IO（`/v1/file/read` · `/write` · `/list` · `/stat`）

不经 shell、二进制安全的 base 内文件读写（与 /v1/exec 的 shell 路径互补，适合需要精确字节控制或无 shell 语义的场景）。各端点独立校验 file_op_hash——凭证的 {op, path} 必须与请求一致，否则 401（防重放：read 凭证不能用于读写别的路径）。

端点	请求体	响应
`POST /v1/file/read`	`{path, offset?, limit?}`	`{content_b64, size, offset, returned, truncated}`（`content_b64` 为 base64url-no-pad，支持 offset/limit 分页）
`POST /v1/file/write`	`{path, content_b64}`	`{bytes_written}`（覆盖写）
`POST /v1/file/list`	`{path?}`（默认 `.`）	`{entries:[{name, kind, size}]}`（按名排序，`kind` 为 `file`/`dir`/`other`）
`POST /v1/file/stat`	`{path}`	`{kind, size, modified_unix}`

path 为 base 内相对路径；词法预检查 + canonicalize + starts_with(base) 三重校验拒绝路径逃逸（.. 不得使深度为负，且 create_dir_all 前先拒，防越界副作用）；符号链接覆盖由 canonicalize 兜底。
单次读写受 SANDBOX_MAX_FILE_BYTES（默认 1 MiB）约束，超出 read 标 truncated、write 直接 400。文件操作在主进程运行（非 exec 子进程），不受 RLIMIT_* 约束，故用此上限替代。
后端 SandboxClient.file_read/write/list/stat 自动签发 file_op_hash 凭证并回写 tool.started/tool.completed/tool.failed 一炁事件（argv 记 [file:<op>, <path>] 供审计 input_summary）。
无 delete 端点（设计上不开放删除，防误删；需清理时由运维直接操作 base 目录）。

配置（环境变量）

变量	默认	说明
`SANDBOX_HOST`	`0.0.0.0`	监听地址
`SANDBOX_PORT`	`8090`	监听端口
`SANDBOX_BASE_WORKDIR`	`../sandbox-work`	沙箱工作根目录（相对二进制所在目录）
`SANDBOX_LOG_DIR`	`../logs`	tracing 文件日志目录（相对二进制所在目录，与后端对齐到项目根 `logs/`）；容器内为 `/app/logs`
`SANDBOX_MAX_TIMEOUT_MS`	`30000`	单次执行全局超时上限（ms）
`SANDBOX_MAX_CONCURRENT`	`8`	最大并发执行数
`SANDBOX_MAX_OUTPUT_BYTES`	`1048576`	单流最大捕获字节数（1 MiB）
`SANDBOX_MAX_FILE_BYTES`	`1048576`	单次文件读写最大字节数（1 MiB）；文件 IO 在主进程，不受 `RLIMIT_*` 约束，故用此上限
`SANDBOX_ALLOWED_ENV`	`PATH,HOME,TZ,LANG`	默认注入子进程的环境变量白名单（逗号分隔）
`SANDBOX_AUTH_ENABLED`	`true`	是否校验司命授权凭证；生产必须为 true
`SANDBOX_ISOLATION_DEFAULT`	`process`	凭证未下发 `isolation_mode` 时的兜底隔离模式（process/container；P0 期间一律按 process）
`SANDBOX_AUTH_SECRET`	—	授权 HMAC 共享密钥（与后端客户端一致），`AUTH_ENABLED=true` 时必填
`SANDBOX_AUTH_TTL_SECONDS`	`30`	授权凭证有效期（秒）
`SANDBOX_AUTH_SECRET_PREVIOUS`	—（空）	旧 secret（逗号分隔），凭证轮换并存窗口；verify 时与主 secret 一并尝试
`SANDBOX_RLIMIT_FSIZE_BYTES`	`67108864`	单文件写入上限（64 MiB，普通工具默认）
`SANDBOX_RLIMIT_AS_BYTES`	`536870912`	虚拟内存上限（512 MiB；仅 Linux 生效——macOS 的 `RLIMIT_AS` 实为 `RLIMIT_RSS` 别名，不真正限制虚拟地址空间，且 server 自身 AS 常超此值会使 `setrlimit` 返回 EINVAL 导致 spawn 失败，故 macOS 跳过）
`SANDBOX_RLIMIT_CPU_SECS`	`max_timeout` 秒	CPU 秒数上限（对齐全局超时）
`SANDBOX_RLIMIT_NPROC`	`64`	子进程数上限（防 fork bomb；root 运行时自动跳过）
`SANDBOX_RLIMIT_NOFILE`	`256`	打开文件数上限
`SANDBOX_RLIMIT_*_MAX`	= 对应 `*_BYTES/SECS`	可选，分级场景的全局硬天花板；未设则不允许上探（默认部署等价单一限额）
`SANDBOX_RLIMIT_DISABLE`	—（空）	显式禁用维度（逗号分隔，如 `nproc`）
`RUST_LOG`	`info`	tracing 日志级别；日志同时写 stdout（彩色）与 `<SANDBOX_LOG_DIR>/sandbox.log`（按日轮转，当天文件名 `sandbox.log.YYYY-MM-DD`）

后端连接沙箱用 .env 中的 RUST_SANDBOX_URL（例如 http://hunjing-sandbox:8090）；本服务的自身配置用上面的 SANDBOX_*。

本地开发

cd sandbox
cargo run                       # 监听 0.0.0.0:8090
# 或指定配置
SANDBOX_PORT=8090 SANDBOX_BASE_WORKDIR=./tmp-work cargo run

# 手动测试
curl -s http://127.0.0.1:8090/healthz
curl -s -X POST http://127.0.0.1:8090/v1/exec \
  -H 'Content-Type: application/json' \
  -d '{"argv":["python3","-c","print(6*7)"]}'

# 验证超时清理
curl -s -X POST http://127.0.0.1:8090/v1/exec \
  -H 'Content-Type: application/json' \
  -d '{"argv":["sh","-c","sleep 30"],"timeout_ms":300}'

# 验证工作目录隔离与逃逸拒绝
curl -s -X POST http://127.0.0.1:8090/v1/exec \
  -H 'Content-Type: application/json' \
  -d '{"argv":["sh","-c","pwd"],"workdir":"../../etc"}'

cargo test                      # 执行内核单元测试（echo / 超时 / 截断 / 路径逃逸 / stdin+env）
cargo build --release           # 产出 release 二进制

Docker

镜像构建见 docker/sandbox/Dockerfile，多阶段（rust 构建 → debian-slim 运行），监听 8090。通过 docker-compose.app.yml 的 --profile sandbox 启用。

容器级隔离：sandbox 仅接入 internal 网络 hunjing-sandbox-net（无公网出站，后端经该网络以服务名 hunjing-sandbox 访问），并受 deploy.resources.limits（memory / cpus / pids）与 /tmp tmpfs 约束。网络拓扑与资源定义见 docker/docker-compose.app.yml。容器日志既可经 docker compose logs hunjing-sandbox（stdout）查看，也持久化到挂载的项目根 logs/sandbox.log.YYYY-MM-DD（与后端 app.log 同目录，便于统一收集）。

docker compose -f docker/docker-compose.infra.yml up -d   # 先建网络（如未建）
docker compose -f docker/docker-compose.app.yml --profile sandbox up -d --build hunjing-sandbox
docker compose -f docker/docker-compose.app.yml logs -f hunjing-sandbox

后续加固（按需，非当前阶段）

自定义 seccomp 白名单（当前用 Docker 默认 profile，已阻止约 50 个危险系统调用；自定义白名单维护成本高且易误伤正常命令）。
workspace 容量配额与按 run 的自动 GC（当前已实现按 run 隔离 + 启动清理 .tmp* 残留）。
更强隔离形态：nsjail / gVisor / firecracker microVM（远期）。

IoT / 边缘设备部署

乾坤沙箱可在 IoT 硬件上以进程模式运行（无需 Docker），单静态二进制即可部署。

交叉编译

# ARM64 静态编译（零运行时依赖）
rustup target add aarch64-unknown-linux-musl
cargo build --release --target aarch64-unknown-linux-musl

# 产物大小约 5-8 MB
ls -lh target/aarch64-unknown-linux-musl/release/hunjing-sandbox

# 部署
scp target/aarch64-unknown-linux-musl/release/hunjing-sandbox \
    root@device:/usr/local/bin/

资源占用

模式	RSS	磁盘
进程模式闲置	~12 MB	~5 MB
进程模式执行中	~25 MB	-
容器模式（需 Docker）	~200 MB+	镜像额外 ~100 MB

启动（进程模式）

ssh root@device \
  'SANDBOX_DOCKER_ENABLED=false \
   SANDBOX_PORT=8090 \
   RUST_LOG=info \
   /usr/local/bin/hunjing-sandbox'

systemd 托管

[Unit]
Description=hunjing-sandbox (乾坤安全沙箱)
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/hunjing-sandbox
Environment=SANDBOX_DOCKER_ENABLED=false
Environment=SANDBOX_PORT=8090
Environment=SANDBOX_BASE_WORKDIR=/var/lib/hunjing-sandbox
Environment=SANDBOX_LOG_DIR=/var/log/hunjing-sandbox
Environment=RUST_LOG=info
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

硬件兼容

硬件	架构	进程模式	容器模式
Raspberry Pi 4/5	ARM64	✅	✅（需 4GB+）
Jetson Orin	ARM64	✅	✅
RK3588 / 全志 H6	ARM64	✅	⚠️（需 4GB+）
x86 工控机 / NUC	x86-64	✅	✅
OpenWRT 路由器	MIPS/ARM	⚠️（需确认内核支持）	❌
ESP32 / MCU	-	❌	❌

README.md Unescape Escape

乾坤 · 魂镜安全沙箱服务（hunjing-sandbox / Sandbox Engine）

司命授权

隔离措施

HTTP API

GET /healthz

GET /metrics

POST /v1/exec

POST /v1/cancel

POST /v1/exec/stream

文件 IO（/v1/file/read · /write · /list · /stat）

配置（环境变量）

本地开发

Docker

后续加固（按需，非当前阶段）

IoT / 边缘设备部署

交叉编译

资源占用

启动（进程模式）

systemd 托管

硬件兼容

README.md

`GET /healthz`

`GET /metrics`

`POST /v1/exec`

`POST /v1/cancel`

`POST /v1/exec/stream`

文件 IO（`/v1/file/read` · `/write` · `/list` · `/stat`）