diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index a6ab733..7637aab 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -329,7 +329,7 @@ stateDiagram-v2 单文件 Node HTTP 服务(`executor/server.js`),零依赖。端点: - `GET /health` → `{ok, running:[{id, pid, cwd, started_at}]}`,免鉴权。 -- `POST /exec` body `{command, cwd?, timeout_ms?, max_output_chars?, env?}` → SSE 流: +- `POST /exec` body `{command, cwd(必填), timeout_ms?, max_output_chars?, env?}` → SSE 流: - `start`(带 id + pid + cwd)→ `out`/`err` 增量分块 → `exit` 收尾。 - 期间每 15s 一条 `: ping` 注释行保活。 - `DELETE /exec/:id` → 杀进程组(`process.kill(-pid, SIGKILL)`)。 @@ -338,6 +338,7 @@ stateDiagram-v2 - `EXECUTOR_TOKEN` 非空时,除 `/health` 外必须 `Authorization: Bearer`(常时间比较)。 - `cwd` 必须落在 `EXECUTOR_ROOTS`(逗号分隔白名单,默认 `/workspace`)realpath 之下,防穿越。 +- `cwd` 不得是任务根本身(realpath 相等即拒):它是全部会话目录的父目录,在其下执行会暴露所有会话,且隔离 wrapper 在此层无从生效;缺省 cwd 落任务根同样被拒 → 等效必填。 - `timeout_ms` 夹在 `[1000, EXECUTOR_MAX_TIMEOUT_MS=1800000]`。 - 输出按 `max_output_chars`(默认 200000)截断,**截断后仍持续消费管道**(防子进程因 pipe 满阻塞),并设 `truncated=true`。 @@ -353,7 +354,7 @@ stateDiagram-v2 | `EXECUTOR_TOKEN` | 空 | 可选 Bearer 鉴权 | | `EXECUTOR_LOG_LEVEL` | `info` | 分级日志(debug 打满请求/响应交互) | -**per-task 挂载隔离**(`server.js` 的 `isolatedCommand`):cwd 在任务根(`EXECUTOR_CWD`)严格之下的命令,spawn 时包一层 wrapper,在新的 mount namespace 里把任务根覆盖为 tmpfs、只把当前会话根(第一层子目录)bind 回原路径——AI 只能看到/改自己的项目,看不到别的会话;cwd 在任务根本身或其外(如 skill 入口跑在技能目录)不隔离直接 spawn。需 compose 配 `cap_add: SYS_ADMIN` + `security_opt: apparmor=unconfined`(不用 privileged:实测 Docker 29,默认 AppArmor profile 拦 `mount(2)`,单加 SYS_ADMIN 不够;默认 seccomp 对持 CAP_SYS_ADMIN 的进程放行 `unshare(2)`/`mount(2)`,无需改动);`unshare`/`mount`/`mktemp` 来自 debian 基础包 util-linux。 +**per-task 挂载隔离**(`server.js` 的 `isolatedCommand`):cwd 在任务根(`EXECUTOR_CWD`)严格之下的命令,spawn 时包一层 wrapper,在新的 mount namespace 里把任务根覆盖为 tmpfs、只把当前会话根(第一层子目录)bind 回原路径——AI 只能看到/改自己的项目,看不到别的会话;cwd 恰为任务根被 /exec 边界直接拒 400(见上);cwd 在任务根外(如 skill 入口跑在技能目录)不隔离直接 spawn。需 compose 配 `cap_add: SYS_ADMIN` + `security_opt: apparmor=unconfined`(不用 privileged:实测 Docker 29,默认 AppArmor profile 拦 `mount(2)`,单加 SYS_ADMIN 不够;默认 seccomp 对持 CAP_SYS_ADMIN 的进程放行 `unshare(2)`/`mount(2)`,无需改动);`unshare`/`mount`/`mktemp` 来自 debian 基础包 util-linux。 **资源护栏**(compose 层,**不在 server.js**): `cpus 2.0` / `mem_limit 2g` / `pids_limit 512` / `ulimits.fsize 2G` —— 防 AI 失控命令。残余缺口(只限单文件不限总量)在 compose 注释里已标。 diff --git a/executor/server.js b/executor/server.js index 5938873..55e2478 100644 --- a/executor/server.js +++ b/executor/server.js @@ -14,6 +14,8 @@ // 安全约束: // - 设置 EXECUTOR_TOKEN 后,除 /health 外必须带 Authorization: Bearer (compose 内网互访,token 可选); // - cwd 必须落在 EXECUTOR_ROOTS(逗号分隔白名单,默认 /workspace)内,先解析再 realpath 校验,防穿越; +// - cwd 不得是任务根(EXECUTOR_CWD)本身:它是全部会话目录的父目录,直接在其下执行会暴露所有会话, +// 隔离 wrapper 在此层也无从生效;缺省 cwd 即落到任务根、同样被拒,等效 cwd 必填; // - timeout_ms 夹在 [1s, EXECUTOR_MAX_TIMEOUT_MS](默认 30 分钟); // - stdout/stderr 各自按 max_output_chars 截断(默认 EXECUTOR_MAX_OUTPUT_CHARS=200000),超限后丢弃剩余输出,exit 事件带 truncated 标记。 // @@ -41,6 +43,8 @@ const PORT = parseInt(process.env.PORT, 10) || 9000; const TOKEN = process.env.EXECUTOR_TOKEN || ''; const ROOTS = (process.env.EXECUTOR_ROOTS || '/workspace').split(',').map(s => s.trim()).filter(Boolean).map(p => path.resolve(p)); const DEFAULT_CWD = process.env.EXECUTOR_CWD || path.join(ROOTS[0], 'tasks'); +// 任务根 realpath:/exec 一律拒绝 cwd 恰好等于它(见 handleExec)。拒绝后「任务根下的命令必进隔离 wrapper」成为硬不变式。 +const REAL_TASK_ROOT = (() => { try { return fs.realpathSync(DEFAULT_CWD); } catch (_) { return null; } })(); const MAX_TIMEOUT = parseInt(process.env.EXECUTOR_MAX_TIMEOUT_MS, 10) || 30 * 60 * 1000; const DEFAULT_MAX_OUT = parseInt(process.env.EXECUTOR_MAX_OUTPUT_CHARS, 10) || 200000; const PING_MS = 15000; @@ -94,6 +98,7 @@ function shq(s) { return "'" + String(s).replace(/'/g, "'\\''") + "'"; } // 3) 在 tmpfs 下重建当前会话目录名,把 anchor bind 回原路径上 // 4) 拆掉 anchor,切到 cwd,exec 用户命令 // cwd 不在任务根下时返回 null(不隔离;主要适用于 skill 入口直接跑在 /workspace/skills/ 的场景)。 +// cwd 恰为任务根本身已在 handleExec 边界拒绝,首条分支仅作兜底。 function isolatedCommand(command, cwd) { if (cwd === DEFAULT_CWD || !cwd.startsWith(DEFAULT_CWD + path.sep)) return null; // 会话根 = 任务根下的第一层子目录(task-YYYYMMDD-NNN);cwd 可能是其下任意深子目录(terminal 的 cd)。 @@ -168,6 +173,8 @@ function killGroup(entry) { function sseWrite(res, obj) { log.debug('sse →', brief(JSON.stringify(obj))); + // 客户端断开后 res 已死:实测 Node 20 对 destroyed 的 write 静默丢弃,但不依赖该行为,写前显式拦。 + if (res.writableEnded || res.destroyed) return; res.write('data: ' + JSON.stringify(obj) + '\n\n'); } @@ -179,9 +186,12 @@ async function handleExec(req, res) { const command = String(args.command || ''); if (!command.trim()) return send(res, 400, { error: 'command 必填' }); - const rawCwd = args.cwd ? String(args.cwd) : DEFAULT_CWD; + const rawCwd = args.cwd ? String(args.cwd) : DEFAULT_CWD; // 缺省落任务根 → 下面边界拒绝,等效必填 const cwd = checkCwd(rawCwd); if (!cwd) return send(res, 400, { error: 'cwd 不存在或不在白名单目录内:' + rawCwd + '(允许:' + ROOTS.join(', ') + ')' }); + if (REAL_TASK_ROOT && cwd === REAL_TASK_ROOT) { + return send(res, 400, { error: 'cwd 不能是任务根本身(全部会话目录的父目录,在其下执行会暴露所有会话):请在具体会话子目录内执行:' + rawCwd }); + } let timeout = parseInt(args.timeout_ms, 10); if (!isFinite(timeout) || timeout <= 0) timeout = 5 * 60 * 1000; @@ -221,7 +231,7 @@ async function handleExec(req, res) { 'Connection': 'keep-alive', 'X-Accel-Buffering': 'no', // nginx 前置时对 SSE 关缓冲(配合 core 的 proxy_buffering off 习惯) }); - const ping = setInterval(() => { res.write(': ping\n\n'); }, PING_MS); + const ping = setInterval(() => { if (!res.writableEnded && !res.destroyed) res.write(': ping\n\n'); }, PING_MS); // 先下发 start 事件:core 靠这里的 id 调 DELETE /exec/:id 取消 sseWrite(res, { type: 'start', id, pid: child.pid, cwd }); @@ -249,11 +259,14 @@ async function handleExec(req, res) { function finish(code) { if (!runs.has(id)) return; clearTimeout(entry.timer); clearInterval(ping); runs.delete(id); + // 清理与日志先行:客户端已断开(destroyed,writableEnded 恒 false)也要留 exit 痕迹; + // 之后不再碰 res:不对已死/已 end 的响应 write(sseWrite 内有同款守卫兜底)也不重复 end()。 + log.info('exit ', id, 'code=' + code, 'killed_by=' + entry.killedBy, 'out=' + out.stdout + 'B err=' + out.stderr + 'B'); + if (res.writableEnded || res.destroyed) return; sseWrite(res, { type: 'exit', code, signal: child.signalCode, killed_by: entry.killedBy, stdout_chars: out.stdout, stderr_chars: out.stderr, truncated: out.truncated, }); - log.info('exit ', id, 'code=' + code, 'killed_by=' + entry.killedBy, 'out=' + out.stdout + 'B err=' + out.stderr + 'B'); res.end(); } child.on('error', err => { entry.killedBy = entry.killedBy || 'spawn_error'; log.error('spawn error', id, err.message); streamChunk('err', Buffer.from('spawn 失败:' + err.message + '\n')); finish(-1); }); diff --git a/executor/smoke-test.js b/executor/smoke-test.js index 88c86a9..785c739 100644 --- a/executor/smoke-test.js +++ b/executor/smoke-test.js @@ -1,9 +1,14 @@ // agent-executor 冒烟测试:node smoke-test.js(在本目录执行)。 -// 覆盖:/health、/exec 流式输出与退出事件、增量下发时序、cwd 白名单拒绝、DELETE 取消、EXECUTOR_TOKEN 鉴权、per-task 挂载隔离。 -// 注意:隔离用例需 root/CAP_SYS_ADMIN(unshare+mount),无权限时自动 SKIP 不计失败。 +// 覆盖:/health、/exec 流式输出与退出事件、增量下发时序、cwd 白名单拒绝、任务根边界(缺省/恰为任务根 → 400)、DELETE 取消、EXECUTOR_TOKEN 鉴权、per-task 挂载隔离、客户端半路断连不击穿服务。 +// 注意:隔离用例需 root/CAP_SYS_ADMIN(unshare+mount),无权限时自动 SKIP 不计失败;其余用例 cwd 故意取任务根外目录,保持非隔离路径可在无权限环境跑。 process.env.PORT = process.env.PORT || '19000'; -process.env.EXECUTOR_ROOTS = process.env.__SELF_DIR__ || __dirname; // 宿主机测试:白名单取本目录 -process.env.EXECUTOR_CWD = process.env.__SELF_DIR__ || __dirname; +const SELF = process.env.__SELF_DIR__ || __dirname; // 宿主机测试:白名单取本目录 +process.env.EXECUTOR_ROOTS = SELF; +// 任务根改用专用子目录(不建在任务根下):主套命令的 cwd 传 SELF(任务根外 → 不进 wrapper), +// 同时留出「cwd=任务根 → 400」的可测边界。 +const TASK_ROOT = SELF + '/.taskroot'; +require('fs').mkdirSync(TASK_ROOT, { recursive: true }); +process.env.EXECUTOR_CWD = TASK_ROOT; delete process.env.EXECUTOR_TOKEN; // 主实例不带 token,鉴权单独测 const { spawn } = require('child_process'); @@ -42,7 +47,7 @@ async function main() { // 2. 基本执行:stdout/stderr/exit,且增量分块下发(a 与 b 之间 sleep,验证非攒到最后) const t0 = Date.now(); - const r2 = await fetch(BASE + '/exec', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ command: 'echo a; sleep 0.6; echo b; echo e1 >&2; exit 3' }) }); + const r2 = await fetch(BASE + '/exec', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ command: 'echo a; sleep 0.6; echo b; echo e1 >&2; exit 3', cwd: SELF }) }); const evs2 = []; const marks = []; for await (const e of sse(r2)) { evs2.push(e); if (e.type === 'out') marks.push(Date.now() - t0); } @@ -57,8 +62,14 @@ async function main() { const r3 = await fetch(BASE + '/exec', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ command: 'pwd', cwd: '/etc' }) }); check('cwd 越权 400', r3.status === 400, 'status=' + r3.status); + // 3.5 任务根边界:缺省 cwd(落任务根)与显式 cwd=任务根都必须 400——任务根是全部会话目录的父目录,放行会绕过隔离。 + const rb1 = await fetch(BASE + '/exec', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ command: 'echo hi' }) }); + check('cwd 缺省(落任务根)400', rb1.status === 400, 'status=' + rb1.status); + const rb2 = await fetch(BASE + '/exec', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ command: 'echo hi', cwd: TASK_ROOT }) }); + check('cwd=任务根本身 400', rb2.status === 400, 'status=' + rb2.status); + // 4. 取消:sleep 30 启动后立即 DELETE - const r4 = await fetch(BASE + '/exec', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ command: 'sleep 30' }) }); + const r4 = await fetch(BASE + '/exec', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ command: 'sleep 30', cwd: SELF }) }); let id4 = null; const evs4 = []; for await (const e of sse(r4)) { evs4.push(e); if (e.type === 'start' && !id4) { id4 = e.id; const k = await fetch(BASE + '/exec/' + id4, { method: 'DELETE' }); check('DELETE /exec/:id 返回 ok', (await k.json()).ok === true); } } const exit4 = evs4[evs4.length - 1]; @@ -66,19 +77,28 @@ async function main() { // 5. 超时自杀 const t5 = Date.now(); - const r5 = await fetch(BASE + '/exec', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ command: 'sleep 30', timeout_ms: 600 }) }); + const r5 = await fetch(BASE + '/exec', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ command: 'sleep 30', timeout_ms: 600, cwd: SELF }) }); const evs5 = await collect(r5); const exit5 = evs5[evs5.length - 1]; check('超时 killed_by=timeout', exit5 && exit5.killed_by === 'timeout', JSON.stringify(exit5)); check('超时耗时接近设定值', Date.now() - t5 < 3000, (Date.now() - t5) + 'ms'); // 6. 输出截断 - const r6 = await fetch(BASE + '/exec', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ command: 'printf x%.0s $(seq 1 500); echo', max_output_chars: 100 }) }); + const r6 = await fetch(BASE + '/exec', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ command: 'printf x%.0s $(seq 1 500); echo', max_output_chars: 100, cwd: SELF }) }); const evs6 = await collect(r6); const outChars = evs6.filter(e => e.type === 'out').reduce((s, e) => s + e.chunk.length, 0); const exit6 = evs6[evs6.length - 1]; check('输出按 max_output_chars 截断', outChars <= 100 && exit6.truncated === true, 'chars=' + outChars + ' exit=' + JSON.stringify(exit6)); + // 7. 客户端半路断连:持续小输出中 abort 掉 SSE 连接,服务不能崩(write-after-destroy 回归护栏)。 + const ac7 = new AbortController(); + const r7 = await fetch(BASE + '/exec', { method: 'POST', headers: { 'Content-Type': 'application/json' }, signal: ac7.signal, body: JSON.stringify({ command: 'while :; do echo x; sleep 0.05; done', cwd: SELF }) }); + for await (const e of sse(r7)) { if (e.type === 'start') break; } + await new Promise(r => setTimeout(r, 300)); // 让服务端先下发若干 out 帧 + ac7.abort(); + await new Promise(r => setTimeout(r, 800)); // 留给服务端 close→杀进程→finish 走完 + check('客户端半路断连不击穿服务(/health 仍 200)', (await fetch(BASE + '/health')).status === 200); + // 7.5 per-task 挂载隔离:另起一个实例(端口 19002),EXECUTOR_CWD=.iso-tasks(任务根), // 下放 iso-a / iso-b 两个「会话」目录;cwd 取 iso-a 的深层子目录(模拟 terminal 的 cd),验证: // 任务根下只看到 iso-a、cd 兄弟会话被拒、自己文件可读;无 mount 权限时整组 SKIP。 @@ -115,14 +135,15 @@ async function main() { // 8. token 鉴权:另起一个带 EXECUTOR_TOKEN 的实例(子进程,端口 19001) const child = spawn(process.execPath, [__dirname + '/server.js'], { env: Object.assign({}, process.env, { PORT: '19001', EXECUTOR_TOKEN: 't9' }), stdio: 'ignore' }); await new Promise(r => setTimeout(r, 500)); - const noTok = await fetch('http://127.0.0.1:19001/exec', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ command: 'echo hi' }) }); + const noTok = await fetch('http://127.0.0.1:19001/exec', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ command: 'echo hi', cwd: SELF }) }); check('无 token 401', noTok.status === 401, 'status=' + noTok.status); const healthNoTok = await fetch('http://127.0.0.1:19001/health'); check('带 token 时 /health 仍免鉴权', healthNoTok.status === 200); - const withTok = await fetch('http://127.0.0.1:19001/exec', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: 'Bearer t9' }, body: JSON.stringify({ command: 'echo hi' }) }); + const withTok = await fetch('http://127.0.0.1:19001/exec', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: 'Bearer t9' }, body: JSON.stringify({ command: 'echo hi', cwd: SELF }) }); const evs8 = await collect(withTok); check('带 token 正常执行', evs8.some(e => e.type === 'out' && e.chunk.trim() === 'hi'), JSON.stringify(evs8)); child.kill('SIGKILL'); + fs.rmSync(TASK_ROOT, { recursive: true, force: true }); console.log(failed ? '\n' + failed + ' 项失败' : '\n全部通过'); process.exit(failed ? 1 : 0);