Skip to content
Vehicle-Security
Transpect
Public

About

Transparent Inspect LLM Agent

Resources

Readme

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository
BranchesTags

Repository files navigation

Transpect

Transpect 是一个 trace-first(以轨迹为先)的 Agent 安全基准与监管平台。它运行真实的 AI Agent 任务(通过 OpenClaw),采集运行时证据(行为日志、Frida 系统级插桩、工具调用产物),重建跨进程数据流,诊断失败轨迹,并施加在线安全护栏——在不安全的 Agent 行为执行之前检测并拦截它。主打演示场景是一次分阶段的小红书水坑攻击(watering-hole)。

仓库围绕"以运行(run)为单位"的存储模型组织:一个任务对应一个自包含的证据目录,位于 monitor/live/runs/<runId>/ 下,不依赖任何全局状态。

transpect.py 是统一入口,串起闭环:

trace -> guard -> evidence -> replay -> audit -> score -> attribution

它把上述阶段全部收敛到同一个运行目录,并分发给 tools/cli/main.py 中的各子命令。请优先使用它,而不是直接调用底层的 tools/... 脚本。

快速开始

最低支持路径是确定性、离线的运行时安全演示。它不需要 OpenClaw、Frida、CodeTracer、R-Judge 或任何 LLM key。

git clone https://github.com/Vehicle-Security/Transpect.git Transpect
cd Transpect

# Apple Silicon:一套统一的 arm64 运行时 / 开发 / Frida 环境
python tools/runtime/setup_frida_arm64.py
source .venv-arm64-frida/bin/activate

# 端到端跑一遍确定性的提示注入(prompt-injection)演示
python transpect.py run config/tasks/demo_prompt_injection.json
python transpect.py analyze --latest
python transpect.py view --latest

这次运行会在 monitor/live/runs/<runId>/ 下写出 trace、guard、evidence、audit、replay、scoring、attribution 各类产物。

若环境里没有 python,请直接使用 .venv-arm64-frida/bin/python。 在 Apple Silicon 上只维护 .venv-arm64-frida 这一套物理 arm64 环境;不要再创建 x86_64 项目 venv 或 .venv 别名。

统一 CLI

运行任务

# 确定性、离线的提示注入演示(无外部依赖)
python transpect.py run config/tasks/demo_prompt_injection.json

# 配置文件驱动;命令行参数覆盖配置文件里的值
python transpect.py run -c config/secure_run.yaml
python transpect.py run -c config/secure_run.yaml --block-threshold 0.85

检查已有运行

python transpect.py analyze --latest   # 重建 evidence/score/attribution/replay/audit/trace
python transpect.py view --latest      # 打印审计产物路径
python transpect.py replay --latest    # 紧凑的回放时间线

真实 Agent 运行(run-real)

run-real 把 Transpect 接到真实的 OpenClaw / task-repo 运行时:它跑现有 task repo 的 agent-trace 流水,把实时 OpenClaw 事件适配成同一套 AgentTrace 模式,再复用完全相同的 guard/evidence/audit/diagnosis 各阶段。

python transpect.py run-real --repo staged_attack \
  --task-id "data/showcase_cases.json#xhs-waterhole-confirm-001"

需要根目录 .env 中配好 BASE_URL、API_KEY、MODEL_ID,以及一个已就绪的 OpenClaw 运行时(见下文「部署级别 · Level 2」)。

若真实 OpenClaw/API 依赖不可用,请跑适配器契约测试,而不要谎称完成了一次在线运行:

python -m unittest monitor.tests.validate.test_real_agent_adapter_contract -v

该契约验证:真实运行器风格的事件能被转换成 trace/agent_events.jsonl,在风险动作前被 guard 拦截,并被 evidence/audit/score/attribution 各构建器消费。

一条命令的在线演示(demo)

transpect.py demo 依次对本机 OpenClaw agent 跑三个 staged-attack 场景,自动加载 .env、自动拉起本地 staged-attack 站点,并为每个场景打印"预期决策 vs 实际决策"。

python transpect.py demo                                 # 三个场景全跑
python transpect.py demo --scenario waterhole_confirm    # 只跑一个场景(可重复)
python transpect.py demo --with-diagnosis                # 同时跑 CodeTracer(更慢)
场景 key 预期决策 说明
normal_browsing ALLOW 良性、只读浏览话题页 —— 稳定
waterhole_confirm REQUIRE_CONFIRMATION 灰区:外部跳转 / 内联 POST,无敏感上传 —— 真正可变
waterhole_block BLOCK staged 照片上传外泄尝试 —— 稳定

关于 LLM 不确定性: demo 驱动的是一个真实、非确定性的 LLM agent,所以灰区场景不会产生固定决策。当模型越界并计划照片上传时,guard 正确地把 REQUIRE_CONFIRMATION 升级为 BLOCK —— 这是护栏在生效,而非 bug。汇总里如实标注(✅ = 匹配意图,⚠️ = 在线偏差)。结果从不被硬编码,策略阈值也不会被调来强行"通过"某个场景。

交互式实时监管(chat)

想要"启动后实时监管 Agent 操作"的平台,用 transpect.py chat。它把你带进一个 REPL:你逐句和真实 OpenClaw Agent 对话,每条消息与 Agent 的每个动作都被实时监管。

python transpect.py chat                        # 自动生成会话 id,自动起站点、加载 .env
python transpect.py chat --session-id my_demo   # 复用/指定会话 id(即运行目录名)

每一轮有两层监管:

  1. 输入闸门(Agent 启动前):你的消息先过 inspect_user_input + inspect_plan。判为 block 的消息直接被拒;判为 require_confirmation 的在终端询问 y/N。
  2. 运行时拦截(网关内,自动):一旦 setup_runtime.py 把行为中介接入 OpenClaw,Agent 尝试的每个工具调用 / 网络请求都在执行前被 guardrail/agent_defense/bridge.py 拦截判定。

一个会话对应一个稳定的 session id,也就是一个运行目录,每一轮追加到同一份 behavior-events.jsonl,安全上下文持续累积。输入 exit / quit / 退出 结束会话,结束时自动做整场分析(除非加 --no-analyze)。同时打开 dashboard 的 /live 页面即可实时看到这次会话。

分层构建命令(单个运行目录)

python transpect.py trace build    --run-dir monitor/live/runs/<runId>
python transpect.py evidence build --run-dir monitor/live/runs/<runId>
python transpect.py diagnose       --run-dir monitor/live/runs/<runId>
python transpect.py score          --run-dir monitor/live/runs/<runId>
python transpect.py audit build    --run-dir monitor/live/runs/<runId>

三层 Trace(raw-first)

除了应用层日志 trace,Transpect 还采集 系统 / 运行时 / 应用 三层证据,使得 Programmatic Tool Calling(PTC)与加密 skill 执行即便在命名工具日志不透明或缺失时依然可见。

Raw trace 契约

真实 OpenClaw 与 child-attach 运行会在 traces/ 下写出采集器原样字段的文件:

  • application_trace.jsonl —— OpenClaw 字段(event、toolName、toolCallId、target、preview、status…)
  • runtime_trace.jsonl —— hook 字段(event=code_eval/skill_load、pid、api、codePreview、name、encrypted…)
  • system_trace.jsonl —— Frida 字段(type、ts、pid、tid、kind、payload.api/fd/path/bytesRead/previewAscii…)

这三层 trace 只存原始事实,不得混入派生概念。

单一适配器与派生分析

monitor/trace_model/raw_adapters.py 是唯一的 raw→fact 解析器:它计算内容身份 / data_ref,把 Frida 截断的 previewAscii 与 OpenClaw 完整内容匹配,从原始命令解析 exec-curl 网络 sink,并把旧版 runtime hook 行转换为 raw event 行。

派生分析产物(data_flow.json、diagnosis/dataflow_graph.json、traces/application_trajectory.json、security-reasoning/shadow_activity.json 及各类报告)都从适配器事实推导。data_ref、call_llm 变换、exec-curl sink、shadow 结论等派生概念只出现在这些分析输出里,不进三层 trace。

真实 Trace 采集

# 真实 OpenClaw read -> LLM -> write,配合 Frida 系统证据
.venv-arm64-frida/bin/python transpect.py chat --real-trace-demo \
  --capture-real-trace --frida on --yes --no-site --no-analyze

# 真实 Agent + 实时 Frida 后代进程 attach(Apple Silicon,需终端 sudo)
sudo .venv-arm64-frida/bin/python transpect.py trace child-attach-demo

# 独立的加密-skill 演示,CLI 仅暴露实时 Frida 证据
.venv-arm64-frida/bin/python transpect.py trace encrypted-skill-demo

# 信息流 + 授权 MVP：5个恶意/6个行为匹配良性场景，每例重复3次
.venv-arm64-frida/bin/python transpect.py trace information-flow-evaluate \
  --output-dir monitor/live/runs/information_flow_demo \
  --timeout 30 --repeat 3

# 固定的42个恶意代码 Skill + 15个行为匹配良性 Skill 信息流泛化实验
.venv-arm64-frida/bin/python transpect.py trace real-skill-information-flow-evaluate \
  --output-dir monitor/live/runs/real_skill_information_flow_<run-id>

# 对已有信息流报告执行任务作用域授权判定
.venv-arm64-frida/bin/python transpect.py trace authorize \
  --run-dir <run-dir> \
  --policy config/skill_capability.example.json

# 在固定的42个恶意与15个行为匹配良性 Skill 上运行最终裁决及适配基线
.venv-arm64-frida/bin/python transpect.py trace skill-audit-compare \
  --output-dir monitor/live/runs/skill_audit_comparison_<run-id> \
  --rsa-repo /path/to/Runtime-Skill-Audit

# 快照本机实际安装的 Skill；记录来源与哈希，但不执行上游内容
.venv-arm64-frida/bin/python transpect.py trace real-skills snapshot

# 下载固定版本、已由上游运行时验证的恶意 Skill pilot；仅隔离保存
.venv-arm64-frida/bin/python transpect.py trace malicious-skills fetch

# 构建断网 Docker 审计镜像，并动态评估带显式代码入口的恶意 Skill
.venv-arm64-frida/bin/python transpect.py trace malicious-skills build-image
.venv-arm64-frida/bin/python transpect.py trace malicious-skills evaluate \
  --output-dir monitor/live/runs/malicious_skill_pilot_<run-id>

# 扩大到预先固定、B1-B9 均衡的 36 个代码型恶意 Skill
.venv-arm64-frida/bin/python transpect.py trace malicious-skills fetch \
  --config config/malicious_skill_expanded.json \
  --output-dir monitor/live/datasets/malicious_skills/expanded_b1_b9_36

# 构建 B1-B15 混合集：B1-B9 代码注入，B10-B15 Prompt Injection
.venv-arm64-frida/bin/python transpect.py trace malicious-skills fetch \
  --config config/mixed_skill_b1_b15.json \
  --output-dir monitor/live/datasets/malicious_skills/mixed_b1_b15
.venv-arm64-frida/bin/python transpect.py trace mixed-skills evaluate \
  --output-dir monitor/live/runs/mixed_skill_b1_b15_<run-id>

# 使用官方 Codex + DeepSeek 运行 B10-B15 真实 Agent 工具调用实验
python transpect.py trace codex-skills build-images
python transpect.py trace codex-skills evaluate \
  --dataset-dir monitor/live/datasets/malicious_skills/mixed_b1_b15_5_each \
  --output-dir monitor/live/runs/codex_skill_pi_<run-id> \
  --limit-per-behavior 5
  • real-trace-demo 驱动本机 OpenClaw agent 走一个安全 sandbox 任务:先落盘原始 OpenClaw read/write/tool/LLM 行 + 实时 Frida 文件事件,再由 DataFlowBuilder 重建 read → call_llm → write + network。Frida 是验收必需,replay 标注的系统证据会被拒绝。
  • child-attach-demo 在发送恰好一轮真实 agent turn 前,先对 OpenClaw 网关启动 ChildProcessWatcher。应用层 trace 只见不透明的 XOR+base64 node -e exec;runtime raw 行显示同 pid 的 code_eval / 加密 skill_load;system raw 行显示被监视子进程的实时 Frida open/read/write。shadow_activity.json 报告 evidence/reason 结论。

真实 Skill 快照与 macOS 免重复输密码的受限 Frida 启动器见 docs/real_skill_evaluation_and_macos_runner.md。真实 Skill 默认保持 unlabeled/not_reviewed/not_executed，未经人工复核不得计入 TPR/FPR。 恶意 Skill 的 Docker 动态实验设计、结果和结论边界见 docs/malicious_skill_dynamic_pilot.md。 代码注入与 Prompt Injection 的 B1-B15 混合实验见 docs/mixed_skill_b1_b15_evaluation.md。 加密 Skill、PTC 审计方法及 75 样本实验的汇报提纲见 docs/skill_audit_report.md。 Marker、跨进程 Source→Sink 证据、置信度和影子模式评测见 docs/information_flow_mvp.md。 Requested、Task Required、User/System Approved 三方能力交集与授权判定见 docs/authorization_mvp.md。 Codex + DeepSeek 真实 Agent 工具调用实验见 docs/codex_deepseek_skill_evaluation.md。 恶意样本仅在 --network none、只读根文件系统、删除全部 capabilities 和假凭据条件下运行。没有显式代码入口、必须由 Agent 解释 SKILL.md 的样本标记为 unsupported，不计作 FN。

Trace 模块研发期间,behavior-mediator 可保持 audit(执行后取证);验证"执行前在线拦截"时再切回 enforce——enforce 会正确地在执行前拦截不透明 node -e。报告里的 behaviorMediatorMode 会保留这项实验前提。

Trace-only 研究基准

python transpect.py trace benchmark build --output-dir <dir>       # 生成 12 例 shadow-trace-bench-v1 fixture
python transpect.py trace benchmark evaluate --dataset-dir <dir>   # 评测 4 种可见性基线

该基准评测 application-only、span-exporter、system-intent、full three-layer 四种可见性,只衡量证据与数据流的恢复能力,不触发 guard / diagnosis / scoring / final judgment。Fixture 系统行显式标为 synthetic,不得当作实时 Frida/eBPF 采集。

AgentHazard 的隔离执行、host 实验和 Linux/eBPF 采集说明分别见 docs/agenthazard_trace_only.md 与 docs/utm_linux_collector.md。上游数据通过 transpect.py trace agenthazard fetch 下载到被忽略的 monitor/live/，不在仓库中重复维护。 当前代码、dry-run、fixture 和采集器单元测试已纳入离线门禁；在真实模型凭据下的 10-case AgentHazard + eBPF 全链路 canary 尚未完成，因此不得把现阶段结果表述为完整实测结论。

紧凑 Trace 布局

真实 Trace 运行优先为 Trace 模块组织目录:

monitor/live/runs/<runId>/
  data_flow.json                     结构化 source/transform/sink 数据流图
  traces/
    application_trace.jsonl          应用层原始事件流
    application_trajectory.json      从应用层派生的会话视图(保留 sourceEventIds 回指原始证据)
    runtime_trace.jsonl              runtime hook 原始事件流
    system_trace.jsonl               Frida 原始系统事件流
  raw/                               仅供审计的输入证据
    openclaw-tools.jsonl
    behavior-events.jsonl
    runtime-events.jsonl
    trajectory.txt                   人类可读:同一个 blob_NNN 如何流经工具调用与系统证据
    real_capture_report.json         验收结果(hasApplicationRead/hasSystemRead/hasLlmTransform/fridaSatisfied…)

外部 Frida 原始日志可能很大,紧凑运行可用 raw/frida-events.ref.json 指向真实 Frida JSONL 而非拷贝。

架构

四层管线:

Layer 1  任务来源      monitor/task_repos/(R-Judge 适配器、staged_attack 演示)、config/tasks/ 演示规格
Layer 2  Agent 执行    OpenClaw 运行任务,behavior mediator 拦截事件
Layer 3  Trace + 诊断  三层 raw trace、合并 trace、CodeTracer bundle/analysis
Layer 4  安全推理      在线护栏、策略引擎、LLM 灰区判官、最终判定

进入管线有两条路径:

  • 确定性演示 / 配置运行(transpect.py run)—— tools/cli/pipeline/secure_pipeline.py 离线端到端跑完:构建 AgentTrace,把事件流过 guardrail/runtime/online_guard.py(在执行前拦截风险动作),再构建 evidence、失败归因、评分、回放时间线、审计报告,全部落到一个运行目录。无需 OpenClaw/LLM。
  • 真实 Agent 运行(transpect.py run-real)—— tools/cli/pipeline/real_agent_adapter.py 调用现有 task-repo agent-trace harness,把实时 OpenClaw 事件适配成同一 AgentTrace 模式,再复用完全相同的 guard/evidence/audit/diagnosis 各阶段。

核心包

  • tools/cli/ —— 统一 CLI。main.py 是 argparse 分发器;pipeline/secure_pipeline.py 与 pipeline/real_agent_adapter.py 是两个管线驱动;config.py 加载 config/*.yaml。
  • guardrail/runtime/ —— CLI 管线用的在线执行层:online_guard.py(观测 + 执行前拦截)、policy_engine.py、risk_scorer.py、state_tracker.py。策略是 guardrail/policies/ 下的 YAML。
  • guardrail/agent_defense/ —— 真实 OpenClaw 路径的协调层:bridge 入口、策略引擎、bypass 升级、动作归一化、trace 合并、最终判定。从 guardrail.security 导入,由 behavior-mediator 调用。
  • guardrail/security/ —— 护栏能力层:intent/plan/action 护栏、风险评分、信任模型、命令策略、决策引擎、LLM 灰区判官。纯检查函数,从不导入 guardrail.agent_defense。
  • monitor/trace_model/ —— 三层 trace 模型:raw_adapters.py(唯一 raw→fact 解析)、dataflow_builder.py、application_trajectory.py。
  • monitor/evidence/ —— evidence_builder.py / evidence_schema.py 从运行目录产出 security-reasoning/evidence_summary.json。
  • tools/audit/ —— build_audit_report.py、build_replay_timeline.py 产出 audit/ 产物。
  • tools/diagnosis/ —— 失败归因、Agent 质量评分、CodeTracer 诊断封装。
  • monitor/instrumentation/frida/ —— 可选 Frida 插桩(仅观测,优雅降级)。

关键设计决策

  • 每次运行自包含在 monitor/live/runs/<runId>/ 下,无全局状态。
  • 安全被融入运行时(在线),不只是事后分析 —— 护栏在风险动作执行前就拦截。
  • 两种策略格式共存:声明式 JSON(config/agent-defense-policy.json)用于真实 OpenClaw agent_defense 路径;YAML(guardrail/policies/*.yaml)用于 CLI guardrail/runtime 路径。
  • LLM 判官只作为灰区(ambiguous)场景的第二意见。
  • 缺失的可选组件(Frida、CodeTracer、R-Judge、LLM)报告 degraded/unavailable,而不破坏 Level 0 演示。
  • 本 README.md 与 CLAUDE.md 是权威的目录布局与用法契约。
  • 组件边界、依赖方向和证据流契约见 docs/architecture.md。

控制台 Dashboard

Dashboard 是 dashboard/console/ 下的 Next.js(TypeScript/React)应用,读取 dashboard/state/ 的 showcase 快照,并通过内置 API 直接读取本机 monitor/live/runs/,提供每 5 秒自动刷新的实时运行看板。

cd dashboard/console
npm install
npm run dev        # 本地开发服务器,默认 http://localhost:3000
npm run build      # 生产构建
npm run lint       # tsc --noEmit 类型检查

页面导航(全部中文):

  • / 总览 —— 平台整体视图
  • /benchmark 基准评测 —— Agent-SafetyBench 等基准结果
  • /demo 现场演示 —— 三个 staged-attack 场景
  • /live 实时运行 —— 直接读取本机 monitor/live/runs/,自动刷新;每跑一次 python transpect.py run … 都会在这里出现,可展开安全时间线
  • /pipeline 防御管线 —— 闭环各阶段
  • /method MATE 方法 —— 策略感知轨迹审计

数据来源是 monitor/live/runs/index.json 及各运行的 behavior-events.jsonl(读取逻辑见 dashboard/console/lib/live-runs.ts,API 路由见 dashboard/console/app/api/live-runs/)。

策略感知轨迹审计器(MATE 风格)

灰区 LLM 判官可作为策略感知轨迹审计器运行,复现 MATE(Policy-Aware Security Auditing for Mobile Agents via Synthesis-Driven Trajectory Learning,USENIX Security 2026,https://github.com/jiangchangyue/MATE)的*方法*。给定一个动作/轨迹,它检索相关的自然语言安全策略,并向 LLM 索取 {Violation, Category, Rationale},其中 Category 是 MATE 14 个风险类别之一。

  • 策略是 guardrail/policies/audit_policies.yaml 里的可编辑文本 —— 改安全要求无需改代码或重训练。
  • 检索:guardrail/security/policy_retriever.py(无依赖词法匹配)。
  • 审计器:guardrail/security/model_judge.py::audit_trajectory(使用 .env 的 LLM)。它复现 MATE 的方法,而非 MATE 尚未发布的微调模型;数字来自 Transpect 自己的 LLM。
  • 只在 require_confirmation 灰区上运行,从不降级一个硬性 block。

在 Agent-SafetyBench 上,扁平灰区判官对 10 条记录返回 10/10 require_confirmation(毫无区分度),而审计器能区分出 9 个 warn + 1 个 require_confirmation。开启:

python tools/benchmarks/run_agentsafetybench.py --limit 10 --auditor

环境与部署级别

LLM 配置

确定性演示不需要 LLM 或 .env。只有跑在线 Agent 任务、启用 LLM 灰区判官或运行 CodeTracer 诊断时才需要:

cp .env.example .env

填入 OpenAI 兼容的模型设置:

BASE_URL=https://api.openai.com/v1
API_KEY=...
MODEL_ID=gpt-4o-mini

这些值被 guardrail/security/model_judge.py、tools/common/task_repo_common.py、tools/diagnosis/run_codetracer_diagnosis.py 消费。.env 被 git 忽略,只提交 .env.example。

若 CodeTracer/ 或 R-Judge/ 不是 Transpect/ 的同级目录:

export CODETRACER_ROOT="$HOME/path/to/CodeTracer"
export R_JUDGE_ROOT="$HOME/path/to/R-Judge"

Level 0:运行时安全演示

需 Python 3.11+ 与 uv sync。无 OpenClaw/Frida/CodeTracer/R-Judge/LLM。

python transpect.py run config/tasks/demo_prompt_injection.json
python tools/validate/deployment_doctor.py --mode replay
python tools/validate/check_portability.py

Level 1:本地演示站点

为在线 task-repo 场景运行 staged attack 站点。

python tools/demo/run_staged_attack_site.py --host 127.0.0.1 --port 8765

Level 2:OpenClaw Agent 在线运行

生成新的真实 Agent 轨迹,需 OpenClaw 网关访问、behavior mediator hook 与模型配置。

cp .env.example .env  # 填好 BASE_URL/API_KEY/MODEL_ID
python tools/runtime/setup_runtime.py --mode core
python tools/validate/doctor.py
python transpect.py run-real --repo staged_attack \
  --task-id "data/showcase_cases.json#xhs-waterhole-confirm-001"

若 doctor.py 报告 scope upgrade pending approval 或 pairing required,先批准所请求的 OpenClaw scope 再重跑。

Level 3:完整证据运行(Frida + CodeTracer)

用于 OS 级 Frida 证据与 CodeTracer 诊断。缺失组件报告 degraded/unavailable,不破坏 Level 0。

python tools/runtime/setup_frida_arm64.py
sudo .venv-arm64-frida/bin/python transpect.py trace child-attach-demo

子进程 attach 需终端 sudo。watcher 以约 20 ms 周期轮询网关后代,极短命进程仍可能落入竞争窗口;报告保留 attach 记录并如实标为 INCONCLUSIVE,不用 replay 冒充实采。若未装 CodeTracer,tools/diagnosis/run_codetracer_diagnosis.py 写出带 status: "unavailable" 的结构化报告,该次运行仍能产出 final judgment、canonical trace 与可回放数据。

Level 4:R-Judge 批量评测

R-Judge 可选,仅当显式 --repo rjudge 时需要。缺失不影响 staged_attack 或 Level 0。

export R_JUDGE_ROOT="$HOME/path/to/R-Judge"
python tools/runtime/run_task_repo.py --repo rjudge --mode list-tasks
python tools/runtime/run_rjudge_batch.py --source-path data/Program --count 5 --concurrency 2

怎么跑数据集

数据集走 task repo 适配器(monitor/task_repos/),由 tools/runtime/run_task_repo.py 与批量脚本驱动,需 Level 2+ 在线运行时。

# 列出某 repo 可用任务
python tools/runtime/run_task_repo.py --repo rjudge --mode list-tasks

# 跑单个任务
python tools/runtime/run_task_repo.py --repo rjudge --mode agent-trace \
  --task-id "data/Application/chatbot.json#37"

# 批量运行(并发 2);加 --dry-run --no-start-runtime 可预览
python tools/runtime/run_rjudge_batch.py --source-path data/Program --count 5 --concurrency 2

# Agent-SafetyBench(可叠加策略感知审计器)
python tools/benchmarks/run_agentsafetybench.py --limit 10 --auditor

# staged attack 数据集(先起站点,再跑任务)
python tools/demo/run_staged_attack_site.py --host 127.0.0.1 --port 8765
python tools/runtime/run_task_repo.py --repo staged_attack --mode agent-trace \
  --task-id "data/xiaohongshu_waterhole_photo_upload.json#xhs-waterhole-photo-upload-001"

每个任务跑完后结果写入 monitor/live/runs/<runId>/ 并登记进 monitor/live/runs/index.json,可在 CLI(view --latest)与 dashboard /live 查看。

运行目录产物

一次运行时安全运行应包含:

trace/agent_events.jsonl
trace/canonical_trace.json
security-reasoning/defense_decision.json
security-reasoning/defense_decisions.jsonl
security-reasoning/evidence_summary.json
security-reasoning/final_judgment.json
diagnosis/agent_quality_score.json
diagnosis/failure_attribution.json
diagnosis/failure_graph.json
audit/replay_timeline.json
audit/audit_report.json

真实 Trace 采集运行额外写出 data_flow.json、traces/(三层 raw trace)与 raw/(审计输入证据),布局见上文「紧凑 Trace 布局」。

测试与验证

# Python
python -m pytest monitor/tests -q
python -m unittest discover -s monitor/tests -p 'test_*.py' -v
python -m unittest monitor.tests.test_agent_defense_chain -v
python -m unittest monitor.tests.validate.test_command_policy -v

# 缺 OpenClaw/API 依赖时,跑适配器契约而非谎称在线运行
python -m unittest monitor.tests.validate.test_real_agent_adapter_contract -v

# Node.js(behavior mediator)
node --test monitor/vendor/runtime-hooks/openclaw-behavior-mediator/tests/behavior-mediator.test.mjs
node --test monitor/vendor/runtime-hooks/openclaw-behavior-mediator/tests/runtime-capture.test.mjs

# 验证
node --check monitor/vendor/runtime-hooks/openclaw-behavior-mediator/index.js
python tools/validate/check_portability.py
python tools/validate/deployment_doctor.py --mode replay
python tools/validate/check_repo.py --skip-start
python tools/validate/run_acceptance.py

仓库布局

Transpect/
├── config/                          任务规格、secure_run.yaml、agent-defense-policy.json
├── dashboard/console/               Next.js 控制台 + 实时看板
├── guardrail/
│   ├── runtime/                     CLI 管线的在线护栏(online_guard、policy_engine…)
│   ├── agent_defense/               真实 OpenClaw 路径的协调层
│   ├── security/                    纯检查护栏能力层 + LLM 灰区判官
│   └── policies/                    YAML 策略、audit_policies.yaml
├── monitor/
│   ├── instrumentation/             Frida 与 Linux syscall/eBPF 采集器
│   ├── live/runs/<runId>/           每次运行的自包含证据
│   ├── runtime/                     OpenClaw 客户端helpers、agent 场景
│   ├── task_repos/                  R-Judge 适配器、staged_attack 演示
│   ├── trace_model/                 三层 trace 模型、raw_adapters、dataflow_builder
│   ├── evidence/                    evidence_builder / evidence_schema
│   ├── trace_benchmark/             Trace-only 研究基准 fixture
│   ├── tests/                       Python 测试
│   └── vendor/runtime-hooks/        仓库自有的 openclaw-behavior-mediator
├── tools/
│   ├── cli/                         统一 CLI(main.py + pipeline/)
│   ├── runtime/  validate/  export/  diagnosis/
│   ├── audit/  benchmarks/  demo/  capture/  common/
├── transpect.py                     统一入口
├── pyproject.toml   uv.lock
├── README.md   CLAUDE.md            权威布局与用法契约

分组后的工具路径(tools/runtime/、tools/validate/、tools/export/、tools/diagnosis/ …)是内部实现入口；对用户稳定的公共入口是根目录 transpect.py。

模块分层(论文主线 vs 平台其他能力)

本仓库包含的东西比论文实际论证的范围要大。config/module_scope.json 给每个顶层目录和主要子包打上分层标记，docs/module_scope.md 解释划分依据并给出各模块的真实行数：

分层 含义
core 论文主线。所有报告的数字都由这部分代码产出。分析模块 6,183 行 + 证据采集器 5,387 行，合计 11,570 行。
platform 平台其他能力:guardrail/runtime、guardrail/agent_defense 的在线拦截、staged_attack showcase、dashboard。证明证据层可以驱动防护,但不参与评测。
experiment 已冻结实验:AgentHazard 全线、R-Judge / AgentSafetyBench 适配器、fixture 基准、改写的外部 baseline。保留是为了可追溯,不在主线上。
infra 共享 helper、CLI 分发、测试、配置与文档。

不移动任何文件——分层只是元数据。移动包会在全仓库范围破坏 import,而换不来任何分析上的好处。tools/validate/check_repo.py 会在某个顶层目录未登记时失败,因此这份清单不会悄悄落后于实际目录树。

注意事项

  • tools/runtime/setup_runtime.py 会更新 ~/.openclaw/openclaw.json,并在 config/applied/ 下写带时间戳的备份。
  • monitor/vendor/runtime-hooks/openclaw-behavior-mediator/ 是仓库自有的运行时集成代码;monitor/vendor/external/ 是 vendored 第三方。
  • 安全决策的用户可见消息使用中文(见 guardrail/security/decision_engine.py)。
  • 可选 Frida 支持位于 monitor/instrumentation/frida/;能 attach 时 agent-trace 运行写运行本地的 frida-events.jsonl,否则在 trace_index.json 中记录 unavailable/attach-failed 状态。

About

Transparent Inspect LLM Agent

Resources

Readme

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages