Santa 部署配置详解：配置描述文件、密钥与同步服务器覆盖选项完整参考

🎅 Santa 是 macOS 上的开源二进制与文件访问授权（binary & file access authorization）安全代理。企业部署 Santa 时，绝大多数行为都通过一个 macOS 配置描述文件（configuration profile / mobileconfig） 下发控制；其中一部分密钥（config keys）还可以被同步服务器（sync server）在运行时覆盖。本文整理配置描述文件的结构、核心密钥清单、证书与信任链相关选项，以及"哪些选项能被 sync server 覆盖、哪些必须本地固定"，帮助新手快速完成 Santa 部署配置。

📦 Santa 组件与配置描述文件结构

Santa 由多个组件协同工作，配置描述文件主要控制 santad 守护进程的行为：

组件	说明
santad	核心守护进程，做执行 / 文件访问授权决策
santasyncservice	后台同步服务，与 sync server 交换规则与事件
Santa.app	GUI 代理，弹出授权 / 拦截通知（含企业品牌）
系统扩展	Endpoint Security 系统扩展，监听 exec 等系统事件
santactl	命令行工具，查看状态、管理本地规则

配置描述文件的 PayloadType 为 com.northpolesec.santa，属于 macOS 之外的"自定义配置文件"，需要借助 MDM 部署。官方文档给出了示例（节选）：

<dict>
    <key>ClientMode</key>
    <integer>1</integer>
    <key>SyncBaseURL</key>
    <string>https://sync-server-hostname/api/santa/</string>
    <key>PayloadType</key>
    <string>com.northpolesec.santa</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
</dict>

完整示例与说明见 profile-configuration.md，全部键值定义可在 santaconfig.ts 中查到（官方文档页：Keys）。

🧭 核心密钥速查：ClientMode、FailClosed 与 StaticRules

以下三个键决定了 Santa 最核心的"管多严"问题：

配置键	类型	默认值	作用	可被 sync server 覆盖
ClientMode	integer	1（Monitor）	客户端运行模式	✅
FailClosed	bool	false	读文件出错 / 临近决策截止时是否拒绝执行	❌
StaticRules	dict 数组	无	硬编码静态规则，优先于同步规则	❌

ClientMode 三种取值（santaconfig.ts）：

• 1 Monitor：未被规则覆盖的二进制允许执行，但记录事件；
• 2 Lockdown：未被规则覆盖的二进制被阻止；
• 3 Standalone（2024.11 起）：未知二进制触发授权弹窗让用户决定。

FailClosed（santaconfig.ts）：在 Lockdown / Standalone 模式下，当 Santa 无法读取可执行文件时，若设为 true 则直接拒绝执行，适合安全优先的环境。

StaticRules（santaconfig.ts）：一套"无论如何都要生效"的应急规则，永远优先于 sync server 下发的规则，常用于保障管理工具在服务器故障时仍可运行。每条规则由 identifier、policy（ALLOWLIST / BLOCKLIST 等）与 rule_type（BINARY、CDHASH、SIGNINGID、CERTIFICATE、TEAMID）组成：

<key>StaticRules</key>
<array>
    <dict>
        <key>identifier</key>
        <string>ZMCG7MLDV9</string>
        <key>policy</key>
        <string>ALLOWLIST</string>
        <key>rule_type</key>
        <string>TEAMID</string>
    </dict>
</array>

⚠️ 注意：一旦设置了 StaticRules，本机 santactl rule 本地改规则的能力会被禁用。

🔁 同步服务器配置：认证证书与信任链

配置 SyncBaseURL（santaconfig.ts）后，后台的 santasyncservice 会周期性地执行 Preflight → EventUpload → RuleDownload → Postflight 四个阶段的同步（sync.md）。同步相关的常用键：

配置键	说明
SyncBaseURL	同步服务器根地址，必须 HTTPS（localhost 除外）
SyncEnableProtoTransfer	使用二进制 protobuf 传输代替 JSON，更快更省流量
SyncClientContentEncoding	请求压缩方式，可选 deflate（默认）/ gzip / none
SyncExtraHeaders	附加到每个请求的自定义 HTTP 头
MachineID / MachineOwner	机器标识与属主，默认取 Hardware UUID，不建议随意覆盖
MachineIDPlist / MachineIDKey	从指定 plist 的指定 key 读取机器标识（示例见 profile-configuration.md）
EnableAllEventUpload	连"已被允许"的执行事件也上传（默认只传被阻止的）
DisableUnknownEventUpload	不上传 Monitor 模式下未知二进制的放行事件

🔐 客户端认证证书三选一

客户端证书用于向 sync server 证明"这台机器是谁"，三个键按优先级互斥（santaconfig.ts）：

1. ClientAuthCertificateFile（+ ClientAuthCertificatePassword）：指向一个 PKCS#12 证书文件路径及其密码，最适合 MDM 统一下发；
2. ClientAuthCertificateCN：按 CN（通用名）在系统钥匙串中查找证书，对应私钥也必须在钥匙串里，大小写敏感；
3. ClientAuthCertificateIssuerCN：按颁发者 CN 查找，前两者未设置时生效。

🛡️ 服务器证书固定（证书钉扎）

• ServerAuthRootsData：内嵌 PEM 格式的受信任根证书数据；
• ServerAuthRootsFile：同上，但改为磁盘 PEM 文件路径。

钉扎后 Santa 只信任指定 CA，能防住中间人替换 sync server。注意：为满足 ATS（App Transport Security），证书链仍须同时被钥匙串信任。

📤 上传内容控制

EventDetailURL / EventDetailText（santaconfig.ts）控制被拦截弹窗里的"了解更多"按钮：支持 %file_identifier%、%team_id%、%machine_id%、%username% 等占位符，可把用户直接带到 sync server 对应事件的页面。

📺 可被 sync server 覆盖的配置选项清单

这是部署时最容易混淆的部分。带"覆盖"标记的键（keys.mdx 中以刷新图标标注）会写入同步状态，随后被 Preflight 响应的字段覆盖。

✅ 可被覆盖（运行时行为，方便运维从服务器"一键调档"）：

键	覆盖它的能力
ClientMode	全量切换 Monitor / Lockdown / Standalone
AllowedPathRegex / BlockedPathRegex	按路径正则放行 / 拦截
EnableTransitiveRules	编译器传递规则开关
ExecutableIntegrityPolicy、BannedUSBBlockMessage、RemountUSBBlockMessage	完整性策略与提示文案
RemovableMediaAction / RemovableMediaRemountFlags / EncryptedRemovableMediaAction / EncryptedRemovableMediaRemountFlags / OnStartUSBOptions	U 盘等可移动介质策略全套
OverrideFileAccessAction	FAA 文件访问策略全局降级（AUDIT_ONLY / DISABLE / none）
EnableAllEventUpload / DisableUnknownEventUpload	事件上传范围

例如 Preflight 响应中 "client_mode": "LOCKDOWN", "block_usb_mount": true 就会把主机切到封锁模式并启用 U 盘拦截（sync_preflight_turn_on_blockusb.json）；覆盖逻辑实现在 SNTSyncPreflight.mm。

❌ 不可被覆盖（本地固定，属"部署配置"范畴）：SyncBaseURL、SyncEnableProtoTransfer、客户端认证三键、证书钉扎两键、MachineID 系列、StaticRules、FailClosed、GUI / 品牌 / 遥测 / 指标等全部展示与导出类选项。

一句话总结：模式、路径正则、U 盘与 FAA 降级、事件上传范围可远程调；认证、身份、静态规则与界面必须写进描述文件。

🖥️ GUI、品牌化与 U 盘策略选项

• EnableSilentMode / EnableSilentTTYMode：关闭 GUI / 终端通知（官方提醒：用户体验会很困惑，慎用）；
• MoreInfoURL：Santa.app 里"更多信息"按钮跳转的 URL；
• UnknownBlockMessage / BannedBlockMessage / FileAccessBlockMessage：被拦截时展示的自定义提示文案；
• BrandingCompanyName / BrandingCompanyLogo / BrandingCompanyLogoDark（2026.1 起）：在所有通知弹窗底部加上"Managed by"品牌区，详见 branding.md（键定义见 santaconfig.ts）。

U 盘 / 可移动介质（santaconfig.ts）：旧键 BlockUSBMount + RemountUSBMode 已弃用（2026.3），推荐：

• RemovableMediaAction：Allow / Block / Remount；
• RemovableMediaRemountFlags：Remount 时追加的挂载参数，如 rdonly、noexec、nosuid；
• EncryptedRemovableMediaAction / EncryptedRemovableMediaRemountFlags：加密卷单独策略；
• OnStartUSBOptions：Santa 启动时对已挂载设备的处理（Unmount / ForceUnmount / Remount / ForceRemount）。

✅ 部署步骤与验证

1. 生成描述文件：用官方 Config Generator 在浏览器中填写各键并下载（生成过程不出本机）；
2. MDM 下发：作为"自定义配置文件"导入 MDM，PayloadRemovalDisallowed 设为 true 防止用户删除；
3. 安装 PKG：通过 MDM / Munki / brew install santa 安装，安装脚本位于 Conf/Package/；
4. 验证状态：

/usr/local/bin/santactl status
sudo santactl doctor

santactl status 会显示当前 Mode、Sync Server 地址、规则计数与上次成功同步时间（install-package.md）；出现 "An error occurred communicating with the Santa daemon" 时按 troubleshooting.md 检查 Full Disk Access 是否授予 com.northpolesec.santa.daemon。

🧾 小结

• 描述文件 PayloadType 为 com.northpolesec.santa，核心键：ClientMode、SyncBaseURL、StaticRules、客户端证书三键；
• 可被 sync server 覆盖的是运行时策略：模式、路径正则、U 盘与 FAA 降级、事件上传开关；认证、身份、静态规则与 GUI 则必须本地固定；
• 推荐路线：先 ClientMode=1（Monitor）单机验证事件上报 → 配置证书与 StaticRules → 再全量推进 Lockdown。

祝部署顺利 🎅