> ## Documentation Index
> Fetch the complete documentation index at: https://hilt.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 事件覆盖与过滤

> macOS 采集器捕获哪些 Apple Endpoint Security 事件，每个事件如何映射到类型化事件，以及用户空间过滤如何将文件打开量削减为与安全相关的数据流。

macOS 采集器（**Hilt EDR** 应用及其 **ESensor** Endpoint Security 系统扩展）订阅 Apple 的 Endpoint Security（ES）框架，并发出一小组固定的类型化事件。与 Linux 采集器不同——后者通过 eBPF 读取原始系统调用跟踪点，必须在内核中丢弃海量数据——ESensor 只接收它显式订阅的 ES 事件类别。因此内核侧的筛选就是 Apple 的 `es_subscribe` 允许列表，而采集器自身的过滤完全发生在用户空间，在事件被序列化为 JSON 行并发送到 [edr-collector](https://hilt.ai/docs/zh/macos-collector/data-flow.md) 之前完成。

传感器发出的每个事件都将**代码签名信任**和**应用归因**作为一等字段携带，因此下面的覆盖范围不仅是"发生了什么"，而是"由谁完成、由谁签名"。完整的字段集参见[事件数据模型](https://hilt.ai/docs/zh/macos-collector/event-data-model.md)。

***

## 事件覆盖

ESensor 订阅 **12 种 Apple Endpoint Security 事件类型**外加一个网络流来源，并向 `endpoint_events` 表发出 **12 个类型化事件**。每一行都标注了 `event_class`（process、file、persistence、device、network）和 `event_type`。

| `event_type` | Apple ES event | `event_class` | 捕获内容 |
| :- | :- | :- | :- |
| `exec` | `NOTIFY_EXEC` | process | 进程生成，携带完整 `argv`、代码签名标识（`signing_id`、`team_id`、`code_signature`）以及二进制的 `cdhash` |
| `fork` | `NOTIFY_FORK` | process | 进程 fork（父进程 → 子进程），用于构建进程树 |
| `signal` | `AUTH_SIGNAL` | process | 发送给进程的信号（kill 尝试）；携带目标 pid 和信号编号。以 **AUTH** 方式订阅，使传感器还能拒绝对自身的篡改 |
| `file_open` | `NOTIFY_OPEN` / `NOTIFY_CREATE` | file | 文件打开或创建，携带 `filename` 和打开 `flags`。**按量占主导（约 95%）** |
| `file_unlink` | `AUTH_UNLINK` | file | 文件删除。以 AUTH 方式订阅以实现传感器自我保护；仍发出等同于 NOTIFY 的遥测 |
| `file_rename` | `AUTH_RENAME` | file | 文件重命名，携带源 `filename` 和 `dest_path`。同样以 AUTH 方式实现自我保护 |
| `file_chmod` | `NOTIFY_SETMODE` | file | 权限变更（chmod），携带新的 `mode` |
| `xattr_set` | `NOTIFY_SETEXTATTR` | file | 扩展属性设置——**Gatekeeper 隔离**篡改的信号；携带 `xattr_name` |
| `xattr_delete` | `NOTIFY_DELETEEXTATTR` | file | 扩展属性删除——移除隔离（绕过 Gatekeeper） |
| `mount` | `NOTIFY_MOUNT` | device | 文件系统挂载——可移动介质和磁盘映像；携带挂载路径和可移动标志 |
| `btm_add` | `NOTIFY_BTM_LAUNCH_ITEM_ADD` | persistence | 注册了 launch agent、守护进程或登录项——**已安装持久化**。使用 macOS 13+ 的 Background Task Management；携带项类型、项路径和托管标志 |
| `net_flow` | NetworkExtension / lsof | network | 出站 TCP 流，携带目标地址和端口、字节计数、方向以及负责应用的 `bundle_id` |

> [!NOTE]
>
> `xattr_delete` 和 `mount` 是真实但**罕见**的事件（移除隔离、USB 或 DMG 挂载）。它们被持续订阅并发出——只是在安静时段你不会看到它们。`btm_add` 同样是低量但高信号：单独一行就可能意味着安装了新的持久化机制。

### 网络流

`net_flow` 是唯一不源自 ES `NOTIFY` 回调的事件。ES 不暴露逐流的网络遥测，因此传感器使用 Apple 的 **NetworkExtension** 内容过滤扩展（**NetFilter**，bundle id `Hilt.EDRApp.NetFilter`）进行逐流归因，并以基于 `lsof` 的轮询器作为始终可用的回退。因此网络流携带与其他所有事件相同的代码签名和应用归因：负责应用的 bundle id、签名标识以及 Mac 设备名。出站模型参见[网络与安全](https://hilt.ai/docs/zh/macos-collector/networking-security.md)。

***

## 哪些内容会被过滤

在一台典型的 Mac 上，`file_open` 大约占**总事件量的 95%**——打开文件是应用整天都在做的事，而其中绝大多数打开是框架加载、字体和区域设置读取、缓存翻搅以及无治理价值的偏好设置 plist 读取。采集器应用**激进的用户空间过滤**，在任何数据离开主机之前将其削减为与安全相关的数据流。

| 类别 | 示例 | 过滤原因 |
| :- | :- | :- |
| **操作系统日常维护打开** | 框架和 dylib 加载、字体和区域设置读取、`~/Library/Caches` 翻搅、偏好设置 plist 读取 | 量极高，无安全信号 |
| **自身事件** | 传感器和转发器自身的文件和网络 I/O | 防止反馈循环 |
| **内部网络流** | 环回和链路本地连接；仅保留**外部**目标 | 仅内部的流量与治理无关 |
| **平台二进制噪声** | 可归因于 Apple 平台二进制的高翻搅读取 | 产生量的系统组件已被充分了解 |

由于每个事件到达时都已预先归因，过滤器可以基于**代码签名**和**应用**而非仅凭路径做决策——例如，抑制来自 Apple 平台二进制的常规读取，同时始终保留来自 `unsigned_or_invalid` 或 `adhoc` 签名进程的读取。

### 仅外部的网络流

网络遥测**按设计仅捕获外部**：NetworkExtension 提供程序和 `lsof` 轮询器都只报告发往主机之外目标的出站流。环回（`127.0.0.0/8`、`::1`）和链路本地流量绝不会被发出。这使 `net_flow` 聚焦于实际的出站流量——数据离开 Mac 之处——而不受主导桌面环境的高量本地主机 IPC 喧闹影响。

***

## 哪些内容绝不会被过滤

某些事件类别无论来源如何都会绕过量过滤，因为它们的安全价值不取决于行为者：

* **所有进程执行**（`exec`）：采集器始终记录执行了什么，包括来自平台二进制和已签名应用的执行。`argv`、`cdhash` 和签名标识始终被捕获。
* **所有持久化事件**（`btm_add`）：安装 launch agent、守护进程或登录项始终会被记录——这是 macOS 的持久化原语。
* **所有篡改信号**（`xattr_set`、`xattr_delete`、`signal`）：隔离属性变更和 kill 尝试绝不会被丢弃，包括针对传感器自身的那些。
* **外部网络流**（`net_flow`）：发往主机外目标的每一个出站流都会被保留，并带有完整的应用归因。
* **敏感路径访问**：即使同一路径类别在其他情况下会很嘈杂，对凭据文件、SSH 密钥、令牌以及安全相关配置的打开也会被保留。

这正是 macOS 差异化优势的体现所在。由于信任和归因被打在每一行上，像\*"哪个 `unsigned_or_invalid` 应用读取了 `~/.ssh`"\*这样的查询在 `endpoint_events` 上就是单个 `WHERE` 子句——这是 Linux 采集器无法构造的表达式，因为它没有逐事件的代码签名裁定。

***

## 它不做什么

* **无内核扩展。** ESensor 是运行在 Apple 现代框架之上的纯用户空间 ES 系统扩展。没有 kext，也不需要 `csrutil disable`——采集器在[启用 System Integrity Protection](https://hilt.ai/docs/zh/macos-collector/networking-security.md) 的情况下运行。
* **无内容检查。** 过滤仅基于元数据运作——路径类别、代码签名、应用 id、目标——绝不基于文件或数据包内容。
* **无 DNS 名称或负载。** NetworkExtension 内容过滤路径提供五元组、字节计数、方向和负责应用，但不提供 DNS 查询名称或解密后的负载。
* **无入站捕获。** 只观测出站流；传感器不打开任何入站套接字，转发器只向配置的接入端点发起出站 HTTPS。
* **无 `WRITE`/`ACCESS`/`STAT`/`LOOKUP` 海量数据。** 这些 ES 事件类别被刻意不订阅；`file_open` 加上 `file_chmod`/`file_rename`/`file_unlink` 以极小的量覆盖了文件活动。

***

## 路线图挂钩（尚未启用）

Apple 的 Endpoint Security 框架暴露了 100 多种 `NOTIFY` 事件类型。采集器目前刻意只订阅一个很小的子集；以下被确定为高价值的后续新增项，但**当前不发出到遥测**：

| Apple ES event | macOS | 会增加什么 |
| :- | :- | :- |
| `NOTIFY_EXIT` | 10.15 | 进程结束——启用退出时间戳、持续时长以及干净的进程树完成 |
| `NOTIFY_SETUID`（以及 `SETGID`/`SETEUID`/…） | 13.0 | 权限变更 / 提权信号 |
| `NOTIFY_GET_TASK`（以及 `GET_TASK_READ`/`_NAME`/`_INSPECT`） | 10.15 | task-port 访问——进程**注入**和调试的核心指标 |
| `NOTIFY_MMAP` / `NOTIFY_MPROTECT` | 10.15 | 内存映射和 `RWX` 保护变更——shellcode 和**代码注入**检测（MMAP 量高，需要激进的非平台二进制过滤） |
| `NOTIFY_TCC_MODIFY` | 15.4 | 隐私权限授予（摄像头、麦克风、屏幕录制、完全磁盘访问、辅助功能） |
| DNS 可见性 | — | `NEDNSProxyProvider` 会暴露 DNS 查询和应答——超越当前五元组流的域级网络可见性 |

> [!NOTE]
>
> ES 可用性在订阅时受限：订阅一个宿主 macOS 版本不支持的事件类型，只会导致该单一类型失败，而非整个客户端。这就是为什么 `btm_add`（macOS 13+ 的 Background Task Management）以及任何未来的 `TCC_MODIFY`（macOS 15.4+）挂钩会在较旧的宿主上优雅降级，而不会破坏传感器。采集器要求 **macOS 15.0（Sequoia）或更高版本**，因此上表中的每个事件在所有受支持的主机上均可用；各事件标注的版本是操作系统 API 的可用版本，而非支持下限。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.