@gpzhang2001/sharpkit-sandbox

Docker 沙箱 capability：容器生命周期、exec（含 PTY）、文件传输、端口解析、Caido 引导。驱动方式为 ctx.subprocess + docker CLI。

形态

Service 插件，注册为 ctx.pentestSandbox（cordis Service，inject: ['subprocess']）。消费方声明 inject: ['pentestSandbox']。

const session = await ctx.pentestSandbox.createSession({
  scanId: 'scan-ab12cd34',                                  // 同 id 复用会话（strix create_or_reuse）
  sources: [{ workspaceSubdir: 'app', sourcePath: '/host/repo', protectMetadata: true }],
  extraFiles: [{ containerPath: '/workspace/notes.md', content: '…' }],  // 只读，staged + bind mount
})
await session.ready()                       // Caido 就绪（guest 登录重试即就绪探测）
const result = await session.exec('nmap --version', { cwd: '/workspace/app', timeoutMs: 60_000 })
const repl = await session.execTty('python3')          // PTY；Ctrl-C 写 '\x03'
await session.putFile(host, '/workspace/f.bin')        // docker cp（二进制安全）
const bytes = await session.getFile('/workspace/f.bin')
const { baseUrl, token, projectId } = await session.caidoEndpoint()
await ctx.pentestSandbox.destroySession('scan-ab12cd34')  // 或交给 fiber dispose 的兜底清理

模块

| 文件 | 职责 | | ----------- | -------------------------------------------------------------------- | | spec.ts | 纯 spec→argv/env 构造（分支级单测覆盖） | | mounts.ts | bind mount / 元数据保护 / worktree gitdir / 额外文件校验（注入式 fs probe） | | caido.ts | guest 登录重试（strix 退避语义）+ 建项目/选中 + 共享 bootstrap handle | | session.ts| 会话：exec/PTY/文件/清理（strix cleanup 顺序，尽力而为） | | index.ts | Service：Config、scan-id 缓存、容器编排、staging、镜像缺失时拉取 |

语义对照（strix runtime）

• 容器：tail -f /dev/null 保活 + 镜像 entrypoint 原样；caps NET_ADMIN,NET_RAW；--add-host host.docker.internal:host-gateway；端口 127.0.0.1 临时发布（network 模式改走容器 IP）
• env：PYTHONUNBUFFERED/HOST_GATEWAY/ 三代理指向容器内 Caido（:48080）+ NO_PROXY=localhost,127.0.0.1；SHARPKIT_HOST_UID/GID 仅 Linux
• Caido：容器内 curl guest 登录（10 次、退避 2,4,6,8,8…s、单次 15s）→ host 端 GraphQL createProject(name=sandbox, temporary) + selectProject；bootstrap 与扫描启动并发，懒 resolve
• 清理顺序：staging 目录 → Caido 关闭 → docker stop -t <grace> + rm（失败升级 rm -f）；每步吞错并记日志
• 额外文件：/workspace/ 前缀、禁空/./../控制字符、祖先级碰撞检查、staging 编号子目录

Config（无硬编码 tunable）

image（默认 ghcr 原版）、containerGraceMs、workspaceRoot、network、memLimit/shmSize/cpus/pidsLimit、logMaxSize/logMaxFile（0/off/none/unlimited 关闭轮转）、runLabelId/runLabelType、caidoLoginAttempts/caidoLoginTimeoutMs、defaultExecTimeoutMs、execCollectMaxBytes。

测试

• tests/spec.test.ts / mounts.test.ts / caido.test.ts：纯函数与注入通道（无 Docker）
• tests/integration.test.ts：全流程冒烟（无 Docker daemon 自动 skip；PENTEST_SANDBOX_IMAGE 可换镜像）
• 覆盖率：spec.ts 100% 分支（v8 coverage 实测）