audit-xcode-security-settings

审计 Xcode 安全设置

评估 Xcode 项目的安全状况，并逐步启用安全构建设置和权利配置——从广泛适用的警告到强化安全防护。

工具偏好

当 GetTargetBuildSettings 因令牌数限制而将输出写入已保存的文件时，请参阅 references/reading-build-settings.md，了解其架构和筛选脚本（scripts/filter_build_settings.py）。不要逐行读取已保存的文件。

当 XcodeGlob、XcodeGrep、XcodeRead 和 XcodeLS 工具可用时，始终使用它们。不要改用 Bash 文件系统工具（ls、find、cat、grep）来了解项目情况。使用这些工具会触发额外的权限提示，并绕过项目范围限制。

• XcodeGlob 用于发现文件——禁止对项目内文件使用 find。
• XcodeGrep 用于搜索内容——禁止对项目内文件使用 grep/rg。
• XcodeRead 用于读取文件内容——禁止对已注册到项目中的文件使用 cat/Read。
• XcodeLS 用于列出目录——禁止对项目内的任何路径使用 ls。

项目根目录和名称已包含在系统提示上下文中。 开始前不要运行 ls 来“验证”项目布局。系统提示已告知工作目录和项目结构。

XcodeGlob 返回空结果并不代表失败。 .xcodeproj 和 .xcworkspace 不会作为文件编入 Xcode 项目组织索引——XcodeGlob "**/*.xcodeproj" 正确返回 0 个匹配项。请改用系统提示上下文中的项目名称。不要改用文件系统 ls/find。

项目组织路径与文件系统路径之间的转换。 XcodeGlob 返回相对于项目组织的路径。读取或编辑文件时：

• 优先使用项目组织路径调用 XcodeRead / XcodeUpdate。
• 如果该路径被拒绝（某些磁盘上的文件，如 .entitlements plist，可能无法通过 XcodeRead 导航），请在路径前添加系统上下文中的项目根目录，转换为文件系统绝对路径。不要使用 find 来发现磁盘上的路径。

只有在 Xcode 工具无法完成操作时（例如，使用 plutil 编辑 plist、执行 git 操作），才改用 Bash。

常见故障模式

症状	原因	正确响应
XcodeGlob "**/*.xcodeproj" 返回 0 个匹配项	.xcodeproj 本身未编入项目索引	使用系统上下文中的项目名称；不要改用 find 或 ls
XcodeRead <project-org-path> 无法读取配置类型文件（.entitlements、.xcsettings、.xcconfig）	某些磁盘上的文件无法通过项目路径导航	使用系统上下文中的项目根目录将路径转换为文件系统绝对路径，然后使用 Read / Edit

工作流

阶段 0：发现

阅读系统提示上下文，其中包含：

• 项目根目录（工作目录）。
• 项目名称和结构（顶层文件、软件包）。
• 当前启用的方案。

不要调用 ls、find 或任何文件系统工具重新发现这些信息。

跟踪进度

开始第 1 阶段前：

1. 以可见的项目符号列表向用户打印工作流计划（这样不喜欢冗长输出的用户也能看到接下来的安排）：

   工作流：

   • 第 1 阶段：分析项目和现有设置
   • 第 2 阶段：应用设置
     • 步骤 1：增强安全性
     • 步骤 2：基本 Clang 安全警告
   • 第 3 阶段：询问已禁用的设置
   • 第 4 阶段：验证已应用的设置
   • 第 5 阶段：报告并更新决策文档
   • 第 6 阶段：可选的后续操作

2. 使用相同的项目调用 TaskCreate，以便喜欢详细信息的用户获得任务跟踪器。

进入每个阶段或子步骤时：

• 打印一行：“▶ 第 N 阶段：……”（子步骤使用“▶ 第 2 阶段 / 步骤 1：……”）。
• 将任务更新为 in_progress。

完成每个阶段或子步骤时：

• 打印一行：“✓ 第 N 阶段：……”（适当时简要说明结果，例如：“✓ 第 3 阶段：未发现已禁用的设置。”）。
• 将任务更新为 completed。

第 6 阶段以单个任务和单行开始。用户选择某项具体后续操作时，开始时打印“▶ 第 6 阶段 / ”，结束时打印“✓ 第 6 阶段 / ”，并创建或更新相应的子任务。

第 1 阶段：分析项目和设置

不与用户交互。静默收集信息。若可用，优先使用 XcodeGlob、XcodeGrep 和 XcodeRead，而不是对应的 Bash 工具（参见“工具偏好”）。

1. 使用 XcodeGlob（**/*.xcodeproj）或 Glob 查找 .xcodeproj 或 .xcworkspace。
2. 使用 XcodeGlob 或 Glob 搜索现有决策文档（**/xcode-security-settings.md）。如果找到，请阅读并提取：语言，以及所有先前设置决策的状态和理由。这些信息将用于后续阶段。
3. 使用 XcodeGlob 或 Glob 检测项目中包含的语言：
   • **/*.c → C
   • **/*.cpp、**/*.cxx、**/*.cc → C++
   • **/*.m → Objective-C
   • **/*.mm → Objective-C++
   • **/*.swift → Swift
4. 枚举目标及其权限文件——对每个目标，记录其产品类型、平台（通过 SDKROOT / SUPPORTED_PLATFORMS），并解析 CODE_SIGN_ENTITLEMENTS，确定磁盘上的 .entitlements 路径（若因配置而异，则逐个配置记录）。第 2 阶段步骤 1 需要此映射。使用 GetTargetBuildSettings 时，请参阅 references/reading-build-settings.md，了解输出架构以及处理大型结果的方法。

第 2 阶段：应用设置

按适用程度从高到低逐步应用设置。

检查现有安全设置。 在 pbxproj 和 xcconfig 文件中搜索目录中的设置（参见 references/settings-and-entitlements-catalog.md）。仅应用尚未设置的项。如果所有设置都已启用，请告知用户并停止。

如何应用构建设置：

• 项目使用 .xcconfig 文件 — 直接编辑 xcconfig。项目级和目标级设置均适用。
• 项目仅使用 .pbxproj — 使用 UpdateTargetBuildSetting 设置目标级设置，使用 UpdateProjectBuildSetting 设置项目级设置。
• 混合使用 — 如果目标有 .xcconfig 文件，则编辑 xcconfig；否则，使用 Xcode 构建设置工具。切勿引入新的配置方式。

尽可能优先使用项目级设置（减少重复）。如果项目不使用 xcconfig，则回退到通过 UpdateTargetBuildSetting 设置目标级设置。

例外 — ENABLE_ENHANCED_SECURITY： 必须在项目级设置。如果项目使用 xcconfig，则在其中设置；否则，使用 UpdateProjectBuildSetting。

步骤 1：增强安全性 — 审核权限和构建设置，然后提出逐目标差异

有关完整的键列表、默认值、已弃用的键、版本迁移和支持的产品类型列表，请阅读 references/enhanced-security.md。有关各项子选项的详情，请参阅：

• references/pointer-authentication.md — arm64e 指针签名
• references/typed-allocators.md — 类型感知内存分配
• references/stack-zero-init.md — 自动将栈变量初始化为零
• references/readonly-platform-memory.md — dyld 状态保护
• references/runtime-restrictions.md — dylib 和 Mach 消息限制
• references/security-compiler-warnings.md — 面向安全的编译器警告
• references/cpp-hardening.md — C++ 标准库加固和边界检查
• references/hardware-memory-tagging.md — ARM MTE

1. 确定支持的目标。 根据 Phase 1 步骤 4 收集的目标映射，跳过产品类型不在 references/enhanced-security.md 的“Supported Product Types”列表中的目标。其余目标均为“支持的目标”。注意：DriverKit 目标仅支持构建设置，跳过对它们的权利变更。

2. 审计每个支持的目标。 收集 ENABLE_ENHANCED_SECURITY 和 ENABLE_POINTER_AUTHENTICATION 的构建设置值（先检查目标级，再检查项目级继承值）。对于非 DriverKit 目标，还要读取权利文件，并收集 com.apple.security.hardened-process* 下的所有键，包括已弃用的键。根据 references/enhanced-security.md Part B 中的必需键和默认启用键进行对照，并为每个目标归类：

   • 最新 — 无需处理。
   • 部分配置 — ENABLE_ENHANCED_SECURITY 为 YES，但缺少默认启用的子选项，或包含已弃用的键，或存在版本 "1" / 已弃用的版本键。
   • 关闭 — ENABLE_ENHANCED_SECURITY 不存在。
   • 无权利文件 — 目标受支持，但尚无 .entitlements 文件。如果用户确认应用更改，将创建一个（见步骤 5）。

重要 如果项目包含任何并非从源代码纳入本项目的二进制依赖项（例如 frameworks、xcframeworks、Swift Packages），请勿启用指针身份验证。如果项目确实包含此类依赖项，请列出它们，并建议用户联系依赖项供应商，以获取同时包含 arm64 和 arm64e 的 Universal 二进制文件。

3. 整理变更集。 对于每个配置部分或关闭的支持目标，按以下顺序整理权利变更（省略空白部分）：

   • 添加权利：缺少的必需键（com.apple.security.hardened-process、...enhanced-security-version-string = "2"）和缺少的默认启用子选项（hardened-heap、dyld-ro、platform-restrictions-string = "2"）。
   • 移除权利：已弃用的键（...platform-restrictions、...enhanced-security-version）。
   • 更新权利：如果版本字符串为 "1"，则更新为 "2"。

   如果支持的目标没有 .entitlements 文件，请在变更集中加入创建文件并配置 CODE_SIGN_ENTITLEMENTS。

   构建设置： 遵循上文“How to apply build settings”中的说明。如果项目使用 xcconfig，请在其中的项目级设置 ENABLE_ENHANCED_SECURITY = YES。否则，请使用 UpdateProjectBuildSetting。

   由于项目级的 ENABLE_ENHANCED_SECURITY = YES 会将 ENABLE_POINTER_AUTHENTICATION = YES 级联应用到每个目标，因此对于平台不支持 arm64e 的目标（通过 SDKROOT / SUPPORTED_PLATFORMS 判断），请预先添加目标级 ENABLE_POINTER_AUTHENTICATION = NO 覆盖值。如果目标已有显式的目标级值，则跳过。

   不要自动启用默认关闭的子选项（MTE 系列）；请报告其状态，并在下方步骤 6 中提供启用选项。

4. 展示并确认。 如果所有支持的目标都已是最新状态，请用一行报告此情况，并继续步骤 2（基本 Clang 安全警告）——无需在没有待应用内容时询问是否确认应用。否则，请打印计划启用 Enhanced Security 的目标列表。 然后简要总结启用 Enhanced Security 的好处，包括它提供的安全保护以及可能需要的代码更改。

   然后通过 AskUserQuestion 询问一次：“应用上述 Enhanced Security 更改吗？”提供“全部应用”“应用部分（选择目标）”“跳过 Enhanced Security”。

5. 应用。

   • 对非 arm64e 平台上的目标，通过 UpdateTargetBuildSetting 设置目标级 ENABLE_POINTER_AUTHENTICATION = NO 覆盖值。跳过已显式设置目标级值的目标。
   • 直接编辑现有的每目标 .entitlements plist——添加必需且默认启用的键，移除已弃用的键，并以原子方式将版本字符串 "1" 迁移为 "2"。
   • 对于没有 .entitlements 文件的目标，创建一个文件并将 CODE_SIGN_ENTITLEMENTS 指向该文件。

   报告：“已在 N 个目标上启用 Enhanced Security。已移除 M 个已弃用的授权项。在 K 个目标上将版本字符串升级为 2。在 T 个非 arm64e 平台目标上添加 arm64e 覆盖值。”

6. 硬件内存标记。 仅支持 SUPPORTED_PLATFORMS（或 SDKROOT）为 macosx、iphoneos / iphonesimulator 或 xros / xrsimulator 的目标。（硬件支持需要 M5 级及更新的 Apple silicon；不支持 tvOS、watchOS 和 DriverKit 目标。）如果未应用 Enhanced Security，或没有已修改的目标匹配这些平台，则跳过此步骤。否则，通过 AskUserQuestion 询问：“可通过 com.apple.security.hardened-process.checked-allocations 启用硬件内存标记。要启用吗？”如果是 → 阅读 references/hardware-memory-tagging.md 并应用其中的设置。

步骤 2：基本 Clang 安全警告

对于包含 C、C++、Objective-C 和 Objective-C++ 的代码库，无需询问即可应用。对于纯 Swift 代码库，跳过此步骤。跳过已启用的设置。除非另有说明，以下所有设置均适用于 C/C++/ObjC/ObjC++。

• GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR
• GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE
• CLANG_WARN_IMPLICIT_FALLTHROUGH = YES
• GCC_WARN_64_TO_32_BIT_CONVERSION = YES
• GCC_TREAT_IMPLICIT_FUNCTION_DECLARATIONS_AS_ERRORS = YES（仅限 C/ObjC/ObjC++）
• CLANG_ANALYZER_SECURITY_FLOATLOOPCOUNTER = YES
• CLANG_ANALYZER_SECURITY_INSECUREAPI_RAND = YES
• CLANG_ANALYZER_SECURITY_INSECUREAPI_STRCPY = YES

简要报告：“已启用其他编译器警告。”

第 3 阶段：询问已禁用的设置

在 pbxproj 和 xcconfig 文件中搜索 references/settings-and-entitlements-catalog.md 中显式设为 NO 的任何构建设置。排除不支持 arm64e 的平台上目标的 ENABLE_POINTER_AUTHENTICATION = NO（该技能会在这些目标上自行设置此项）。对于支持 arm64e 的目标，若发现 ENABLE_POINTER_AUTHENTICATION = NO，则应标记——这是值得询问的主动选择退出。若未发现其他已禁用的设置，则跳过此阶段。仅考虑与第 1 阶段检测到的语言相关的设置——请参阅目录中的 Scope 列。

对于发现的每项已禁用设置，检查决策文档中是否有状态为 Disabled 且附带理由的条目。

**如果决策文档中记录了理由，**请在报告中说明，然后继续。该理由记录了先前的决定，之后可重新审查。

**如果决策文档中没有相关条目，**请询问用户：

“我发现 CLANG_ANALYZER_SECURITY_INSECUREAPI_RAND 被显式设为 NO，但没有说明原因。这样设置有原因吗？”

如果用户提供了原因，请接受并将理由记录到决策文档中，以便今后重新审查。如果没有原因，则建议重新启用。

这也适用于技能通常会启用的任何设置，例如 ENABLE_ENHANCED_SECURITY。如果其中任何设置已显式设为 NO，请按相同流程先检查决策文档，再进行询问。

阶段 4：验证设置

对于阶段 2 中修改的每个目标，使用 GetTargetBuildSettings 验证所应用的每项构建设置是否显示预期值。如果某项设置缺失或值不符合预期，请在报告中标记，说明当前 Xcode 版本可能不支持该设置。有关输出架构和处理大量结果的步骤，请参阅 references/reading-build-settings.md。

阶段 5：报告和决策文档

生成精简摘要：

1. 已启用： 列出已启用的项目级设置。
2. 各目标的增强安全性： 对每个受支持的目标，用一行说明：目标名称、最终状态（已是最新 / 已应用 / 用户跳过），以及简要变更（新增的权利、移除的弃用键、版本升级、是否创建了权利文件）。将因产品类型不受支持而跳过的目标汇总为一行，而不是逐个列出。
3. 已处于启用状态： 列出已正确配置的设置。
4. 已询问： 列出发现处于禁用状态的设置，以及询问后的处理结果。

决策文档。 阅读 references/decision-document.md，并按其中说明创建或更新决策文档。

阶段 6：可选后续步骤

按顺序逐项提出以下选项。每项都是独立的“是 / 否”问题，不要合并成一个多选提示。有关建议的采用顺序和基于语言构成的决策矩阵，请参阅 references/adoption-strategy.md。

1. 其他设置。 通过 AskUserQuestion 提问：“还有一些诊断设置可以发现更多问题，但也可能产生误报。要启用它们吗？”如果用户回答“是” → 阅读 references/additional-settings.md 并按其中说明操作。

2. 边界安全编程模型（仅当存在 C 或 C++ 代码时）。对于 C 项目，提问：“想了解如何采用 ENABLE_C_BOUNDS_SAFETY 吗？这是基于注解的 C 边界安全编程模型——调用 Xcode 的 bounds-safety 技能即可开始。”对于 C++ 项目，提问：“想了解如何采用 ENABLE_CPLUSPLUS_BOUNDS_SAFE_BUFFERS 吗？它支持 C++ 边界安全缓冲区模式——调用 Xcode 的 bounds-safety 技能即可开始。”

面向用户的交互指南

• 回复保持精简。 使用简短的句子。
• 尽量减少向用户提问。 预定提问有两个：增强安全性的应用确认，以及硬件内存标记选项。其他问题视情况而定：询问有意禁用的设置（仅当显式设置为 = NO 且没有记录原因时），以及询问决策文档的位置（仅首次创建时）。
• 报告进度，让用户了解进展：“正在启用……”“正在评估……”“保持启用 / 正在还原……”
• 使用 AskUserQuestion 询问已禁用设置、确认是否应用增强安全性（包括提供“应用于部分目标”选项），以及询问决策文档的位置（仅首次创建时）。
• 提问时提供用户作答所需的背景信息。 例如，先说明安全保护的作用，再询问是否启用。应描述它提供的保护，而不是如何启用。
• 列出 Xcode 构建设置时使用项目符号列表。 不要用逗号分隔列表。