falcosecurity/libs

# falcosecurity/libs [](https://github.com/falcosecurity/evolution/blob/main/REPOSITORIES.md#core-scope) [](https://github.com/falcosecurity/evolution/blob/main/REPOSITORIES.md#stable) [](./COPYING) [](https://github.com/falcosecurity/libs/actions/workflows/ci.yml) [](#drivers-officially-supported-architectures) [](https://github.com/falcosecurity/libs/actions/workflows/latest-kernel.yml) [](https://falcosecurity.github.io/libs/) 本仓库包含 **libsinsp**、**libscap**、**内核模块** 和 **现代 eBPF 探针** 的源代码。 这些组件是 [Falco](https://github.com/falcosecurity/falco) 以及其他处理同类数据项目的基础。 俗话说，一图胜千言： ## 项目布局 * [_driver/_](./driver) 包含内核模块和现代 eBPF 探针的源代码，即所谓的 **驱动程序**。 * [_userspace/_](./userspace) 包含 libscap 和 libsinsp 库的代码。 * **libscap**（即 *系统捕获* 库）是一个用户空间库，它直接与驱动程序通信，从环形缓冲区（驱动程序将事件放入其中）读取系统调用事件，并将其转发给 libsinsp。此外，libscap 实现了操作系统状态采集，并支持读写 scap 文件。 * **libsinsp**（即 *系统检查* 库）从 libscap 接收事件，并使用机器状态对其进行丰富：此外，它通过其内部规则引擎执行基于规则评估的事件过滤。最后，它管理输出。 * [_proposals/_](./proposals) 出人意料地包含了提案列表。 * [_cmake/modules/_](./cmake/modules) 包含用于构建外部依赖项以及 libscap 和 libsinsp 的模块；使用者（如 Falco）使用这些模块在其项目中构建本库。 ## 驱动程序官方支持的架构 我们的驱动程序官方支持以下架构： 要访问关于 Falco 驱动程序内核测试的最新状态报告，请访问此[页面](https://falcosecurity.github.io/libs/)。它提供了支持的系统调用列表以及[报告](https://falcosecurity.github.io/libs/report/)。
## 版本控制

展开版本控制详情

本项目对 _libs_ 和 _drivers_ 组件使用不同的编号序列，两者都遵循[语义化版本控制 2.0.0](https://semver.org/)。具体来说，_drivers_ 组件的版本号在 SemVer 字符串的[构建元数据](https://semver.org/#spec-item-10)部分包含一个 `driver` 后缀（例如 `5.1.0+driver`），以区别于 _libs_ 的版本（例如 `0.12.0`）。关于我们如何管理这些组件版本控制的更多详情，请查阅我们的[发布流程文档](./release.md)。 当从 Git 工作目录构建本项目时，构建系统（参见 [CMakeLists.txt](./CMakeLists.txt)）将自动确定所有组件的正确版本。 对于[官方发布的构建](https://github.com/falcosecurity/libs/releases)，将使用相应的 Git 标签作为版本号。 对于开发版本，应用以下模式： `..-+[-driver]` 其中： - `..` 代表下一个版本号，反映了发布分支的补丁版本或开发分支的次版本。 - `` 是领先提交的数量，领先自： - 分支上的最新标签（针对发布分支）；或 - 与拥有最新标签版本的分支的最近共同祖先（针对开发分支）。 - `` 指提交哈希值的前 7 位。 - `[-driver]` 是一个可选后缀，专门用于 _driver_ 版本。 例如，`0.13.0-2+abcdef0` 意味着当前 _HEAD_（_G_，提交哈希 `abcdef0`）领先于与拥有 `0.12.0` 标签（_C_）的发布分支的共同祖先（_E_）两个提交： ``` A---B---C (tag: 0.12.0, branch: release/0.12.x) / D---E---F---G (HEAD -> abcdef0) ``` 此方案确保了在比较构建版本号时，无论它们是发布版还是开发版，都能获得正确的[优先级](https://semver.org/#spec-item-11)。 如果你在 Git 工作目录之外构建本项目，或者想覆盖版本号，你必须正确设置相应的 `cmake` 变量。例如，使用 `-DFALCOSECURITY_LIBS_VERSION=x.y.z -DDRIVER_VERSION=a.b.c+driver`。

## 构建

展开构建说明

为了方便起见，除了 Falco [官方文档](https://falco.org/docs/install-operate/source/)中提供的信息外，我们还在此处包含了构建 `libs` 模块的说明。这些说明旨在用于在您自己的 Linux 开发机器上构建和测试 `libs`。但是，如果您打算采用 CI 或在容器内构建，则需要考虑一些额外因素。官方网站]((https://falco.org/docs/install-operate/source/)) 在这方面不断扩展其指导。 本项目使用 `cmake` 构建系统，关键的 `make` 目标如下： * `driver` -> 构建 kmod * `scap` -> 构建 libscap（如果启用，`modern_ebpf` 驱动程序将被捆绑到 `scap` 中） * `sinsp` -> 构建 libsinsp（依赖于 `scap` 目标） * `scap-open` -> 构建一个用于测试驱动程序的 `libscap` 小型示例二进制文件（依赖于 `scap`） * `sinsp-example` -> 构建一个用于测试驱动程序和/或 `libsinsp` 功能的 `libsinsp` 小型示例二进制文件（依赖于 `scap` 和 `sinsp`） 您可以参考主 [CMakeLists.txt](CMakeLists.txt) 文件来探索可用的目标和标志。 首先，创建并进入 `build/` 文件夹： ``` mkdir build && cd build ``` ### 使用捆绑依赖项构建用户空间 构建项目最简单的方法是使用 `BUNDLED_DEPS` 选项（默认启用），这意味着大部分依赖项将在构建过程中被获取和编译： ``` cmake -DUSE_BUNDLED_DEPS=ON ../; make sinsp ``` ### 使用系统依赖项构建用户空间 若要使用系统依赖项构建，首先请确保已安装所有必需的软件包。请参考 Falco 的[官方文档](https://falco.org/docs/install-operate/source/)。 ``` cmake -DUSE_BUNDLED_DEPS=OFF ../; make sinsp ``` ### 构建驱动程序 - kmod 要构建 kmod 驱动程序，您需要安装内核头文件。请查阅 Falco 的[官方文档](https://falco.org/docs/install-operate/source/)。 ``` make driver # 验证已创建 kmod 二进制目标文件，使用 `.ko` 扩展名。 ls -l driver/src/scap.ko; ``` ### 构建驱动程序 - 现代 eBPF 探针 要构建现代 eBPF 探针，需要满足一些额外的先决条件： * 较新版本的 `clang`（>=`12`）。 * 较新版本的 `bpftool`，输入 `bpftool gen` 您应该至少看到以下功能： 用法: bpftool gen object OUTPUT_FILE INPUT_FILE [INPUT_FILE...] <--- bpftool gen skeleton FILE [name OBJECT_NAME] <--- bpftool gen help 如果您想使用 `bpftool` 镜像仓库，版本 [`6.7`](https://github.com/libbpf/bpftool/releases/tag/v6.7.0) 应该足够了。 如果您想直接从内核源码树编译，至少应选择 `5.13` 标签。 * 您的内核需暴露 BTF，您可以通过 `ls /sys/kernel/btf/vmlinux` 进行检查。您应该会看到这行： /sys/kernel/btf/vmlinux * 内核版本 >=`5.8`。 现代 eBPF 驱动程序的构建过程不需要内核头文件，并且不受您的内核版本约束。这得益于现代 eBPF 驱动程序的 CO-RE（一次编译，到处运行）功能。 CO-RE 允许驱动程序在具有向后移植 BTF（BPF 类型格式）支持的内核或内核版本 >= 5.8 上工作。驱动程序无需直接了解正在运行的内核即可解释内核数据结构，这并非魔法——它利用了预定义的类型信息和基于 BTF 的重定位。我们维护了一个包含基本内核数据结构定义的 [vmlinux.h](driver/modern_bpf/definitions/vmlinux.h) 文件，允许 eBPF 程序动态引用字段。此外，对于需要系统头文件中的宏或函数的情况，我们在 [struct_flavors.h](driver/modern_bpf/definitions/struct_flavors.h) 中重新定义了它们。结合 CO-RE（一次编译，到处运行），这使得驱动程序能够在不同内核版本之间保持可移植性。 现代 eBPF 驱动程序构建过程使用 `bpftool` 生成一个 eBPF 头文件骨架文件。该骨架文件是一个 C 头文件，其中将编译后的 eBPF 程序作为字节码嵌入。 ``` cmake \ -DUSE_BUNDLED_DEPS=ON \ -DBUILD_LIBSCAP_MODERN_BPF=ON ../; make ProbeSkeleton # 验证已创建现代 eBPF 字节码/最终组合头文件（包含所有 `.o` modern_ebpf 文件），使用 `.h` 扩展名。 ls -l skel_dir/bpf_probe.skel.h; # 现在在链接过程中于 `scap` 里包含 skel_dir/bpf_probe.skel.h。 make scap ``` 由于现代 eBPF 已包含在 `scap` 中，运行 `make scap` 会自动涵盖 `make ProbeSkeleton` 构建步骤。 您也可以拆分构建过程，并指定包含 `bpf_probe.skel.h` 文件的目录。 ``` cmake \ -DUSE_BUNDLED_DEPS=ON \ -DBUILD_LIBSCAP_MODERN_BPF=ON \ -DMODERN_BPF_SKEL_DIR="/tmp/skel-dir" ../; ``` ## 测试

展开测试说明

本仓库为 `scap` 和 `sinsp` 提供了便捷的测试示例二进制文件： * `scap-open` -> 构建一个用于测试驱动程序的 `libscap` 小型示例二进制文件（依赖于 `scap`），请查看该程序的[文档](./userspace/libscap/examples/01-open/README.md) * `sinsp-example` -> 构建一个用于测试驱动程序和/或 `libsinsp` 功能的 `libsinsp` 小型示例二进制文件（依赖于 `scap` 和 `sinsp`），请查看该程序的[文档](./userspace/libsinsp/examples/README.md) 在开发新功能时，您将根据所开发的内容运行其中之一，以测试和验证您的更改。 这里有一个 `cmake` 命令示例，它将启用所有测试和组件所需的一切。默认情况下，以下标志是禁用的，但 `USE_BUNDLED_DEPS` 和 `CREATE_TEST_TARGETS` 除外（它们默认启用）。 ``` cmake \ -DUSE_BUNDLED_DEPS=ON \ -DBUILD_LIBSCAP_MODERN_BPF=ON \ -DBUILD_DRIVER=ON \ -DMODERN_BPF_DEBUG_MODE=ON \ -DCREATE_TEST_TARGETS=ON \ -DENABLE_LIBSCAP_TESTS=ON \ -DENABLE_DRIVERS_TESTS=ON \ -DENABLE_LIBSINSP_E2E_TESTS=ON ../; ``` ``` nproc=$(grep processor /proc/cpuinfo | tail -n 1 | awk '{print $3}'); rm -f driver/src/scap.ko; make driver; # scap-open 二进制文件 rm -f libscap/examples/01-open/scap-open; make -j$(($nproc-1)) scap-open; # sinsp-example 二进制文件 rm -f libsinsp/examples/sinsp-example; make -j$(($nproc-1)) sinsp-example; ``` 这些是我们的 CI 系统强制执行的常规单元测试： ``` # sinsp 传统单元测试 make -j$(($nproc-1)) unit-test-libsinsp; # 运行 make run-unit-test-libsinsp; # scap 传统单元测试 make -j$(($nproc-1)) libscap_test; # 运行 sudo ./test/libscap/libscap_test; ``` 专门的驱动程序测试可以在 [test/drivers](test/drivers) 中找到，但请注意可能存在某些限制，我们正在尽最大努力确保跨各种发行版的兼容性。我们的 CI 系统也强制执行这些测试，但请注意，目前，用于驱动程序测试的 CI 系统是专门为 Ubuntu 设计的。因此，如果您遇到一些与您的更改无关的测试失败，请不必过于担心。 ``` make -j$(($nproc-1)) drivers_test; # 通过更改标志运行每个驱动程序测试 sudo ./test/drivers/drivers_test -m; ``` 下面提到的测试超出了“单元测试”的范围。在这方面，我们也致力于确保它们在您的 `localhost` 上顺利运行，以进行 PR 前的测试，尽我们所能： - [test/e2e](test/e2e) - 由我们的 CI 强制执行 有关 CI 驱动的 Falco 驱动程序内核测试的当前状态报告，请访问此[页面](https://falcosecurity.github.io/libs/)。 总的来说，Falco 项目的 `libs` 仓库包含许多由 CI 驱动的检查。有关最新信息，请参阅 [workflows](.github/workflows/) 目录下的 CI 定义。 ### [实验性] 运行 libsinsp 端到端测试 要在 x86_64 上正确运行新的 libsinsp 端到端测试，需要 `gcc-multilib` 和 `g++-multilib`。要运行测试，请使用以下命令： ``` make -j$(($nproc-1)) libsinsp_e2e_tests; # 通过更改标志运行每个驱动程序测试 sudo ./test/libsinsp_e2e/libsinsp_e2e_tests -m; ```

## 如何贡献 有关如何贡献的更多信息，请参考[贡献指南](https://github.com/falcosecurity/.github/blob/main/CONTRIBUTING.md)和[行为准则](https://github.com/falcosecurity/evolution/CODE_OF_CONDUCT.md)。 要向本仓库贡献代码，我们恳请您仔细阅读[构建](#build)和[测试](#testing)部分。 ## 许可证 本项目根据 [Apache 2.0](./COPYING) 开源许可证授权给您。某些子组件可能有单独的许可证。您可以在[这里](./NOTICES)找到许可通知。

标签：Bash脚本, Docker镜像, eBPF技术, Falco基础, 事件捕获, 事件驱动, 内核模块开发, 内核驱动, 客户端加密, 开源监控工具, 性能监控, 探针驱动, 用户空间库, 系统事件处理, 系统调用捕获, 网络协议, 运行时监控, 驱动源码