A tool to shift-left sensitive changes on your Android deployable archives
aaw is command-line tool and a cross-over between functionalities from
apkanalyzer and
bundletool.
This utility has as goal helping with detection of newly introduced Android frameworks
components and permissions in your release archives (.apk or .aab), especially transitive
ones brought by 3rd party project dependencies, following a shift-left approach.
aaw is distributed as a
truly-executable
fatjar, and
it's tested against jdk11, jdk17 and jdk21 on Unix boxes. In addition, this project has
end-to-end tests targeting the following Android products with public open-source releases
on Github:
This tool requires jdk11 or newer and a valid Android SDK installation. aaw inspects the
following environment variables when locating your Android SDK installation folder:
$ANDROID_HOME$ANDROID_SDK$ANDROID_SDK_HOME
You can grab executables directly from
Github releases.
Unzip it and add it to your $PATH.
Alternatively, there is an asdf-plugin available as well.
The following snippets use ProntonMail releases as examples, in particular versions 3.0.7 (November/2022) and 3.0.17 (October/2023)
Every command supports archives in .apk and .aab formats.
$> aaw overview -a tmp/ProtonMail-3.0.7.apk
┌────────────────────────────┬───────────────────────┐
│ Attribute │ Evaluation │
├────────────────────────────┼───────────────────────┤
│ Application Id │ ch.protonmail.android │
├────────────────────────────┼───────────────────────┤
│ Minimum SDK │ 23 │
├────────────────────────────┼───────────────────────┤
│ Target SDK │ 31 │
├────────────────────────────┼───────────────────────┤
│ Total Used Features │ 2 │
├────────────────────────────┼───────────────────────┤
│ Total Manifest permissions │ 14 │
├────────────────────────────┼───────────────────────┤
│ Dangerous permissions │ Yes │
├────────────────────────────┼───────────────────────┤
│ Activities │ 54 │
├────────────────────────────┼───────────────────────┤
│ Services │ 14 │
├────────────────────────────┼───────────────────────┤
│ Broadcast Receivers │ 15 │
├────────────────────────────┼───────────────────────┤
│ Content Providers │ 4 │
└────────────────────────────┴───────────────────────┘This mimics functionally from apkanalyser and supports a --json switch for
automation purposes.
$> aaw generate --archive=tmp/ProtonMail-3.0.7.apk
Baseline available at : ch.protonmail.android.toml
This command will produce a <applicationId>.toml file in the current directory, which is
intended to be available in your VCS. This toml tracks a subset of information from the
related merged AndroidManifest.xml, namely:
- Application Permissions
- Device Compatibility
- Activities, Services, Content Providers and Broadcast Receivers
Optionally, you can generate a compact version of a baseline by passing "trusted" packages,
usually the ones related to your project structure. Those must be passed in a single argument,
comma (,) separated
$> aaw generate --archive=tmp/ProtonMail-3.0.7.apk --trusted='ch.protonmail,me.proton.core'
Baseline available at : ch.protonmail.android.toml
$> more ch.protonmail.android.toml
applicationId = "ch.protonmail.android"
permissions = [
"android.permission.ACCESS_NETWORK_STATE",
"android.permission.FOREGROUND_SERVICE",
"android.permission.GET_ACCOUNTS",
"android.permission.INTERNET",
"android.permission.READ_CONTACTS",
"android.permission.READ_EXTERNAL_STORAGE",
"android.permission.RECEIVE_BOOT_COMPLETED",
"android.permission.SCHEDULE_EXACT_ALARM",
"android.permission.USE_BIOMETRIC",
"android.permission.USE_FINGERPRINT",
"android.permission.VIBRATE",
"android.permission.WAKE_LOCK",
"android.permission.WRITE_EXTERNAL_STORAGE",
"com.google.android.c2dm.permission.RECEIVE"
]
features = [
"android.hardware.faketouch",
"android.hardware.screen.portrait"
]
trustedPackages = [
"ch.protonmail",
"me.proton.core"
]
activities = [
"androidx.biometric.DeviceCredentialHandlerActivity",
"com.google.android.gms.common.api.GoogleApiActivity"
]
.
.
.
# Considering the baseline file generated in the previous example
$> aaw compare -a tmp/ProtonMail-3.0.17.apk -b ch.protonmail.android.toml
Your baseline file does not match the supplied artifact.
┌─────────────┬───────────────────────────────────────────────────────────────────┬────────────┐
│ Category │ Finding │ Missing at │
├─────────────┼───────────────────────────────────────────────────────────────────┼────────────┤
│ Permissions │ android.permission.POST_NOTIFICATIONS │ Baseline │
├─────────────┼───────────────────────────────────────────────────────────────────┼────────────┤
│ Permissions │ android.permission.READ_MEDIA_AUDIO │ Baseline │
├─────────────┼───────────────────────────────────────────────────────────────────┼────────────┤
│ Permissions │ android.permission.READ_MEDIA_IMAGES │ Baseline │
├─────────────┼───────────────────────────────────────────────────────────────────┼────────────┤
│ Permissions │ android.permission.READ_MEDIA_VIDEO │ Baseline │
├─────────────┼───────────────────────────────────────────────────────────────────┼────────────┤
│ Components │ com.google.android.play.core.common.PlayCoreDialogWrapperActivity │ Baseline │
├─────────────┼───────────────────────────────────────────────────────────────────┼────────────┤
│ Components │ androidx.profileinstaller.ProfileInstallReceiver │ Baseline │
└─────────────┴───────────────────────────────────────────────────────────────────┴────────────┘
This example illustrates how to track sensitive changes as part of your Continuous Integration, assuming that you have a snapshot of your releasable archive produced at CI runtime.
compare can also exit with a failure status if a fresh archive does not match an existing
baseline, forcing a baseline update as part of pull/merge request.
$> aaw compare -a tmp/ProtonMail-3.0.17.apk -b ch.protonmail.android.toml --failIn addition, compare can produce output in a json format as well
$> aaw compare -a tmp/ProtonMail-3.0.17.apk -b ch.protonmail.android.toml --jsonThis tool was inspired by the following blog posts and existing tools
Copyright (c) 2023 - Dotanuki Labs - The MIT license