DOCA YARA 检查应用程序指南 - NVIDIA 文档

本指南提供在 NVIDIA® BlueField® DPU 之上实现的 YARA 检查。

简介

YARA 检查使用 DOCA App Shield 库监控主机系统中的所有进程，以查找特定的 YARA 规则。

这种安全功能有助于从独立且受信任的 DPU 中识别主机进程中的恶意软件检测模式。这是一种创新的入侵检测系统 (IDS)，因为它旨在 DPU 的 Arm 内核上独立运行，而不会妨碍主机。

这个基于 DOCA App Shield 的应用程序提供了直接从 DPU 读取、分析和验证主机（裸机/VM）内存的功能。

通过使用该库，此应用程序扫描主机进程并查找预定义的 YARA 规则。在每次扫描迭代之后，应用程序都会指示是否匹配任何规则。一旦有匹配项，应用程序将报告在哪个进程中检测到哪些规则。报告将打印到控制台，并使用进程间通信 (IPC) 导出到 DOCA 遥测服务 (DTS)。

本指南介绍如何使用 DOCA App Shield 库构建 YARA 检查，该库利用 DPU 的能力，例如基于硬件的 DMA、完整性等。

注意

由于 DOCA App Shield 库仅支持 Windows 主机的 YARA API，因此此应用程序只能用于检查 Windows 主机。

系统设计

主机的参与仅限于生成传递给 DPU 所需的 ZIP 和 JSON 文件。这在应用程序触发之前完成，此时主机仍处于“安全”状态。

生成所需的文件可以通过在主机上运行 DOCA App Shield 的 doca_apsh_config.py 工具来完成。有关更多信息，请参阅 DOCA App Shield。

system-design-diagram-version-1-modificationdate-1734470464383-api-v2.png

应用程序架构

用户使用 DOCA 工具 doca_apsh_config.py 创建 ZIP 和 JSON 文件，并将它们复制到 DPU。

应用程序可以将 YARA 规则检测报告给

文件
终端
DTS

application-architecture-diagram-version-1-modificationdate-1734470464763-api-v2.png

这些文件是通过在主机上针对零时间进程运行 doca_apsh_config.py 生成的。
以下步骤以规律的时间间隔重复执行
1. YARA 检查应用程序从 DOCA App Shield 库请求所有应用程序的列表。
2. 应用程序循环遍历所有进程，并使用 DOCA App Shield 库检查 YARA 规则是否匹配。
3. 如果找到 YARA 规则（一个或多个），则 YARA 证明应用程序会报告结果，其中包含时间戳以及有关进程和规则的详细信息，发送至
  - 本地遥测文件 – 代表真实 DTS 将接收的数据的文件夹和文件
    
    注意
    
    这些文件仅用于此示例的目的，因为通常此数据不会导出到用户可读的文件中。
  - DOCA 日志
  - DTS IPC 接口（即使没有 DTS 处于活动状态）
App Shield 代理在首次检测到 YARA 规则时退出。

DOCA 库

此应用程序利用以下 DOCA 库

有关更多信息，请参阅它们各自的编程指南。

局限性

该应用程序仅在 Ubuntu 22.04 环境中可用
该应用程序仅支持检查 Windows 主机

编译应用程序

信息

有关如何安装 BlueField 相关软件的详细信息，请参阅 DOCA Linux 安装指南。

DOCA 参考应用程序的安装包含应用程序的源代码以及匹配的编译说明。这允许“按原样”编译应用程序，并提供修改源代码然后编译应用程序新版本的能力。

提示

有关应用程序以及开发和编译技巧的更多信息，请参阅 DOCA 参考应用程序页面。

应用程序的源代码可以在应用程序的目录 /opt/mellanox/doca/applications/yara_inspection/ 下找到。

编译所有应用程序

所有 DOCA 应用程序都在单个 meson 项目下定义。因此，默认情况下，编译包括所有应用程序。

要一起构建所有应用程序，请运行

复制
已复制！

            
            cd /opt/mellanox/doca/applications/
meson /tmp/build 
ninja -C /tmp/build

信息

doca_yara_inspection 在 /tmp/build/yara_inspection/ 下创建。

仅编译当前应用程序

要直接仅构建 YARA 检查应用程序

复制
已复制！

            
            cd /opt/mellanox/doca/applications/
meson /tmp/build -Denable_all_applications=false -Denable_yara_inspection=true
ninja -C /tmp/build

信息

doca_yara_inspection 在 /tmp/build/yara_inspection/ 下创建。

或者，可以在 meson_options.txt 文件中设置所需的标志，而不是在编译命令行中提供它们

在 /opt/mellanox/doca/applications/meson_options.txt 中编辑以下标志
- 将 enable_all_applications 设置为 false
- 将 enable_yara_inspection 设置为 true

运行以下编译命令

复制
已复制！

            
            cd /opt/mellanox/doca/applications/
meson /tmp/build 
ninja -C /tmp/build

信息

doca_yara_inspection 在 /tmp/build/yara_inspection/ 下创建。

故障排除

有关应用程序编译中遇到的任何问题，请参阅 DOCA 故障排除。

运行应用程序

先决条件

配置 BlueField 的固件

在 BlueField 系统上，配置 PF 基地址寄存器和 NVME 仿真。运行

复制
已复制！

            
            dpu> mlxconfig -d /dev/mst/mt41686_pciconf0 s PF_BAR2_SIZE=2 PF_BAR2_ENABLE=1 NVME_EMULATION_ENABLE=1

执行 BlueField 系统重启，以使 mlxconfig 设置生效。

可以使用以下命令验证此配置

复制
已复制！

            
            dpu> mlxconfig -d /dev/mst/mt41686_pciconf0 q | grep -E "NVME|BAR"

下载目标系统（主机/VM）符号。

对于 Ubuntu

复制
已复制！

            
            host> sudo tee /etc/apt/sources.list.d/ddebs.list << EOF
deb http://ddebs.ubuntu.com/ $(lsb_release -cs) main restricted universe multiverse
deb http://ddebs.ubuntu.com/ $(lsb_release -cs)-updates main restricted universe multiverse
deb http://ddebs.ubuntu.com/ $(lsb_release -cs)-proposed main restricted universe multiverse
EOF
host> sudo apt install ubuntu-dbgsym-keyring
host> sudo apt-get update
host> sudo apt-get install linux-image-$(uname -r)-dbgsym

对于 CentOS

复制
已复制！

            
            host> yum install --enablerepo=base-debuginfo kernel-devel-$(uname -r) kernel-debuginfo-$(uname -r) kernel-debuginfo-common-$(uname -m)-$(uname -r)

Windows 不需要任何操作

执行 IOMMU 直通。此阶段仅在某些默认未启用 IOMMU 的情况下需要（例如，当主机使用 AMD CPU 时）。
注意
如果不确定是否需要此步骤，请跳过此步骤。仅当 DMA 失败并在 dmesg 中显示类似于以下内容的消息时，才返回到此步骤
复制

已复制！

host> dmesg [ 3839.822897] mlx5_core 0000:81:00.0: AMD-Vi: Event logged [IO_PAGE_FAULT domain=0x0047 address=0x2a0aff8 flags=0x0000]
- 找到您操作系统的 grub 文件（最可能是 /boot/grub/grub.conf、/boot/grub2/grub.cfg 或 /etc/default/grub）并打开它进行编辑。运行
  复制
  
  已复制！
```
            
            host> vim /etc/default/grub
        
```
- 搜索定义 GRUB_CMDLINE_LINUX_DEFAULT 的行，并添加参数 iommu=pt。例如
  复制
  
  已复制！
```
            
            GRUB_CMDLINE_LINUX_DEFAULT="iommu=pt <intel/amd>_iommu=on"
        
```
- 运行
  
  注意
  
  在执行电源循环之前，请确保执行正常关机。
  - 对于 Ubuntu
    复制
    
    已复制！
    
    host> sudo update-grub host> ipmitool power cycle
  - 对于 CentOS
    复制
    
    已复制！
    
    host> grub2-mkconfig -o /boot/grub2/grub.cfg host> ipmitool power cycle
  - 对于 Windows 目标：关闭 Hyper-V 功能。

DOCA App Shield 库使用巨页用于 DMA 缓冲区。因此，用户必须分配 42 个巨页。

运行

复制
已复制！

            
            dpu> nr_huge=$(cat /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages)
     nr_huge=$((42+$nr_huge))
     echo $nr_huge | sudo tee -a /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages

创建 ZIP 和 JSON 文件。运行

复制
已复制！

            
            target-system> cd /opt/mellanox/doca/tools/
target-system> python3 doca_apsh_config.py <pid-of-process-to-monitor> --os <windows/linux> --path <path to dwarf2json executable  or pdbparse-to-json.py>
target-system> cp /opt/mellanox/doca/tools/*.* <shared-folder-with-baremetal>
dpu> scp <shared-folder-with-baremetal>/* <path-to-app-shield-binary>

如果目标系统未安装 DOCA，则可以从 BlueField 复制脚本。

所需的 dwaf2json 和 pdbparse-to-json.py 未随 DOCA 提供。

注意

如果内核和进程 .exe 没有更改，则无需重新执行此步骤。

应用程序执行

YARA 检查应用程序以源代码形式提供。因此，在执行应用程序之前需要进行编译。

应用程序使用说明

复制
已复制！

            
            Usage: doca_yara_inspection [DOCA Flags] [Program Flags]
 
DOCA Flags:
  -h, --help                        Print a help synopsis
  -v, --version                     Print program version information
  -l, --log-level                   Set the (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
  --sdk-log-level                   Set the SDK (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
  -j, --json <path>                 Parse all command flags from an input json file
 
Program Flags:
  -m, --memr <path>                 System memory regions map
  -f, --vuid                        VUID of the System device
  -d, --dma                         DMA device name
  -o, --osym <path>                 System OS symbol map path
  -t, --time <seconds>              Scan time interval in seconds

信息

此用法打印输出可以使用 -h（或 --help）选项打印到命令行

复制
已复制！

            
            ./doca_yara_inspection -h

信息

有关其他信息，请参阅“命令行标志”部分。

在 BlueField 上运行应用程序的 CLI 示例

复制
已复制！

            
            ./doca_yara_inspection -m mem_regions.json -o symbols.json -f MT2125X03335MLNXS0D0F0VF1 -d mlx5_0 -t 3

注意

所有使用的标识符（-f 和 -d 标志）都应与所需设备的标识符匹配。

命令行标志

标志类型	短标志	长标志	描述
通用标志	`h`	`help`	打印帮助概要
	`v`	`version`	打印程序版本信息
	`l`	`log-level`	设置应用程序的日志级别 DISABLE=10 CRITICAL=20 ERROR=30 WARNING=40 INFO=50 DEBUG=60 TRACE=70（需要使用 `TRACE` 日志级别支持进行编译）
	N/A	`sdk-log-level`	设置程序的日志级别 DISABLE=10 CRITICAL=20 ERROR=30 WARNING=40 INFO=50 DEBUG=60 TRACE=70
	`j`	`json`	从输入 JSON 文件解析所有命令标志
程序标志	`m`	`memr`	从主机传输的预生成 `mem_regions.json` 文件的路径
	`f`	`pcif`	暴露给目标系统的 VF/PF 的系统 PCIe 功能供应商唯一标识符 (VUID)。用于 DMA 操作。要获取此参数，请运行复制已复制！ `target-system> lspci -vv \| grep "\[VU\] Vendor specific:"` 示例输出复制已复制！ `[VU] Vendor specific: MT2125X03335MLNXS0D0F0 [VU] Vendor specific: MT2125X03335MLNXS0D0F1` 为连接到目标系统的每个 DPU 打印两个 VUID。第一个是 `pf0` 上的 DPU 的 VUID，第二个是端口 `pf1` 上的 DPU 的 VUID。注意在 DPU 上运行此命令会输出 VUID，中间带有一个额外的“EC”字符串。您必须删除“EC”才能获得正确的 VUID。在 PF0/1 上分配的 VF 的 VUID 是 PF 的 VUID，带有一个额外的后缀 `VF<vf-number>`，其中 `vf-number` 是 VF 索引 +1。例如，对于上面示例中的输出 PF0 VUID = MT2125X03335MLNXS0D0F0 PF1 VUID = MT2125X03335MLNXS0D0F1 PF0 上 VF0 的 VUID = MT2125X03335MLNXS0D0F0VF1 VUID 即使在重置后也持久存在。
	`d`	`dma`	要使用的 DMA 设备名称
	`o`	`osym`	从主机传输的预生成 `symbols.json` 文件的路径
	`t`	`time`	扫描之间休眠的秒数

信息

有关支持的标志和执行模式的更多信息，请参阅 DOCA Arg Parser。

故障排除

有关 DOCA 应用程序的安装或执行中遇到的任何问题，请参阅 DOCA 故障排除。

应用程序代码流程

解析应用程序参数。

初始化参数解析器资源并注册 DOCA 常规参数。

复制
已复制！

            
            doca_argp_init();

注册应用程序参数。

复制
已复制！

            
            register_apsh_params();

解析参数。

复制
已复制！

            
            doca_argp_start();

初始化 DOCA App Shield lib 上下文。

创建 lib 上下文。

复制
已复制！

            
            doca_apsh_create();

为 lib 设置 DMA 设备。

复制
已复制！

            
            open_doca_device_with_ibdev_name();
doca_apsh_dma_dev_set();

启动上下文

复制
已复制！

            
            doca_apsh_start();
apsh_system_init();

初始化 DOCA App Shield lib 系统上下文处理程序。

获取暴露给系统的远程 PCIe 功能的表示。

复制
已复制！

            
            open_doca_device_rep_with_vuid();

创建并启动系统上下文处理程序。

复制
已复制！

            
            doca_apsh_system_create();
doca_apsh_sys_os_symbol_map_set();
doca_apsh_sys_mem_region_set();
doca_apsh_sys_dev_set();
doca_apsh_sys_os_type_set();
doca_apsh_system_start();

遥测初始化。
复制

已复制！
```
            
            telemetry_start();
        
```
1. 初始化新的遥测架构。
2. 注册 YARA 类型事件。
3. 设置输出到文件（除了默认 IPC）。
4. 启动遥测架构。
5. 使用 gethostname() 名称作为源 ID，初始化并启动新的 DTS 源。

循环直到 YARA 规则匹配。

从主机获取所有进程。

复制
已复制！

            
            doca_apsh_processes_get();

检查 YARA 规则识别，如果存在匹配项，则发送 DTS 事件。

复制
已复制！

            
            doca_apsh_yara_get();
if (yara_matches_size != 0) {
	/* event fill logic
	doca_telemetry_exporter_source_report();
DOCA_LOG_INFO();
sleep();

遥测销毁。

复制
已复制！

            
            telemetry_destroy();

YARA 检查清理。

复制
已复制！

            
            doca_apsh_system_destroy();
doca_apsh_destroy();
doca_dev_close();
doca_dev_rep_close();

参数解析器销毁。

复制
已复制！

            
            doca_argp_destroy();

参考

/opt/mellanox/doca/applications/yara_inspection/

本页内容