cap-go/capgo-skills

capacitor-security

App-level security audit and hardening for Capacitor apps.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-security

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

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 as SEC001, STO002, NET003, CAP004, AND004, IOS001.
  • API keys, service-role keys, or .env values appear in src/, dist/, www/, or capacitor.config.*.
  • Auth tokens are stored with Preferences.set, localStorage, IndexedDB, or plain SQLite.
  • capacitor.config.* contains server.cleartext: true, server.url, broad server.allowNavigation, android.allowMixedContent, or webContentsDebuggingEnabled: 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

  1. 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, and index.html.
  2. Scan. Run the Capgo scanner from the project root (Node 18+):
bash
   npx @capgo/capgo-sec@latest scan --severity medium

The npm package is @capgo/capgo-sec; it installs a capsec binary. npx capsec does not work because no package named capsec exists on npm.

  1. Grep for what scanners miss (see Verification). Build the web app first and also grep dist/ or www/: bundlers inline import.meta.env.* and process.env.* values.
  2. 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 allowNavigation hosts, a strict CSP.
  3. Fix by area, loading the matching reference below.
  4. Re-run the scan and Verification checks, then npx cap sync and 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.json is copied into native assets. Values in plugins.* config (including @capgo/capacitor-env) are extractable. Move secret-bearing calls to a backend.
  • `allowNavigation` grants bridge access. On Android, every allowNavigation entry 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/browser or @capgo/inappbrowser instead.
  • `server.url` and `server.cleartext` are 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.webContentsDebuggingEnabled default to on only in debug builds. A hardcoded true exposes the WebView to Safari / chrome://inspect on any release build.
  • CapacitorHttp is not pinning. plugins.CapacitorHttp.enabled only routes fetch/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 behind accessControl (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.

ReferenceLoad when
references/capsec-scanner.mdRunning the scanner, reading rule IDs, CI gating, JSON/HTML reports
references/secrets-and-storage.mdHardcoded keys, .env leakage, token storage, Keychain/Keystore, encrypted SQLite, logging
references/network.mdHTTPS/ATS/cleartext, network_security_config.xml, certificate pinning, CORS vs CapacitorHttp
references/webview-and-bridge.mdCSP, allowNavigation, iframes, postMessage, eval, deep link/OAuth validation
references/platform-hardening.mdAndroidManifest 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.

bash
# 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 (filenames only; never print matching values)
npm run build
grep -rlE "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

ErrorCauseFix
net::ERR_CLEARTEXT_NOT_PERMITTED (Android)HTTP request blocked; cleartext is off by default since API 28Use 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 ATSUse 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 presentBackend does not allow the WebView originAllow 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 directiveCSP connect-src missing a hostAdd the exact API origin to connect-src. Do not fall back to *.
Pinned requests fail after a certificate renewalPin matched only the old leaf certPin the CA or intermediate plus a backup cert; ship the backup before rotating.
npm error 404 Not Found - GET https://registry.npmjs.org/capsecWrong package nameUse 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 changeTreat 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/
aus demselben Repository

Weitere Skills

Alle Skills
cap-go
Community

capacitor-best-practices

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 d

Installationen / 1h
2
GitHub Stars
79
Aktualisiert
12. Nov.
cap-go
Community

capacitor-deep-linking

Implements and debugs deep links in Capacitor apps - custom URL schemes, iOS Universal Links (apple-app-site-association, Associated Domains entitlement), Android App Links (assetlinks.json, autoVerify), and routing via @capacitor/app appUrlOpen + App.getLaunchUrl(). Covers the Capacitor 8.5+ UIScene change where AppDelegate application(:open:options:) and continue userActivity stop being called and custom handling must move to SceneDelegate, plus cold vs warm launch testing. Use when links open

Installationen / 1h
2
GitHub Stars
77
Aktualisiert
17. Okt.
cap-go
Community

debugging-capacitor

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 Studi

Installationen / 1h
2
GitHub Stars
74
Aktualisiert
17. Okt.
cap-go
Community

capacitor-plugins

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

Installationen / 1h
2
GitHub Stars
74
Aktualisiert
17. Okt.