audit-xcode-security-settings

Files (17)

• SKILL.md
• additional-settings.md · references/
• adoption-strategy.md · references/
• cpp-hardening.md · references/
• decision-document.md · references/
• enhanced-security.md · references/
• hardware-memory-tagging.md · references/
• pointer-authentication.md · references/
• reading-build-settings.md · references/
• readonly-platform-memory.md · references/
• runtime-restrictions.md · references/
• security-compiler-warnings.md · references/
• settings-and-entitlements-catalog.md · references/
• stack-zero-init.md · references/
• typed-allocators.md · references/
• universal-binaries-for-libraries.md · references/
• filter_build_settings.py · scripts/

SKILL.md (first lines)

# Audit Xcode Security Settings

Assess an Xcode project's security posture and progressively enable security build settings and entitlements — from broadly applicable warnings through Enhanced Security hardening.

## Tool Preferences

When XcodeGlob, XcodeGrep, XcodeRead, XcodeLS, and XcodeUpdate tools are available, ALWAYS use them. Do not fall back to Bash filesystem tools (`ls`, `find`, `cat`, `grep`) to learn about the project. They trigger extra permission prompts and bypass project scoping.

- **XcodeGlob** for file discovery — `find` is forbidden for files inside the project.
- **XcodeGrep** for content search — `grep`/`rg` is forbidden for files inside the project.
- **XcodeRead** for file contents — `cat`/`Read` is forbidden for files registered in the project.
- **XcodeLS** for directory listing — `ls` is forbidden for any path inside the project.
- **XcodeUpdate** for in-place edits of project-registered files — same `filePath` / `oldString` / `newString` (+ optional `replaceAll`) signature as the built-in `Edit` tool, but accepts project-org paths. `Edit` is forbidden for files registered in the project; use it only for on-disk files that aren't project-indexed (e.g. `.entitlements` plists translated to filesystem absolute paths per the failure-modes table below).

**Project root and name are already in the system prompt context.** Do NOT run `ls` to "verify" the project layout before starting. The system prompt already tells you the working directory and the project structure.

**Empty XcodeGlob results are not a failure.** The `.xcodeproj` and `.xcworkspace` are not indexed as files inside the Xcode project organization — `XcodeGlob "**/*.xcodeproj"` correctly returns 0 matches. Use the project name from system-prompt context instead. Do not fall back to filesystem `ls`/`find`.

**Path translation between project-org and filesystem.** XcodeGlob returns project-org-relative paths. To read or edit a file:
- Prefer `XcodeRead` / `XcodeUpdate` with the project-org path.
- If that path is rejected (some on-disk files like `.entitlements` plists may not be navigable through `XcodeRead`), translate to a filesystem absolute path by prepending the project root from system context. Do NOT use `find` to discover the on-disk path.

Fall back to Bash only for operations the Xcode tools cannot do (e.g., `plutil` for plist editing, git operations).

### Common Failure Modes

| Symptom | Cause | Correct Response |
|---|---|---|
| `XcodeGlob "**/*.xcodeproj"` returns 0 matches | The `.xcodeproj` itself isn't a project-indexed file | Use the project name from system context; do not fall back to `find` or `ls` |
| `XcodeRead <project-org-path>` fails for a config-type file (`.entitlements`, `.xcsettings`, `.xcconfig`) | Some on-disk artifacts aren't navigable via project paths | Translate to filesystem absolute path using the project root from system context, then use `Read` / `Edit` |

## Workflow

## Phase 1: Briefing

Before doing any work, tell the user — in two or three sentences — what this skill is, what it will do, and roughly how much of their time and attention to expect:

- **What it is.** An audit of the project's Xcode security build settings and entitlements (compiler warnings, hardened-process capabilities, pointer authentication, universal binaries for libraries, etc.).
- **What happens.** I analyze the project, write an editable plan file at the project root for you to review, and apply only the changes you approve. Nothing is modified until you pick Run.
- **Time commitment.** A few minutes of my time to analyze (longer on projects with many targets — I'll narrate progress). Then your review time on the plan file, which can be quick or thorough — your call. After Run, applying is fast; two things can pause for your input — the inquiry step (if there are deliberately-disabled settings whose rationale isn't documented), and a final yes/no on whether to keep the plan file in your project as a record.
This all usually takes about 15-30 minutes, depending on the number of build targets and how long it takes for you to review and approve the plan.

Keep it tight — the user already invoked the skill knowing they wanted an audit.
The briefing exists so they have realistic expectations.

## Phase 2: Discovery

Read the Environment block in the system prompt. Relevant fields:
- `Primary working directory` — the project root (the project name is the basename).
- `Is a git repository` — whether the project is git-tracked (used by Phase 4 Step 1).

## Track Progress

Every per-target / per-setting action that needs to happen must have its own task for transparency.

- Phase 3 creates one task per target (`Audit <target>`); the task closes once Phase 3 has produced both the per-target audit-table rows and (for supported product types) the Enhanced-Security bucket for that target. After all per-target tasks complete, Phase 3 writes `<project-root>/xcode-security-audit-scratchpad.md` via the `Write` tool (filesystem only — the scratchpad is agent-internal state, not user-facing, so it deliberately is **not** registered in the Xcode project). Phases 4–7 re-read it via `Read`; they never assume the data is in memory. Do not stage this file in git.
- Phase 4 (Plan & Approve) is one task that completes when the user picks Run/Cancel.
- On Run, Phase 4 step 5 parses the plan, appends a `## Plan Selection` section to the scratchpad, and creates fine-grained tasks:
  - One `Apply Enhanced Security to <target>` per target needing changes (only if "Enhanced Security" is checked).
  - `Apply Basic Clang Safety Warnings` if checked.
  - `Apply Hardware Memory Tagging` if checked.
  - `Apply Additional Diagnostic Settings` if checked.
  - `Emit Bounds Safety Adoption guidance` if checked.
  - One `Inquire about <MACRO> on <target>` per Phase-6 candidate (only if "Inquire about disabled settings" is checked).
  - `Report and update decision document`.
  - `Remove scratchpad` — always second-to-last; also fires on error paths.
  - `Prompt to remove plan file` — always last; also fires on error paths.

When entering each phase or sub-step:
- Print one line: "▶ Phase N: …" (or "▶ Phase N / Step M: …" for sub-steps).
- Update the task to `in_progress`.

When finishing each phase or sub-step:
- Print one line: "✓ Phase N: …" (with a brief outcome if applicable, e.g., "✓ Phase N: No disabled settings found.").
- Update the task to `completed`.

### Phase 3: Analyze Project and Settings

No user interaction. Gather facts in the background.

#### Step 1: Locate the existing decision document

`XcodeGlob '**/xcode-security-settings.md'`. If found, `XcodeRead` it and extract languages + prior setting decisions with their statuses and rationale. This informs subsequent phases.

#### Step 2: Detect languages

One `XcodeGlob` per language. Empty result is not a failure — record the language as absent.

- `**/*.c` → C
- `**/*.cpp`, `**/*.cxx`, `**/*.cc` → C++
- `**/*.m` → Objective-C
- `**/*.mm` → Objective-C++
- `**/*.swift` → Swift

#### Step 3: Build the audit table

See `references/reading-build-settings.md` for column definitions, the construction recipe, and the canonical predicates ("already hardened", "at default OFF", "deliberately disabled"). At a glance:

1. Enumerate the project's explicit targets. Skip implicit/aggregate targets (no real product type).
2. For each target: `TaskCreate "Audit <target>"`, set in_progress. Call `GetTargetBuildSettings`, run `scripts/filter_build_settings.py` over the resulting JSON, and record `evaluatedValue` and `setAtTargetLevel` (`yes` if `targetValue` is present in the JSON). Leave the task in_progress — Step 4 closes it.
3. One project-wide `XcodeGrep` for the catalog regex over `*.xcconfig` and `**/project.pbxproj`. Record per-macro `numMatchesInXCConfigs`, `numMatchesInPbxproj`, and the file:line citations.
4. The audit table is the joined view: one row per (target, catalog macro). Phases 4, 5, and 6 all consume this table; nothing else is re-fetched.

This step scales with target count: each `GetTargetBuildSettings` call takes several seconds, and there is one per target. On projects with roughly ten or more targets it can take a few minutes.

#### Step 4: Per-target Enhanced-Security state

Route each target into one of three buckets by product type (inferred per the table in `references/reading-build-settings.md`):

- **Entitlements-supported** — product type is in the "Supported Product Types" list of `references/enhanced-security.md` (applications, XPC services, system extensions, driver extensions [build settings only], tools). Read the resolved `CODE_SIGN_ENTITLEMENTS` plist and bucket the target as **Up-to-date**, **Partial**, **Off**, or **No-entitlements-file**.
- **Library/framework** — product type is in the qualifying set listed in `references/universal-binaries-for-libraries.md` (frameworks, static frameworks, static libraries, dynamic libraries). No entitlements read. Phase 5 will configure a universal-binary `ARCHS` recommendation for these.
- **Skipped** — anything else (test bundles, app extensions, etc.).

`TaskUpdate "Audit <target>"` to completed once the bucket is recorded (immediately for **Library/framework** and **Skipped** — they need no entitlements read). Phases 4 and 5 consume these buckets — neither re-reads entitlements.

On large projects this iterates over many `.entitlements` plists — if Step 3 took noticeable time, this one will too.

#### Step 5: Persist the analysis

Write `<project-root>/xcode-security-audit-scratchpad.md` via the **`Write` tool** (not `XcodeWrite` — the scratchpad is agent-internal state and intentionally is not registered in the Xcode project, so it doesn't clutter the user's Project Navigator). Resolve `<project-root>` from the Environment block's `Primary working directory`. The file has two sections:

From guillevc/skills, MIT.

More from guillevc/skills