Agent-Hellboy/ltm

# ltm Linux 的机器历史调试器。通过 eBPF 记录进程、文件、网络、内存和 块 I/O，将元数据存储在 SQLite 中，并回答有关主机上发生事件的 时间线 / diff / 自然语言 / SQL 问题。 ## 快速开始 ``` go build -o bin/ltm ./cmd/ltm sudo ./bin/ltm start # record (eBPF; root, Linux/x86_64) ./bin/ltm timeline --since 5m ./bin/ltm watch # live tail; Ctrl-C to stop ./bin/ltm diff --from 10m --to now ./bin/ltm query "who modified /etc/some.conf?" sudo ./bin/ltm stop ``` 录制需要 root 权限（或 `CAP_BPF` + `CAP_PERFMON`）。查询则不需要。 在没有活动主机的情况下：`ltm benchmark --count 1000` 会生成合成事件。 全局标志位于子命令**之前**（`ltm --db /tmp/ltm.db status`）。 默认值：DB `~/.local/share/ltm/ltm.db`，PID `~/.local/run/ltm.pid`。 在任何读取命令中添加 `--json` 以获取机器可读的输出。 ## 命令 | 命令 | 作用 | |---|---| | `start` / `stop` / `status` | 控制记录器 | | `timeline` | 通过 `--pid --uid --comm --category --action --path --exe --since --until --limit` 进行过滤（可重复；`--path`/`--exe` 为 SQL `LIKE`） | | `watch` | 实时追踪（`--interval --since --category --comm --pid`） | | `diff --from --to` | 两个时间点之间的机器状态更改 | | `query ""` | 自然语言（通过模板，或 agent → SQL） | | `query sql [""]` | 只读 SQL；不带参数则打印 schema（`ltm sql` 也可以） | | `prune --older-than 720h` | 删除旧行并执行 `VACUUM` | | `benchmark --count N` | 写入 N 个合成事件（不使用 eBPF） | | `version` | 构建版本、commit、平台 | ## 存储与查询 一个 SQLite 数据库，WAL writer 由 daemon 持有。每条读取路径均以 只读模式打开（`PRAGMA query_only=ON`）——查询永远不会与 writer 发生冲突，也 不会修改日志。仅存储元数据；不含文件内容。 ``` export LTM_AGENT=claude # or codex, cursor, gemini, auto, or a custom command ltm query "which process wrote to files the most today?" ``` Agent SQL 会先打印出来，然后在只读连接上运行，并且除非它是 单个 `SELECT` 语句，否则将被拒绝。无 agent（或 agent 故障）→ 使用内置模板。 ## 记录内容 约 60 个 tracepoint：**进程**（exec、exit、fork、clone、kill），**文件** （open/close、read/write、rename、unlink、link、symlink、mkdir、rmdir、chmod、 chown、stat、access、truncate、dup、pipe、……），**内存**（mmap、munmap、 mprotect），**网络**（socket、connect、bind、listen、accept、send/recv、 shutdown），**块**（`block_rq_issue`）。 BPF 会跳过 `/proc`、`/sys`、`/dev` 以及 daemon 自身的 PID。完整列表： `internal/ebpf/tracepoints_linux.go`。在修改 `collector.bpf.c` 后，使用 `make ebpf` 重新构建。 ### 限制 - **仅限 x86_64 录制** — BPF 构建于 `-D__TARGET_ARCH_x86` ([#2](https://github.com/Agent-Hellboy/ltm/issues/2))。查询可在任何地方运行。 - **仅限 IPv4 地址** — IPv6 的 connect/bind 在存储时没有解码地址。 - **字节数**是系统调用的*请求*大小（enter probe）；简短/失败的 I/O 会被多算；`readv`/`writev`/`sendmsg`/`recvmsg` 报告为 `0`。 - **fd→path** 涵盖 fd ≤ 1024 的情况，并且在 PID 大量重用后可能会出现错误归因； 更高的 fd 在记录时没有路径。 ## 开发 ``` go test ./... # any OS make integration # real eBPF recording; Linux + root ``` 布局：`cmd/ltm` 入口点；其他所有内容位于 `internal/` 下 （`cli`、`daemon`、`collector`、`ebpf`、`storage`、`agent`、`diff`、`query`）。 文档：[`docs/`](docs/)（CLI、查询、录制、架构、安全性）。 贡献者规则：[`AGENTS.md`](AGENTS.md)。

标签：API集成, Docker镜像, EVTX分析, LLM集成, SQLite, 可观测性, 日志审计