AcTrail

行动轨迹，真实轨迹。 验证智能体实际行为，而非仅仅是其表述。

AcTrail 会记录 AI 智能体进程树在 Linux/WSL 上的实际操作，然后将证据关联回可追溯的行为：进程启动、文件与 IPC 活动、网络连接、TLS/明文负载、HTTP 语义、LLM 请求与响应、资源样本以及策略决策。

适用场景

当智能体自身的日志不足以说明问题时，请使用 AcTrail。AcTrail 可解答：

• 运行了哪些进程树，以及它生成了哪些命令？
• 它接触了哪些文件、套接字、管道和网络端点？
• 它向 LLM 提供商发送了什么，又收到了什么返回？
• 哪些底层负载、HTTP 或进程事件能证明某个高层级行为？
• 哪些观察结果是完整的、部分的、被阻止的或降级的？

安装

在开发或测试检出版本时，从源代码安装：

./scripts/install-release.sh /usr/local/bin

安装脚本会检查构建依赖项，使用 npm ci 安装 actrailweb 前端依赖项，构建缺失的发布二进制文件，并将其复制到目标目录。仅当目标目录需要提升权限时，脚本才会在最终复制步骤中使用 sudo。如果不想安装到 /usr/local/bin，可以使用其他目录。

RPM 包从最新发布页面发布：

https://gitcode.com/openeuler/AcTrail/releases/latest

下载与您的版本和架构匹配的软件包，例如：

AcTrail-<VERSION>-<RELEASE>.<DISTRO>.<ARCH>.rpm

然后使用您的系统包工具进行安装：

sudo rpm -Uvh AcTrail-<VERSION>-<RELEASE>.<DISTRO>.<ARCH>.rpm

首次运行

最快的路径是默认的本地工作流程：

flowchart LR
    Init["actraild init<br/>(create config file)"] --> Start["actraild start<br>(prepare for observation)"]
    Start --> Launch["actrailctl launch<br>(start and observe an agent)"]
    Launch --> Web["actrailweb<br/>(view the traces)"]

默认配置支持广泛的数据收集，并且可能会持久化存储敏感的明文载荷，包括提示词、API 密钥、Authorization 头部以及模型响应。请先在可随时停用的开发主机或工作负载上使用它。

以下命令假设 actraild、actrailctl 和 actrailweb 已安装在 PATH 中。如果是从源代码检出且未安装，则请改用相应的 ./target/release/... 二进制文件。

初始化配置，启动守护进程，运行一个被追踪的命令，并打开 Web UI：

sudo actraild init
sudo actraild start
sudo actrailctl launch --name quickstart -- \
  bash -lc 'echo ACTRAIL_QUICKSTART_OK; id >/dev/null; ls /etc/hosts >/dev/null'
sudo actrailweb

打开 http://127.0.0.1:18080，选择 quickstart 追踪，查看进程树、衍生操作、证据、诊断信息和原始详情。

actrailweb 在前台运行。使用 UI 时请保持其开启，停止守护进程前按 Ctrl-C。

使用完毕后停止守护进程：

sudo actraild stop

如需包含预期输出和清理步骤的完整分步指南，请参阅 docs/examples/01.quick-start/README.md。

功能展示

领域	观测内容
进程活动	启动、退出、进程树成员关系、命令上下文以及智能体调用标记。
文件与进程间通信活动	文件事件、内存映射（mmap）活动、Unix 套接字、管道/命名管道（FIFOs），以及针对频繁终端操作或批量读取模式的精简摘要。
网络与载荷	套接字活动、TLS 明文捕获、HTTP/HTTP2/SSE 语义、保留的载荷元数据以及载荷证据链接。
大语言模型（LLM）行为	服务提供商路由、请求与响应操作、规范化请求块、组装的响应文本/推理过程、工具调用以及使用情况摘要。
治理	文件访问监控（fanotify）实施事实、允许/拒绝决策、资源样本、诊断信息、JSON 导出以及 OTEL JSON 导出。

选择你的路径

目标	起始位置
运行 AcTrail 一次并查看跟踪	docs/examples/01.quick-start/README.md
学习日常 CLI 命令	docs/usage.md
检查内核、权限、BTF、tracefs、seccomp 和 fanotify 要求	docs/platform-requirements.md
部署持久化主机守护进程	docs/deployment.md
针对安全问题选择功能路径	docs/use-cases.md
捕获 LLM HTTP/TLS 载荷	docs/examples/02.llm-http-payload-capture/README.md
验证对真实智能体的广泛覆盖	docs/examples/08.full-monitor-validation/README.md
运行真实智能体验收用例	tests/agent-trace/README.md

运行时形态

flowchart LR
    Operator["operator"] --> CLI["actraild / actrailctl"]
    CLI --> Daemon["actraild"]
    Daemon --> Collectors["eBPF / seccomp / TLS sync / samplers"]
    Collectors --> Analyzers["ingest / payload / HTTP / semantic analyzers"]
    Analyzers --> Store["AcTrail storage"]
    Store --> Viewer["actrailviewer"]
    Store --> Web["actrailweb"]
    Store --> Export["JSON / OTEL export"]

组件	功能
actraild	运行数据收集、分析、追踪生命周期管理、存储写入及实时导出。
actrailctl	初始化配置、检查守护进程就绪状态、启动被追踪的工作负载、列出追踪记录以及清理运行时 artifacts。
actrailviewer	通过命令行界面读取存储内容，以获取摘要、事件、负载、操作、诊断信息、JSON 及 OTEL 格式数据。
actrailweb	通过只读 Web 用户界面读取存储内容，界面围绕语义化操作证据构建。

安全注意事项

AcTrail 由配置驱动且采用快速失败机制：必要功能若无法正常运行，应明显报错，而非静默降低收集级别。

actraild 需要具备目标 Linux/WSL 内核所要求的权限，以便进行 eBPF 跟踪点/用户探针挂载。Seccomp 和 fanotify 相关路径有额外的内核和权限要求。

负载捕获可能会留存提示词、API 密钥、Authorization 头、文件节选以及模型响应。在一次性验证环境外使用宽泛配置前，请务必审查脱敏、留存、导出及存储设置。

许可证

AcTrail 采用木兰宽松许可证，第 2 版。详见 LICENSE。

eBPF C 程序包含 Linux 内核验证器许可部分字符串，例如 char LICENSE[] SEC("license") = "GPL";；这些字符串用于 BPF 加载/辅助函数兼容性，并不替代仓库级别的许可证。