{"id":22500541,"url":"https://github.com/dotanuki-labs/android-archives-watchdog","last_synced_at":"2025-04-12T13:35:00.740Z","repository":{"id":203536472,"uuid":"688201825","full_name":"dotanuki-labs/android-archives-watchdog","owner":"dotanuki-labs","description":"A tool to shift-left sensitive changes on your Android deployable archives","archived":false,"fork":false,"pushed_at":"2025-04-08T18:02:20.000Z","size":11828,"stargazers_count":13,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-08T19:23:49.041Z","etag":null,"topics":["android","android-tools","automation","ci","mobile-security"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dotanuki-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-06T21:34:35.000Z","updated_at":"2025-04-08T18:02:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"87fc1b71-6c22-4efc-89f0-6b19517d4dfb","html_url":"https://github.com/dotanuki-labs/android-archives-watchdog","commit_stats":null,"previous_names":["dotanuki-labs/android-archives-watchdog"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotanuki-labs%2Fandroid-archives-watchdog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotanuki-labs%2Fandroid-archives-watchdog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotanuki-labs%2Fandroid-archives-watchdog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotanuki-labs%2Fandroid-archives-watchdog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dotanuki-labs","download_url":"https://codeload.github.com/dotanuki-labs/android-archives-watchdog/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248573788,"owners_count":21126904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","android-tools","automation","ci","mobile-security"],"created_at":"2024-12-06T23:01:20.533Z","updated_at":"2025-04-12T13:35:00.705Z","avatar_url":"https://github.com/dotanuki-labs.png","language":"Kotlin","funding_links":[],"categories":["Kotlin"],"sub_categories":[],"readme":"# Android Archives Watchdog 🐶\n\n[![ktlint](https://img.shields.io/badge/code%20style-%E2%9D%A4-FF4081.svg)](https://ktlint.github.io/)\n[![Maintainability](https://api.codeclimate.com/v1/badges/26b1c97497c6cab9c023/maintainability)](https://codeclimate.com/github/dotanuki-labs/android-archives-watchdog/maintainability)\n[![CI](https://github.com/dotanuki-labs/android-archives-watchdog/actions/workflows/ci.yaml/badge.svg)](https://github.com/dotanuki-labs/android-archives-watchdog/actions/workflows/ci.yaml)\n[![License](https://img.shields.io/github/license/dotanuki-labs/norris)](https://choosealicense.com/licenses/mit)\n\n## Overview\n\n\u003e A tool to shift-left sensitive changes on your Android deployable archives\n\n`aaw` is command-line tool and a cross-over between functionalities from\n[apkanalyzer](https://developer.android.com/tools/apkanalyzer) and\n[bundletool](https://developer.android.com/tools/bundletool).\n\nThis utility has as goal helping with detection of newly introduced Android frameworks\ncomponents and permissions in your release archives (`.apk` or `.aab`), especially transitive\nones brought by 3rd party project dependencies, following a shift-left approach.\n\n`aaw` is distributed as a\n[truly-executable](https://skife.org/java/unix/2011/06/20/really_executable_jars.html)\n[fatjar](https://imperceptiblethoughts.com/shadow/), and\nit's tested against `jdk11`, `jdk17` and `jdk21` on Unix boxes. In addition, this project has\nend-to-end tests targeting the following Android products with public open-source releases\non Github:\n\n- [DuckDuckGo](https://github.com/duckduckgo/Android)\n- [ProntonMail](https://github.com/ProtonMail/proton-mail-android)\n- [WooCommerce](https://github.com/woocommerce/woocommerce-android)\n- [Mozilla Firefox](https://github.com/mozilla-mobile/firefox-android)\n\n## Requirements\n\nThis tool requires `jdk11` or newer and a valid Android SDK installation. `aaw` inspects the\nfollowing environment variables when locating your Android SDK installation folder:\n\n- `$ANDROID_HOME`\n- `$ANDROID_SDK`\n- `$ANDROID_SDK_HOME`\n\n## Installing\n\nYou can grab executables directly from\n[Github releases](https://github.com/dotanuki-labs/android-archives-watchdog/releases).\nUnzip it and add it to your `$PATH`.\n\nAlternatively, there is an\n[asdf-plugin](https://github.com/dotanuki-labs/asdf-aaw)\navailable as well.\n\n## Using\n\nThe following snippets use\n[ProntonMail](https://github.com/ProtonMail/proton-mail-android)\nreleases as examples, in particular versions\n[3.0.7](https://github.com/ProtonMail/proton-mail-android/releases/tag/3.0.7) (November/2022) and\n[3.0.17](https://github.com/ProtonMail/proton-mail-android/releases/tag/3.0.17) (October/2023)\n\nEvery command supports archives in `.apk` and `.aab` formats.\n\n### Getting an overview from an Android archive\n\n```bash\n$\u003e aaw overview -a tmp/ProtonMail-3.0.7.apk\n\n┌────────────────────────────┬───────────────────────┐\n│ Attribute                  │ Evaluation            │\n├────────────────────────────┼───────────────────────┤\n│ Application Id             │ ch.protonmail.android │\n├────────────────────────────┼───────────────────────┤\n│ Minimum SDK                │ 23                    │\n├────────────────────────────┼───────────────────────┤\n│ Target SDK                 │ 31                    │\n├────────────────────────────┼───────────────────────┤\n│ Total Used Features        │ 2                     │\n├────────────────────────────┼───────────────────────┤\n│ Total Manifest permissions │ 14                    │\n├────────────────────────────┼───────────────────────┤\n│ Dangerous permissions      │ Yes                   │\n├────────────────────────────┼───────────────────────┤\n│ Activities                 │ 54                    │\n├────────────────────────────┼───────────────────────┤\n│ Services                   │ 14                    │\n├────────────────────────────┼───────────────────────┤\n│ Broadcast Receivers        │ 15                    │\n├────────────────────────────┼───────────────────────┤\n│ Content Providers          │ 4                     │\n└────────────────────────────┴───────────────────────┘\n```\n\nThis mimics functionally from `apkanalyser` and supports a `--json` switch for\nautomation purposes.\n\n### Generating a baseline from an Android archive\n\n```bash\n$\u003e aaw generate --archive=tmp/ProtonMail-3.0.7.apk\n\nBaseline available at : ch.protonmail.android.toml\n\n```\n\nThis command will produce a `\u003capplicationId\u003e.toml` file in the current directory, which is\nintended to be available in your VCS. This `toml` tracks a subset of information from the\nrelated merged `AndroidManifest.xml`, namely:\n\n- [Application Permissions](https://developer.android.com/guide/topics/manifest/manifest-intro#perms)\n- [Device Compatibility](https://developer.android.com/guide/topics/manifest/manifest-intro#compatibility)\n- [Activities, Services, Content Providers and Broadcast Receivers](https://developer.android.com/guide/topics/manifest/manifest-intro#components)\n\nOptionally, you can generate a compact version of a baseline by passing \"trusted\" packages,\nusually the ones related to your project structure. Those must be passed in a single argument,\ncomma (`,`) separated\n\n```bash\n$\u003e aaw generate --archive=tmp/ProtonMail-3.0.7.apk --trusted='ch.protonmail,me.proton.core'\n\nBaseline available at : ch.protonmail.android.toml\n\n$\u003e more ch.protonmail.android.toml\n\napplicationId = \"ch.protonmail.android\"\npermissions = [\n    \"android.permission.ACCESS_NETWORK_STATE\",\n    \"android.permission.FOREGROUND_SERVICE\",\n    \"android.permission.GET_ACCOUNTS\",\n    \"android.permission.INTERNET\",\n    \"android.permission.READ_CONTACTS\",\n    \"android.permission.READ_EXTERNAL_STORAGE\",\n    \"android.permission.RECEIVE_BOOT_COMPLETED\",\n    \"android.permission.SCHEDULE_EXACT_ALARM\",\n    \"android.permission.USE_BIOMETRIC\",\n    \"android.permission.USE_FINGERPRINT\",\n    \"android.permission.VIBRATE\",\n    \"android.permission.WAKE_LOCK\",\n    \"android.permission.WRITE_EXTERNAL_STORAGE\",\n    \"com.google.android.c2dm.permission.RECEIVE\"\n]\nfeatures = [\n    \"android.hardware.faketouch\",\n    \"android.hardware.screen.portrait\"\n]\ntrustedPackages = [\n    \"ch.protonmail\",\n    \"me.proton.core\"\n]\nactivities = [\n    \"androidx.biometric.DeviceCredentialHandlerActivity\",\n    \"com.google.android.gms.common.api.GoogleApiActivity\"\n]\n .\n .\n .\n\n```\n\n### Comparing an archive against a baseline\n\n```bash\n# Considering the baseline file generated in the previous example\n$\u003e aaw compare -a tmp/ProtonMail-3.0.17.apk -b ch.protonmail.android.toml\n\nYour baseline file does not match the supplied artifact.\n\n┌─────────────┬───────────────────────────────────────────────────────────────────┬────────────┐\n│ Category    │ Finding                                                           │ Missing at │\n├─────────────┼───────────────────────────────────────────────────────────────────┼────────────┤\n│ Permissions │ android.permission.POST_NOTIFICATIONS                             │ Baseline   │\n├─────────────┼───────────────────────────────────────────────────────────────────┼────────────┤\n│ Permissions │ android.permission.READ_MEDIA_AUDIO                               │ Baseline   │\n├─────────────┼───────────────────────────────────────────────────────────────────┼────────────┤\n│ Permissions │ android.permission.READ_MEDIA_IMAGES                              │ Baseline   │\n├─────────────┼───────────────────────────────────────────────────────────────────┼────────────┤\n│ Permissions │ android.permission.READ_MEDIA_VIDEO                               │ Baseline   │\n├─────────────┼───────────────────────────────────────────────────────────────────┼────────────┤\n│ Components  │ com.google.android.play.core.common.PlayCoreDialogWrapperActivity │ Baseline   │\n├─────────────┼───────────────────────────────────────────────────────────────────┼────────────┤\n│ Components  │ androidx.profileinstaller.ProfileInstallReceiver                  │ Baseline   │\n└─────────────┴───────────────────────────────────────────────────────────────────┴────────────┘\n\n```\n\nThis example illustrates how to track sensitive changes as part of your Continuous Integration,\nassuming that you have a snapshot of your releasable archive produced at CI runtime.\n\n`compare` can also exit with a failure status if a fresh archive does not match an existing\nbaseline, forcing a baseline update as part of pull/merge request.\n\n```bash\n$\u003e aaw compare -a tmp/ProtonMail-3.0.17.apk -b ch.protonmail.android.toml --fail\n```\n\nIn addition, `compare` can produce output in a `json` format as well\n\n```bash\n$\u003e aaw compare -a tmp/ProtonMail-3.0.17.apk -b ch.protonmail.android.toml --json\n```\n\n## Credits\n\nThis tool was inspired by the following blog posts and existing tools\n\n- [Android CI : Reveal Manifest changes in a Pull Request](https://proandroiddev.com/android-ci-reveal-manifest-changes-in-a-pull-request-a5cdd0600afa)\n- [How to compare apk / aab files](https://medium.com/bumble-tech/how-to-compare-apk-aab-files-par-1634563a5af6)\n- [Diffuse](https://github.com/JakeWharton/diffuse)\n\n## License\n\nCopyright (c) 2023 - Dotanuki Labs - [The MIT license](https://choosealicense.com/licenses/mit/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotanuki-labs%2Fandroid-archives-watchdog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdotanuki-labs%2Fandroid-archives-watchdog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotanuki-labs%2Fandroid-archives-watchdog/lists"}