用 Capsec 对 Capacitor/Ionic…

当需要为 Capacitor/Ionic 应用做安全审计、排查硬编码密钥、加固存储/网络/认证/加密/WebView 及 iOS/Android 平台配置时使用。

适用场景

解决思路

1. 运行安全扫描：`npx capsec scan` 扫描当前目录（无需安装），或 `npx capsec scan ./my-app` 扫描指定路径；CI 模式用 `npx capsec scan --ci`（发现 high/critical 问题时退出码为 1）。
2. 选择输出格式：默认 CLI 输出；JSON 报告用 `npx capsec scan --output json --output-file report.json`；HTML 报告用 `npx capsec scan --output html --output-file security-report.html`。
3. 过滤扫描结果：用 `--severity high` 只看 critical/high；用 `--categories secrets,network,storage` 限定类别；用 `--exclude "**/test/**,**/*.spec.ts"` 排除测试文件。
4. 修复密钥泄露（SEC001/SEC002）：不要把 API Key 硬编码在代码里，改用环境变量，例如 `import { Env } from '@capgo/capacitor-env'; const API_KEY = await Env.get({ key: 'API_KEY' });`。
5. 修复存储安全（STO001-STO006）：不要用 Preferences/localStorage 明文存 token，改用安全存储，例如 `NativeBiometric.setCredentials({ username: email, password: token, server: 'api.myapp.com' })`；SQLite 需加密，凭据必须用 Keychain/Keystore。
6. 修复网络安全（NET001-NET008）：生产环境禁用明文流量，Capacitor 配置中设置 `server: { cleartext: false, allowNavigation: ['https://api.myapp.com'] }`；启用 SSL/TLS 证书固定；避免 WebSocket 不安全连接、CORS 通配符、URL 参数传敏感数据。
7. 修复 Capacitor 特有问题（CAP001-CAP010）：生产环境关闭 WebView 调试（`webContentsDebuggingEnabled: process.env.NODE_ENV === 'development'`）；限制 allowNavigation；避免原生桥暴露、对用户输入使用 eval、不安全的 postMessage 处理；启用 root/越狱检测；注意 live update 安全。
8. 修复 Android 安全（AND001-AND008）：在 AndroidManifest.xml 中设置 `android:usesCleartextTraffic="false"`、`android:allowBackup="false"`、`android:networkSecurityConfig="@xml/network_security_config"`；通过 network_security_config.xml 配置域名级明文禁用与证书 pin（`<pin digest="SHA-256">your-pin-hash</pin>`）；不要硬编码签名密钥；限制导出组件权限。
9. 修复 iOS 安全（IOS001-IOS008）：不要用 `NSAllowsArbitraryLoads` 全局关闭 ATS，改为在 Info.plist 中仅对特定域名设置 `NSExceptionDomains` 并指定 `NSExceptionMinimumTLSVersion` 为 TLSv1.2；安全使用 Keychain；校验 URL Scheme；避免粘贴板泄露敏感数据；配置正确的 entitlements；启用越狱检测；敏感页面禁用截屏。
10. 修复认证问题（AUTH001-AUTH006）：用 `jwt.verify(token, publicKey, { algorithms: ['RS256'], issuer: 'https://auth.myapp.com', audience: 'myapp' })` 校验 JWT 签名，而非仅 `jwt.decode`；安全实现生物识别；使用强随机数；设置会话超时；OAuth 必须带 state 参数；不要硬编码凭据。
11. 修复 WebView 安全（WEB001-WEB005）：在 index.html 添加 CSP meta 标签，例如 `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';`；避免 JS 注入、不安全 iframe、外部脚本加载；`target="_blank"` 加 `noopener`。
12. 修复加密问题（CRY001-CRY004）：用 AES-GCM 替代 DES 等弱算法（`CryptoJS.AES.encrypt(data, key, { mode: CryptoJS.mode.GCM, padding: CryptoJS.pad.Pkcs7 })`）；不要硬编码密钥，用 PBKDF2 派生（`crypto.subtle.deriveKey({ name: 'PBKDF2', salt, iterations: 100000, hash: 'SHA-256' }, baseKey, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt'])`）；使用安全随机 IV；用强密码哈希。
13. 修复日志问题（LOG001/LOG002）：不要 `console.log` 密码或 token，改为记录脱敏信息（如 userId）；生产环境移除 console 日志，或用 `if (process.env.NODE_ENV === 'development')` 包裹调试日志。
14. 集成 CI/CD：GitHub Actions 中在 checkout 与 setup-node 后运行 `npx capsec scan --ci --output json --output-file security-report.json`，并用 `actions/upload-artifact@v4`（`if: always()`）上传报告；GitLab CI 中用 node:20 镜像运行 `npx capsec scan --ci` 并将 `security-report.json` 作为 security 报告 artifacts，仅在 merge_requests 和 main 上运行。
15. 配置扫描：运行 `npx capsec init` 生成 capsec.config.json，在其中设置 `exclude`（如 `**/node_modules/**`、`**/dist/**`、`**/*.test.ts`、`**/*.spec.ts`）、`severity`、`categories`，并按规则覆盖，例如 `"LOG002": { "enabled": false }`、`"SEC001": { "severity": "critical" }`。
16. 实现 root/越狱检测：使用 `import { IsRoot } from '@capgo/capacitor-is-root'; const { isRooted } = await IsRoot.isRooted();`，检测到后按需警告用户、限制敏感功能或直接阻止应用运行。
17. 发布前执行检查清单：运行 `npx capsec scan --severity high`；移除所有 console.log；关闭 WebView 调试；移除开发用 URL；确认无硬编码密钥；启用证书固定；实现 root/越狱检测；添加 CSP；凭据使用安全存储；Android 启用 ProGuard；核对 iOS ATS 设置。
18. 持续维护：在 CI/CD 中定期运行安全扫描；监控新漏洞；定期更新依赖；审查第三方插件；审计认证流程。

适用边界 · 注意事项

• 非 Capacitor/Ionic 项目（如纯 Web、React Native、原生 Android/iOS）不适用，因为规则针对 Capacitor 配置与插件。
• 需要依赖 Capsec 扫描器及 Capgo 系列插件（capacitor-env、capacitor-native-biometric、capacitor-is-root）时，属于特定工具链场景。