为什么需要审计？

如果 AI 助手偷偷执行了 rm -rf /你事后怎么知道？

使用者痛点：缺少事后追溯手段，导致安全事故难以定位；运维人员常常在事故发生后才发现问题，浪费大量排查时间。

审计日志正是为了解决这些痛点而生。每一次命令执行，都会在 audit.jsonl 中留下完整记录：

{"runId":"abc-123","time":"2024-10-15T10:00:00Z","event":"sandbox.command.started","command":"ls","mode":"workspace-write","approved":true}
{"runId":"abc-123"。"time":"2024-10-15T10:00:01Z","event":"sandbox.command.finished","command":"ls","exitCode":0,"durationMs":1023,"stdoutBytes":128,"stderrBytes":0}

审计目录结构

使用者痛点：日志分散、找不到对应的输出文件或元数据时需要手动搜索多个目录，效率低下。

${元数据目录}/audit/
├── audit.jsonl ← 所有事件的 JSONL 日志
├── abc-123/ ← 单次 run 的目录。以 runId 为名
│ ├── stdout.txt ← 命令的 stdout 输出
│ ├── stderr.txt ← 命令的 stderr 输出
│ └── metadata.json ← run 摘要
├── def-456/
│ ├── stdout.txt
│ ├── stderr.txt
│ └── metadata.json
└── ...

SandboxRunSession —— 单次 Run 的会话

使用者痛点：开发者需要自己维护 runId、方法等上下文信息，容易出错且代码冗余。

export class SandboxRunSession {
readonly ctx: AuditContext;readonly paths: RunFilePaths;private constructor(
private readonly auditRecorder: SandboxAuditRecorder。ctx: AuditContext,paths: RunFilePaths,) {
this.ctx = ctx;其实，this.paths = paths;}
get runId: string {
return this.ctx.runId;}
static open: SandboxRunSession {
const runId = createUUID;// 自动生成唯一 ID
fs.mkdirSync;fs.mkdirSync,{ recursive: true });const ctx: AuditContext = {
auditDir: options.auditDir,runId。projectRoot: options.projectRoot,executionRoot: options.executionRoot,};return new SandboxRunSession(
options.auditRecorder。ctx,getRunFilePaths
);}
async record: Promise {
return this.auditRecorder.record;其实，}
writeMetadata: void {
fs.writeFileSync(
this.paths.metadataPath。
JSON.stringify,'utf8'
);}
}

open —— 创建 Run 会话

static open: SandboxRunSession {
const runId = createUUID;// 自动生成唯一 ID
// 创建根目录和本次运行专属目录
fs.mkdirSync;fs.mkdirSync,{ recursive: true });const ctx = {
auditDir: options.auditDir,runId。projectRoot: options.projectRoot,executionRoot: options.executionRoot,};return new SandboxRunSession(
options.auditRecorder。ctx,getRunFilePaths
);}

record —— 写审计事件

async record: Promise {
// 自动注入当前会话的 runId，调用方无需手动传递
return this.auditRecorder.record;}

writeMetadata —— 写 Run 摘要

writeMetadata: void {
// 每次覆盖写入。保持最新状态
fs.writeFileSync(
this.paths.metadataPath,JSON.stringify,'utf8'
);}

metadata.json 示例：

{
从"kind"来看，"sandbox.command","command": "ls -la","riskLevel": "L0","approved": true,"requestedMode": "workspace-write","effectiveMode": "workspace-write"。"exitCode": 0,"durationMs": 1023,"stdoutBytes": 128,"stderrBytes": 0
}

getRunFilePaths ——计算 Run 子方法

export function getRunFilePaths: RunFilePaths {
const runDir = path.join;return {
stdoutPath: path.join。stderrPath: path.join,metadataPath: path.join,};话说回来，}

audit.ts —— 审计辅助函数集合

createRunId

export function createRunId: string {
return createUUID;}

createAuditContext

export function createAuditContext: AuditContext {
return SandboxRunSession.open({
auditRecorder:getSharedAuditRecorder。auditDir,projectRoot,executionRoot,}).ctx;}

createSandboxAuditRecorder

export function createSandboxAuditRecorder: SandboxAuditRecorder {
// 同一 auditDir 共用同一个 recorder，避免重复打开文件句柄
return getSharedAuditRecorder;}

buildCommandAuditMetadata

export function buildCommandAuditMetadata: Record {
return { kind:'sandbox.command',...input };}

normalizeSandboxEvent

export function normalizeSandboxEvent: sandbox.${string} | string {
return event.startsWith?event : sandbox.${event};}

审计事件类型