CODESA APK Guard #

codesa_apk_guard es un plugin de seguridad para aplicaciones Flutter en Android e iOS.

Proporciona una API Flutter respaldada por controles de seguridad implementados de forma nativa en Kotlin para Android y Swift para iOS, orientados a detectar indicadores relacionados con manipulación de la aplicación, reempaquetado, depuración, root/jailbreak, hooking, emuladores o Simulator, clonación, herramientas de modificación y alteraciones del entorno de ejecución.

Actualmente el plugin soporta Android e iOS.

Vista general #

Controles de seguridad nativos para aplicaciones Flutter en Android e iOS.

La imagen anterior muestra la aplicación de ejemplo ejecutando el análisis de seguridad y presentando los resultados de los controles. Un hallazgo representa una señal de riesgo que debe ser evaluada de acuerdo con la política de seguridad de la aplicación consumidora.

Objetivo #

CODESA APK Guard permite incorporar controles defensivos de seguridad dentro de aplicaciones Flutter sin trasladar la lógica principal de detección a Dart.

La arquitectura general es:

Aplicación Flutter

        |

        v

CodesaApkGuard

        |

        v

MethodChannel

        |

        +--------------------+

        |                    |

        v                    v

Plugin Android          Plugin iOS

        |                    |

        v                    v

Detectores Kotlin       Detectores Swift

        |                    |

        +---------+----------+

                  |

                  v

             GuardReport

La aplicación consumidora puede utilizar los resultados para tomar sus propias decisiones de riesgo.

En Android, CodesaApkGuard.enforce() puede aplicar el mecanismo de cierre nativo cuando blockOnDetection está habilitado.

En iOS, enforce() ejecuta actualmente los controles y devuelve el GuardReport, pero no finaliza forzosamente el proceso de la aplicación.

Controles disponibles #

| # | Control | Descripción |

|---|---|---|

| 1 | Code Hooking | Detecta indicadores asociados con frameworks o mecanismos de hooking e instrumentación. |

| 2 | Security Config Manipulation | Revisa configuraciones de seguridad potencialmente inseguras o manipuladas según la plataforma. |

| 3 | Source Code Modification | Valida la integridad del código o ejecutable contra referencias SHA-256 configuradas. |

| 4 | Application Repackaging | Busca inconsistencias de identidad, firma o empaquetado según la plataforma. |

| 5 | Application Debugging | Detecta indicadores de depuración activa según las capacidades de cada plataforma. |

| 6 | Rooted Device | Detecta indicadores de root en Android y de jailbreak en iOS. |

| 7 | App Cloning Environment | Detecta indicadores relacionados con clonación o virtualización de aplicaciones. |

| 8 | Malware & Cheat Tool | Busca indicadores de herramientas de manipulación o cheat según las señales disponibles en cada plataforma. |

| 9 | Emulator | Detecta ejecución dentro de un emulador Android o iOS Simulator. |

| 10 | USB Debugging | Detecta ADB en Android; en iOS informa que no existe una API pública equivalente. |

| 11 | Speed Modification | Busca anomalías temporales que puedan indicar manipulación de velocidad. |

| 12 | Other | Categoría reservada para futuras extensiones o controles específicos. |

Requisitos #

• Flutter >=3.44.0

• Dart >=3.12.0 <4.0.0

Android #

• Android API 23 o superior

• Java 17

• Configuración compatible con Android Gradle Plugin 9

iOS #

• iOS 13.0 o superior

• Swift 5

• Swift Package Manager o CocoaPods

Instalación #

Instalación desde pub.flutter-io.cn:

dependencies:

  codesa_apk_guard: ^0.2.0

Después:

flutter pub get

Durante desarrollo local puede utilizarse mediante path:

dependencies:

  codesa_apk_guard:

    path: ../codesa_apk_guard

Importación #

import 'package:codesa_apk_guard/codesa_apk_guard.dart';

Uso básico #

Para ejecutar los controles sin cerrar automáticamente la aplicación:

final report = await CodesaApkGuard.check();

Después puede evaluarse el resultado:

if (report.safe) {

  print('No se detectaron amenazas configuradas.');

} else {

  for (final finding in report.detectedFindings) {

    print('Tipo: ${finding.type}');

    print('Severidad: ${finding.severity}');

    print('Confianza: ${finding.confidence}');

    print('Detalle: ${finding.details}');

  }

}

Seleccionar controles específicos #

Es posible indicar exactamente qué controles deben ejecutarse:

final report = await CodesaApkGuard.check(

  config: const ApkGuardConfig(

    checks: {

      ThreatType.codeHooking,

      ThreatType.applicationRepackaging,

      ThreatType.applicationDebugging,

      ThreatType.rootedDevice,

      ThreatType.emulator,

      ThreatType.usbDebugging,

    },

  ),

);

Los tipos disponibles son:

ThreatType.codeHooking

ThreatType.securityConfigManipulation

ThreatType.sourceCodeModification

ThreatType.applicationRepackaging

ThreatType.applicationDebugging

ThreatType.rootedDevice

ThreatType.appCloningEnvironment

ThreatType.malwareCheatTool

ThreatType.emulator

ThreatType.usbDebugging

ThreatType.speedModification

ThreatType.other

Cuando checks está vacío, la configuración enviada al código nativo permite ejecutar el conjunto de controles soportados.

ThreatType.other está reservado actualmente y no posee un detector nativo independiente.

check() y enforce() #

El plugin ofrece dos formas principales de ejecución.

CodesaApkGuard.check() #

Ejecuta los controles configurados y devuelve el reporte.

final report = await CodesaApkGuard.check();

Este método no cierra automáticamente la aplicación.

Es la opción apropiada cuando la aplicación consumidora desea implementar su propia política:

final report = await CodesaApkGuard.check();

if (!report.safe) {

  // Aplicar política de riesgo de la aplicación.

}

CodesaApkGuard.enforce() #

Permite ejecutar los controles utilizando el mecanismo de bloqueo del plugin.

final report = await CodesaApkGuard.enforce();

La configuración predeterminada utilizada por enforce() habilita:

blockOnDetection: true

Cuando se detecta una amenaza configurada y existe una Activity Android disponible, el plugin puede finalizar la tarea de la aplicación mediante:

finishAffinity()

Comportamiento de enforce() en iOS #

En iOS, enforce() no finaliza actualmente el proceso de la aplicación.

El plugin ejecuta los controles configurados y devuelve el mismo modelo GuardReport para que la aplicación consumidora aplique su propia política de seguridad.

No se utiliza exit(0) ni otra terminación forzada del proceso como mecanismo equivalente a finishAffinity().

Configuración explícita con enforce() #

Si se proporciona manualmente un ApkGuardConfig, se utiliza el valor de blockOnDetection de esa configuración.

Para bloquear:

await CodesaApkGuard.enforce(

  config: const ApkGuardConfig(

    blockOnDetection: true,

    checks: {

      ThreatType.rootedDevice,

      ThreatType.emulator,

      ThreatType.usbDebugging,

    },

  ),

);

Si se proporciona:

blockOnDetection: false

el reporte podrá contener amenazas, pero el mecanismo de cierre no será aplicado.

Configuración #

Ejemplo:

const config = ApkGuardConfig(

  blockOnDetection: false,

  checks: {

    ThreatType.codeHooking,

    ThreatType.sourceCodeModification,

    ThreatType.applicationRepackaging,

    ThreatType.applicationDebugging,

    ThreatType.rootedDevice,

  },

  expectedSigningSha256: [

    'SHA256_CERTIFICADO_PRODUCCION',

  ],

  expectedDexSha256: [

    'SHA256_DEX_CONFIABLE',

  ],

);

Uso:

final report = await CodesaApkGuard.check(

  config: config,

);

Comportamiento de los controles en iOS #

La API Dart utiliza los mismos ThreatType en Android e iOS, pero algunas señales disponibles son diferentes por las características y APIs públicas de cada plataforma.

| Control | Comportamiento en iOS |

|---|---|

| Code Hooking | Inspecciona imágenes cargadas en el proceso y busca indicadores conocidos de hooking o instrumentación. |

| Security Config Manipulation | Revisa configuraciones relevantes de NSAppTransportSecurity y excepciones ATS potencialmente inseguras. |

| Source Code Modification | Calcula SHA-256 del ejecutable principal y lo compara con expectedExecutableSha256 cuando se configura una referencia. |

| Application Repackaging | Compara el Bundle Identifier con expectedBundleIdentifiers cuando se configura una referencia. |

| Application Debugging | Detecta si el proceso está siendo trazado por un debugger. |

| Rooted Device | En iOS representa detección heurística de jailbreak. |

| App Cloning Environment | Revisa inconsistencias del bundle, sandbox e identidad de ejecución compatibles con un entorno alterado. |

| Malware & Cheat Tool | Busca artefactos o imágenes cargadas asociadas con herramientas de manipulación. No enumera aplicaciones instaladas. |

| Emulator | Detecta ejecución dentro de iOS Simulator. |

| USB Debugging | iOS no expone una API pública equivalente a ADB; este control es informativo y la depuración activa se cubre con Application Debugging. |

| Speed Modification | Compara la progresión del reloj de pared y del reloj monotónico durante un intervalo controlado. |

Integridad del ejecutable en iOS #

Para Source Code Modification, iOS puede comparar el SHA-256 del ejecutable principal contra expectedExecutableSha256.

const config = ApkGuardConfig(

  expectedExecutableSha256: [

    'SHA256_EJECUTABLE_IOS_CONFIABLE',

  ],

);

El hash esperado debe provenir de un proceso de build o release controlado. Si no se configura una referencia, el plugin puede calcular el hash actual, pero no afirma que el ejecutable haya sido validado contra una referencia confiable.

Identidad de aplicación en iOS #

Application Repackaging puede comparar el Bundle Identifier actual contra expectedBundleIdentifiers.

const config = ApkGuardConfig(

  expectedBundleIdentifiers: [

    'com.empresa.aplicacion',

  ],

);

Esta señal ayuda a detectar inconsistencias de identidad, pero no equivale a una validación criptográfica de firma como la disponible en Android.

Jailbreak #

En iOS, ThreatType.rootedDevice representa la búsqueda heurística de indicadores de jailbreak. La ausencia de indicadores no garantiza que el dispositivo no haya sido modificado.

El iOS Simulator no se reporta automáticamente como dispositivo con jailbreak.

USB Debugging en iOS #

iOS no expone a aplicaciones de terceros una API pública equivalente a ADB_ENABLED de Android. Por eso ThreatType.usbDebugging en iOS es informativo y no afirma detectar un estado global de depuración USB.

La detección de un debugger adjunto al proceso se realiza mediante ThreatType.applicationDebugging.

Simulator #

En iOS, ThreatType.emulator reporta positivamente la ejecución dentro de iOS Simulator.

Por tanto, si se ejecutan todos los controles en Simulator, report.safe puede ser false debido únicamente al hallazgo ThreatType.emulator.

Privacy Manifest #

La implementación iOS incluye PrivacyInfo.xcprivacy.

El control Speed Modification utiliza tiempo monotónico del sistema y el Privacy Manifest declara el uso correspondiente de Required Reason APIs. El manifest se incluye como recurso tanto con Swift Package Manager como con CocoaPods.

Modificación del código fuente en Android #

El control Source Code Modification calcula hashes SHA-256 de las entradas:

classes\*.dex

del APK instalado.

Los hashes esperados pueden configurarse mediante:

expectedDexSha256: [

  'SHA256_DEX_CONFIABLE',

]

El detector compara los hashes obtenidos del APK instalado contra el conjunto de hashes confiables configurado.

Una diferencia puede indicar que el bytecode instalado no corresponde con la referencia esperada.

Importante sobre los hashes DEX #

Los hashes confiables deben generarse y administrarse mediante un proceso de build/release controlado.

No es recomendable calcular un hash y simplemente incorporarlo dentro del mismo artefacto sin diseñar previamente la estrategia de integridad.

Modificar código o configuración de la aplicación puede modificar el DEX generado y, por consiguiente, su SHA-256.

Si no se configura expectedDexSha256, el detector informa que no existe una referencia DEX configurada en lugar de afirmar que hubo modificación.

Reempaquetado de aplicación en Android #

El control Application Repackaging puede validar la huella SHA-256 del certificado utilizado para firmar la aplicación.

Ejemplo:

const config = ApkGuardConfig(

  expectedSigningSha256: [

    'SHA256_CERTIFICADO_PRODUCCION',

  ],

);

En producción debe utilizarse la huella correspondiente al certificado de confianza de la aplicación.

No debe utilizarse el certificado debug como referencia de confianza para producción.

Validación del instalador #

También pueden configurarse paquetes instaladores confiables.

La configuración predeterminada contempla instaladores Android conocidos utilizados por Google Play y determinados instaladores del sistema.

También puede configurarse explícitamente mediante expectedInstallerPackages:

const config = ApkGuardConfig(

  expectedInstallerPackages: [

    'com.android.vending',

    'com.google.android.packageinstaller',

    'com.samsung.android.packageinstaller',

  ],

);

Una aplicación distribuida mediante mecanismos diferentes debe definir una política acorde con su modelo de distribución.

El instalador debe considerarse una señal adicional y no una prueba absoluta de integridad.

Code Hooking #

El detector nativo busca diferentes indicadores relacionados con tecnologías de hooking o instrumentación, entre ellas:

• Frida

• Xposed

• LSPosed

• Substrate

• Riru

• Zygisk

La detección utiliza señales disponibles localmente como mapas de memoria del proceso, información del runtime y clases conocidas cuando corresponda.

Estos mecanismos son heurísticos. Una herramienta avanzada puede intentar ocultar sus indicadores.

Manipulación de configuración de seguridad #

El control revisa configuraciones relevantes de Android, entre ellas indicadores relacionados con:

• tráfico cleartext;

• aplicación testOnly;

• configuración de backup.

El plugin no modifica silenciosamente la política de seguridad de la aplicación consumidora.

Por ejemplo, una aplicación puede decidir utilizar:

\<application

    android:allowBackup="false"

    android:usesCleartextTraffic="false">

\</application>

La configuración final continúa siendo responsabilidad de la aplicación que integra el plugin.

Application Debugging #

El detector revisa indicadores como:

• ApplicationInfo.FLAG_DEBUGGABLE;

• debugger conectado;

• estado de espera de debugger.

Las aplicaciones de producción normalmente deben compilarse sin el indicador debuggable.

Root en Android #

El control de root utiliza diferentes señales disponibles para la aplicación Android.

Puede revisar indicadores como:

• ubicaciones conocidas de su;

• ejecutables relacionados con root;

• características del build;

• características del entorno Android.

Un indicador de riesgo no necesariamente demuestra acceso root activo.

Asimismo, no detectar indicadores no garantiza que el dispositivo esté completamente libre de modificaciones.

Clonación y virtualización #

El plugin revisa indicadores asociados con clonación o virtualización:

• consistencia de identidad del paquete;

• consistencia entre UID esperado y UID del proceso;

• directorio de datos;

• rutas de archivos, cache y no-backup;

• indicadores encontrados en los mapas de memoria del proceso.

También se consideran cadenas asociadas con determinados entornos conocidos, como:

• VirtualApp

• VirtualXposed

• Parallel Space

• Dual Space

• VMOS

• F1 VM

• X8 Sandbox

La ausencia de estos indicadores no garantiza la detección de todas las plataformas de virtualización existentes.

Malware & Cheat Tool #

El plugin puede consultar identificadores de paquetes conocidos asociados con determinadas herramientas de modificación.

Android aplica restricciones de visibilidad de paquetes.

Por esta razón, el AndroidManifest.xml del plugin declara las consultas \<queries> necesarias para los paquetes actualmente utilizados por este detector.

Este mecanismo no debe interpretarse como un antivirus o sistema completo de detección de malware.

Emulator #

La detección de emulador utiliza diferentes propiedades del entorno Android.

Entre las señales evaluadas pueden encontrarse:

• fingerprints genéricos o de emulador;

• modelos asociados con Android SDK / Emulator;

• hardware como goldfish o ranchu;

• productos relacionados con SDK/emulator;

• fabricantes asociados con determinados emuladores.

Se utilizan varias señales para evitar depender únicamente de una propiedad.

USB Debugging / ADB en Android #

El plugin comprueba el estado de ADB disponible mediante Android.

Cuando está habilitado puede reportar:

ADB/USB debugging is enabled

La decisión de bloquear una aplicación por tener ADB habilitado pertenece a la política de seguridad de la aplicación consumidora.

Speed Modification #

El detector compara la progresión del reloj del sistema con tiempo monotónico transcurrido durante un intervalo controlado.

Una diferencia significativa puede representar una anomalía temporal.

Este control es heurístico y no debe interpretarse por sí solo como prueba definitiva de la existencia de una herramienta de modificación de velocidad.

Reporte de seguridad #

CodesaApkGuard.check() y CodesaApkGuard.enforce() devuelven un GuardReport.

Ejemplo:

final report = await CodesaApkGuard.check();

print(report.safe);

for (final finding in report.findings) {

  print(finding.type);

  print(finding.detected);

  print(finding.severity);

  print(finding.confidence);

  print(finding.details);

}

Para consultar únicamente hallazgos detectados:

for (final finding in report.detectedFindings) {

  print(finding.type);

}

Estrategia recomendada para producción #

CODESA APK Guard debe utilizarse como una capa dentro de una estrategia de defensa en profundidad.

Para aplicaciones con operaciones sensibles se recomienda complementar estos controles con:

• autorización del lado servidor;

• sesiones y tokens revocables;

• tokens con tiempos de vida adecuados;

• decisiones de riesgo en backend;

• servicios de integridad de aplicación/dispositivo;

• almacenamiento seguro;

• TLS y políticas de seguridad de red;

• controles del proceso de firma y publicación;

• monitoreo y detección de anomalías.

Las decisiones críticas de autorización no deberían depender exclusivamente de un detector ejecutado en el cliente.

Falsos positivos y falsos negativos #

Algunos controles de seguridad en Android e iOS son necesariamente heurísticos.

Una detección puede indicar un entorno sospechoso o de mayor riesgo sin demostrar necesariamente una actividad maliciosa.

De igual forma, la ausencia de un hallazgo no demuestra que el dispositivo o la aplicación no hayan sido comprometidos.

La aplicación consumidora debe definir su política teniendo en cuenta:

• tipo de amenaza;

• severidad;

• confianza;

• contexto;

• nivel de riesgo del negocio.

Plataformas soportadas #

| Plataforma | Estado |

|---|---|

| Android | Soportado |

| iOS | Soportado |

| Web | No soportado |

| Windows | No soportado |

| macOS | No soportado |

| Linux | No soportado |

Aplicación de ejemplo #

El proyecto incluye una aplicación Flutter dentro de:

example/

Para ejecutarla:

cd example

flutter run

Para validar Android en modo Release:

flutter build apk --release

Para validar iOS en Simulator:

flutter build ios --simulator

Para compilar una aplicación iOS destinada a dispositivo físico o distribución se requiere la configuración de firma correspondiente en Xcode.

Validación durante desarrollo #

Desde la raíz:

flutter pub get
flutter analyze
flutter test

Compilación Android Release:

cd example
flutter build apk --release

Compilación iOS para Simulator:

cd example
flutter build ios --simulator

Validación previa a publicación:

cd ..

flutter pub publish --dry-run

Limitaciones de seguridad #

Los controles ejecutados en el cliente funcionan dentro de un entorno que puede estar bajo control del propietario o de un atacante.

Un atacante con capacidades suficientes puede intentar:

• modificar la APK;

• alterar código Dart o nativo;

• instrumentar funciones;

• ocultar indicadores de root;

• modificar propiedades del sistema;

• alterar resultados de los detectores;

• evadir mecanismos de bloqueo.

Por esta razón, CODESA APK Guard no afirma que una aplicación Android o iOS sea imposible de modificar, analizar, instrumentar, clonar o evadir.

El plugin proporciona señales de seguridad que pueden utilizarse como parte de una arquitectura defensiva más amplia.

Uso responsable #

Este plugin está diseñado para protección defensiva de aplicaciones.

En interfaces de producción se recomienda evitar mostrar al usuario información interna innecesariamente detallada sobre los mecanismos utilizados para detectar amenazas.

Licencia #

Consulte el archivo LICENSE incluido con el paquete.