DOCA App Shield Agent 应用程序指南 - NVIDIA 文档

本指南提供了基于 NVIDIA® BlueField® DPU 的进程内省系统实现。

简介

App Shield Agent 使用 DOCA App Shield 库监控主机系统中的进程。

这种安全功能有助于从独立且可信的 DPU 中识别系统中核心进程的损坏。这是一项主要的创新入侵检测系统 (IDS) 功能，因为它无法从主机内部提供。

The DOCA App Shield Library 提供了直接从 DPU 读取、分析和验证主机（裸机/VM）内存的功能。

使用该库，此应用程序哈希特定进程及其库的不可写内存页（以及未加载的页）。然后，应用程序定期验证已加载的页。

应用程序在每次迭代后报告通过/失败，直到首次证明失败。报告既打印到控制台，也使用进程间通信 (IPC) 导出到 DOCA Telemetry Service (DTS)。

本指南介绍了如何使用 DOCA App Shield 库构建安全进程监控，该库利用了 DPU 的优势，例如基于硬件的 DMA、完整性等。

系统设计

App Shield Agent 旨在 DPU 的 Arm 上独立运行，而不会妨碍主机。

主机的参与仅限于在需要生成必要的 ZIP 和 JSON 文件以传递给 DPU 时，配置对新进程的监控。这在初始阶段（“时间 0”）完成，此时主机仍处于“安全”状态。

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

high-level-diagram-version-1-modificationdate-1734469400997-api-v2.png

应用程序架构

用户使用 DOCA 工具 doca_apsh_config.py 创建三个强制性文件，并将它们复制到 DPU。应用程序可以将证明结果报告给

文件
终端
DTS

app-shield-arch-version-1-modificationdate-1734469401320-api-v2.png

这些文件是通过在主机上针对时间零时的进程运行 doca_apsh_config.py 生成的。

注意

动作 2-5 定期重复。
App Shield Agent 从 DOCA App Shield 库请求新的证明。
DOCA App Shield 库创建一个新的证明
1. 扫描和哈希进程内存页（当前正在使用中）。
2. 将哈希与原始哈希进行比较。
3. 为进程中涉及的每个 lib/exe 创建证明。每个证明都包含有效页数和总页数。
App Shield Agent 搜索每个证明，查找已用页数和有效页数之间的不一致。
App Shield Agent 将带有时间戳和扫描计数的报告结果报告给
1. 本地遥测文件 – 一个文件夹和文件，代表真实的 DTS 将收到的数据。这些文件仅用于本示例的目的，因为通常此数据不会导出到用户可读的文件中。
2. DOCA 日志（没有扫描计数）。
3. DTS IPC 接口（即使没有 DTS 处于活动状态）。
App Shield Agent 在首次证明失败时退出。

DOCA 库

此应用程序利用以下 DOCA 库

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

编译应用程序

信息

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

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

提示

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

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

编译所有应用程序

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

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

复制
已复制！

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

信息

doca_app_shield_agent 在 /tmp/build/app_shield_agent/ 下创建。

仅编译当前应用程序

要仅构建 App Shield Agent 应用程序

复制
已复制！

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

信息

doca_app_shield_agent 在 /tmp/build/app_shield_agent/ 下创建。

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

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

运行以下编译命令

复制
已复制！

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

信息

doca_app_shield_agent 在 /tmp/build/app_shield_agent/ 下创建。

故障排除

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

运行应用程序

先决条件

配置 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]
1. 找到您操作系统的 grub 文件（很可能是 /boot/grub/grub.conf、/boot/grub2/grub.cfg 或 /etc/default/grub）并打开它进行编辑。运行
  复制
  
  已复制！
```
            
            host> vim /etc/default/grub
        
```
2. 搜索定义 GRUB_CMDLINE_LINUX_DEFAULT 的行，并添加参数 iommu=pt。例如
  复制
  
  已复制！
```
            
            GRUB_CMDLINE_LINUX_DEFAULT="iommu=pt <intel/amd>_iommu=on"
        
```
3. 运行
  
  注意
  
  在执行电源循环之前，请务必执行正常关机。
  - 对于 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。

创建 ZIP 和 JSON 文件。运行

复制
已复制！

            
            target-system> cd /opt/mellanox/doca/tools/
target-system> python3 doca_apsh_config.py --pid <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 复制脚本。

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

注意

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

应用程序执行

App Shield Agent 应用程序以源代码形式提供；因此，在执行应用程序之前需要进行编译。

应用程序使用说明

复制
已复制！

            
            Usage: doca_app_shield_agent [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:
  -p, --pid                         Process ID of process to be attested
  -e, --ehm <path>                  Exec hash map path
  -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
  -s, --osty <windows|linux>        System OS type - windows/linux
  -t, --time <seconds>              Scan time interval in seconds

信息

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

复制
已复制！

            
            ./doca_app_shield_agent -h

信息

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

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

复制
已复制！

            
            ./doca_app_shield_agent -p 13577 -e hash.zip -m mem_regions.json -o symbols.json -f MT2125X03335MLNXS0D0F0VF1 -d mlx5_0 -t 3 -s linux

注意

所有使用的标识符（-f、-p 和 -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 文件解析所有命令标志
程序标志	`p`	`pid`	要证明的进程的 PID
	`e`	`ehm`	从主机传输的预生成 `hash.zip` 文件的路径
	`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` 文件的路径
	`s`	`osty`	进程运行的系统的操作系统类型（`windows` 或 `linux`）
	`t`	`time`	扫描之间休眠的秒数

信息

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

故障排除

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

应用程序代码流程

解析应用程序参数。

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

复制
已复制！

            
            doca_argp_init();

注册应用程序参数。

复制
已复制！

            
            register_apsh_params();

解析参数。

复制
已复制！

            
            doca_argp_start();

初始化 DOCA App Shield 库上下文。

创建库上下文。

复制
已复制！

            
            doca_apsh_create();

为库设置 DMA 设备。

复制
已复制！

            
            doca_devinfo_list_create();
doca_dev_open();
doca_devinfo_list_destroy();
doca_apsh_dma_dev_set();

启动上下文

复制
已复制！

            
            doca_apsh_start();
apsh_system_init();

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

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

复制
已复制！

            
            doca_devinfo_remote_list_create();
doca_dev_remote_open();
doca_devinfo_remote_list_destroy();

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

复制
已复制！

            
            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();

通过 pid 查找目标进程。

复制
已复制！

            
            doca_apsh_processes_get();

遥测初始化。
复制

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

获取进程的初始证明。

复制
已复制！

            
            doca_apsh_attestation_get();

循环直到证明验证失败。

复制
已复制！

            
            doca_apsh_attst_refresh();
/* validation logic */
doca_telemetry_exporter_source_report();
DOCA_LOG_INFO();
sleep();

DOCA App Shield Agent 销毁。

复制
已复制！

            
            doca_apsh_attestation_free();
doca_apsh_processes_free();
doca_apsh_system_destroy();
doca_apsh_destroy();
doca_dev_close();
doca_dev_remote_close();

遥测销毁。

复制
已复制！

            
            telemetry_destroy();

参数解析器销毁。

复制
已复制！

            
            doca_argp_destroy();

参考

/opt/mellanox/doca/applications/app_shield_agent/

在本页中