夜雨聆风学习资料网

ARTICLE · 1364041

Uber ADR Sensor 源码笔记

Uber ADR Sensor 源码笔记

这篇是 Uber ADR Sensor 组件的源码研究笔记,整理自我的阅读记录。事实、表格与结论均与我的完整笔记(bx-sec/agentic-adr-notes 仓库 sensor/source-notes.md)对齐,文中关键结论都标注了证据来源。

Sensor 组件概览速查图。图中流程与数字仅作速查,具体口径以本文正文和附录 B 的证据索引为准

01

Sensor 是什么

1.1 设计动机,可观测性鸿沟

ADR 论文(arXiv:2605.17380,MLSys 2026)指出企业 AI 代理安全面临三大持续挑战,Sensor 直接解决第一个,有限的可观测性。

现有 EDR 工具能看到文件写入,但看不到代理推理、prompt 或连接意图与执行的因果链。

传统 EDR 设计于 MCP 出现之前,仅捕获系统级遥测(文件写入、进程活动、网络调用)。当 AI 代理写入文件时,EDR 能看到 write() 系统调用,但看不到,触发该操作的用户 prompt(「帮我修复这个 bug」)、代理的推理过程(chain-of-thought)、调用了哪些 MCP 工具及其参数,以及 prompt → reasoning → tool call → outcome 的因果关系。

论文中的关键示例,用户要求「总结 Jira ticket」,但代理读取了 ~/.ssh/id_rsa 并发起 HTTP 请求。EDR 看到文件读取和网络连接,但无法判断这些行为是否偏离用户意图。Sensor 通过捕获代理会话语义链来闭合这个鸿沟(受来源日志记录完整性限制)。

1.2 在 ADR 系统中的位置

ADR 系统包含五个互补能力,Sensor 承担其中「可观测性」。Sensor 的产出(AgentEvent)是 Detector 的输入,没有 Sensor 的遥测,Detector 的两级检测架构(Tier 1 分诊 + Tier 2 深度推理)就没有数据可分析。

能力
组件
开源状态
发现未授权 AI 工具
ADR Discovery
✅ 已开源
观察代理活动
ADR Sensor
✅ 已开源
评估防御能力
ADR-Bench
✅ 已开源
检测威胁
ADR Detector
✅ 已开源
阻止不安全操作
ADR Prevention
❌ 未开源

1.3 与 Discovery 的边界

Discovery 回答「端点上有哪些 AI 工具」,Sensor 回答「这些工具在做什么」。两者共享端点但数据模型完全不同。Discovery 发现 ~/.claude 目录存在,说明安装了 Claude Code;Sensor 解析 ~/.claude/projects/ 下的 JSONL transcripts,还原 Claude Code 的完整会话历史。

维度
Discovery
Sensor
产出
Asset 快照(静态清单)
AgentEvent 集合(每 session 一条记录)
触发
单次扫描或定期扫描
单次运行;论文描述 Uber 生产环境每小时外部调度
数据来源
文件系统、包管理器、注册表、进程表
AI 代理的本地日志/数据库
时间维度
快照时刻
回溯窗口(默认 14 天)
下游消费者
安全审查、资产登记
威胁检测、安全监控

02

能力范围

2.1 能做什么

能力
说明
多源日志采集
从 11 个 AI 代理平台的本地存储中解析会话数据
统一标准化
将不同格式(JSONL、SQLite、JSON)转换为统一的 AgentEvent schema
会话重建
关联分散的日志条目,基于各代理已持久化的记录尽可能重建 prompt → reasoning → tool call → outcome 的行为链(受来源日志的记录完整性、截断和缺失限制)
工具调用记录
捕获 MCP 工具调用的名称、类型、参数、结果和状态
环境上下文
捕获 session 级配置(MCP 服务器、权限模式、模型版本、插件、技能)
Token 用量
规范化每轮和累计 token 计数(部分代理支持)
多格式导出
JSON / JSONL 文件输出 + OpenTelemetry OTLP/HTTP Logs 导出
跨平台
macOS、Linux、Windows 三平台支持
诊断
结构化健康报告(ok / empty / no_input / partial / failed)
增量保存
--save-sessions 按 session 粒度保存,支持增量更新

2.2 不能做什么

限制
说明
不是 EDR
不捕获系统级遥测(进程、文件写入、网络连接),只捕获代理语义层
不实时阻断
Sensor 是观察者,不拦截代理操作;Prevention 组件未开源
不修改代理行为
不注入 prompt、不修改 MCP 配置、不干预代理执行
不做威胁检测
检测由 Detector 组件负责;Sensor 只负责数据采集和标准化
不支持所有 AI 工具
仅支持 11 个平台的日志解析;未列出的代理需开发新解析器
不捕获 VS Code Copilot Chat
Copilot CLI 解析器仅覆盖 session-state/,不读取 VS Code 扩展存储
不捕获未保存会话
只解析已持久化的日志,内存中的活动不在范围内
不脱敏 OTLP 导出
OTLP 导出不应用脱敏或字段投影,prompts、凭据、路径都可能被传输
仓库研究工件风险
ADR 仓库整体为研究工件。OPEN_SOURCE_REVIEW.md 列出的已知 CVE 风险对应 Detection/(AgentDojo 的 pinned 依赖,以及 LlamaFirewall 基线依赖树),不是 Sensor 运行时依赖。Sensor 运行时依赖仅 tabulate 和 zstandard,OTLP 可选依赖为 opentelemetry-*。部署前需对 Sensor 依赖集合单独审计
无实时流
CLI 是单次运行工具,无内置调度器;论文所述「每小时调度」是 Uber 生产环境的部署方式(外部 cron 调度),非 Sensor CLI 自身功能

2.3 11 个支持的 AI 代理平台

Agent
Source key
日志格式
平台
Claude Code
claude
JSONL(~/.claude/projects/)
macOS, Linux, Windows
Cursor IDE
cursor
SQLite(state.vscdb)
macOS, Linux, Windows
Cline
cline
JSON task 文件
macOS, Linux, Windows
Claude Desktop
claude_desktop
JSONL audit 日志
macOS, Windows
OpenAI Codex CLI
codex
JSONL + SQLite catalogs
macOS, Linux, Windows
GitHub Copilot CLI
copilot
JSONL(~/.copilot/session-state/)
macOS, Linux, Windows
DeepSeek Harness
dsh
JSONL / Zstandard(~/.dsh/sessions/)
macOS, Linux, Windows
Warp Terminal
warp
SQLite(warp.sqlite)
macOS, Windows
opencode
opencode
SQLite(opencode.db)或 JSON tree
macOS, Linux
Gemini CLI
gemini
JSONL journals + legacy JSON
macOS, Linux, Windows
Google Antigravity
antigravity
JSONL transcript
macOS, Linux, Windows

所有来源默认回溯 14 天。平台自动跳过,不支持当前操作系统的来源会被自动跳过,例如 Linux 上 --source all 不会尝试 claude_desktop(仅 macOS/Windows)。PLATFORM_RESTRICTED_SOURCES 映射控制此行为。

2.4 四维遥测模型

维度
采集内容
揭示信息
AgentEvent 对应字段
用户提示
原始自然语言指令
意图
chat_history[].content(role=user)
代理推理
中间思考过程和决策步骤
解释
chat_history[].content(role=assistant)+ tools
MCP 工具调用
工具调用序列、参数、结果
行为
chat_history[].tools[]
环境上下文
MCP 配置、权限模式、模型
能力
session_context

重要边界,Sensor 采集的是各代理已持久化到本地的日志或数据库。不同来源对 thinking、工具进度、工具结果、历史分支和内容截断的记录并不相同。因此 chat_history[].content(role=assistant)不能一概等同于完整推理过程,日志中的 tool result 也不能单独证明操作已对操作系统产生了预期效果。Sensor 提供的是支持意图/行为分析的语义遥测数据,判断行为是否偏离用户意图、是否构成威胁,是 Detector 组件的职责。

因果链示例如下。如果因果链断裂,用户要求「总结 Jira ticket」但代理调用了 read_file("~/.ssh/id_rsa"),Sensor 采集的遥测数据会暴露这种偏离,供 Detector 进一步判断是否构成威胁。

用户 prompt: "帮我总结这个 Jira ticket"    ↓代理推理: "我需要先读取 Jira ticket 内容"    ↓工具调用: jira_mcp.get_ticket(id=PROJ-123)    ↓工具结果: ticket 内容...    ↓代理推理: "现在我总结一下"    ↓代理响应: "这个 ticket 是关于..."

03

技术实现方案

3.1 整体架构。五层结构,自上而下。

① AI Agent Logs,各代理平台的原始日志(JSONL、SQLite、JSON 等),格式各异

② Source-Specific Parsers,每个代理一个解析器,都实现 BaseParser 接口

③ Unified Schema(AgentEvent),统一 schema,消除源格式差异。字段含 uuid、timestamp、source、session_id、hostname、username、host_os、model、project_path、chat_history、session_context、token_usage

④ AgentObserver,编排器,执行 Ingest → Filter → Display → Export 流水线

⑤ 输出,JSON/JSONL 文件 和/或 OTLP Logs 导出到 Collector/SIEM

3.2 AgentEvent 统一 Schema

每个解析的 session 生成一个 AgentEvent。AgentEvent 是 Session 级记录,不是逐条行为事件流——一个 AgentEvent 包含整个会话的 chat_history(消息数组 + 工具调用),OTLP 导出也将每个 AgentEvent 作为一条 adr.agent.session LogRecord 发送。一次性采集生成当前日志的全量快照;--save-sessions 的增量更新是按 session 粒度的快照刷新,不是实时事件流。

完整字段示例。

{  "uuid": "sha256-hash",  "timestamp": "2025-06-15T10:30:00+00:00",  "source": "claude",  "session_id": "claude_abc123",  "hostname": "my-laptop",  "username": "developer",  "host_os": "Darwin",  "model": "claude-sonnet-4-20250514",  "project_path": "/home/user/my-project",  "chat_history": [    {"role": "user", "content": "Help me fix this bug",     "tools": [], "sequence_id": "msg_0"},    {"role": "assistant", "content": "Let me look at the code.",     "tools": [{"tool_name": "read_file", "tool_type": "tool_use",       "arguments": {"path": "main.py"},       "result": "def hello(): ...", "status": "success"}],     "sequence_id": "msg_1"}  ],  "session_context": {    "title": "Config review", "is_dispatch": false,    "init": {      "tools": ["Bash", "Read"],      "mcp_servers": [{"name": "github"}],      "permission_mode": "acceptEdits",      "model": "claude-sonnet-4",      "claude_code_version": "2.1.0"}  },  "token_usage": {    "last_turn": {"input_tokens": 120, "output_tokens": 30,      "total_tokens": 150},    "cumulative": {"input_tokens": 420, "output_tokens": 90,      "total_tokens": 510},    "model_context_window": 128000}}

字段说明要点。uuid 是 SHA-256 哈希,由 hostname、username、timestamp、source、session_id、消息数量、工具数量及每条消息前 100 字符摘要拼接后求哈希,不是完整 payload 的内容指纹,工具结果变化时 session UUID 不一定改变。username 取 sensor 进程运行身份,从不从环境变量读取。session_id 格式为 <source>_<native_id>。host_os 取 platform.system() 值(Darwin、Linux、Windows)。chat_history 为 ChatMessage 数组,session_context 与 token_usage 为可选字段。

ChatMessage 结构,role(user | assistant)、content、tools(ToolUsage 数组:tool_name、tool_type、arguments、result、status)、sequence_id。tool_type 取值如 tool_use、mcp_tool 等,status 如 success、error 等。

session_context 是解析器可恢复的 session 级配置,即代理对自身权限和能力的视图,可含 title、is_dispatch、session_type、cli_session_id、memory_enabled、skills_enabled、plugins_enabled、available_slash_commands 及 init(tools、mcp_servers、permission_mode、model、plugins、skills 等)。init 中的字段因代理不同而异,但都反映代理启动时的能力配置。对安全分析而言,permission_mode 和 mcp_servers 是关键信号。

token_usage 规范化 token 计数(仅非负整数),分 last_turn(最近一轮)和 cumulative(累计),可含 input_tokens、cached_input_tokens、cache_write_input_tokens、output_tokens、reasoning_output_tokens、total_tokens,另有 model_context_window。

3.3 解析器架构

每个解析器继承 BaseParser,实现统一的解析接口,parse_all() 返回 list[AgentEvent],是所有解析器的统一出口。

from adr_sensor.parsers.base_parser import BaseParserclass MyAgentParser(BaseParser):    def __init__(self, max_age_days: int = 14):        self.base_path = Path.home() / ".my-agent/logs"        self.max_age_days = max_age_days    def parse_all(self) -> list[AgentEvent]:        entries = []        # 解析代理日志文件并转换为 AgentEvent 对象        return entries

解析器注册机制。AgentObserver.SOURCES 是一个元组,注册所有支持的来源,claude(Claude Code)、cursor(Cursor IDE)、cline、claude_desktop、codex(OpenAI Codex CLI)、copilot(GitHub Copilot CLI)、dsh(DeepSeek Harness)、warp(Warp Terminal)、opencode、gemini(Gemini CLI)、antigravity(Google Antigravity)。

ingest_all() 遍历 SOURCES,通过 self.<source>_parser 查找解析器实例,无需 per-source 分支。PLATFORM_RESTRICTED_SOURCES 列表控制平台限制来源。CLI 自动从 SOURCES 构建 --source 选项。

添加新解析器四步,在 adr_sensor/parsers/ 下创建新解析器继承 BaseParser;在 parsers/__init__.py 中导出;在 observer.py 中注册(构造解析器为 self.<source>_parser、在 SOURCES 中添加 source key、如需平台限制添加到 PLATFORM_RESTRICTED_SOURCES);在 tests/ 中添加测试。

项目结构。adr_sensor/ 下有 __init__.py(包导出)、cli.py(CLI 入口)、observer.py(编排器)。

exporters/ 目录,config.py 为 OTLP/HTTP JSON 配置,opentelemetry.py 为 OpenTelemetry Logs exporter。

parsers/ 目录,base_parser.py 抽象基类 + 11 个解析器(claude、cursor、cline、claude_desktop、codex、copilot、dsh、gemini、opencode、warp、antigravity)。

schemas/ 目录,agent_event_schema.py 定义 AgentEvent、ChatMessage、ToolUsage,system_config_schema.py 定义 SystemConfiguration。utils/ 目录含 string_utils.py、timestamp_utils.py。另有 examples/opentelemetry-config.json 与 tests/ 目录。

3.4 AgentObserver 编排器。Sensor 的编排核心,执行 Ingest → Filter → Display → Export 流水线。核心方法,ingest_all() 摄入所有/特定来源返回 (events, configs),可传 source_filter="claude" 按来源过滤;display_summary(events, configs) 打印摄入摘要表;save_to_file(events, configs, output_format="json") 保存到文件。

from adr_sensor import AgentObserverobserver = AgentObserver()events, configs = observer.ingest_all()observer.display_summary(events, configs)observer.save_to_file(events, configs, output_format="json")

3.5 输出与导出

文件输出两种格式,JSON 用于单文件分析(包含所有 events),JSONL 用于大型日志集和流式处理(每行一个 event)。默认输出目录 ./output,可通过 --output-dir 自定义。--save-sessions 按 session 粒度保存并支持增量更新,保存路径默认 $XDG_CACHE_HOME/adr_sensor(默认 ~/.cache/adr_sensor)。

OpenTelemetry OTLP 导出默认禁用,仅在 --otel-config 指向 JSON 配置文件时初始化。配置字段有 endpoint(完整 OTLP/HTTP logs URL,含 /v1/logs)、service_name、headers(认证头)、timeout_seconds、flush_timeout_seconds、certificate_file(PEM 证书包,可选,相对路径从配置文件目录解析)、gen_ai_attributes(设为 true 添加 GenAI 语义约定属性,默认关闭)。

OTLP 导出关键行为。不应用脱敏或字段投影——prompts、responses、工具参数/结果、用户名、主机名、本地路径都可能被传输。每个 AgentEvent 作为 adr.agent.session LogRecord 发送,Body 为 AgentEvent.get_non_null_fields() 的完整字典。交付检查点(.adr-otel-delivery.<hash>.json)跟踪成功导出,仅存储哈希。至少一次交付语义,重试可能产生重复记录。支持 mTLS 客户端证书/密钥路径。不支持动态 HTTP 凭据提供者插件。

gen_ai_attributes: true 时,每个 source 的 native ID 映射为 gen_ai.conversation.id,映射关系如下。

· antigravity,取对话目录名

· claude,取 JSONL sessionId(subagents 用父 session 的 sessionId)

· claude_desktop,取 Metadata 的 cliSessionId(缺失时省略)

· cline,取 Task 目录名

· codex,取 session_meta payload.id

· copilot,取 session.start/session.resume 的 sessionId

· cursor,取 Composer ID

· dsh,取 Session header id

· gemini,取 sessionId(subagents 保持自己的)

· opencode,取 Session id(去掉 ses_ 前缀,映射回 ses_<id>)

· warp,取 agent_conversations.conversation_id

3.6 诊断与健康

文件
位置
内容
diagnostics.jsonl
--output-dir
所有摘要
error.log
--output-dir
仅 partial 和 failed 摘要
resource.log
--output-dir(--resource 启用时)
资源日志
sensor_runtime_errors.jsonl
--log-file 启用时
警告和错误 JSON 行
sensor_runtime_debug.jsonl
--log-file 启用时
debug 和 info 消息

所有诊断文件在 1 MiB 时轮转,保留 2 个备份。健康状态五种,ok(成功捕获)、empty(无有意义输出)、no_input(输入不存在)、partial(有可用输出但观察到错误)、failed(错误且无可用输出)。

健康记录示例(结构化诊断不包含 prompts、工具参数/结果、路径、session ID、异常消息、traceback)。

{  "schema_version": 1,  "event": "adr.sensor.health",  "timestamp": "2026-01-01T00:00:00.000+00:00",  "sensor_version": "0.0.0",  "source": "claude", "stage": "parse", "status": "partial",  "suspected_schema_drift": false,  "counts": {"events_returned": 2, "events_emitted": 2,    "events_filtered": 0},  "reasons": {"record_decode_error": 1}}

隐私说明三条。结构化诊断不含敏感信息;运行时日志的 message 和 stack 可能包含本地文件路径和错误文本;--log-file-content-free 丢弃 message 和 stack,--log-identity 添加 username 和 hostname(opt-in)。

3.7 CLI

参数
说明
--source <key>
指定来源代理(默认 all)
--save-sessions
保存单独的 session 文件(增量)
--output-format <fmt>
输出格式,json(默认)或 jsonl
--all-history
包含所有历史(不仅最近 14 天)
--output-dir <path>
自定义输出目录(默认 ./output)
--otel-config <path>
导出到 OTLP/HTTP logs endpoint
--no-save
不写 JSON 文件(配合 --otel-config 使用)
--quiet / -q
仅打印警告和错误
--log-level <level>
最低日志级别,debug、info、warning、error
--fail-on-error
观察到解析/保存/诊断失败时非零退出
--resource
启用 resource.log
--log-file
将运行日志写为 JSON 行
--log-file-content-free
丢弃 message 和 stack,保留其余字段
--log-identity
在每条记录中添加 username 和 hostname

常用命令。adr-sensor 基本用法(从所有支持的代理收集);adr-sensor --source claude 指定来源;--save-sessions 保存 session 文件;--output-format jsonl 导出 JSONL;--all-history 包含所有历史;--otel-config ./opentelemetry-config.json 导出到 OTLP endpoint;--no-save --otel-config 仅导出 OTLP 不写本地文件;开发环境 uv run adr-sensor --source gemini --no-save 从源码运行。

输出流,stdout 打印进度消息,stderr 打印警告和错误,始终打印摄入摘要表。

3.8 Python API

from adr_sensor import AgentObserverobserver = AgentObserver()events, configs = observer.ingest_all(source_filter="claude")for event in events:    print(f"Source: {event.source}, Session: {event.session_id}")    print(f"Messages: {len(event.chat_history)}")    for msg in event.chat_history:        if msg.tools:            for tool in msg.tools:                print(f"  Tool: {tool.tool_name} ({tool.tool_type})")                print(f"  Args: {tool.arguments}")

04

各代理日志路径与解析细节

4.1 Claude Code

· 日志路径,递归读取 ~/.claude/projects/ 下的 transcripts

· 子代理,包含 <project>/<sessionId>/subagents/agent-<agentId>.jsonl 及嵌套工作流目录

· Session ID 规则,主会话 claude_<sessionId>;子代理 claude_<sessionId>_agent_<agentId>,含 parent_session_id 和 agent_id

· 数据处理,保留字符串和文本块消息(含工具结果附带的用户文本),通过 tool-call ID 匹配结果,跳过格式错误的记录但不丢弃周围消息

· 兼容同一物理行拼接的完整 JSON 对象和对象间的 NUL 填充;不完整的尾部被跳过,不连接物理行或修复消息内文本

· 元数据,每个事件包含 raw_log_path、稳定的对话起始 timestamp、session_context.last_event_at 和 event_count

· 默认回溯 14 天(按文件修改时间);顶层工具参数字符串和工具结果在 1,000 字符处截断

· 不导入非文本内容块和单独溢出的工具输出文件

4.2 Cursor IDE

· 日志格式,SQLite 数据库(state.vscdb)

· 平台 macOS、Linux、Windows;默认回溯 14 天

4.3 Cline (Claude Dev)

· 扩展 ID,saoudrizwan.claude-dev;支持 VS Code(主要)、Cursor、VS Code Insiders、VSCodium、Windsurf

· 日志路径,macOS ~/Library/Application Support/<Editor>/User/globalStorage/saoudrizwan.claude-dev/tasks/;Linux ~/.config/<Editor>/User/globalStorage/...;Windows %APPDATA%\<Editor>\User\globalStorage\...

· 处理,扫描所有候选目录,规范化用户提示和助手工具使用(包括 <use_mcp_tool> 调用),跨编辑器去重

· 默认回溯 14 天(按 task 文件修改时间);ClineParser(base_path=...) 可限制单个 task 目录

4.4 Claude Desktop

· 覆盖 Claude Desktop 的本地代理模式(发布为 Claude Cowork),支持 macOS 和 Windows

· 交互式会话,.../local-agent-mode-sessions/<user>/<org>/local_<uuid>/audit.jsonl

· 调度会话(委派后台代理),.../<user>/<org>/agent/local_ditto_<uuid>/audit.jsonl

· 区别标识,调度会话使用 claude_desktop_dispatch_ 前缀和 is_dispatch: true 标志

4.5 OpenAI Codex CLI

· 日志路径,$CODEX_HOME/sessions/(默认 ~/.codex)

· SQLite catalogs,只读查询每个 $CODEX_HOME/state_*.sqlite 的兼容 threads 表,必须有 id 和 rollout_path 列,updated_at 和 updated_at_ms 可选;相对路径从 CODEX_HOME 解析,仅接受已存在的 .jsonl 文件

· 去重与过滤,catalog 和文件系统路径去重;使用文件修改时间和 catalog 更新时间戳中较新者

· 默认回溯 14 天;max_age_days 参数值 ≤ 0 禁用年龄过滤

4.6 GitHub Copilot CLI

· 日志路径,macOS /Users/<user>/.copilot/session-state/;Linux /home/<user>/.copilot/session-state/;Windows %USERPROFILE%\.copilot\session-state\

· 环境变量,COPILOT_HOME 覆盖配置目录,Sensor 读取 $COPILOT_HOME/session-state/

· 读取文件,每个 session 的 events.jsonl + 可选 workspace.yaml 和 vscode.metadata.json

· 默认回溯 14 天(按 events.jsonl 修改时间);仅覆盖 CLI session state,不读取 VS Code Copilot Chat 扩展的存储

4.7 DeepSeek Harness

· 日志路径,$DSH_HOME/sessions/(默认 ~/.dsh/sessions/)

· 格式,默认 Zstandard 压缩日志,也支持未压缩的 JSONL v3 日志

· Generation 处理,一个 session 目录有多代日志时,仅考虑最高 generation,且仅在 v3 格式时导入

· 规范化内容,工具参数和结果、PTC 子调度、失败状态、批准、provider/model 上下文、沙箱模式、权限预设、类型化消息内容、token 使用量

· 默认回溯 14 天

4.8 Warp Terminal

· 日志格式,SQLite 数据库(warp.sqlite)

· 平台 macOS、Windows;默认回溯 14 天

4.9 opencode

· 数据目录,~/.local/share/opencode(Linux 和 macOS),支持 $XDG_DATA_HOME 和 $OPENCODE_DB

· 后端一 SQLite(当前版本),opencode.db 或 opencode-<channel>.db(非稳定频道),只读打开,仅当包含 session、message 和 part 表时使用

· 后端二 JSON 文件树(旧版本),storage/ 目录,含 per-session、per-message 和 per-part JSON 文件

· MCP 工具命名,opencode 将 MCP 工具命名为 <server>_<tool>,含下划线的非内置工具记为 tool_type: "mcp_tool" 并填充 server_name

4.10 Gemini CLI

· 扫描根目录,macOS/Linux ~/.gemini/tmp/;Windows %USERPROFILE%\.gemini\tmp\;macOS Seatbelt 沙箱额外扫描 ~/.cache/.gemini/tmp/

· 环境变量,GEMINI_CLI_HOME 覆盖父主目录,路径变为 $GEMINI_CLI_HOME/.gemini/tmp(非 $GEMINI_CLI_HOME/tmp);GeminiParser(base_path=...) 支持自定义路径

· 读取内容,当前 chats/**/*.jsonl journals、legacy chats/*.json 对话快照、用户/助手文本、工具参数和结果、状态和批准请求、model 和 token 使用量、嵌套子代理会话

· 数据处理,Session resume 时起始时间戳保持稳定;--save-sessions 原地刷新已更改的快照;按 ID 合并重复的 journal 消息,工具进度更新不重复消息或 token 总计;rewind 和 checkpoint 后早期活动仍保留;history_scope 为 all_recorded_branches;不添加任何脱敏或截断

· 不收集,仅 prompt 的 logs.json、编辑器聊天存储、shell 历史、未保存会话及这些根之外的文件

· MCP 调用,显式 mcp_/限定工具名标识;记录名模糊时 server 归属留空

· 默认回溯 14 天(按文件修改时间);--all-history 包含更旧文件

· 契约验证对照上游 record types、journal writer、storage paths、supported platforms;测试使用合成记录在三个 host 上运行,不需要 Gemini 账户

4.11 Google Antigravity

· Brain 目录,Antigravity CLI ~/.gemini/antigravity-cli/brain/;Antigravity 2.0 ~/.gemini/antigravity2/brain/;Antigravity IDE ~/.gemini/antigravity-ide/brain/

· Legacy 路径,~/.antigravity/brain/、%APPDATA%\Google\Antigravity\brain\、~/Library/Application Support/Google/Antigravity/brain/、~/.config/google/antigravity/brain/

· 环境变量,ANTIGRAVITY_HOME 和 AGY_HOME 作为存储覆盖

· 数据文件,每个对话目录为 .system_generated/logs/transcript.jsonl + 可选 transcript_full.jsonl

· Transcript 选择,比较可用快照,选择最新记录修订版;同一修订版优先选择未截断数据和完整 transcript

· Step Types,USER_INPUT(用户提示)、PLANNER_RESPONSE(助手输出 + thinking 文本 + 工具调用)、GENERIC(模型输出);Thinking 文本以 [Thinking] 标签保留

· 工具规范化,原生工具直接记录;MCP 调用(如 mcp_<server>_<tool> 或 <server>:<tool>)解析填充 server_name 和 tool_name

· 数据保留,不截断工具参数或字符串化嵌套值;若源 transcript 报告 truncated_fields 则标记 is_truncated

· 默认回溯 14 天

05

正反例测试方法集

5.1 测试设计原则五条。合成记录驱动,所有测试使用合成 transcripts/记录,不启动实际 AI 代理;契约验证,多个解析器对照上游源码验证(record types、journal writer、storage paths);跨平台覆盖,Gemini CLI 解析器的 CI 在 macOS、Linux、Windows 三平台运行;无需账户,测试不需要任何 AI 代理的账户或 API key;可复现,所有测试可在隔离环境中独立复现。

5.2 正例测试集(完整脚本见笔记仓库,此处记录目的与预期)。

P-01 单源采集 Claude Code。验证解析器能正确解析 JSONL 日志并生成 AgentEvent。预期,输出目录含 JSONL 文件,每行合法 JSON,source 为 claude,session_id 以 claude_ 开头,chat_history 非空,timestamp 为 ISO 8601,hostname 和 username 已填充。

P-02 多源采集全量。验证 --source all 自动发现并采集所有已安装代理。预期,摘要表列出全部 11 个来源,不支持当前 OS 的来源为 no_input 或自动跳过,至少一个来源状态为 ok,未安装的代理为 no_input。

P-03 JSONL 格式导出。验证每行是合法 JSON,无解析错误。

P-04 工具调用记录。验证正确捕获工具调用的 tool_name、tool_type、arguments,且捕获数量 > 0。

P-05 增量保存。验证 --save-sessions 按 session 粒度保存,第二次运行不重新保存未变化的 session 文件。

P-06 Python API 调用。验证 AgentObserver Python API 返回 events 列表,每个 event 有 source 和 chat_history 属性。

P-07 诊断文件生成。验证诊断文件包含 schema_version、event、status 字段且 event 为 adr.sensor.health,并验证不含 password/api_key/token 等敏感信息。

5.3 反例测试集。

N-01 无日志的来源。验证未安装的代理被正确处理为 no_input 或 empty,不抛异常,退出码 0。

N-02 格式错误的日志文件。验证损坏的行被跳过、有效行仍被解析为 AgentEvent,诊断状态为 partial(有错误但有可用输出),--fail-on-error 时退出码非零。

N-03 不支持的来源。传入不存在的 source key 被正确拒绝,CLI 报错并列出可用 source 列表,退出码非零。

N-04 空目录作为日志路径。GeminiParser(base_path=...) 指向空目录,返回空列表,不抛异常。

N-05 权限不足的日志目录。权限不足的文件被跳过,不导致整个解析失败,诊断记录 denied 或类似状态。

N-06 超大日志文件。10 万条记录不导致内存溢出或超时,被聚合为 1 个 session 级 AgentEvent,处理完成或 partial 状态。注意 ClaudeParser 的 base_path 固定为 ~/.claude/projects/,不接受 base_path 参数也不支持环境变量覆盖(与 GeminiParser 的 GEMINI_CLI_HOME 不同),隔离测试只能在该目录下建子目录,测试后应删除。

N-07 OTLP 导出无可用 endpoint。OTLP 导出失败但不导致整个运行崩溃,错误记录在诊断文件中,--fail-on-error 时退出码非零。

N-08 --source all 在无任何代理的环境。Docker 隔离环境验证所有来源状态为 no_input,不抛异常,退出码 0。

5.4 边界测试集。

B-01 默认 14 天回溯窗口。创建 20 天前的旧日志,验证默认 14 天不包含,--all-history 包含。

B-02 跨平台自动跳过。Linux 上验证 claude_desktop 不出现在处理列表中。PLATFORM_RESTRICTED_SOURCES 目前只包含 claude_desktop(Darwin/Windows),被命中的来源在 ingest_all() 循环中直接 continue,不会出现在诊断记录中。warp 虽有平台限制(仅 macOS/Windows 有数据库路径)但不在该映射里,在 Linux 上会被尝试解析并产生 no_input,不属于平台跳过。

B-03 子代理会话关联。验证 Claude Code 子代理 session_id 含 _agent_ 后缀,session_context 含 parent_session_id 和 agent_id 字段。无子代理日志时应标记为手工检查。

B-04 MCP 工具调用识别。验证 MCP 工具被标记为 tool_type "mcp_tool" 且 server_name 字段存在(源码 ToolUsage dataclass 定义 server_name: Optional[str] = None,值为 None 表示记录名模糊时无法归属 MCP server,断言验证字段存在性而非值非空)。

B-05 --fail-on-error 退出码。有解析错误时返回非零退出码,无错误时返回 0。cli.py 实现是 observer.has_errors 为 True 时 raise SystemExit(1),has_errors 在诊断写入失败或任一诊断记录状态为 partial/failed 时为真,OTLP 导出失败也会触发 SystemExit(1)。测试时不要在命令后加 || true,否则退出码是 true 的而非 sensor 的。

5.5 测试运行方式。单元测试用 pytest,pip install -e ".[dev]" 后运行 pytest tests/ -v,可加 --cov=adr_sensor 生成覆盖率,ruff 做 lint。

测试特点,合成记录、跨平台(Gemini 解析器测试在三个 host 的 CI 上运行)、无需账户、契约验证(Gemini CLI 对照 record types、journal writer、storage paths、supported platforms;DeepSeek Harness 对照 JSONL persistence contract 和 v3 event declarations)。

截至 Gemini CLI 支持 commit 93ed35c,244 个 Sensor 测试在 Python 3.11 上全部通过。

集成测试从源码安装,git clone https://github.com/uber/ADR 后在 Sensor/ 目录 uv sync 或 pip install -e ".[dev]",再运行 uv run pytest tests/ -v。

CI 工作流。截至 uber/ADR@6b33dff(2026-10-16),仓库中与 Sensor 相关的实际 CI 工作流为 .github/workflows/sensor-gemini.yml。触发条件为 PR 或 push 到 main 且改动涉及 Sensor/** 或该工作流文件。执行矩阵,ubuntu-latest、macos-latest、windows-latest 三平台,固定 Python 3.12(非多版本矩阵),仅运行 pytest tests/test_gemini_parser.py -q。

维度
声明范围
CI 已验证
Python 版本
requires-python = ">=3.9"(声明 3.9–3.13)
仅 3.12
操作系统
classifiers 声明 macOS/Windows/Linux
三平台(仅 Gemini 测试)
测试范围
tests/ 目录全部测试(快照 6b33dff 下 426 个 def test_ 函数)
仅 Gemini parser 子集

pyproject.toml 声明支持的 Python 版本范围不能替代实际 CI 验证证据。其他解析器(Claude/Cursor/Cline 等)的跨平台测试覆盖情况未在仓库工作流中体现。

06

安全分析与技术权衡

6.1 与 EDR 的对比

特性
传统 EDR
ADR Sensor
可见性层级
系统级(文件/进程/网络)
语义级(prompt/推理/工具调用)
行为链重建
无法关联意图与执行
基于持久化日志尽可能重建 prompt→reasoning→tool→outcome 行为链(受来源记录完整性限制)
AI 代理行为理解
无法区分代理行为与人类操作
提供支持意图/行为分析的语义遥测,供 Detector 判断是否偏离用户意图
MCP 工具调用可见性
不可见
记录参数和结果(受截断限制)
设计时代背景
MCP 之前
MCP 之后
语义威胁检测
不支持
不在 Sensor 职责范围,由 Detector 基于 Sensor 提供的遥测数据执行
部署方式
系统级守护进程
单次运行的 Python CLI(论文描述 Uber 生产环境每小时外部调度)
性能开销
持续监控,资源占用高
论文报告每次 0.182 秒(Uber 生产环境数据)

职责边界,Sensor 的职责是解析、标准化和输出代理活动遥测。是否偏离用户意图、是否构成威胁,是 Detector 组件基于 Sensor 产出的 AgentEvent 执行的检测逻辑。AgentObserver 源码(observer.py)不包含任何意图判断、威胁检测或行为分析代码,其完整职责链为 Parser 解析 → 内容过滤 → 增量去重 → 原子写入 → 健康记录 → 摘要展示。

6.2 与网关方案的对比。论文还讨论了 LLM/MCP 网关作为替代方案。

特性
网关方案
ADR Sensor
实现难度
较易
需要端点部署
流式响应兼容
不兼容
兼容
环境上下文
部分信息缺失
完整
需修改 MCP 主机
需要
不需要
实时阻断能力
天然支持
需配合 Hooks
部署位置
网络中间层
端点

6.3 设计权衡

设计决策
选择
代价
日志解析 vs 实时拦截
日志解析(事后采集)
不支持实时阻断
端点部署 vs 网关
端点
不需要修改 MCP 主机,但需管理端点覆盖
回溯窗口
默认 14 天
超过 14 天的历史需 --all-history
截断限制
Claude Code 工具参数/结果 1,000 字符
超长内容被截断,可能丢失部分上下文
OTLP 导出不脱敏
完整数据传输
prompts、凭据、路径可能被传输到 SIEM
合成记录测试
不启动实际 AI 代理
无法覆盖真实代理的所有行为变体
Session 级记录粒度
每 session 一个 AgentEvent
非逐条工具调用实时上报;增量更新是 session 级快照刷新
仓库研究工件定位
仓库整体非 production-ready
已知 CVE 对应 Detection/ 的 AgentDojo pinned 依赖与 LlamaFirewall 基线依赖树;Sensor 运行时依赖仅 tabulate + zstandard,部署前需单独审计

07

附录

附录 A 代码坐标索引。路径相对 Sensor/adr_sensor/,基于源码快照 6b33dff(2026-10-16)。

__init__.py 包导出 | cli.py CLI 入口 | observer.py 编排器schemas/agent_event_schema.py AgentEvent, ChatMessage, ToolUsageschemas/system_config_schema.py SystemConfigurationparsers/base_parser.py BaseParser 抽象基类parsers/claude_parser.py | cursor_parser.py | cline_parser.pyclaude_desktop_parser.py | codex_parser.py | copilot_parser.pydsh_parser.py | gemini_parser.py | opencode_parser.pywarp_parser.py | antigravity_parser.pyexporters/config.py OTLP/HTTP JSON 配置exporters/opentelemetry.py OpenTelemetry Logs exporterutils/string_utils.py | utils/timestamp_utils.pyexamples/opentelemetry-config.json OTLP 配置示例 | tests/ 测试目录

附录 B 关键技术结论及证据索引。18 条结论,每条均给出证据来源。

结论
证据来源
C1 · Sensor 是语义层遥测工具,非系统级 EDR
论文 §1 设计动机;README "ADR Observability"
C2 · 支持 11 个 AI 代理平台
README 支持列表;Gemini CLI commit 93ed35c
C3 · AgentEvent 是统一 schema,含 chat_history + session_context + token_usage
schemas/agent_event_schema.py;README schema 示例
C4 · 每个解析器实现 BaseParser 接口
parsers/base_parser.py;README 添加新解析器
C5 · AgentObserver.ingest_all() 遍历 SOURCES 元组
observer.py;README Python API
C6 · 默认回溯窗口 14 天,按文件修改时间
README 各代理日志路径节
C7 · Claude Code 工具参数/结果在 1,000 字符处截断
README Claude Code 节
C8 · OTLP 导出不应用脱敏
README OTLP 导出节,明确警告
C9 · Sensor 不做威胁检测,检测由 Detector 负责;AgentObserver 无意图判断/行为分析代码
README 五大能力;论文 §3;observer.py 源码(固定快照 6b33dff)
C10 · 论文未在正文中明确提及 "AgentEvent Schema"
论文 HTML 全文
C11 · 244 个 Sensor 测试在 Python 3.11 上通过
Gemini CLI commit 93ed35c commit message
C12 · Uber 生产环境每小时外部调度,0.182 秒/次,非 CLI 内置调度器
论文 §4
C13 · 仓库整体为研究工件;已知 CVE 对应 Detection/ 的 AgentDojo pinned 依赖与 LlamaFirewall 基线依赖树;Sensor 运行时依赖仅 tabulate + zstandard
docs/OPEN_SOURCE_REVIEW.md;Sensor/pyproject.toml(固定快照 6b33dff)
C14 · CI 工作流 sensor-gemini.yml 为三 OS × Python 3.12,仅执行 test_gemini_parser.py;pyproject.toml 声明 3.9–3.13 但 CI 仅验证 3.12
.github/workflows/sensor-gemini.yml;Sensor/pyproject.toml(固定快照 6b33dff)
C15 · Copilot CLI 不覆盖 VS Code Copilot Chat 扩展
README Copilot CLI 节
C16 · AgentEvent 是 Session 级记录(每 session 一个),非逐条行为事件流;OTLP 导出为每 session 一条 LogRecord
schemas/agent_event_schema.py;README OTLP 导出节
C17 · UUID 由 hostname/username/timestamp/source/session_id/消息数/工具数/前 100 字符摘要拼接后 SHA-256,非完整 payload 哈希;工具结果变化时 UUID 不一定改变
schemas/agent_event_schema.py __post_init__(固定快照 6b33dff);README
C18 · CLI 默认输出格式为 json,需显式指定 --output-format jsonl 生成 JSONL 文件
cli.py argparse 定义(固定快照 6b33dff)

· ADR,Agentic AI Detection and Response,Uber 开源的企业 AI 代理安全系统

· Sensor,ADR 的遥测采集组件,解析 AI 代理日志并标准化为 AgentEvent

· AgentEvent,Sensor 的统一输出 schema,Session 级记录(每 session 一个),包含会话聊天历史、工具调用、上下文和 token 用量

· AgentObserver,Sensor 的编排器,执行 ingest → filter → display → export 流水线

· BaseParser,所有解析器的抽象基类,定义 parse_all() 接口

· MCP,Model Context Protocol,AI 代理与外部工具通信的协议

· OTLP,OpenTelemetry Protocol,用于将遥测数据导出到 Collector/SIEM

· EDR,Endpoint Detection and Response,传统端点检测与响应工具

· ADR-Bench,ADR 的安全基准,302 个任务、133 个 MCP 服务器、17 种攻击技术

· Discovery,ADR 的端点资产发现组件,回答「端点上有哪些 AI 工具」

· Detector,ADR 的威胁检测组件,两级架构(Tier 1 分诊 + Tier 2 深度推理)

· session_context,AgentEvent 中的 session 级配置字段,代理对自身权限的视图

· token_usage,AgentEvent 中的 token 计数字段,分 last_turn 和 cumulative

· ChatMessage,chat_history 中的消息单元,含 role、content、tools

· ToolUsage,tools 中的工具调用记录,含 name、type、arguments、result

笔记读完的几点个人判断,放在最后。Sensor 的价值在于它不发明新数据,而是承认各代理自己已经在本地写好了足够详细的日志,然后把这些散落、异构、容易被忽视的数据规范化成安全分析可用的形态。它的边界同样清晰,不做检测、不做阻断、不做实时,只负责把「代理到底做了什么」这一层观测补上。用它之前想清楚两件事,一是 OTLP 管道按敏感数据管道管理,二是声明支持范围与 CI 验证范围之间的差距需要自己补齐。

参考材料uber/ADR 仓库 Sensor/ 目录,源码快照 6b33dff(2026-10-16)ADR 论文 arXiv:2605.17380(MLSys 2026)完整源码笔记 bx-sec/agentic-adr-notes 之 sensor/source-notes.md

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料