跳转到内容

std.os.linux.seccomp

标准库Zig 0.17.1官方原文
源码std/os/linux/seccomp.zig

第 1 行

Linux 内核安全计算机制的相关接口,使进程能够限制对系统调用接口的访问。

Seccomp 最初仅有“严格”模式,只允许调用 read(2)、write(2)、_exit(2) 和 sigreturn(2)。由于这种模式对通用应用程序的实用性有限,后来增加了使用用户自定义过滤器的模式。

Seccomp 过滤器是经典 BPF 程序。从概念上说,seccomp 程序附加到内核,并在每次系统调用时执行。接受校验的“数据包”是 data 结构,判定结果则是内核对调用进程采取的操作。这些操作都是“通过”或“失败”结果的变体:通过允许系统调用继续执行,失败则阻止调用并返回某种错误值。完整操作列表见 ::RET。仅支持字长大小的绝对加载指令(ld [k])以读取 data 结构。

过滤器接口的一些问题长期以来使编写过滤器十分困难:

  1. Linux 支持的每种处理器架构都有各自的 ABI 和系统调用接口。不同架构的系统调用编号、参数乃至是否实现该调用都没有一致性保证。因此,若未查阅 syscalls(2) 等文档并在目标硬件上测试,就不能假设过滤器可移植。还必须检查 data.arch,确认过滤器是为正确架构编译的。
  2. 许多系统调用接受 unsigned long 或 size_t 参数,其大小取决于 ABI。由于 BPF 程序在 32 位机器上执行,校验 64 位参数需要分别针对高、低字执行两组加载与比较指令。
  3. 字节序进一步增加了复杂性。系统调用数据与网络数据包不同,采用目标机器的字节序。小端机器上编译的过滤器不能在大端机器上工作,反之亦然。例如,检查 data.arg1 的高 32 位时,大端系统需要从 @offsetOf(data, "arg1") + 4 加载,小端系统则从 @offsetOf(data, "arg1") 加载。要使过滤器跨字节序移植,必须在编译期调整这些偏移量,类似 OpenSSH 的处理方式[1]。
  4. 通过 vDSO 在用户空间实现的系统调用无法被跟踪或过滤。可以禁用或忽略 vDSO,但编写过滤器时必须考虑这一点。
  5. 软件库,尤其是动态加载的库,往往会随着时间使用更多系统调用,因此过滤器也必须随之演进。调用这些库的新版本代码时,静态过滤器可能导致功能受限乃至失效。glibc 等关键库已有此类问题[2]。

借助 Zig 和标准库可以缓解部分问题。由于目标处理器在编译期已知,正确的系统调用编号会混入 os 命名空间中的 std.os.SYS(参见 arch_bits,位于 os/linux.zig)。引用未实现的系统调用会导致编译错误。字节序相关偏移量也可以仿照 OpenSSH 的示例定义:

const offset = if (native_endian == .little) struct {
    pub const low = 0;
    pub const high = @sizeOf(u32);
} else struct {
    pub const low = @sizeOf(u32);
    pub const high = 0;
};

遗憾的是,问题 5 没有简单的解决方案。最可靠的策略是持续测试较新的 Zig 版本、不同 libc 和不同发行版,并设计能够兼容它们的过滤器。另一种方式是在运行时注入过滤器。由于过滤器在 execve(2) 后仍然保留,可以在执行程序前设置过滤器,而程序无需知道这一过程。systemd[3] 和 Cloudflare 的沙箱库[4] 就采用这种方式。

[1]: https://github.com/openssh/openssh-portable/blob/master/sandbox-seccomp-filter.c#L81 [2]: https://sourceware.org/legacy-ml/libc-alpha/2017-11/msg00246.html [3]: https://www.freedesktop.org/software/systemd/man/systemd.exec.html#SystemCallFilter= [4]: https://github.com/cloudflare/sandbox

另见

std.os.linux.seccomp.ADDFD_FLAG

命名空间

第 148 行

参见 seccomp_unotify(2)。

std.os.linux.seccomp.ADDFD_FLAG.SEND

常量

第 150 行

std.os.linux.seccomp.ADDFD_FLAG.SETFD

常量

第 149 行

std.os.linux.seccomp.data

容器

第 153 行

字段

nr: c_int

系统调用编号。

arch: u32

CPU 架构及系统调用约定。 取值为 std.os.linux.AUDIT 中定义的值之一。

instruction_pointer: u64
arg0: u64
arg1: u64
arg2: u64
arg3: u64
arg4: u64
arg5: u64

std.os.linux.seccomp.FILTER_FLAG

命名空间

第 101 行

SET_MODE_FILTER 操作的位标志。

std.os.linux.seccomp.FILTER_FLAG.LOG

常量

第 103 行

std.os.linux.seccomp.FILTER_FLAG.NEW_LISTENER

常量

第 105 行

std.os.linux.seccomp.FILTER_FLAG.SPEC_ALLOW

常量

第 104 行

std.os.linux.seccomp.FILTER_FLAG.TSYNC

常量

第 102 行

std.os.linux.seccomp.FILTER_FLAG.TSYNC_ESRCH

常量

第 106 行

std.os.linux.seccomp.GET_ACTION_AVAIL

常量

第 97 行

std.os.linux.seccomp.GET_NOTIF_SIZES

常量

第 98 行

std.os.linux.seccomp.IOCTL

别名

第 82 行

别名目标 std.os.linux.ioctl

std.os.linux.seccomp.IOCTL_NOTIF

命名空间

第 137 行

std.os.linux.seccomp.IOCTL_NOTIF.ADDFD

常量

第 141 行

std.os.linux.seccomp.IOCTL_NOTIF.ID_VALID

常量

第 140 行

std.os.linux.seccomp.IOCTL_NOTIF.RECV

常量

第 138 行

std.os.linux.seccomp.IOCTL_NOTIF.SEND

常量

第 139 行

std.os.linux.seccomp.MODE

命名空间

第 85 行

std.os.linux.seccomp.MODE.DISABLED

常量

第 87 行

未使用 Seccomp。

std.os.linux.seccomp.MODE.FILTER

常量

第 91 行

使用用户提供的过滤器。

std.os.linux.seccomp.MODE.STRICT

常量

第 89 行

使用硬编码过滤器。

std.os.linux.seccomp.notif

容器

第 179 行

字段

id: u64

每个过滤器唯一的通知 cookie。

pid: u32

触发通知的线程 ID。

flags: u32

事件信息位掩码。目前设为零。

data: data

当前系统调用数据。

std.os.linux.seccomp.notif_addfd

容器

第 204 行

字段

id: u64
flags: u32
srcfd: u32
newfd: u32
newfd_flags: u32

std.os.linux.seccomp.notif_resp

容器

第 191 行

监督进程发给内核的决策载荷。

字段

id: u64

筛选器 cookie。

val: i64

伪造系统调用的返回值。

@"error": i32

设为零以伪造成功,或设为负错误编号以表示失败。

flags: u32

包含决策的位掩码。USER_NOTIF_FLAG_CONTINUE 表示允许系统调用,零表示伪造返回值。

std.os.linux.seccomp.notif_sizes

容器

第 170 行

与 ::GET_NOTIF_SIZES 命令配合使用,用于检查内核结构是否已更改。

字段

notif: u16

::notif 的大小。

notif_resp: u16

::resp 的大小。

data: u16

::data 的大小。

std.os.linux.seccomp.RET

命名空间

第 112 行

seccomp BPF 程序的动作值。 低 16 位用于可选返回数据。 高 16 位按允许程度从低到高排序。

std.os.linux.seccomp.RET.ACTION

常量

第 133 行

std.os.linux.seccomp.RET.ACTION_FULL

常量

第 132 行

std.os.linux.seccomp.RET.ALLOW

常量

第 129 行

允许。

std.os.linux.seccomp.RET.DATA

常量

第 134 行

std.os.linux.seccomp.RET.ERRNO

常量

第 121 行

返回 errno。

std.os.linux.seccomp.RET.KILL

别名

第 117 行

别名目标 std.os.linux.seccomp.RET.KILL_THREAD

std.os.linux.seccomp.RET.KILL_PROCESS

常量

第 114 行

终止进程。

std.os.linux.seccomp.RET.KILL_THREAD

常量

第 116 行

终止线程。

std.os.linux.seccomp.RET.LOG

常量

第 127 行

记录日志后允许。

std.os.linux.seccomp.RET.TRACE

常量

第 125 行

交给跟踪器,或禁止。

std.os.linux.seccomp.RET.TRAP

常量

第 119 行

禁止并强制触发 SIGSYS。

std.os.linux.seccomp.RET.USER_NOTIF

常量

第 123 行

将系统调用转发给用户空间监督程序,以作决定。

std.os.linux.seccomp.SET_MODE_FILTER

常量

第 96 行

std.os.linux.seccomp.SET_MODE_STRICT

常量

第 95 行

std.os.linux.seccomp.USER_NOTIF_FLAG_CONTINUE

常量

第 145 行

告知内核,监督程序允许此系统调用继续执行。

源码

std/os/linux/seccomp.zig

//! Linux 内核安全计算机制的相关接口,使进程能够限制对系统调用接口的访问。
//!
//! Seccomp 最初仅有“严格”模式,只允许调用 read(2)、write(2)、_exit(2) 和 sigreturn(2)。由于这种模式对通用应用程序的实用性有限,后来增加了使用用户自定义过滤器的模式。
//!
//! Seccomp 过滤器是经典 BPF 程序。从概念上说,seccomp 程序附加到内核,并在每次系统调用时执行。接受校验的“数据包”是 `data` 结构,判定结果则是内核对调用进程采取的操作。这些操作都是“通过”或“失败”结果的变体:通过允许系统调用继续执行,失败则阻止调用并返回某种错误值。完整操作列表见 ::RET。仅支持字长大小的绝对加载指令(`ld [k]`)以读取 `data` 结构。
//!
//! 过滤器接口的一些问题长期以来使编写过滤器十分困难:
//!
//! 1. Linux 支持的每种处理器架构都有各自的 ABI 和系统调用接口。不同架构的系统调用编号、参数乃至是否实现该调用都没有一致性保证。因此,若未查阅 syscalls(2) 等文档并在目标硬件上测试,就不能假设过滤器可移植。还必须检查 `data.arch`,确认过滤器是为正确架构编译的。
//! 2. 许多系统调用接受 `unsigned long` 或 `size_t` 参数,其大小取决于 ABI。由于 BPF 程序在 32 位机器上执行,校验 64 位参数需要分别针对高、低字执行两组加载与比较指令。
//! 3. 字节序进一步增加了复杂性。系统调用数据与网络数据包不同,采用目标机器的字节序。小端机器上编译的过滤器不能在大端机器上工作,反之亦然。例如,检查 `data.arg1` 的高 32 位时,大端系统需要从 `@offsetOf(data, "arg1") + 4` 加载,小端系统则从 `@offsetOf(data, "arg1")` 加载。要使过滤器跨字节序移植,必须在编译期调整这些偏移量,类似 OpenSSH 的处理方式[1]。
//! 4. 通过 vDSO 在用户空间实现的系统调用无法被跟踪或过滤。可以禁用或忽略 vDSO,但编写过滤器时必须考虑这一点。
//! 5. 软件库,尤其是动态加载的库,往往会随着时间使用更多系统调用,因此过滤器也必须随之演进。调用这些库的新版本代码时,静态过滤器可能导致功能受限乃至失效。glibc 等关键库已有此类问题[2]。
//!
//! 借助 Zig 和标准库可以缓解部分问题。由于目标处理器在编译期已知,正确的系统调用编号会混入 `os` 命名空间中的 `std.os.SYS`(参见 `arch_bits`,位于 `os/linux.zig`)。引用未实现的系统调用会导致编译错误。字节序相关偏移量也可以仿照 OpenSSH 的示例定义:
//!
//! ```zig
//! const offset = if (native_endian == .little) struct {
//!     pub const low = 0;
//!     pub const high = @sizeOf(u32);
//! } else struct {
//!     pub const low = @sizeOf(u32);
//!     pub const high = 0;
//! };
//! ```
//!
//! 遗憾的是,问题 5 没有简单的解决方案。最可靠的策略是持续测试较新的 Zig 版本、不同 libc 和不同发行版,并设计能够兼容它们的过滤器。另一种方式是在运行时注入过滤器。由于过滤器在 execve(2) 后仍然保留,可以在执行程序前设置过滤器,而程序无需知道这一过程。systemd[3] 和 Cloudflare 的沙箱库[4] 就采用这种方式。
//!
//! [1]: https://github.com/openssh/openssh-portable/blob/master/sandbox-seccomp-filter.c#L81
//! [2]: https://sourceware.org/legacy-ml/libc-alpha/2017-11/msg00246.html
//! [3]: https://www.freedesktop.org/software/systemd/man/systemd.exec.html#SystemCallFilter=
//! [4]: https://github.com/cloudflare/sandbox
//!
//! 另见
//! - seccomp(2)、seccomp_unotify(2)
//! - https://www.kernel.org/doc/html/latest/userspace-api/seccomp_filter.html
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
const IOCTL = @import("ioctl.zig");

// prctl(2) 形式 `prctl(PR_SET_SECCOMP, mode)` 的模式。
pub const MODE = struct {
    /// 未使用 Seccomp。
    pub const DISABLED = 0;
    /// 使用硬编码过滤器。
    pub const STRICT = 1;
    /// 使用用户提供的过滤器。
    pub const FILTER = 2;
};

// seccomp(2) 形式 `seccomp(operation, flags, args)` 的操作
pub const SET_MODE_STRICT = 0;
pub const SET_MODE_FILTER = 1;
pub const GET_ACTION_AVAIL = 2;
pub const GET_NOTIF_SIZES = 3;

/// SET_MODE_FILTER 操作的位标志。
pub const FILTER_FLAG = struct {
    pub const TSYNC = 1 << 0;
    pub const LOG = 1 << 1;
    pub const SPEC_ALLOW = 1 << 2;
    pub const NEW_LISTENER = 1 << 3;
    pub const TSYNC_ESRCH = 1 << 4;
};

/// seccomp BPF 程序的动作值。
/// 低 16 位用于可选返回数据。
/// 高 16 位按允许程度从低到高排序。
pub const RET = struct {
    /// 终止进程。
    pub const KILL_PROCESS = 0x80000000;
    /// 终止线程。
    pub const KILL_THREAD = 0x00000000;
    pub const KILL = KILL_THREAD;
    /// 禁止并强制触发 SIGSYS。
    pub const TRAP = 0x00030000;
    /// 返回 errno。
    pub const ERRNO = 0x00050000;
    /// 将系统调用转发给用户空间监督程序,以作决定。
    pub const USER_NOTIF = 0x7fc00000;
    /// 交给跟踪器,或禁止。
    pub const TRACE = 0x7ff00000;
    /// 记录日志后允许。
    pub const LOG = 0x7ffc0000;
    /// 允许。
    pub const ALLOW = 0x7fff0000;

    // 返回值各部分的掩码。
    pub const ACTION_FULL = 0xffff0000;
    pub const ACTION = 0x7fff0000;
    pub const DATA = 0x0000ffff;
};

pub const IOCTL_NOTIF = struct {
    pub const RECV = IOCTL.IOWR('!', 0, notif);
    pub const SEND = IOCTL.IOWR('!', 1, notif_resp);
    pub const ID_VALID = IOCTL.IOW('!', 2, u64);
    pub const ADDFD = IOCTL.IOW('!', 3, notif_addfd);
};

/// 告知内核,监督程序允许此系统调用继续执行。
pub const USER_NOTIF_FLAG_CONTINUE = 1 << 0;

/// 参见 seccomp_unotify(2)。
pub const ADDFD_FLAG = struct {
    pub const SETFD = 1 << 0;
    pub const SEND = 1 << 1;
};

pub const data = extern struct {
    /// 系统调用编号。
    nr: c_int,
    /// CPU 架构及系统调用约定。
    /// 取值为 `std.os.linux.AUDIT` 中定义的值之一。
    arch: u32,
    instruction_pointer: u64,
    arg0: u64,
    arg1: u64,
    arg2: u64,
    arg3: u64,
    arg4: u64,
    arg5: u64,
};

/// 与 ::GET_NOTIF_SIZES 命令配合使用,用于检查内核结构是否已更改。
///
pub const notif_sizes = extern struct {
    /// ::notif 的大小。
    notif: u16,
    /// ::resp 的大小。
    notif_resp: u16,
    /// ::data 的大小。
    data: u16,
};

pub const notif = extern struct {
    /// 每个过滤器唯一的通知 cookie。
    id: u64,
    /// 触发通知的线程 ID。
    pid: u32,
    /// 事件信息位掩码。目前设为零。
    flags: u32,
    /// 当前系统调用数据。
    data: data,
};

/// 监督进程发给内核的决策载荷。
pub const notif_resp = extern struct {
    /// 筛选器 cookie。
    id: u64,
    /// 伪造系统调用的返回值。
    val: i64,
    /// 设为零以伪造成功,或设为负错误编号以表示失败。
    ///
    @"error": i32,
    /// 包含决策的位掩码。USER_NOTIF_FLAG_CONTINUE 表示允许系统调用,零表示伪造返回值。
    ///
    flags: u32,
};

pub const notif_addfd = extern struct {
    id: u64,
    flags: u32,
    srcfd: u32,
    newfd: u32,
    newfd_flags: u32,
};