capacitor-security
App-level security audit and hardening for Capacitor apps. Use when the user wants a security review, OWASP MASVS check, or pentest fixes; runs the Capgo scanner (npx @capgo/capgo-sec scan, capsec, rule IDs like SEC001, NET003, CAP004); finds API keys or .env values in the web bundle; stores tokens in @capacitor/preferences or localStorage; needs Keychain/Keystore storage, certificate pinning, CSP, or root/jailbreak detection; or sees server.cleartext, allowNavigation, webContentsDebuggingEnabled, NSAllowsArbitraryLoads, android:usesCleartextTraffic, android:allowBackup, net::ERRCLEARTEXTNOTPERMITTED, or ATS "requires the use of a secure connection" errors. Do not use for Xcode build-setting hardening (use capacitor-ios-security-hardening), deep link setup (capacitor-deep-linking), App Store review (capacitor-apple-review-preflight), CI design (capacitor-ci-cd), or live update setup (capgo-live-updates).
- Installs
- 1.2K
- 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-security- 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-security 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 Security
Audit and harden the app layer of a Capacitor app: secrets in the bundle, on-device storage, network transport, WebView and native bridge exposure, and platform manifests.
When to Use
TRIGGER when:
- The user asks for a security audit, OWASP Mobile Top 10 / MASVS review, or wants to fix pentest findings.
- The user wants to run or interpret
@capgo/capgo-sec(capsec) results, rule IDs such asSEC001,STO002,NET003,CAP004,AND004,IOS001. - API keys, service-role keys, or
.envvalues appear insrc/,dist/,www/, orcapacitor.config.*. - Auth tokens are stored with
Preferences.set,localStorage, IndexedDB, or plain SQLite. capacitor.config.*containsserver.cleartext: true,server.url, broadserver.allowNavigation,android.allowMixedContent, orwebContentsDebuggingEnabled: true.- Native files contain
NSAllowsArbitraryLoads,android:usesCleartextTraffic="true",android:allowBackup="true",android:debuggable, or exported components without permissions. - The user needs certificate pinning, a Content Security Policy, screenshot protection, or root/jailbreak detection.
Do not use:
- Xcode build settings, Enhanced Security, pointer authentication, stack/heap hardening ->
capacitor-ios-security-hardening. - Universal Links / App Links setup ->
capacitor-deep-linking(this skill only covers validating incoming URLs). - Privacy manifests, App Review rejections ->
capacitor-apple-review-preflight; store listing ->capacitor-app-store. - Pipeline structure and signing secrets in CI ->
capacitor-ci-cd. - Live update installation and channels ->
capgo-live-updates(this skill covers only bundle encryption). - Runtime crashes and WebView inspection ->
debugging-capacitor.
Workflow
- Inspect before editing. Read
capacitor.config.ts|json,package.json(Capacitor major, installed plugins),android/app/src/main/AndroidManifest.xml,android/app/src/main/res/xml/network_security_config.xml(if any),ios/App/App/Info.plist,*.entitlements, andindex.html. - Scan. Run the Capgo scanner from the project root (Node 18+):
The npm package is
npx @capgo/capgo-sec@latest scan --severity medium@capgo/capgo-sec; it installs acapsecbinary.npx capsecdoes not work because no package namedcapsecexists on npm. - Grep for what scanners miss (see Verification). Build the web app first and also grep
dist/orwww/: bundlers inlineimport.meta.env.*andprocess.env.*values. - Triage and report before invasive changes. Group findings by Critical/High/Medium/Low with file and line. Ask the user before changes that alter behavior: certificate pinning (can lock out users when certs rotate), blocking rooted devices, removing
allowNavigationhosts, a strict CSP. - Fix by area, loading the matching reference below.
- Re-run the scan and Verification checks, then
npx cap syncand test a release build on a device.
Capacitor-specific traps
- Nothing in the bundle is secret. Web assets ship inside the IPA/APK and
capacitor.config.jsonis copied into native assets. Values inplugins.*config (including@capgo/capacitor-env) are extractable. Move secret-bearing calls to a backend. allowNavigationgrants bridge access. On Android, everyallowNavigationentry is added to the bridge's allowed origin rules, so pages from those hosts can call your native plugins. Only list hosts you control. Open third-party pages with@capacitor/browseror@capgo/inappbrowserinstead.server.urlandserver.cleartextare dev-only. Capacitor documents both as "not intended for use in production." A committed LAN IP ships a WebView that loads remote code over HTTP.- Debuggable WebView in release.
ios.webContentsDebuggingEnabled/android.webContentsDebuggingEnableddefault to on only in debug builds. A hardcodedtrueexposes the WebView to Safari /chrome://inspecton any release build. - CapacitorHttp is not pinning.
plugins.CapacitorHttp.enabledonly routesfetch/XHR through native networking. Pinning requires@capgo/capacitor-ssl-pinning, which hooks into CapacitorHttp. - Biometric prompt is not authentication.
verifyIdentity()can be hooked on rooted/jailbroken devices. Keep secrets behindaccessControl(hardware-bound Keychain/Keystore item) and validate sessions server-side. - OAuth via custom schemes needs PKCE. Any app can register
myapp://. Use PKCE and prefer Universal/App Links for redirects. - Live update bundles are public unless encrypted. Private channels limit who receives a bundle. They do not make it confidential.
References
Only load a reference when its topic is in play.
| Reference | Load when |
|---|---|
| references/capsec-scanner.md | Running the scanner, reading rule IDs, CI gating, JSON/HTML reports |
| references/secrets-and-storage.md | Hardcoded keys, .env leakage, token storage, Keychain/Keystore, encrypted SQLite, logging |
| references/network.md | HTTPS/ATS/cleartext, network_security_config.xml, certificate pinning, CORS vs CapacitorHttp |
| references/webview-and-bridge.md | CSP, allowNavigation, iframes, postMessage, eval, deep link/OAuth validation |
| references/platform-hardening.md | AndroidManifest flags, R8, iOS Info.plist/entitlements, screenshot protection, root/jailbreak detection, live update encryption |
Xcode compiler/linker hardening is not covered here: use capacitor-ios-security-hardening.
Verification
Run from the project root. Each grep should return nothing for a release build, or only intentional, documented hits.
# 1. Scanner gate (exit code 1 on high/critical)
npx @capgo/capgo-sec@latest scan --ci
# 2. Dev-only config left in capacitor.config
grep -nE "cleartext|server:\s*\{|\"url\"|url:|allowMixedContent|webContentsDebuggingEnabled" capacitor.config.*
# 3. Secrets in the built bundle (build first)
npm run build
grep -rnE "sk_live_|sk-ant-|sk-proj-|AKIA[0-9A-Z]{16}|service_role|-----BEGIN (RSA |EC )?PRIVATE KEY" dist/ www/ 2>/dev/null
# 4. Tokens in plain storage
grep -rnE "(Preferences\.set|localStorage\.setItem)\(.*(token|password|secret|jwt)" -i src/
# 5. Android manifest flags
grep -nE "usesCleartextTraffic|allowBackup|debuggable|exported=\"true\"" android/app/src/main/AndroidManifest.xml
# 6. iOS transport and file sharing
plutil -p ios/App/App/Info.plist | grep -E "NSAllowsArbitraryLoads|NSExceptionAllowsInsecureHTTPLoads|UIFileSharingEnabled|LSSupportsOpeningDocumentsInPlace"
# 7. Native projects pick up config changes
npx cap sync
Then install a release build on a device and confirm: login works, API calls succeed (pinning did not break them), Safari Web Inspector / chrome://inspect cannot attach.
Error handling
| Error | Cause | Fix |
|---|---|---|
net::ERR_CLEARTEXT_NOT_PERMITTED (Android) | HTTP request blocked; cleartext is off by default since API 28 | Use HTTPS. For dev live reload only, use server.cleartext: true in a dev-only config. Never ship usesCleartextTraffic="true". |
The resource could not be loaded because the App Transport Security policy requires the use of a secure connection. (iOS, NSURLError -1022) | HTTP URL under ATS | Use HTTPS. If a legacy host is unavoidable, add a narrow NSExceptionDomains entry, never NSAllowsArbitraryLoads. |
... has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present | Backend does not allow the WebView origin | Allow capacitor://localhost (iOS) and https://localhost (Android default) on the server, or enable CapacitorHttp. Do not add Access-Control-Allow-Origin: * to authenticated endpoints. |
Refused to connect to '<url>' because it violates the following Content Security Policy directive | CSP connect-src missing a host | Add the exact API origin to connect-src. Do not fall back to *. |
| Pinned requests fail after a certificate renewal | Pin matched only the old leaf cert | Pin the CA or intermediate plus a backup cert; ship the backup before rotating. |
npm error 404 Not Found - GET https://registry.npmjs.org/capsec | Wrong package name | Use npx @capgo/capgo-sec@latest scan. |
No protected credentials found / No protected data found (code 21, @capgo/capacitor-native-biometric) | Nothing stored with accessControl, fresh install, or the item was invalidated by a biometric enrollment change | Treat as "logged out": re-authenticate against the server, then store again with AccessControl.BIOMETRY_CURRENT_SET or BIOMETRY_ANY. |
Resources
- Capacitor security guide: https://capacitorjs.com/docs/guides/security
- Capgo security scanner: https://capgo.app/security-scanner/ (source: https://github.com/Cap-go/capgo-sec)
- OWASP Mobile Top 10: https://owasp.org/www-project-mobile-top-10/
- OWASP MASVS / MASTG: https://mas.owasp.org/
FAQ
What does the capacitor-security skill do?
App-level security audit and hardening for Capacitor apps. Use when the user wants a security review, OWASP MASVS check, or pentest fixes; runs the Capgo scanner (npx @capgo/capgo-sec scan, capsec, rule IDs like SEC001, NET003, CAP004); finds API keys or .env values in the web bundle; stores tokens in @capacitor/preferences or localStorage; needs Keychain/Keystore storage, certificate pinning, CSP, or root/jailbreak detection; or sees server.cleartext, allowNavigation, webContentsDebuggingEnabled, NSAllowsArbitraryLoads, android:usesCleartextTraffic, android:allowBackup, net::ERRCLEARTEXTNOTPERMITTED, or ATS "requires the use of a secure connection" errors. Do not use for Xcode build-setting hardening (use capacitor-ios-security-hardening), deep link setup (capacitor-deep-linking), App Store review (capacitor-apple-review-preflight), CI design (capacitor-ci-cd), or live update setup (capgo-live-updates).
How do I install capacitor-security?
Run npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-security 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-security/ (personal) or .claude/skills/capacitor-security/ (project).
Which AI agents can use capacitor-security?
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-security 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-security?
It is published by cap-go in cap-go/capgo-skills. It has 1,221 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 security skills
azure-compliance
microsoft/azure-skills
Run Azure compliance and security audits with azqr plus Key Vault expiration checks. Covers best-practice assessment, resource review, policy/compliance validation, and security posture checks. WHEN: compliance scan, security audit, BEFORE running azqr (compliance cli tool), Azure best practices, Key Vault expiration check, expired certificates, expiring secrets, orphaned resources, compliance assessment.
minimal-run-and-audit
lllllllama/rigorpilot-skills
Rigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation command and write standardized reprooutputs/ files, including patch notes when repository files changed. Do not use for training execution, initial repo intake, generic environment setup, paper lookup, target selection, hidden scientific-meaning changes, or end-to-end orchestration by itself.
seo-audit
coreyhaines31/marketingskills
When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," "indexing issues," "stuck on page 2," "striking distance keywords," "title tag rewrite," "low CTR," "local SEO," "Google Business Profile," or "map pack." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema. For AI search optimization, see ai-seo.
firebase-security-rules-auditor
firebase/agent-skills
Audits Firebase (Firestore, Cloud Storage) security rules for vulnerabilities, privilege escalation, role bypasses, create vs update inconsistencies, resource exhaustion, type safety, size limits, and hasOnly ownership checks. Use when auditing/reviewing rules, running red-team rule assessments, or scoring against auditor checklists. Don't use for Firebase CLI (login, deploy), Auth, Crashlytics, Remote Config, or database queries.
audit
pbakaus/impeccable
Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review.
competitors
coreyhaines31/marketingskills
When the user wants to create competitor comparison or alternative pages for SEO and buyer-facing use. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' 'competitive landing pages,' 'how do we compare to X,' 'competitor teardown,' 'audit our competitor pages,' 'are our comparison pages out of date,' or 'competitive asset audit.' Use this for any content that positions your product against competitors. Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. For auditing existing claims (not researching competitors from scratch, which is competitor-profiling; not technical SEO on these pages, which is seo-audit), use the asset audit here. For internal battle cards and sales-specific competitor docs, see sales-enablement.