capacitor-ios-security-hardening

Capacitor iOS セキュリティ強化

Capacitor アプリとそのネイティブプラグインのセキュリティ関連 Xcode ビルド設定を監査し、ユーザーの承認を得た段階ごとに有効にします。このスキルが変更するのはビルド設定とエンタイトルメントのみです。Web コード、ATS、署名、シークレットには一切触れません。

使用するタイミング

次の場合に使用します：

• ユーザーが Capacitor アプリの iOS ビルド構成を監査または強化したい場合
• ユーザーが Enhanced Security、ENABLE_ENHANCED_SECURITY、プロセス強化エンタイトルメント、ポインター認証、arm64e、またはメモリータグ付けについて質問した場合
• Enhanced Security を有効にした後、arm64e に関するエラーでリンク手順が失敗した場合
• プラグインの作成者が、プラグインの Swift／ObjC／C コードに対してより厳格な警告や静的解析を求める場合
• ユーザーが CI で「Build and Analyze」／xcodebuild analyze を実行したい場合

次の場合は使用しないでください：

• ATS、TLS ピンニング、署名、シークレット、WebView の構成、Capsec スキャン：capacitor-security
• App Store のプライバシーマニフェストと審査チェックリスト：capacitor-apple-review-preflight
• AppDelegate から SceneDelegate への移行：capacitor-uiscene-migration
• Android の R8、ネットワークセキュリティ構成：capacitor-security

計画に影響する事実

• ビルド設定はプロジェクトの境界を越えて適用されません。 App ターゲットの設定は Pods（ios/App/Pods/Pods.xcodeproj）、SPM パッケージ（プラグイン、CapApp-SPM）、または npx cap sync が生成する Cordova プラグインパッケージには適用されません。プラグインコードの強化はアプリではなく、プラグインのリポジトリ（podspec／Package.swift）で行います。
• 標準的な Capacitor アプリの App ターゲットは純粋な Swift です（AppDelegate.swift、SceneDelegate.swift）。Clang の警告やアナライザーのチェッカーが関係するのは、アプリのターゲットに .m、.mm、.c、または .cpp ファイルがある場合だけです。提案する前に使用言語を確認してください。
• Capacitor 8 のテンプレートでは、Stage A の警告がすでに 3 つプロジェクトレベルで設定されています（GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR、GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE、GCC_WARN_64_TO_32_BIT_CONVERSION = YES）。すでに強化済みとして報告してください。再度追加しないでください。
• WKWebView のコンテンツには影響しません。 JavaScript と JIT は WebKit 独自のプロセスで実行されます。Enhanced Security のエンタイトルメントは、アプリのプロセスと、アプリにリンクされたネイティブコード（Capacitor ランタイム、プラグイン、SDK）に適用されます。
• ポインター認証により、デバイスビルドに arm64e スライスが追加されます。 アプリにリンクされるすべてのバイナリにも arm64e が必要です。そうでない場合、リンクに失敗します。これが Capacitor アプリで主な破損リスクとなります。references/enhanced-security.md を参照してください。
• 生成されたファイルは編集しないでください。 ios/App/Pods/**、Pods-App.*.xcconfig、ios/App/CapApp-SPM/Package.swift、ios/capacitor-cordova-ios-plugins/**、ios/debug.xcconfig（SPM テンプレート、Debug のみ、CLI によって管理）は、CocoaPods または npx cap sync によって書き換えられます。設定は App プロジェクト（Xcode の Build Settings。project.pbxproj に書き込まれます）か、チームがすでに管理している xcconfig に記述してください。
• 最終的な判断はユーザーに委ねられます。 Enhanced Security により、潜在していたメモリーバグがクラッシュにつながることがあります。変更を加える前に調査結果を報告し、承認を得てください。リリース前に実機でテストしてください。

参考資料

トピックが関係する場合にのみ、該当する参考資料を読み込みます。

ファイル	読み込むタイミング
references/settings-catalog.md	監査テーブルの作成時：追跡対象の全設定、強化された値、言語の適用範囲、リスク
references/reading-build-settings.md	xcodebuild -showBuildSettings の実行、監査スクリプトの使用、「明示的に無効」と「デフォルトでオフ」の区別
references/enhanced-security.md	Enhanced Security 機能の有効化、エンタイトルメント、CocoaPods／SPM／バイナリ SDK 使用時のポインター認証、メモリータグ付け
references/plugin-authors.md	プラグインコードの強化：podspec の pod_target_xcconfig、Package.swift の警告設定、プラグインリポジトリの分析、arm64e xcframework の配布
references/decision-log.md	チームの決定文書の作成または更新

スクリプト：scripts/audit-build-settings.mjs は、xcodebuild -showBuildSettings -json の出力を追跡対象の設定に絞り込み、それぞれを強化済み、デフォルト、または明示的に設定済み（pbxproj が指定された場合）として示します。

ワークフロー

1. 概要を伝え、ソース管理を確認する

監査を先に行い、計画を作成し、ユーザーの承認を得るまで何も変更しないことを、2〜3 文でユーザーに伝えます。プロジェクトに git がない場合は、先にコミットするよう勧めます。ユーザーが断った場合は中止します。

2. 調査する（読み取り専用）

1. iOS プロジェクトを確認します：ios/App/App.xcodeproj が存在することを確認します。SPM（ios/App/CapApp-SPM/）と CocoaPods（ios/App/Podfile、App.xcworkspace）のどちらを使っているか記録します。
2. package.json（@capacitor/ios）から Capacitor のバージョンを読み取ります。Capacitor 8 のデプロイ対象は iOS 15、Capacitor 9 は iOS 16 で、Xcode 27 が必要です。
3. App ターゲットフォルダー内の言語を検出します：find ios/App/App -name '*.m' -o -name '*.mm' -o -name '*.c' -o -name '*.cpp'。また、C++／ObjC++ に上書きされたファイルの種類を検出するため、grep -E 'sourcecode\.cpp\.' ios/App/App.xcodeproj/project.pbxproj も実行します。
4. バイナリを含むネイティブ依存関係を一覧表示します：node_modules/**/ios/** 内の xcframework、プラグインの Package.swift ファイル内の binaryTarget、podspec 内の vendored_frameworks。
5. 既存の決定文書（ios/xcode-security-settings.md など）を探し、過去の決定を読みます。
6. Debug と Release の評価済み設定を読み取ります（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

7. 評価済みの CODE_SIGN_ENTITLEMENTS パスにあるエンタイトルメントファイルを読み取ります。標準テンプレートに何もないのは正常です。

3. 計画を作成して確認を求める

計画をチャット内（またはユーザー指定のファイル）に記載します。段階ごとにまとめ、該当する項目のみを示します：

段階	項目	デフォルト
A. コンパイラーの警告	セキュリティ警告 5 項目。ターゲットに C／ObjC／C++ が含まれる場合のみ	オン
B. 静的アナライザー	セキュリティチェッカーと clang-tidy チェック。アナライザーは Analyze 時にのみ実行されるため、ビルドへのリスクはありません	オン
C. Enhanced Security	プロジェクトレベルの機能、App ターゲットのエンタイトルメント、依存関係の計画に沿ったポインター認証	オン（依存関係の確認後）
D. メモリータグ付け	checked-allocations + soft-mode	オフ（提案する）
E. 追加の診断	警告量の多い設定	オフ（提案する）
F. 無効な設定	文書化された理由のない、明示的な = NO の各項目について確認する	オン

ユーザーに承認、編集、キャンセルのいずれかを求めます。ユーザーに判断を委ねるべき実際の選択事項：

• arm64e スライスのないバイナリ SDK：ポインター認証を App ターゲットでオフにする（Enhanced Security のその他の設定は維持）か、ベンダーの対応を待つ。
• CocoaPods：Pod ターゲットでポインター認証を有効にする post_install フックを追加するか、App ターゲットでオフにする。
• メモリータグ付け：対応ハードウェアでテストする計画がある場合に限る。

4. 1 段階ずつ適用する

• 設定は、設定がターゲットごとに異なる場合（エンタイトルメント、ポインター認証のオプトアウト）を除き、App.xcodeproj のプロジェクトレベルで適用し、すべてのターゲットに継承されるようにします。
• 推奨手順：Xcode（プロジェクト > ビルド設定 > すべて）で設定するようユーザーに依頼します。その後、project.pbxproj を grep で確認します。自分で project.pbxproj を編集する場合は、プロジェクト独自の Debug と Release の XCBuildConfiguration エントリー（PBXProject の buildConfigurationList に記載されているもの）の buildSettings ディクショナリーだけを編集し、KEY = VALUE; の構文を維持して、-showBuildSettings を再実行して確認します。
• App ターゲットで Signing & Capabilities > + Capability > Enhanced Security から Enhanced Security を追加します。これにより App.entitlements が作成または更新され、CODE_SIGN_ENTITLEMENTS が設定されます。詳細については、references/enhanced-security.md を参照してください。
• 各段階の後、次の段階に進む前にビルド（手順 5）します。段階によってビルドが失敗した場合は、その段階の変更を元に戻し、理由を判断ログに記録してから続行します。

5. 検証する

# 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

• 監査スクリプトを再実行します。承認済みの設定がすべて強化済みとして表示されます。
• シミュレーターのビルドが引き続き動作することを確認します。シミュレーター SDK には arm64e がなく、ビルドシステムがこれを除外します。シミュレーター専用のオプトアウトは追加しないでください。
• 実機でアプリを実行します。起動、プラグイン呼び出し、JS の pause ／ resume イベントを確認します。メモリータグ付けをソフトモードにした状態で、Xcode Organizer またはデバイスログ（ios-android-logs）からシミュレートされたクラッシュレポートを収集します。

6. 報告して記録する

有効にした項目、すでに強化済みだった項目、スキップした項目とその理由、arm64e を妨げている依存関係、リリース前にハードウェアでテストするためのアクションアイテムを報告します。その後、判断ドキュメント（references/decision-log.md）を更新します。

エラー処理

症状	原因	対処法
Enhanced Security を有効にした後、arm64e に関するメッセージが表示されてリンクに失敗する	pod、SPM パッケージ、または xcframework が arm64e なしでビルドされている	lipo -archs で特定します。ソース pod の場合は post_install フックを使用します。SPM ソースパッケージの場合は、ワークスペース設定 iOSPackagesShouldBuildARM64e を使用します。スライスのないバイナリの場合は、App ターゲットで ENABLE_POINTER_AUTHENTICATION = NO に設定し、ベンダーに問い合わせます。references/enhanced-security.md を参照してください
[CP] Embed Pods Frameworks で Sandbox: rsync(...) deny(1) file-write-create が発生する	CocoaPods のスクリプトフェーズで ENABLE_USER_SCRIPT_SANDBOXING = YES が設定されている	CocoaPods の使用中は App ターゲットで NO のままにし、理由を記録します。SPM への移行後（cocoapods-to-spm）に再検討します
ステージ A の後に新しい警告が大量に表示される	以前は警告が無効になっていた	まず実際のバグを修正します。警告が生成コードまたはベンダーコードに関するものなら、その警告は有効のままにし、そのコードへの対応は保留します。プロジェクト全体で -Werror を切り替えてはいけません
設定を変更したのに、-showBuildSettings には古い値が表示される	誤ったレベルで設定したか、ターゲットレベルの値がプロジェクト設定を上書きしている	Xcode でターゲットの列を確認します。理由がなければターゲットのオーバーライドを削除します
メモリータグ付けが原因で、新しいデバイスだけアプリの起動時にクラッシュする	ソフトモードを早く無効にしすぎたか、ネイティブライブラリにメモリーバグがある	ソフトモードを再度有効にしてレポートを収集し、ライブラリを修正または更新します（zip や SQLite など、同梱されている C コードが原因の場合がよくあります）
npx cap sync または pod install の後に編集内容が消えた	生成ファイルを編集した	設定を App プロジェクト、またはプラグイン独自の podspec ／ Package.swift に移します

関連スキル

• capacitor-security：ATS、署名、シークレット、WebView、ストレージのセキュリティ
• cocoapods-to-spm：SPM により pod 関連の強化に伴う摩擦を大幅に軽減します
• capacitor-plugin-spm-support：プラグインの Package.swift のレイアウト
• ios-android-logs：デバイスからクラッシュレポートとメモリータグ付けレポートを取得します