logira

面向不可预测自动化的操作系统级运行时审计。

logira 是一个仅观察的 Linux CLI，通过 eBPF 记录运行时的 exec、file 和 net 事件。它帮助你了解 AI 代理运行及其他形式自动化过程中实际发生的情况，提供每次运行的本地存储，用于审计、运行后审查、搜索和检测分类。

什么是 logira？

• 基于 eBPF 的运行时进程执行、文件活动和网络活动采集。
• 采用 cgroup v2 运行范围跟踪，因此事件可归因于单一受审计的运行。
• 每次运行的本地存储采用 JSONL 和 SQLite 格式，用于时间线审查和快速查询。
• 内置默认检测规则，并可添加自定义 YAML 规则。
• 设计上仅观察：logira 记录和检测，但不强制执行或阻止。

为什么使用 logira？

• 审计 AI 代理在一次运行中实际执行、更改和连接了哪些内容（例如 codex --yolo 或 claude --dangerously-skip-permissions）。
• 保留可信的执行痕迹，不依赖代理自身的文本叙述。
• 检测高风险行为模式，如凭据访问、破坏性命令、持久化更改和可疑网络出口。
• 运行后通过结构化事件历史和检测结果审查和分享取证证据。
• 为本地自动化或 CI 任务添加轻量级运行时审计，而不改变工作负载行为。

默认检测

logira 包含一套有观点、仅观察的默认规则集，旨在审计 AI 代理运行。 你也可以通过 logira run --rules <file> 添加自己的每次运行规则 YAML。

• 凭据和密钥写入：~/.ssh、~/.aws、kube/gcloud/docker 配置、.netrc、.git-credentials、注册表凭据。
• 敏感凭据读取：SSH 私钥、AWS 凭据/配置、kubeconfig、docker 配置、.netrc、.git-credentials。
• 持久化和配置更改：/etc 下的写入、systemd 单元、cron、用户自启动项、Shell 启动文件。
• 临时释放文件：在 /tmp、/dev/shm、/var/tmp 下创建的可执行文件。
• 可疑执行模式：curl|sh、wget|sh、隧道/反向 Shell 工具和参数、base64 解码带 Shell 提示。
• 代理安全破坏性模式：rm -rf、git clean -fdx、、、 及类似命令。

安装

通过脚本安装（推荐）

选项1：通过便捷脚本安装：

curl -fsSL https://raw.githubusercontent.com/melonattacker/logira/main/install.sh | sudo bash

选项2：通过发布压缩包手动安装：

tar -xzf logira_vX.Y.Z_linux-<arch>.tar.gz
cd logira_vX.Y.Z_linux-<arch>
sudo ./install-local.sh

重新安装/升级后：

• 首次安装：通常不需要额外步骤（install.sh 会运行 systemctl enable --now）。
• 在已有安装上重新安装/升级：重启 logirad 以确保新二进制文件正在运行。

sudo systemctl daemon-reload
sudo systemctl restart logirad.service
sudo systemctl status logirad.service --no-pager

从源代码安装

构建：

make build

启动根守护进程（需要用于跟踪）：

sudo ./logirad

# 1) 生成 eBPF 对象（仅当缺失时需要）
make generate

# 2) 安装 systemd 单元
sudo install -D -m 0644 packaging/systemd/logirad.service /etc/systemd/system/logirad.service

# 3) 安装守护进程二进制文件（单元默认路径为 /usr/local/bin/logirad）
sudo install -m 0755 ./logirad /usr/local/bin/logirad

# 4) （推荐）通过环境文件将 systemd 指向 eBPF .o 文件。
# 这样可以避免依赖服务工作目录。
sudo mkdir -p /etc/logira
sudo tee /etc/logira/logirad.env >/dev/null <<'EOF'
LOGIRA_EXEC_BPF_OBJ=/absolute/path/to/collector/linux/exec/trace_bpfel.o
LOGIRA_NET_BPF_OBJ=/absolute/path/to/collector/linux/net/trace_bpfel.o
LOGIRA_FILE_BPF_OBJ=/absolute/path/to/collector/linux/filetrace/trace_bpfel.o
EOF

# 5) 启用 + 启动
sudo systemctl daemon-reload
sudo systemctl enable --now logirad

# 查看日志
sudo journalctl -u logirad -f

# 检查状态
systemctl status logirad --no-pager

# 停止 + 禁用
sudo systemctl stop logirad
sudo systemctl disable --now logirad

使用方法

以普通用户身份运行受审计的代理（事件会自动保存）：

./logira run -- bash -lc 'echo hi > x.txt; curl -s https://example.com >/dev/null'
./logira run --rules ./my-rules.yaml -- bash -lc 'cat ~/.aws/credentials >/dev/null'

运行 Codex CLI：

./logira run -- codex --yolo "Update the README to be clearer and add examples."

运行 Claude Code CLI：

./logira run -- claude --dangerously-skip-permissions "Find and fix flaky tests."

列出运行记录：

./logira runs

查看并解释上一次运行：

./logira view last
./logira view last --ts both
./logira view last --color always
./logira explain last
./logira explain last --show-related
./logira explain last --drill 35

查询事件：

./logira query last --type detection
./logira query last --type net --dest 140.82.121.4:443
./logira query last --related-to-detections --type net
./logira query last --contains curl

命令

• logira run -- <command...>：在审计下运行命令并自动保存为新运行
• logira runs：列出已保存的运行
• logira view [last|<run-id>]：运行仪表盘（使用 --raw 获取传统文本）
• logira query [last|<run-id>] [filters...]：按类型搜索事件，以表格形式输出
• logira explain [last|<run-id>]：按默认分组显示检测结果（--show-related、--drill）

规则：

• 内置默认规则集始终处于活动状态（internal/detect/rules/default_rules.yaml）
• 可通过 logira run --rules <yaml-file> 添加每次运行的自定义规则
• 自定义规则示例和测试命令：参阅 examples/rules/README.md
• 文件事件保留由文件规则驱动；--watch 仅为向后兼容性而弃用

数据存储在哪里？

默认主目录：~/.logira（可通过 LOGIRA_HOME 覆盖）

每次运行存储于：

~/.logira/
  runs/<run-id>/
    events.jsonl
    index.sqlite
    meta.json

run-id 格式：YYYYMMDD-HHMMSS-<tool>

文档

• JSONL 架构：docs/jsonl.md
• SQLite 架构：docs/sqlite.md
• 自定义规则语法：docs/rules.md
• 开发说明（BPF 生成、测试）：docs/development.md

注意事项

• 需要 Linux 内核 5.8+。
• 需要 systemd（正常安装中根守护进程 logirad 应在 systemd 下运行）。
• 需要 cgroup v2（可通过 logira status 检查）。
• 跟踪需要根守护进程 logirad 正在运行；logira run 本身不需要 sudo。
• 如果缺少 BPF 对象文件，请设置 LOGIRA_EXEC_BPF_OBJ / LOGIRA_NET_BPF_OBJ / LOGIRA_FILE_BPF_OBJ。

安装路径（默认）

安装程序放置：

• 二进制文件：/usr/local/bin/logira、/usr/local/bin/logirad
• BPF 对象：/usr/local/lib/logira/bpf/
• systemd 单元：/etc/systemd/system/logirad.service
• 环境文件：/etc/logira/logirad.env（设置 LOGIRA_EXEC_BPF_OBJ、LOGIRA_NET_BPF_OBJ、LOGIRA_FILE_BPF_OBJ）

许可证

Apache License 2.0。详情见 LICENSE。

collector/linux/ 下的 eBPF 程序采用双重许可：Apache-2.0 或 GPL-2.0-only。

这确保了在加载需要仅 GPL 助手的 eBPF 程序时与 Linux 内核的兼容性。