【免费下载链接】agent-beaconThe cross-harness, self-improving memory layer for AI agents.项目地址https://gitcode.com/gh_mirrors/ag/agent-beacon点击查看免费下载agent-beacon 是一个开源的跨运行时cross-harnessAI Agent 遥测采集与检测平台。它以OpenTelemetryOTLP为采集基座把本地编码 Agent、浏览器、CI 流水线、云端 Agent 沙箱等不同来源的活动统一归一化为一份事件模型runtime.jsonl再用开放的威胁规则引擎threat-rules对其做检测帮助新手也能看懂Agent 到底做了什么、风险在哪。整条链路分五步Collect → Normalize → Store → Correlate → Detect。下面逐层拆解。一、采集Collect如何抓住不同 Agent 的遥测不同 Agent 运行时暴露遥测的方式完全不同agent-beacon 的思路是用每个运行时最强的接口而不是把所有工具硬塞进一个适配器。1. 本地 AgentOTLP 接收 原生 Hook 双通道本地 collector 是 Beacon 定制版的 OpenTelemetry Collector只监听本机回环地址OTLP gRPC127.0.0.1:4317OTLP HTTP127.0.0.1:4318支持 Hook 的运行时如 Claude Code、Cline、OpenCode则由 beacon-hooks 适配器在钩子触发时同步写入结构化事件。采集器以系统服务运行macOS 用 launchd、Linux 用 systemd、Windows 用服务全部在本机完成默认不向任何远端发送数据。2. 浏览器、CI 与云端 Agent场景采集方式数据落点浏览器聊天ChatGPT / ClaudeMV3 扩展读取页面流向本机127.0.0.1:4318发送 OTLP本地runtime.jsonlCI 流水线beacon ci exec拉起临时 collector随作业生命周期存活作业产物中的runtime.jsonl云端 AgentDevin、Cursor Cloud 等沙箱内运行beacon-hooks每轮上传压缩快照到自有 S3/GCS安装端点后beacon endpoint会自动发现本机已有的 Claude Code、Codex、Cursor、Gemini CLI 等运行时并记录每种遥测面Native config / Hook config / Plugin是否由 Beacon 托管——这就是上图中 Beacon Managed 列的含义。完整覆盖情况见 docs/runtimes。二、归一化Normalize把方言翻译成统一语言这是 agent-beacon 架构中最核心的部分。各运行时的字段名、事件名、ID 拼法各不相同Claude Code 用prompt.idCodex 用turn_idCursor 用generation_id……直接消费原始数据等于要理解每一种方言。1. beaconjson 导出器归一化的主力是构建进beacon-otelcol的beaconjson导出器源码位于 collector-builder/exporter/beaconjsonexporter/设计约定见 README.md。它负责把 OTLP 的 logs / traces / metrics / resource attributes 映射为统一事件写入一行一个完整 JSON 对象的runtime.jsonl用户模式~/.beacon/endpoint/logs/runtime.jsonl过滤通用进程噪音指标、脱敏密钥、截断超长内容单事件上限 64KB。2. 统一事件模型归一化后的每条事件都带有一致的骨架详见 docs/telemetry-schema/event-schema.mdx字段作用event.action归一化动作prompt.submitted、tool.invoked、command.executed、file.modified、approval.requested等harness产生事件的 Agent 运行时session/run会话与作业上下文tool/command/file/mcp/approval分析所需的具体实体gen_ai.usage规范化后的 token 用量input/output/cache/reasoning 互不重叠归一化规则集中在 pkg/asymptoteobserve/normalizer.go 与 pkg/asymptoteobserve/harness.go映射对照表见 docs/telemetry-schema/normalization.mdx。3. 溯源标记这条事件是怎么来的归一化有一个代价同样一个event.action来源的可信度其实不同。为此每条事件携带两个独立的溯源字段harness.collection_method采集机制——hook运行时原生钩子、pluginBeacon 托管插件、otlpOpenTelemetry 导出、poll轮询运行时 APIevent.fidelity动作是运行时明确命名的observed还是 Beacon推断出来的inferred。这两个字段独立存在同一条 OTLP 流里声明了事件名的记录是observed只有自由文本只能做模式匹配的记录是inferred。这样检测规则可以显式要求确定性例如只信任observed的审批事件——在只有 pre-tool 通知、没有审批钩子的运行时上Beacon 合成的approval.allowed事件就标记为inferred避免把看到了工具调用误当成操作者批准了。4. 身份与顺序跨来源对齐的密钥gen_ai.tool.call.id运行时自己给一次工具调用的名字tool_use_id、call_id、callId…都归一到此把调用—结果—审批串成一次prompt.id一次用户提问及其后所有动作的回合 ID把各运行时五花八门的拼法turn_id、generation_id统一按它过滤即可拿到完整一个回合event.id确定性 UUID由会话动作目标调用 ID 派生保证 hook 和 OTLP 对同一动作的两份记录共享同一身份天然去重排序字段(timestamp, sequence)因为 hook 是拦截瞬间同步写入、exporter 按周期写入日志追加顺序≠发生顺序所以所有消费方都按时间戳序号重排后再分析。三、存储与关联Store Correlate一份 JSONL 还原完整时间线Beacon 把活动日志路径保持稳定达到 10 MiB 轮转、保留 5 份编号归档本地只读 Dashboard 直接读这份日志提供会话时间线、Detections/Findings、Token Usage 等视图因为所有来源共享同一套 session / run / tool-call / prompt ID一个 Agent 会话会被重建为有序时间线而不是散落的记录。本地数据流与隐私边界脱敏、截断、仅回环服务在 docs/security/data-flow-threat-model.mdx 中有完整说明。四、检测Detect开放的威胁规则引擎有了统一事件模型检测规则就能写一次、跨所有运行时生效。这正是 spec/threat-rules/SPEC.md 定义的开放标准当前版本threat-rules/v1.1规则是 YAML、匹配逻辑是 CEL、输入是 Beacon 事件、且每条规则自带测试用例——任何能复现规则所声明判定结果的引擎都算符合标准。官方称之为Agent 遥测界的 Sigma 层。1. 两种匹配方式单事件匹配一条 CEL 表达式独立评估每个事件。会话级关联correlation在同一个 session 的时间窗口内按步骤顺序或order: any不要求顺序匹配多个事件。仓库自带规则 secret-read-then-egress.rule.yaml 是典型例子——读取了凭证文件 短时间内出现外发网络命令无论谁先谁后都判定为一次窃取特征每个会话最多触发一次correlation: scope: session window: 120s order: any steps: - id: read_secret match: e.event.action file.read e.file.path.matches((\.env|credentials|id_rsa|\.aws/)) - id: egress match: e.event.action command.executed e.command.command.matches(curl\s.*https?://)2. 引擎工作方式引擎内嵌在 CLI 中规则语料是外部数据。beacon scan的运行流程细节见 docs/detections/engine.mdx按优先级解析规则--rules dir→ 本地规则库~/.beacon/endpoint/rules→ 内置基线加载期校验校验 spec 版本、严格解码 YAML、编译 CEL 表达式、检查成熟度等级——坏规则提前失败扫描结果不含糊读取runtime.jsonl并按(timestamp, sequence)排序评估规则输出Finding规则 ID、严重度、emit.reason解释、会话 ID 和触发它的事件证据。CEL 契约要求表达式类型检查为bool、字段路径必须存在于事件 Schema、缺失字段按空值处理而非崩溃、正则使用 RE2 语义。核心实现位于 pkg/asymptoteobserve/threatrules/evaluator.go、correlation.go、loader.go 等。3. 成熟度与内建测试每条规则声明statusexperimental结构有效即可→stable必须同时有命中与不命中的 fixture且全部通过→deprecated。规则内置的tests即符合性边界规则声明该发生什么引擎用 fixture 证明。这让任何检测引擎都可以离线自证正确无需真实端点。内置规则库按威胁类别组织覆盖凭证访问、上下文窃取、高危命令、敏感编辑、提示注入、审批滥用、源码库篡改等方向规则目录见 rules/检测概览与 Finding 示例见 docs/detections/index.mdx。扫描是只读且离线的不改动遥测、不拉取规则唯一触网的动作是显式的beacon rules pull。五、快速上手与延伸阅读beacon scan # 对本地 runtime.jsonl 运行当前检测 beacon scan --json # 机器可读的 Finding 输出 beacon scan --fail-on high # 出现 high/critical 发现时以非零码退出可接入 CI 门禁 beacon rules list # 查看当前生效的检测规则想深入源码建议按数据流顺序阅读关注点位置总体架构docs/architecture/architecture.mdx统一事件 Schemadocs/telemetry-schema/event-schema.mdxOTLP/Hook → 字段映射docs/telemetry-schema/normalization.mdxOTel 导出器collector-builder/exporter/beaconjsonexporter/检测标准YAMLCELfixturespec/threat-rules/SPEC.md威胁规则引擎pkg/asymptoteobserve/threatrules/隐私与内容处理docs/security/retention-redaction.mdx一句话总结agent-beacon 用 OpenTelemetry 做采集入口用统一事件模型做中枢用开放规则标准做出口——三者解耦又对齐让你在不理解任何一种 Agent 运行时私有格式的前提下就能观测、审计并检测 AI Agent 的每一步行为。赞分享【免费下载链接】agent-beaconThe cross-harness, self-improving memory layer for AI agents.项目地址https://gitcode.com/gh_mirrors/ag/agent-beacon点击查看免费下载相关推荐防止提示词注入与数据外泄agent-beacon威胁检测引擎完全指南防止提示词注入与数据外泄agent beacon威胁检测引擎完全指南 agent beacon 是一款开源的跨框架cross harnessAI AgenGitpod Agent Smith 实战指南基于 ELF 签名的威胁检测与违规治理Gitpod Agent Smith 实战指南基于 ELF 签名的威胁检测与违规治理 Agent Smith 是 Gitpod 工作区安全治理的核心守护组件开发工具后端云原生AgentOps semconv 模块详解基于 OpenTelemetry GenAI 规范的 AI Agent 遥测语义约定AgentOps semconv 模块详解基于 OpenTelemetry GenAI 规范的 AI Agent 遥测语义约定 AgentOps SDK 通过人工智能大模型LLMOps可观测性AI 评测Agent Traces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
