name: capacitor-security
description: Comprehensive security guide for Capacitor apps using Capsec scanner. Covers 63+ security rules across secrets, storage, network, authentication, cryptography, and platform-specific vulnerabilities. Use this skill when users need to secure their mobile app or run security audits.

Capacitor Security with Capsec

Zero-config security scanning for Capacitor and Ionic apps.

When to Use This Skill

• User wants to secure their app
• User asks about security vulnerabilities
• User needs to run security audit
• User has hardcoded secrets
• User needs CI/CD security scanning
• User asks about OWASP mobile security

Quick Start with Capsec

Run Security Scan

# Scan current directory (no installation needed)
bunx capsec scan

# Scan specific path
bunx capsec scan ./my-app

# CI mode (exit code 1 on high/critical issues)
bunx capsec scan --ci

Output Formats

# CLI output (default)
bunx capsec scan

# JSON report
bunx capsec scan --output json --output-file report.json

# HTML report
bunx capsec scan --output html --output-file security-report.html

Filtering

# Only critical and high severity
bunx capsec scan --severity high

# Specific categories
bunx capsec scan --categories secrets,network,storage

# Exclude test files
bunx capsec scan --exclude "**/test/**,**/*.spec.ts"

Security Rules Reference

Secrets Detection (SEC)

What Capsec Detects:
- AWS Access Keys
- Google API Keys
- Firebase Keys
- Stripe Keys
- GitHub Tokens
- JWT Secrets
- Database Credentials
- 30+ secret patterns

Fix Example:

// BAD - Hardcoded API key
const API_KEY = 'sk_live_abc123xyz';

// GOOD - Use environment variables
import { Env } from '@capgo/capacitor-env';
const API_KEY = await Env.get({ key: 'API_KEY' });

Storage Security (STO)

Fix Example:

// BAD - Plain preferences for tokens
import { Preferences } from '@capacitor/preferences';
await Preferences.set({ key: 'auth_token', value: token });

// GOOD - Use secure storage
import { NativeBiometric } from '@capgo/capacitor-native-biometric';
await NativeBiometric.setCredentials({
  username: email,
  password: token,
  server: 'api.myapp.com',
});

Network Security (NET)

Fix Example:

// BAD - HTTP in production
const config: CapacitorConfig = {
  server: {
    cleartext: true,  // Never in production!
  },
};

// GOOD - HTTPS only
const config: CapacitorConfig = {
  server: {
    cleartext: false,
    // Only allow specific domains
    allowNavigation: ['https://api.myapp.com'],
  },
};

Capacitor-Specific (CAP)

Fix Example:

// BAD - Debug mode in production
const config: CapacitorConfig = {
  ios: {
    webContentsDebuggingEnabled: true,  // Remove in production!
  },
  android: {
    webContentsDebuggingEnabled: true,  // Remove in production!
  },
};

// GOOD - Only in development
const config: CapacitorConfig = {
  ios: {
    webContentsDebuggingEnabled: process.env.NODE_ENV === 'development',
  },
};

Android Security (AND)

Fix AndroidManifest.xml:

<!-- BAD -->
<application android:usesCleartextTraffic="true">

<!-- GOOD -->
<application
    android:usesCleartextTraffic="false"
    android:allowBackup="false"
    android:networkSecurityConfig="@xml/network_security_config">

network_security_config.xml:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="false">
        <domain includeSubdomains="true">api.myapp.com</domain>
        <pin-set>
            <pin digest="SHA-256">your-pin-hash</pin>
        </pin-set>
    </domain-config>
</network-security-config>

iOS Security (IOS)

Fix Info.plist:

<!-- BAD - Disables ATS -->
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

<!-- GOOD - Specific exceptions only -->
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>legacy-api.example.com</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSExceptionMinimumTLSVersion</key>
            <string>TLSv1.2</string>
        </dict>
    </dict>
</dict>

Authentication (AUTH)

Fix Example:

// BAD - No JWT validation
const decoded = jwt.decode(token);

// GOOD - Verify JWT signature
const decoded = jwt.verify(token, publicKey, {
  algorithms: ['RS256'],
  issuer: 'https://auth.myapp.com',
  audience: 'myapp',
});

WebView Security (WEB)

Fix - Add CSP:

<!-- index.html -->
<meta http-equiv="Content-Security-Policy" content="
  default-src 'self';
  script-src 'self';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: https:;
  connect-src 'self' https://api.myapp.com;
  font-src 'self';
  frame-ancestors 'none';
">

Cryptography (CRY)

Fix Example:

// BAD - Weak algorithm
const encrypted = CryptoJS.DES.encrypt(data, key);

// GOOD - Strong algorithm
const encrypted = CryptoJS.AES.encrypt(data, key, {
  mode: CryptoJS.mode.GCM,
  padding: CryptoJS.pad.Pkcs7,
});

// BAD - Hardcoded key
const key = 'my-secret-key-123';

// GOOD - Derived key
const key = await crypto.subtle.deriveKey(
  { name: 'PBKDF2', salt, iterations: 100000, hash: 'SHA-256' },
  baseKey,
  { name: 'AES-GCM', length: 256 },
  false,
  ['encrypt', 'decrypt']
);

Logging (LOG)

Fix Example:

// BAD - Logging sensitive data
console.log('User password:', password);
console.log('Token:', authToken);

// GOOD - Redact sensitive data
console.log('User authenticated:', userId);
// Use conditional logging
if (process.env.NODE_ENV === 'development') {
  console.debug('Debug info:', data);
}

CI/CD Integration

GitHub Actions

name: Security Scan

on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v1

      - name: Run Capsec Security Scan
        run: bunx capsec scan --ci --output json --output-file security-report.json

      - name: Upload Security Report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: security-report
          path: security-report.json

GitLab CI

security-scan:
  image: oven/bun:latest
  script:
    - bunx capsec scan --ci
  artifacts:
    reports:
      security: security-report.json
  only:
    - merge_requests
    - main

Configuration

capsec.config.json

{
  "exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/*.test.ts",
    "**/*.spec.ts"
  ],
  "severity": "low",
  "categories": [],
  "rules": {
    "LOG002": {
      "enabled": false
    },
    "SEC001": {
      "severity": "critical"
    }
  }
}

Initialize Config

bunx capsec init

Root/Jailbreak Detection

import { IsRoot } from '@capgo/capacitor-is-root';

async function checkDeviceSecurity() {
  const { isRooted } = await IsRoot.isRooted();

  if (isRooted) {
    // Option 1: Warn user
    showWarning('Device security compromised');

    // Option 2: Restrict features
    disableSensitiveFeatures();

    // Option 3: Block app (for high-security apps)
    blockApp();
  }
}

Security Checklist

Before Release

• [ ] Run bunx capsec scan --severity high
• [ ] Remove all console.log statements
• [ ] Disable WebView debugging
• [ ] Remove development URLs
• [ ] Verify no hardcoded secrets
• [ ] Enable certificate pinning
• [ ] Implement root/jailbreak detection
• [ ] Add Content Security Policy
• [ ] Use secure storage for credentials
• [ ] Enable ProGuard (Android)
• [ ] Verify ATS settings (iOS)

Ongoing

• [ ] Run security scans in CI/CD
• [ ] Monitor for new vulnerabilities
• [ ] Update dependencies regularly
• [ ] Review third-party plugins
• [ ] Audit authentication flows

Resources

• Capsec Documentation: https://capacitor-sec.dev
• OWASP Mobile Top 10: https://owasp.org/www-project-mobile-top-10
• OWASP MASTG: https://mas.owasp.org/MASTG
• Capgo Security Plugins: https://capgo.app