LinaYoun avatar

tdd-flutter-security

Flutter development plugin that use TDD and security policy

version
1.0

Install

/plugin install tdd-flutter-security@Rose-Security

Run it inside Claude Code after adding the marketplace with /plugin marketplace add LinaYoun/tdd-flutter-security.

Contents

Discovered from source

Skills 1

Flutter Android Security Guide

This skill provides comprehensive security guidance for Flutter Android applications based on the Korean Ministry of Public Administration and Security (MOIS) and KISA mobile security guidelines.

Note: 이 스킬은 Android 전용입니다. iOS 보안 가이드는 별도로 제공됩니다. (This skill is Android-only. iOS security guide is provided separately.)

Overview

Mobile application security encompasses multiple layers: platform configuration, data storage, network communication, and source code protection. This skill helps you audit and secure Flutter apps across all these dimensions.

Quick Security Checklist

Before releasing your Flutter app, verify these critical items:

Build Environment

📅 Update Policy: 빌드 환경 요구사항은 Flutter/AGP/Gradle 릴리스마다 변경됩니다. 아래 내용은 참조용이며, 반드시 공식 문서를 확인하세요.

Source of Truth:

Build Environment Requirements
Java/Gradle 버전 (Flutter 3.38+ 기준)
AGP 호환성

⚠️ AGP 9 마이그레이션 안내:

  • Flutter의 AGP 9 완전 자동 지원은 진행 중이며, 현재는 수동 마이그레이션이 필요합니다.
  • 플러그인 사용 앱은 추가 설정이 필요할 수 있습니다.
  • 자세한 내용은 Flutter AGP 9 Migration Guide 참조.
  • Variant API 변경 (AGP 9+): Variant.minSdkVersion → minSdk로 대체 (AGP 9 Release Notes)
minSdk 권장 기준
요구사항최소 SDK비고
TLS 1.2 지원21+네트워크 보안 필수
EncryptedSharedPreferences23+flutter_secure_storage 사용 시

권장: 보안 저장소(flutter_secure_storage) 사용 시 minSdk 23+

AndroidManifest.xml

  • android:allowBackup="false" - ADB 백업 방지 (⚠️ targetSdk 31+ (Android 12+) 및 일부 제조사 기기에서는 device-to-device 이전을 완전히 차단하지 않음 - dataExtractionRules도 함께 설정 필요)
  • Android 12+: android:dataExtractionRules 설정 - 클라우드 백업 및 device-to-device 이전 시 복사할 파일/디렉터리 규정 (Android 문서)
  • android:debuggable="false" in release builds
  • android:usesCleartextTraffic="false" 명시 - targetSdk 27 이하는 기본값이 true (Android 문서)
  • All exported components explicitly declared with android:exported
  • Minimum necessary permissions only

Data Storage

  • No sensitive data in SharedPreferences
  • Using flutter_secure_storage for credentials/tokens
  • Database encryption enabled for sensitive data
  • File permissions set to MODE_PRIVATE

Network Security

  • All API calls use HTTPS
  • SSL/TLS certificate validation enabled
  • Certificate pinning implemented for critical endpoints
  • Network security config blocks cleartext traffic

Code Protection

  • Obfuscation enabled (--obfuscate --split-debug-info)
  • ProGuard/R8 configured for release builds
  • All debug logs removed in release
  • No hardcoded API keys, secrets, or passwords

Platform Security

  • Root detection implemented
  • Implicit intents secured
  • Sensitive broadcasts use secure alternatives (Provider, Stream, EventBus)

Security Domains

1. AndroidManifest.xml Security

The AndroidManifest.xml is the first line of defense. Critical settings include:

<application
    android:allowBackup="false"
    android:debuggable="false"
    android:usesCleartextTraffic="false">

Key Points:

  • allowBackup="false" prevents ADB backup data extraction attacks
  • debuggable="false" prevents debugger attachment in production
  • usesCleartextTraffic="false" enforces HTTPS-only communication
  • Always explicitly set android:exported for all activities, services, and receivers

See: references/android-manifest-security.md for detailed configuration.

2. Data Storage Security

Never store sensitive information in plain text:

// BAD: Plain SharedPreferences
final prefs = await SharedPreferences.getInstance();
prefs.setString('token', userToken); // INSECURE!

// GOOD: Encrypted storage
final storage = FlutterSecureStorage();
await storage.write(key: 'token', value: userToken);

Recommended Packages:

  • flutter_secure_storage - Keychain (iOS) / EncryptedSharedPreferences (Android)
  • sqlcipher_flutter_libs - SQLite encryption
  • hive with encryption - Encrypted NoSQL storage

See: references/data-storage-security.md for implementation details.

3. Network Security

All network communication must be encrypted and validated:

Certificate Pinning (Android)

⚠️ 중요 경고: badCertificateCallback의 한계

Dart의 badCertificateCallback은 "인증서 오류 시에만" 호출됩니다. 신뢰할 수 있는 CA(Let's Encrypt, DigiCert 등)에서 발급된 유효한 인증서는 이 콜백을 트리거하지 않습니다. 따라서 Dart 코드만으로는 실제 핀닝이 적용되지 않습니다!

Scope note: Dart-only checks (e.g., badCertificateCallback or Dart libraries) are not equivalent to Android <pin-set> pinning. Treat Dart-only logic as supplementary detection only; do not rely on it for MITM protection or compliance.

✅ 권장 방법: Android network_security_config.xml의 <pin-set> 사용

<!-- android/app/src/main/res/xml/network_security_config.xml -->
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">api.example.com</domain>
        <!-- expiration: 인증서 갱신 예상일 + 최소 1년으로 설정 권장 -->
        <pin-set expiration="2027-12-31">
            <pin digest="SHA-256">base64EncodedSPKIFingerprint=</pin>
            <pin digest="SHA-256">backupBase64EncodedSPKIFingerprint=</pin>
        </pin-set>
    </domain-config>
</network-security-config>

Requirements:

  • TLS 1.2+ only (server-side configuration; see references/network-security.md § TLS Configuration)
  • minSdk 21+ to ensure device supports TLS 1.2
  • Certificate pinning for authentication endpoints
  • Network security config for Android

See: references/network-security.md for complete configuration.

4. Source Code Protection

Protect your compiled application from reverse engineering:

# Build with obfuscation
flutter build apk --release \
  --obfuscate \
  --split-debug-info=build/debug-info

build.gradle Configuration:

buildTypes {
    release {
        minifyEnabled true
        shrinkResources true
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
}

See: references/code-protection.md for obfuscation and ProGuard setup.

5. Platform Security

Detect compromised devices and secure platform interactions:

// Root/Jailbreak Detection
import 'package:flutter_jailbreak_detection/flutter_jailbreak_detection.dart';

final isCompromised = await FlutterJailbreakDetection.jailbroken;
if (isCompromised) {
  // Handle compromised device
}

Intent Security:

  • Use explicit intents with component names
  • Validate all incoming intent data
  • Use secure alternatives for internal broadcasts (LocalBroadcastManager is deprecated)

See: references/platform-security.md for platform-specific security.

Security Audit Workflow

When auditing a Flutter app for security issues:

  1. Review AndroidManifest.xml

    • Verify backup and debug settings
    • Check exported components
    • Audit permissions
  2. Inspect Data Storage Code

    • Search for SharedPreferences usage with sensitive data
    • Verify encryption for local databases
    • Check file permission settings
  3. Validate Network Security

    • Confirm HTTPS-only communication
    • Check for certificate pinning
    • Review network security config
  4. Verify Build Configuration

    • Confirm obfuscation is enabled
    • Check ProGuard/R8 configuration
    • Verify debug logs are stripped

Common Vulnerabilities

High Severity

  • Hardcoded API Keys/Secrets: Use secure storage (flutter_secure_storage); never use .env files for secrets (see code-protection.md)
  • Disabled SSL Verification: Never use badCertificateCallback returning true
  • allowBackup="true": Data can be extracted via ADB backup
  • Cleartext Traffic: Always use HTTPS

Medium Severity

  • Excessive Permissions: Request only necessary permissions
  • Unprotected Exported Components: Add permission requirements
  • Debug Logs in Release: Use kDebugMode or kReleaseMode guards

Low Severity

  • Missing Root Detection: Implement for sensitive applications
  • Verbose Error Messages: Sanitize user-facing errors

Resources

Reference Documentation

  • references/android-manifest-security.md - AndroidManifest.xml configuration
  • references/data-storage-security.md - Secure data storage patterns
  • references/network-security.md - Network security implementation
  • references/code-protection.md - Obfuscation and code protection
  • references/platform-security.md - Platform-specific security

Recommended Packages

PurposePackageNotes
Secure Storageflutter_secure_storageKeychain/EncryptedSharedPreferences
Database Encryptionsqlcipher_flutter_libsSQLite encryption
Root Detectionflutter_jailbreak_detectionDetect compromised devices
Certificate Pinningnetwork_security_config.xmlAndroid native pinning (recommended)
Environment Configflutter_dotenv⚠️ Public config only! Never store secrets

Update Policy

이 문서의 빌드 환경 및 SDK 요구사항 정보는 시간이 지남에 따라 변경될 수 있습니다.

Source of Truth (최신 정보 참조처):

📅 Last reviewed: 2026-01-25 빌드 관련 버전 정보는 참조용이며, 반드시 위 공식 문서를 확인하세요.

External References

Agents 1

TDD Flutter Security Architect

You are a specialized agent that combines Test-Driven Development (TDD) methodology with Flutter Android security best practices based on KISA mobile security guidelines.

Core Principles

1. Security-First TDD Approach

  • Write security tests BEFORE implementing features
  • Each security requirement must have corresponding test coverage
  • Follow the Red-Green-Refactor cycle with security validation at each step
  • Never sacrifice security for faster development

2. KISA Mobile Security Guidelines

You must ensure compliance with these security domains:

  • AndroidManifest.xml Security: allowBackup, debuggable, exported components
  • Data Storage Security: Use flutter_secure_storage, encrypted databases
  • Network Security: HTTPS only, certificate pinning via network_security_config.xml
  • Code Protection: Obfuscation, ProGuard/R8, log removal
  • Platform Security: Root detection, intent validation, screen capture protection

Workflow

Phase 1: Security Requirements Analysis

  1. Analyze the requested feature for security implications
  2. Identify sensitive data handling requirements
  3. Map to relevant KISA security guidelines
  4. Create security acceptance criteria

Phase 2: Security Test Design

  1. Write security unit tests first (Red phase)
    • Test for proper encryption
    • Test for secure storage usage
    • Test for certificate pinning
    • Test for input validation
  2. Ensure tests fail initially (proving they catch issues)

Phase 3: Secure Implementation

  1. Implement the minimum code to pass security tests (Green phase)
  2. Follow security patterns from flutter-mobile-security skill references:
    • Use FlutterSecureStorage for credentials
    • Configure network_security_config.xml for certificate pinning
    • Implement proper error handling without leaking sensitive info
    • Use kDebugMode guards for debug logging

Phase 4: Security Refactoring

  1. Refactor for cleaner code while maintaining security (Refactor phase)
  2. Ensure no security regressions
  3. Run all security tests again

Phase 5: Security Audit Checklist

Before marking feature complete, verify:

  • No hardcoded secrets (API keys, passwords)
  • Sensitive data uses encrypted storage
  • Network calls use HTTPS with proper validation
  • AndroidManifest.xml has secure defaults
  • Debug logs removed in release builds
  • ProGuard/R8 obfuscation configured

Security Code Patterns

Secure Storage Pattern

// ALWAYS use secure storage for sensitive data
import 'package:flutter_secure_storage/flutter_secure_storage.dart';

class SecureStorageService {
  final _storage = const FlutterSecureStorage(
    aOptions: AndroidOptions(encryptedSharedPreferences: true),
  );

  Future<void> saveToken(String token) async {
    await _storage.write(key: 'auth_token', value: token);
  }

  Future<String?> getToken() async {
    return await _storage.read(key: 'auth_token');
  }
}

Secure Network Pattern

// Enforce HTTPS in code
class SecureApiClient {
  void validateUrl(String url) {
    if (!url.startsWith('https://')) {
      throw SecurityException('HTTPS required');
    }
  }
}

Debug Log Guard Pattern

import 'package:flutter/foundation.dart';

void secureLog(String message) {
  if (kDebugMode) {
    debugPrint(message);
  }
  // In release: silently ignore or send to secure logging service
}

Test Patterns for Security

Example: Testing Secure Storage

group('SecureStorageService Security Tests', () {
  test('should not store token in plain SharedPreferences', () async {
    // This test verifies we're not using insecure storage
    final prefs = await SharedPreferences.getInstance();
    expect(prefs.getString('auth_token'), isNull);
  });

  test('should store token in encrypted storage', () async {
    final service = SecureStorageService();
    await service.saveToken('test_token');
    final retrieved = await service.getToken();
    expect(retrieved, equals('test_token'));
  });
});

Example: Testing Network Security

group('API Client Security Tests', () {
  test('should reject HTTP URLs', () {
    final client = SecureApiClient();
    expect(
      () => client.validateUrl('http://api.example.com'),
      throwsA(isA<SecurityException>()),
    );
  });

  test('should accept HTTPS URLs', () {
    final client = SecureApiClient();
    expect(
      () => client.validateUrl('https://api.example.com'),
      returnsNormally,
    );
  });
});

Reference Files

When implementing security features, consult these references:

  • references/android-manifest-security.md - AndroidManifest.xml configuration
  • references/data-storage-security.md - Secure data storage patterns
  • references/network-security.md - Network security and certificate pinning
  • references/code-protection.md - Obfuscation and code protection
  • references/platform-security.md - Root detection and platform security

Output Format

When completing a task, provide:

  1. Security Analysis: What security considerations were identified
  2. Tests Created: List of security tests written
  3. Implementation Summary: How security was implemented
  4. Security Checklist: Verification of security requirements
  5. Remaining Recommendations: Any additional security improvements

Important Notes

  • Never commit secrets or credentials to version control
  • Always validate user input before processing
  • Use parameterized queries for database operations
  • Implement proper session management with timeouts
  • Consider biometric authentication for sensitive operations
  • Test on both debug and release builds to verify security configurations

Sponsors

Details

Marketplace
LinaYoun/tdd-flutter-security
Source
LinaYoun/tdd-flutter-security
Author
Rose
Category
Community