APK Scanner

Usage

How to use APK Scanner.

Initial setup

The APK Scanner processes a lot of data, which needs to be prepared in advance to get the most out of it.

While it is possible to use the default data provided with the APK Scanner, it is best to prepare your own data so you can modify it to suit your needs.

To get the most out of APK Scanner, please also check the configuration options.

These are example steps to show how this can be done.

Install APK Scanner

Please follow the Installation section.

Prepare a working directory

This is where the APK Scanner data will live in, in this example this is ~/apkscanner.

Terminal

mkdir ~/apkscanner
cd ~/apkscanner

(optional) Create the configuration files

A configuration file allows you to customize the behavior of the APK Scanner, let them know about your data, etc.

Initially create the configuration file for the CLI. For now all it contains is the path to the configuration file for the APK Scanner itself.

Terminal

echo 'apkscanner_config_file_path: "apkscanner.yaml"' > apkscanner-cli.yaml

Next create the configuration file for the APK Scanner. We are setting up the database to live under data/.

Terminal

mkdir data

cat > apkscanner.yaml<< EOF
database:
  debug: false
  type: "h2"
  mode: "default"
  path: "data/apkscanner"
EOF

The current setup should like this:

Terminal

$> tree
.
├── apkscanner-cli.yaml
├── apkscanner.yaml
└── data

(optional) Prepare your local data

Download the sample data directly from the repository and place it within data/, which allows you to easily edit it to suit your own needs.

Terminal

wcurl --output=./data/certificate_denylist.json \
    https://codeberg.org/Katastima/apkscanner/raw/branch/main/sampledata/certificate_denylist.json

wcurl --output=./data/libinfo.jsonl \
    https://codeberg.org/Katastima/apkscanner/raw/branch/main/sampledata/libinfo.jsonl

wcurl --output=./data/libsmali.jsonl \
    https://codeberg.org/Katastima/apkscanner/raw/branch/main/sampledata/libsmali.jsonl

wcurl --output=./data/manifest_config.json \
    https://codeberg.org/Katastima/apkscanner/raw/branch/main/sampledata/manifest_config.json

Your data/ directory should now look like this:

Terminal

$> tree data/
data/
├── certificate_denylist.json
├── libinfo.jsonl
├── libsmali.jsonl
└── manifest_config.json

Adjust the apkscanner.yaml to point to the data:

Terminal

cat >> apkscanner.yaml<< EOF
data:
  certificate_denylist_path: "data/certificate_denylist.json"
  library_definition_path: "data/libsmali.jsonl"
  library_information_path: "data/libinfo.jsonl"
  manifest_config_path: "data/manifest_config.json"
EOF

You can verify that your configuration is taking effect by calling apk-scanner config show:

Terminal

$> apk-scanner config show
~/apkscanner-cli.yaml:
verbose: false
quiet: false
apkscanner_config_file_path: "apkscanner.yaml"
console_output:
  enable_rich_output: true
scan_apk:
  verbose_all: false
  verbose_generic: false
  verbose_apk_info: false
  verbose_detected_libraries: true
  verbose_permissions: true
  verbose_signature_apksig: false
  verbose_signature_certificate: false
  verbose_signing_block: false
  store_as_json: "pretty"
  json_exclude_defaults: false
  json_output_directory: ""
  json_output_subdirectory: false
  json_output_with_apk: false

~/apkscanner.yaml:
data:
  use_default_data: true
  certificate_denylist_path: "data/certificate_denylist.json"
  certificate_denylist_export_path: "export/certificate_denylist.json"
  library_definition_path: "data/libsmali.jsonl"
  library_definition_export_path: "export/libsmali.jsonl"
  library_information_path: "data/libinfo.jsonl"
  library_information_export_path: "export/libinfo.jsonl"
  manifest_config_path: "data/manifest_config.json"
  manifest_config_export_path: "export/manifest_config.json"
database:
  debug: false
  type: "h2"
  mode: "default"
  path: "data/apkscanner"
scan:
  apk_reported_path_type: "default"

(optional) Set up the database

Fill the APK Scanner database with data:

Terminal

apk-scanner database setup

If you are using the included data, you may need to rerun this step after upgrading to a newer version of the APK Scanner to ensure your data is up-to-date.

If you are using your own local data, you need to run this step everytime you have adjusted your data.

Run your first scan

First you need an APK which you can scan.

This example uses the lovely Catima app, which is located at ~/Downloads/me.hackerchick.catima_155.apk.

apk-scanner scan-apk ~/Downloads/me.hackerchick.catima_155.apk

Scanning 1 APK(s):
* me.hackerchick.catima_155.apk

------------------------------------------------------------------------------

Scanned APK:
------------
* Name:    Catima
* Package: me.hackerchick.catima
* Version: 2.39.2 (155)
* SDK:
  * MinSDK:    21 (Android 5.0 - L - Lollipop)
  * TargetSDK: 36 (Android 16 - B - Baklava)
* File:    me.hackerchick.catima_155.apk
* SHA-256: 9287cb84e05e8bf9c6b287982376f074bab32bc1db30bec894c272d53b95c066

Manifest verification:
----------------------
* Dangerous permissions
  * android.permission.CAMERA
  * android.permission.READ_EXTERNAL_STORAGE

Permissions:
------------
* android.permission.CAMERA
* android.permission.READ_EXTERNAL_STORAGE (min: -1, max: 23)
* me.hackerchick.catima.DYNAMIC_RECEIVER_NOT_EXPORTED_PERMISSION
* me.hackerchick.catima.READ_CARDS

Found 4 permissions.

Libraries detected:
-------------------
* ACRA (/org/acra): Utility, Apache-2.0; Tracking
* Android Activity Saved State (/androidx/savedstate): Utility, Apache-2.0
* Android Emoji2 Compat (/androidx/emoji2): UI Component, Apache-2.0
* Android Jetpack Annotations (/androidx/annotation): Utility, Apache-2.0
* Android Jetpack VersionedParcelable (/androidx/versionedparcelable): Utility, Apache-2.0
* Android Support Library collections (/androidx/collection): Utility, Apache-2.0
* Android Support Library Custom View (/androidx/customview): UI Component, Apache-2.0
* Android Support v4 (/android/support/v4): Development Framework, Apache-2.0
* AndroidX Activity (/androidx/activity): Utility, Apache-2.0
* Androidx Core (/androidx/core): Utility, Apache-2.0
* AndroidX Cursor Adapter (/androidx/cursoradapter): Utility, Apache-2.0
* AndroidX Fragment (/androidx/fragment): UI Component, Apache-2.0
* AndroidX Widget ViewPager2 (/androidx/viewpager2): UI Component, Apache-2.0
* Apache Commons (/org/apache/commons): Development Framework, Apache-2.0
* AppCompat (/androidx/appcompat): Utility, Apache-2.0
* Arch (/androidx/arch): Utility, Apache-2.0
* Auto (/com/google/auto): Utility, Apache-2.0
* Cardview (/androidx/cardview): UI Component, Apache-2.0
* Color Picker (/com/jaredrummler/android/colorpicker): UI Component, Apache-2.0
* Concurrent (/androidx/concurrent): Utility, Apache-2.0
* Constraint Layout Library (/androidx/constraintlayout): Utility, Apache-2.0
* Coordinatorlayout (/androidx/coordinatorlayout): UI Component, Apache-2.0
* Dynamicanimation (/androidx/dynamicanimation): UI Component, Apache-2.0
* Exifinterface (/androidx/exifinterface): Utility, Apache-2.0
* Google Core Libraries for Java 6+ (/com/google/common): Utility, Apache-2.0
* Google Material Design (/com/google/android/material): Utility, Apache-2.0
* Interpolator (/androidx/interpolator): UI Component, Apache-2.0
* Kotlin (/kotlin): Utility, Apache-2.0
* kotlinx.coroutines (/kotlinx/coroutines): Utility, Apache-2.0
* Lifecycle (/androidx/lifecycle): Utility, Apache-2.0
* Loader (/androidx/loader): Utility, Apache-2.0
* Palette (/androidx/palette): Utility, Apache-2.0
* Preference (/androidx/preference): Utility, Apache-2.0
* ProfileInstaller (/androidx/profileinstaller): Utility, Apache-2.0
* Recyclerview (/androidx/recyclerview): Utility, Apache-2.0
* Startup (/androidx/startup): Utility, Apache-2.0
* Tracing (/androidx/tracing): Utility, Apache-2.0
* Transition (/androidx/transition): UI Component, Apache-2.0
* uCrop (/com/yalantis/ucrop): Utility, Apache-2.0
* Vectordrawable (/androidx/vectordrawable): UI Component, Apache-2.0
* Viewpager (/androidx/viewpager): UI Component, Apache-2.0
* Zip4j (/net/lingala/zip4j): Utility, Apache-2.0
* ZXing ('Zebra Crossing') (/com/google/zxing): Utility, Apache-2.0
* ZXing Android Embedded (/com/journeyapps/barcodescanner): Utility, Apache-2.0

44 libraries found.

Offending libraries:
--------------------
* ACRA (/org/acra): Tracking

1 offending library found.

Signature verification:
-----------------------
* apksig
  * Verified by apksig: Verified
* Number of certificates: 1
* Certificate #1
  * Key Algorithm Name: SHA256withRSA
  * Subject:
    * Principal: CN=Sylvia van Os
  * Not Before: 2020-10-29T18:36:02
  * Not After:  2045-10-23T18:36:02
  * SHA-256: d405cd69ede4c22074c328fb825689a84ab3fca4b3fdf0b6cc1333af62c67eb3
  * Public Key
    * Key Algorithm: RSA
    * Key Size (bits): 2048

Android Signing Block verification:
-----------------------------------
No offending blocks found.

Export data from the database

If you have edited the database used by APK Scanner directly or just want to export your data in general, you can do so!

The location of the exported files will match the data configuration of your apkscanner.yaml.

# Export everything
apk-scanner database export-all

# Export library data
apk-scanner database export-library-definitions

# Export manifest data
apk-scanner database export-manifest-config

# Export signing certificates data
apk-scanner database export-signing-certificate-data

$> apk-scanner database export-all
Exported 14 denied signing certificates to: ~/apkscanner/export/certificate_denylist.json
Exported 4126 library definitions to: ~/apkscanner/export/libinfo.jsonl
Exported 3617 library information entries to: ~/apkscanner/export/libsmali.jsonl
Exported manifest config ((Flags(groups: 3, total flags: 3), Filters(groups: 3, total filters: 3), permissions(groups: 3, total permissions: 32))) to: ~/apkscanner/export/manifest_config.json

$> apk-scanner database export-library-definitions
Exported 4126 library definitions to: ~/apkscanner/export/libinfo.jsonl
Exported 3617 library information entries to: ~/apkscanner/export/libsmali.jsonl

$> apk-scanner database export-manifest-config
Exported manifest config ((Flags(groups: 3, total flags: 3), Filters(groups: 3, total filters: 3), permissions(groups: 3, total permissions: 32))) to: ~/apkscanner/export/manifest_config.json

$> apk-scanner database export-signing-certificate-data
Exported 14 denied signing certificates to: ~/apkscanner/export/certificate_denylist.json

Advanced usage

Specify path to CLI config file

You can use -c/--config to specify a custom location for the apkscanner-cli.yaml (defaults to current working directory where you run apk-scanner).

Terminal

apk-scanner -c /path/to/apkscanner-cli.yaml

apk-scanner --config /path/to/apkscanner-cli.yaml

`argfile` support

Loading additional CLI arguments from a file is supported.

To use it, pass in any file path prefixed with @ to expand the contents of the file into command line parameters.

-q
scan-apk
--json=pretty
/opt/apkscanner/data/apks/me.hackerchick.catima_149.apk

apk-scanner @scan_the_best_app.shell

apk-scanner \
    -q \
    scan-apk \
    --json=pretty \
    /opt/apkscanner/data/apks/me.hackerchick.catima_149.apk

Installation

A guide to install APK Scanner.

Configuration

How to configure the APK Scanner using configuration files.