bhanuprakasheagala/eTraceGen-eBPFEventTelemetryEngine

# eTraceGEN: eBPF 事件遥测引擎 `eTraceGen` 是一个基于 eBPF（内核空间）和现代 C++（用户空间）构建的 Linux 事件遥测引擎。 它旨在捕获并流式传输高价值的运行时遥测数据，涵盖： - 进程生命周期活动 - 文件操作 - 系统调用活动 - 最小化的网络套接字生命周期元数据 未来（v1 版本后）的领域： - DNS 事件 - HTTP/HTTPS 关联 - 更深度的网络遥测（流关联、协议上下文） 该项目有意设计为优先考虑可移植性的流水线： - 最小化且安全的内核端工作 - 与用户空间共享的类型化事件契约 - 用户空间的解码/丰富/过滤/输出阶段 - 在完整 eBPF 运行时不可用时进行优雅降级 ## 范围界定 - **当前发布目标 (v1)：** 进程 + 文件 + 系统调用遥测，以及最小化的网络套接字生命周期事件。 - **当前网络范围：** 仅限元数据的 `socket`/`connect`/`accept4`/`bind`/`listen`/`close`；不涉及 TLS 检查，也不进行 L7 解析。 - **设计原则：** 保持内核路径最小化，精确配对进入/退出操作，并在受控的里程碑中扩展领域。 ## 本仓库的目标受众 - 构建 Linux 可观测性/安全遥测系统的工程师 - 学习通过 C++ 实践 eBPF + libbpf 集成的开发者 - 希望在添加功能之前理解内部机制的人员 ## 文档导航 - [深度解析索引](docs/README.md) - [架构](docs/01-system-architecture.md) - [执行流程 (分步)](docs/02-execution-story.md) - [事件契约与 ABI](docs/03-event-contract.md) - [内核 eBPF 端](docs/04-kernel-side.md) - [用户空间流水线](docs/05-userspace-side.md) - [构建、可移植性与兼容性](docs/06-build-portability.md) - [路线图与扩展设计](docs/07-roadmap-and-extension.md) - [代码详解 (逐文件)](docs/code-walk/README.md) - [Linux 主机设置与启动](docs/linux-setup.md) ## 快速构建 ``` cmake -S . -B build cmake --build build -j ``` ## 构建 BPF 对象 (Linux) 使用仓库脚本： ``` ./scripts/build_bpf.sh ``` 或通过 CMake 辅助目标： ``` cmake --build build --target bpf_object ``` 这将生成： - `bpf/vmlinux.h`（从 `/sys/kernel/btf/vmlinux` 生成） - `bpf/event_logger.bpf.o` ## 快速运行 ``` ./build/etracegen ``` 可选的运行时覆盖参数： ``` ETRACEGEN_BPF_OBJECT=/absolute/path/to/event_logger.bpf.o ./build/etracegen ETRACEGEN_CONFIG=/absolute/path/to/config.yaml ./build/etracegen ``` 通过在配置中设置系统调用编号来启用选定的系统调用遥测： ``` filters: syscall_allowlist: [0, 1, 2] ``` 注意：系统调用编号与架构相关（`x86_64` 对比 `arm64`）。 启用内核端的 PID/UID 过滤： ``` filters: pid_allowlist: [1234] uid_allowlist: [1000] ``` 领域行为： - `domains.process: false` => 禁用进程生命周期事件 - `domains.file: false` => 禁用文件事件 - `domains.syscall: false` => 禁用系统调用事件（忽略允许列表） - `domains.network_socket: false` => 禁用网络套接字事件 过滤行为： - `pid_allowlist: []` => 禁用 PID 过滤 - `uid_allowlist: []` => 禁用 UID 过滤 - `syscall_allowlist: []` => 禁用系统调用遥测 ## 当前状态 - C++20 用户空间流水线已实现。 - libbpf 收集器路径可以从 BPF 对象打开/加载/附加/轮询事件。 - 当 libbpf 不可用时，存根收集器（Stub collector）回退机制正常工作。 - 进程生命周期遥测包括 exec/fork/exit 以及 clone/clone3/vfork 结果事件，并在可用时捕获子进程 PID。 - 文件探针（`openat`、`unlinkat`、`renameat2`）在内核中跨进入/退出进行配对，并附带准确的系统调用 `ret` 结果发出。 - 内核端的 PID/UID 允许列表过滤器在进程/文件/系统调用遥测中强制执行。 - 内核 BPF 统计信息（`bpf_stats`）每 30 秒定期报告一次，并在 libbpf 后端处于活动状态时在关闭时报告。 - 启动能力报告在进程启动时发出（包括后端、程序附加覆盖率、配置加载状态、map 可用性以及适用时的降级原因）。 - 选定的系统调用遥测通过 `raw_syscalls/sys_enter` + `raw_syscalls/sys_exit` 实现，并由配置（`filters.syscall_allowlist`）进行允许列表优先控制。 - 最小化的网络套接字遥测对 `socket`、`connect`、`accept4`、`bind`、`listen` 和 `close` 处于活动状态，仅包含元数据负载，不进行 TLS 检查。 ## 完整 Linux eBPF 模式的依赖项 - clang/llvm - libbpf - bpftool - 内核 BTF（通常为 `/sys/kernel/btf/vmlinux`） ## 开发命令包装器 ``` ./scripts/dev.sh help ``` 常用命令： - `./scripts/dev.sh build` - `./scripts/dev.sh bpf` - `./scripts/dev.sh host-check` - `./scripts/dev.sh check` - `./scripts/dev.sh check --linux-strict --skip-build` ## 一键检查 ``` ./scripts/run_all_checks.sh ``` Linux 严格模式（使用严格预检）： ``` ./scripts/run_all_checks.sh --linux-strict ``` ## 集成冒烟测试 (Linux) ``` ./scripts/integration_smoke.sh ``` 这将验证： - 进程事件已发出 - 文件事件已发出 - 文件事件包含 `ret` 结果字段 - 当启用 `filters.syscall_allowlist` 时系统调用事件已发出（在 x86_64 冒烟路径上断言） ## V1 验证套件 (Linux) ``` ./scripts/validate_v1_linux.sh ``` 此套件验证： - 基线进程/文件/系统调用发出 - PID 允许列表阻止所有行为 - UID 允许列表阻止所有行为 - UID 允许当前用户行为 - PID 允许自身行为（事件受限于预期 PID） ## V1 发布预检 跨平台预检： ``` ./scripts/release_check_v1.sh ``` Linux 发布关卡： ``` ./scripts/release_check_v1.sh --linux-strict ``` 或运行完整的编排检查： ``` ./scripts/run_all_checks.sh ```

标签：API安全, API集成, Bash脚本, CO-RE, Docker镜像, Homebrew安装, Hpfeeds, HTTP工具, IP 地址批量处理, JSON输出, libbpf, Linux内核, SQLite数据库, XML 请求, 事件解析, 内核监控, 内核级事件, 动态分析, 可观测性, 后渗透, 安全开发, 安全渗透, 数据流水线, 文件监控, 流量元数据, 现代C++, 系统调用, 系统遥测, 网络安全审计, 网络设备安全