capacitor-ios-security-hardening
Audits and progressively hardens Xcode security build settings for a Capacitor iOS app (ios/App/App.xcodeproj, scheme App) and native plugin code (Swift/ObjC/C, Package.swift, podspec). Covers xcodebuild -showBuildSettings -json, security compiler warnings, static analyzer checkers (xcodebuild analyze), Xcode Enhanced Security (ENABLEENHANCEDSECURITY, com.apple.security.hardened-process entitlements, pointer authentication / arm64e, memory tagging soft mode), what is safe for a WKWebView hybrid app vs what breaks CocoaPods, SPM binary xcframeworks or Cordova plugins, staged adoption, and a decision log. Use for "harden my iOS build", "enable Enhanced Security", security build settings audit, arm64e link errors after enabling pointer authentication, or Build and Analyze setup. Do not use for ATS/TLS, signing, secrets or WebView rules (capacitor-security), or App Store review (capacitor-apple-review-preflight).
- Installs
- 53
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-ios-security-hardening- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads capacitor-ios-security-hardening automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Capacitor iOS Security Hardening
Audit the security-relevant Xcode build settings of a Capacitor app and its native plugins, then enable them in stages the user approves. This skill changes build settings and entitlements only. It never touches web code, ATS, signing, or secrets.
When to Use
TRIGGER when:
- The user wants to audit or harden the iOS build configuration of a Capacitor app
- The user asks about Enhanced Security,
ENABLE_ENHANCED_SECURITY, hardened-process entitlements, pointer authentication, arm64e, or memory tagging - After enabling Enhanced Security, the link step fails with errors that mention
arm64e - A plugin author wants stricter warnings or static analysis for plugin Swift/ObjC/C code
- The user wants "Build and Analyze" /
xcodebuild analyzein CI
Do not use:
- ATS, TLS pinning, signing, secrets, WebView config, Capsec scans:
capacitor-security - App Store privacy manifest and review checklist:
capacitor-apple-review-preflight - The AppDelegate to SceneDelegate migration:
capacitor-uiscene-migration - Android R8, network security config:
capacitor-security
Facts that change the plan
- Build settings do not cross project boundaries. Settings on the App target do not apply to Pods (
ios/App/Pods/Pods.xcodeproj), to SPM packages (plugins,CapApp-SPM), or to the Cordova plugin package thatnpx cap syncgenerates. Hardening plugin code is done in the plugin repo (podspec / Package.swift), not in the app. - The App target of a stock Capacitor app is pure Swift (
AppDelegate.swift,SceneDelegate.swift). Clang warnings and analyzer checkers only matter if the app target has.m,.mm,.cor.cppfiles. Detect languages before proposing them. - The Capacitor 8 templates already set three Stage A warnings at project level (
GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR,GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE,GCC_WARN_64_TO_32_BIT_CONVERSION = YES). Report them as already hardened. Do not re-add them. - WKWebView content is not affected. JavaScript and JIT run in WebKit's own processes. Enhanced Security entitlements apply to the app process and the native code linked into it (Capacitor runtime, plugins, SDKs).
- Pointer authentication adds an
arm64eslice to device builds. Every binary linked into the app must also havearm64e, or the link fails. This is the main breakage risk in Capacitor apps. See references/enhanced-security.md. - Do not edit generated files.
ios/App/Pods/**,Pods-App.*.xcconfig,ios/App/CapApp-SPM/Package.swift,ios/capacitor-cordova-ios-plugins/**andios/debug.xcconfig(SPM template, Debug only, CLI-managed) are rewritten by CocoaPods ornpx cap sync. Put settings in the App project (Xcode Build Settings, which writesproject.pbxproj) or in an xcconfig the team already owns. - The user owns the result. Enhanced Security turns latent memory bugs into crashes. Report findings and get approval before changing anything. Test on real hardware before shipping.
References
Only load a reference when its topic is in play.
| File | Load when |
|---|---|
| references/settings-catalog.md | Building the audit table: every tracked setting, its hardened value, language scope, risk |
| references/reading-build-settings.md | Running xcodebuild -showBuildSettings, using the audit script, telling "explicitly disabled" from "default off" |
| references/enhanced-security.md | Enabling the Enhanced Security capability, entitlements, pointer authentication with CocoaPods/SPM/binary SDKs, memory tagging |
| references/plugin-authors.md | Hardening plugin code: podspec pod_target_xcconfig, Package.swift warning settings, analyzing a plugin repo, shipping arm64e xcframeworks |
| references/decision-log.md | Creating or updating the team's decision document |
Script: scripts/audit-build-settings.mjs filters xcodebuild -showBuildSettings -json output to the tracked settings and marks each as hardened, default, or explicitly set (when given the pbxproj).
Workflow
1. Brief and check source control
Tell the user in two or three sentences: you will audit first, write a plan, and change nothing until they approve. If the project has no git, recommend committing first. Stop if they decline.
2. Discover (read-only)
- Confirm the iOS project:
ios/App/App.xcodeprojexists. Note SPM (ios/App/CapApp-SPM/) vs CocoaPods (ios/App/Podfile,App.xcworkspace). - Read the Capacitor version from
package.json(@capacitor/ios). Capacitor 8 deploys to iOS 15, Capacitor 9 to iOS 16 and needs Xcode 27. - Detect languages in the App target folder:
find ios/App/App -name '*.m' -o -name '*.mm' -o -name '*.c' -o -name '*.cpp'. Also rungrep -E 'sourcecode\.cpp\.' ios/App/App.xcodeproj/project.pbxprojto catch files whose type was overridden to C++/ObjC++. - List native dependencies that ship binaries: xcframeworks in
node_modules/**/ios/**,binaryTargetin pluginPackage.swiftfiles,vendored_frameworksin podspecs. - Look for an existing decision document (
ios/xcode-security-settings.mdor similar) and read prior decisions. - Read evaluated settings for Debug and Release (see references/reading-build-settings.md):
xcodebuild -showBuildSettings -json -project ios/App/App.xcodeproj -target App -configuration Release > /tmp/app-release.json
node <skill>/scripts/audit-build-settings.mjs /tmp/app-release.json --pbxproj ios/App/App.xcodeproj/project.pbxproj
- Read the entitlements file at the evaluated
CODE_SIGN_ENTITLEMENTSpath. The stock template has none; that is normal.
3. Build the plan and ask
Write the plan into the chat (or a file the user names). Group it by stage. Show only items that apply:
| Stage | Items | Default |
|---|---|---|
| A. Compiler warnings | The five security warnings, only if C/ObjC/C++ is present in the target | on |
| B. Static analyzer | The security checkers plus the clang-tidy check; analyzer runs only on Analyze, so no build risk | on |
| C. Enhanced Security | Capability at project level, entitlements on the App target, pointer authentication with the dependency plan | on, after the dependency check |
| D. Memory tagging | checked-allocations + soft-mode | off, offer |
| E. Extra diagnostics | The noisier warnings | off, offer |
| F. Disabled settings | Ask about each explicit = NO that has no documented reason | on |
Ask the user to approve, edit or cancel. Real judgement calls to put to the user:
- A binary SDK with no
arm64eslice: turn pointer authentication off on the App target (keeps the rest of Enhanced Security) or wait for the vendor. - CocoaPods: add a
post_installhook that enables pointer authentication on pod targets, or turn it off on the App target. - Memory tagging: only with a plan to test on capable hardware.
4. Apply, one stage at a time
- Apply settings at the project level of
App.xcodeprojso every target inherits them, unless the setting is per target (entitlements, pointer-authentication opt-out). - Best path: ask the user to set them in Xcode (project > Build Settings > All). Then verify with
greponproject.pbxproj. If you editproject.pbxprojyourself, edit only thebuildSettingsdictionaries of the project's own Debug and ReleaseXCBuildConfigurationentries (the ones listed by the PBXProjectbuildConfigurationList), keep theKEY = VALUE;syntax, and re-run-showBuildSettingsto confirm. - Add Enhanced Security through Signing & Capabilities > + Capability > Enhanced Security on the App target. This creates or updates
App.entitlementsand wiresCODE_SIGN_ENTITLEMENTS. Details: references/enhanced-security.md. - After each stage, build (step 5) before starting the next one. If a stage breaks the build, revert that stage, record why in the decision log, and continue.
5. Verify
# Sync, then build for a device (arm64e only exists for device SDKs)
npx cap sync ios
xcodebuild -project ios/App/App.xcodeproj -scheme App -configuration Release \
-destination 'generic/platform=iOS' CODE_SIGNING_ALLOWED=NO build
# CocoaPods projects: use -workspace ios/App/App.xcworkspace instead of -project
# Static analyzer
xcodebuild -project ios/App/App.xcodeproj -scheme App -configuration Debug \
-destination 'generic/platform=iOS Simulator' analyze
# Confirm the slices of the built app binary
lipo -archs ~/Library/Developer/Xcode/DerivedData/App-*/Build/Products/Release-iphoneos/App.app/App
- Re-run the audit script. Every approved setting shows as hardened.
- Simulator builds keep working: simulator SDKs have no
arm64e, and the build system drops it. Do not add a simulator-only opt-out. - Run the app on a real device. Check launch, plugin calls, and the JS
pause/resumeevents. With memory tagging in soft mode, collect the simulated crash reports from Xcode Organizer or the device logs (ios-android-logs).
6. Report and record
Report: what was enabled, what was already hardened, what was skipped and why, which dependencies block arm64e, and the action item to test on hardware before release. Then update the decision document (references/decision-log.md).
Error Handling
| Symptom | Cause | Fix |
|---|---|---|
Link fails with messages that mention arm64e after enabling Enhanced Security | A pod, SPM package or xcframework was built without arm64e | Find it with lipo -archs. Source pods: post_install hook. SPM source packages: workspace setting iOSPackagesShouldBuildARM64e. Binary with no slice: ENABLE_POINTER_AUTHENTICATION = NO on the App target and ask the vendor. See references/enhanced-security.md |
Sandbox: rsync(...) deny(1) file-write-create in [CP] Embed Pods Frameworks | ENABLE_USER_SCRIPT_SANDBOXING = YES with CocoaPods script phases | Keep it NO on the App target while on CocoaPods, record the reason, revisit after the SPM migration (cocoapods-to-spm) |
| New warnings flood after Stage A | Warnings were off before | Fix real bugs first. If a warning is in generated or vendored code, keep it on and defer that code; never flip -Werror for the whole project |
Settings changed but -showBuildSettings shows the old value | Set on the wrong level, or a target-level value overrides the project | Check the target column in Xcode; remove the target override if it has no reason |
| App crashes at launch only on newer devices after memory tagging | Soft mode was turned off too early, or a native library has a memory bug | Re-enable soft mode, collect reports, fix or update the library (often bundled C code such as zip or SQLite) |
Edits vanished after npx cap sync or pod install | A generated file was edited | Move the setting to the App project or to the plugin's own podspec / Package.swift |
Related Skills
capacitor-security: ATS, signing, secrets, WebView and storage securitycocoapods-to-spm: SPM removes most pod-related hardening frictioncapacitor-plugin-spm-support: Package.swift layout for pluginsios-android-logs: capture crash and memory-tagging reports from devices
FAQ
What does the capacitor-ios-security-hardening skill do?
Audits and progressively hardens Xcode security build settings for a Capacitor iOS app (ios/App/App.xcodeproj, scheme App) and native plugin code (Swift/ObjC/C, Package.swift, podspec). Covers xcodebuild -showBuildSettings -json, security compiler warnings, static analyzer checkers (xcodebuild analyze), Xcode Enhanced Security (ENABLEENHANCEDSECURITY, com.apple.security.hardened-process entitlements, pointer authentication / arm64e, memory tagging soft mode), what is safe for a WKWebView hybrid app vs what breaks CocoaPods, SPM binary xcframeworks or Cordova plugins, staged adoption, and a decision log. Use for "harden my iOS build", "enable Enhanced Security", security build settings audit, arm64e link errors after enabling pointer authentication, or Build and Analyze setup. Do not use for ATS/TLS, signing, secrets or WebView rules (capacitor-security), or App Store review (capacitor-apple-review-preflight).
How do I install capacitor-ios-security-hardening?
Run npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-ios-security-hardening in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/capacitor-ios-security-hardening/ (personal) or .claude/skills/capacitor-ios-security-hardening/ (project).
Which AI agents can use capacitor-ios-security-hardening?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is capacitor-ios-security-hardening safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains capacitor-ios-security-hardening?
It is published by cap-go in cap-go/capgo-skills. It has 53 recorded installs.
More from cap-go/capgo-skills
capacitor-best-practices
cap-go/capgo-skills
Review and set up Capacitor apps against current best practices (Capacitor 8.5 stable, 9 alpha via @next). Use for a Capacitor codebase review, capacitor.config.ts audit, new project setup, aligning @capacitor/core/cli/ios/android and plugin majors, plugin patterns (availability checks, checkPermissions/requestPermissions, error code handling, web fallbacks), or release prep; or on " " plugin is not implemented on ios, Could not find the web assets directory, platform has not been added yet, a dev server.url shipped to production, lost edits in android/app/src/main/assets/public, SPM vs CocoaPods, or AppDelegate/UIScene drift. Do not use for security audits (capacitor-security), performance (capacitor-performance), tests (capacitor-testing), crashes (debugging-capacitor), major upgrades (capacitor-app-upgrades), SPM migration (cocoapods-to-spm), UIScene adoption (capacitor-uiscene-migration), or live updates (capgo-live-updates).
ionic-design
cap-go/capgo-skills
Builds and reviews Ionic Framework UI in Capacitor apps (Ionic 9 current, Ionic 8 still common) - page structure (ion-header/ion-content/ion-footer), lists, modern form syntax (label/labelPlacement on ion-input/ion-select), sheet modals, tabs + ion-router-outlet, CSS variable theming, dark palettes (palettes/dark.system.css, .ion-palette-dark), iOS vs MD mode, and Ionic 8 - 9 breaking changes (React Router 6, Vue Router 5, Angular 18-22 zoneless, removed ion-picker-legacy, boolean autocorrect, npx @ionic/migrate). Use when writing Ionic components, theming an Ionic app, fixing platform-mode styling, or upgrading @ionic/react, @ionic/vue, @ionic/angular. Do not use for Konsta UI (konsta-ui), Tailwind setup (tailwind-capacitor), raw safe-area CSS (safe-area-handling), keyboard resize (capacitor-keyboard), or Ionic Appflow/Enterprise migrations (ionic-appflow-migration, ionic-enterprise-sdk-migration).
capacitor-plugins
cap-go/capgo-skills
Pick, install, and wire up Capacitor plugins for native features (camera, filesystem, geolocation, biometrics, in-app purchases, social login, SQLite, calendar, contacts, health, BLE, NFC, etc.). Covers official @capacitor/ packages (Capacitor 8.5 stable, 9 alpha on next) plus the 145-package @capgo/ index, native permission keys (Info.plist, AndroidManifest, variables.gradle minSdk), npx cap sync / cap ls verification, and errors like '"Camera" plugin is not implemented on ios', 'unable to find plugin', UNIMPLEMENTED, and OS-PLUG- codes. Use for "which plugin should I use for X", adding a plugin, or a plugin call failing after install. Do not use for push setup (capacitor-push-notifications), splash assets (capacitor-splash-screen), keyboard layout (capacitor-keyboard), deep links (capacitor-deep-linking), OTA updates (capgo-live-updates), upgrading plugin source code (capacitor-plugin-upgrades), or adding SPM to a plugin (capacitor-plugin-spm-support).
debugging-capacitor
cap-go/capgo-skills
Diagnoses and fixes runtime bugs in Capacitor iOS/Android apps - white/blank screen on launch, startup crashes, "X" plugin is not implemented on ios/android, net::ERRCLEARTEXTNOTPERMITTED, App Transport Security blocks, CORS on capacitor://localhost, permission denials, live reload not connecting, and Capacitor 8.5+ UIScene regressions (appUrlOpen, universal links, pause/resume silent because AppDelegate callbacks stopped). Covers Safari Web Inspector, chrome://inspect, Xcode/LLDB, Android Studio, npx cap run --url (Capacitor 9) vs -l --host (8), xcrun simctl openurlprivacypush, xcrun devicectl device process launchopenURL, xctrace. Do not use for only reading device logs (ios-android-logs), the UIScene migration itself (capacitor-uiscene-migration), deep-link setup (capacitor-deep-linking), speed (capacitor-performance), crash SDKs (capacitor-native-observability), tests (capacitor-testing), or upgrades/build errors (capacitor-app-upgrades, cocoapods-to-spm).
capacitor-testing
cap-go/capgo-skills
Testing guide for Capacitor apps and plugins. Covers web-layer unit and component tests with Vitest and mocked Capacitor plugins (vi.mock('@capacitor/core'), registerPlugin), Playwright for the web build, Appium E2E with NATIVEAPP / WEBVIEW context switching, native plugin unit tests with Swift Testing vs XCTest (what can migrate, CAPPluginCall patterns, xcodebuild test on a simulator) and Android JUnit, plus an agent-driven verification loop on simulators and devices (build, install, launch, screenshot, UI hierarchy, tap, logs) with xcrun simctl, xcrun devicectl, adb, Xcode MCP device tools, and live reload via npx cap run --url (Capacitor 9) or -l --host --port (Capacitor 8). Use when adding tests, mocking plugins, "does it work on device", verifying a UI change on a simulator, migrating XCTest to Swift Testing, or setting up test CI. Do not use for crash log capture (ios-android-logs), WebView debugging sessions (debugging-capacitor), or build pipelines (capacitor
safe-area-handling
cap-go/capgo-skills
Fixes notch, Dynamic Island, home indicator, display cutout, and system bar overlap in Capacitor apps. Covers viewport-fit=cover + env(safe-area-inset-), the Capacitor 8 SystemBars core plugin (insetsHandling, injected --safe-area-inset- CSS variables for Android WebView < 140, removal of android.adjustMarginsForEdgeToEdge), Android 15/16 enforced edge-to-edge (overlaysWebView and backgroundColor of @capacitor/status-bar no longer work at targetSdk 36), iOS contentInset, and insets that change at runtime on rotation, iPad/foldable resizable windows. Use when headers sit under the status bar, tab bars hide behind the gesture bar, env() returns 0 on Android, or layout broke after upgrading to Capacitor 8 / targetSdk 35+. Do not use for keyboard overlap (capacitor-keyboard), Ionic/Konsta component theming (ionic-design, konsta-ui), Tailwind utility setup (tailwind-capacitor), or iOS multi-window/resizability adoption (capacitor-ios-resizability).
Popular mobile skills
design-mobile-apps
designed-by-ai/skills
Design mobile app screens with Sleek, edit Sleek projects, and implement their designs in React Native or HTML.
ios-design
uizze.sh
Design and review iOS UI/UX for iPhone apps in SwiftUI, UIKit, or React Native. Use for mobile app design, screen redesigns, navigation flows, typography, forms, keyboard and safe-area layout, and accessibility checks. Apply Apple Human Interface Guidelines and consult real product references through the optional Uizze connection.
vercel-react-native-skills
vercel-labs/agent-skills
React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.
animate-expo
emilkowalski/skills
Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use animate.
xcode-project-setup
firebase/agent-skills
Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).
firebase-remote-config-basics
firebase/agent-skills
Manages Firebase Remote Config templates, feature flags, loading strategies, and SDKs (Android, iOS). Use when downloading/deploying remoteconfig JSON templates, managing version history/feature flags, setting in-app defaults, fetchAndActivate(), real-time listeners, or SDK setup. Don't use for Firebase Hosting, Auth, Firestore, Data Connect, Crashlytics, or App Hosting.