> ## 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.

# 安装流程（独立安装）

> 从已公证的 .pkg 安装 Hilt macOS 采集器：端到端完成扩展批准与 Full Disk Access，且始终保持 System Integrity Protection 启用。

本页介绍 Hilt macOS 采集器的**独立**安装方式——即直接下载路径：在未加入 MDM 的 Mac 上运行单个已公证的 `.pkg`。这是个人用户（或评估者）手动完成一次的体验。

整个设置过程为**一次安装加两次授权**：先批准系统扩展，再授予 Full Disk Access。无需 Terminal，无需 `csrutil`，无需开发者模式。若需要可同时省去这两次授权的零点击主机群路径，请参阅[通过 MDM 部署](https://hilt.ai/docs/zh/macos-collector/deploy-mdm.md)。

> [!NOTE]
>
> 在整个流程中，**System Integrity Protection (SIP) 始终保持启用**。该采集器是一个经过公证、以 Developer ID 签名的应用，其 Endpoint Security 扩展携带一份 Apple 颁发的预置描述文件，授权 `com.apple.developer.endpoint-security.client` entitlement。由于该 entitlement 是以合法方式授权的，你永远无需运行 `csrutil disable`，也无需启用开发者模式。目标 Mac 始终保持完全加固状态。

## What gets installed

采集器以单个组件形式交付：**Hilt EDR**（`EDRApp.app`，由团队 Cybe Corporation 签名，Team ID `MVMB6LCP2A`）。该应用内嵌两个 Apple 系统扩展——**不含内核扩展 (kext)**。

| Item | Identifier | Role |
| :- | :- | :- |
| Hilt EDR 应用 | `Hilt.EDRApp` | 宿主应用；负责激活系统扩展 |
| ESensor（ES 扩展） | `Hilt.EDRApp.ESensor` | Endpoint Security 遥测传感器——进程 / 文件 / 网络 / 持久化事件 |
| NetFilter（网络扩展） | `Hilt.EDRApp.NetFilter` | `NEFilterDataProvider` 内容过滤器，用于按流进行网络归因 |
| Forwarder LaunchDaemon | — | 通过出站 HTTPS 将 ESensor 的 JSON 行事件发送到 Hilt `edr-collector` |

运行 `.pkg` 后：

| Path | Purpose |
| :- | :- |
| `/Applications/EDRApp.app` | 已公证的 Hilt EDR 应用及其内嵌的系统扩展 |
| Forwarder LaunchDaemon | 一个小型 launchd 作业，读取 ESensor 的事件流并通过 HTTPS 发送 |

`.pkg` 本身已公证，并以 Developer ID Installer 证书签名，因此 Gatekeeper 会在无任何警告的情况下接受它。

## Install procedure

**1. Run the notarized .pkg**

双击 `.pkg`，并在提示时以管理员密码进行身份验证。安装程序会将 **`EDRApp.app`** 放入 `/Applications`，并注册 forwarder LaunchDaemon。

由于软件包已公证并已装订（stapled），Gatekeeper 不会弹出任何“无法验证开发者”或恶意软件警告。安装无需重启。

**2. Launch the app — it requests the system extension**

从 `/Applications` 中打开一次 **Hilt EDR**。首次启动时，应用会提交一个 `OSSystemExtensionRequest` 以激活 ESensor Endpoint Security 扩展，macOS 随即弹出系统提示，告知该扩展已被阻止并需要批准。

在该提示上点击 **Open System Settings**（或 **Allow**）。应用会保持激活请求处于待定状态，直到你完成下一步。

**3. Approve the Endpoint Security extension**

前往 **System Settings → General → Login Items & Extensions → Endpoint Security Extensions**，启用 **ESensor**，并进行身份验证。

这是一道适用于*每一款*第三方 Endpoint Security 产品的 Apple 安全关卡——在没有 MDM 的情况下无法通过点击省去。一旦批准，该扩展即被允许加载。

**4. Grant Full Disk Access to ESensor**

前往 **System Settings → Privacy & Security → Full Disk Access**，为 **ESensor** 条目启用开关（显示为 *ESensor* / **"Hilt EDR Sensor"**）。完成上一步后，它会自动出现在此列表中。

> [!NOTE]
>
> Full Disk Access 条目名为 **ESensor / "Hilt EDR Sensor"**，*而非* "EDRApp"——请为该条目开启开关。Full Disk Access 是任何 Endpoint Security 客户端的硬性要求（参见下文的 [Full Disk Access](#why-full-disk-access-is-required)）。

这就是全部用户体验：**批准一次，开启 Full Disk Access 一次。** 无需更改 SIP，无需开发者模式，无需 Terminal。

## Why Full Disk Access is required

Endpoint Security 客户端在订阅事件之前，必须通过两道相互独立的运行时关卡。它们很容易混淆，因此请务必区分清楚：

| Gate | What it checks | Failure if unmet |
| :- | :- | :- |
| **Entitlement** | 内嵌的预置描述文件授权 ES entitlement（由 SIP 下的 AMFI 强制执行） | `es_new_client()` 返回 `ES_NEW_CLIENT_RESULT_ERR_NOT_ENTITLED` |
| **Full Disk Access** | 宿主进程拥有 TCC Full Disk Access | `es_new_client()` 返回 `ES_NEW_CLIENT_RESULT_ERR_NOT_PERMITTED` |

经过公证并正确签名的采集器始终能通过第一道关卡。第二道关卡是 **Full Disk Access**，在独立流程中需由你（用户）完成。在 ESensor 获得 Full Disk Access 之前，`es_new_client()` 会以 `ES_NEW_CLIENT_RESULT_ERR_NOT_PERMITTED` 失败。

ESensor 的设计能够自动从此情形中恢复。当它遇到 `ERR_NOT_PERMITTED` 时会**退出**，`launchd` 会在数秒后将其重新启动。因此，如果你在授予 Full Disk Access 之前启动应用，该扩展只会循环重启，直到你打开开关——此时*下一次*重启便会成功，事件随即开始流动。**在授予 Full Disk Access 之后，你无需重启应用或 Mac。**

> [!NOTE]
>
> 这正是安装步骤以 Full Disk Access 结尾的原因。顺序很宽容——放在最后授予也没问题——但在该开关打开之前，传感器不会发送任何遥测。

## SIP, notarization, and the sandbox

该构建的三项特性使其能够在一台正常、加固的 Mac 上运行：

* **SIP 保持启用。** ES 扩展位于一个已签名的 bundle 中，该 bundle 携带 Apple 颁发的预置描述文件，将 Endpoint Security entitlement 列入允许列表，因此在 SIP 开启的情况下，内核的可信执行层 (AMFI) 依然承认该 entitlement。无需 `csrutil disable`，无需 `systemextensionsctl developer on`。
* **已公证并已装订。** 应用、其扩展以及 `.pkg` 均以 Developer ID 证书签名，使用 Hardened Runtime，并经 Apple 公证 + 装订。公证满足 Gatekeeper 的恶意软件/签名检查——它*并非*激活扩展的环节。扩展仍需被批准（步骤 3）或由 MDM 预先批准。
* **ES 扩展不使用 App Sandbox。** Endpoint Security 扩展**绝不能**使用 App Sandbox；无论 Full Disk Access 状态如何，被沙盒化的宿主进程都会导致 `es_new_client()` 以 `ERR_NOT_PERMITTED` 失败。

## Verification — what you see once it is running

当扩展获得批准且 Full Disk Access 被授予后，ESensor 会连接其 Endpoint Security 客户端，forwarder 随即开始发送事件。你可以在主机上和仪表盘中确认安装情况：

**在 Mac 上：**

* **System Settings → General → Login Items & Extensions → Endpoint Security Extensions** 显示 **ESensor** 已启用。
* **System Settings → Privacy & Security → Full Disk Access** 显示 **ESensor / "Hilt EDR Sensor"** 开关已打开。
* ESensor 扩展稳定运行（无重启循环），表示 `es_new_client()` 已成功——既无 `ERR_NOT_ENTITLED` 也无 `ERR_NOT_PERMITTED`。

**在 Hilt 仪表盘中：**

该主机会出现在 **Collectors** 主机群视图中，带有 **macOS** 主机类型徽章，其活动会流入 **Investigate**、**Networks**、**Files** 和 **Users** 视图。事件到达时会带有 Linux 采集器无法生成的、macOS 特有的一等字段——代码签名判定（`platform` / `developer_id` / `adhoc` / `unsigned_or_invalid`）、`signing_id`、`team_id` 和 `cdhash`，以及应用归因（`application_id`、`application_display_name`、`responsible_pid`、`session_id`、`device_name`）。完整 schema 请参阅[事件数据模型](https://hilt.ai/docs/zh/macos-collector/event-data-model.md)。

在仪表盘背后，路径为：

```text theme={null}
ESensor (JSON lines) -> forwarder LaunchDaemon -> outbound HTTPS -> edr-collector
  -> MSK (dag.endpoint.exec/file/net) -> enrichment (ENRICH_PLATFORM=macos) -> ClickHouse endpoint_events
```

完整管道请参阅[数据流](https://hilt.ai/docs/zh/macos-collector/data-flow.md)。

## What this install does NOT do

* **不会禁用 System Integrity Protection。** 全程无 `csrutil disable`，无 Recovery 启动，无开发者模式。
* **不会安装内核扩展。** 该采集器是完全运行于用户空间、基于 Apple 现代框架的系统扩展。
* **不会打开任何入站套接字，也不会“phone home”。** forwarder 仅向配置的接入端点发起出站 HTTPS。不存在任何入站监听器。
* **不会读取文件内容。** ESensor 采集事件元数据（路径、操作、签名身份、归因）——而非所涉文件的字节内容。
* **不会自动更新。** 在早期访问期间，升级通过重新运行已公证的 `.pkg` 完成；macOS 上尚不提供设备端自动更新。

## Requirements

| Requirement | Detail |
| :- | :- |
| **macOS version** | 15.0 (Sequoia) 或更高——安装脚本与 pkg 的 `preinstall` 脚本在低于 15.0 时会直接失败 |
| **Architecture** | 通用：Apple Silicon 与 Intel |
| **Privileges** | 一次管理员身份验证以运行 `.pkg`；一次用户身份验证以批准扩展 |
| **Network** | 通往你所配置 Hilt 接入端点的出站 HTTPS |
| **MDM** | 独立路径无需 MDM；零点击主机群安装请参阅[通过 MDM 部署](https://hilt.ai/docs/zh/macos-collector/deploy-mdm.md) |

> [!NOTE]
>
> Hilt macOS 采集器处于**早期访问**阶段。此处描述的、SIP 保持开启的已公证 `.pkg` 安装方式即为正式交付模型。macOS 上尚不提供自动更新与设备端隔离响应。

## Next steps

* **要部署到主机群？** 使用[通过 MDM 部署](https://hilt.ai/docs/zh/macos-collector/deploy-mdm.md)推送系统扩展和 PPPC 描述文件，以预先批准扩展并预先授予 Full Disk Access——一次静默、零点击的安装。
* **想了解采集了哪些内容？** 查看[事件数据模型](https://hilt.ai/docs/zh/macos-collector/event-data-model.md)以及 macOS 特有的签名和归因字段。
* **想追踪整条管道？** 参阅[数据流](https://hilt.ai/docs/zh/macos-collector/data-flow.md)，了解从 ESensor 到 `endpoint_events` 的路径。


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