Merge branch 'master' of https://github.com/OWASP/owasp-mastg into pr…

…/nmsa/3026

.gitignore

@@ -29,4 +29,5 @@ docs/assets/Images
 OWASP_MASVS.yaml
 cross_references.yaml
 drafts/
-Payload/
+Payload/
+.vscode/settings.json

Document/0x02a-Frontispiece.md

@@ -58,7 +58,7 @@ All our Changelogs are available online at the OWASP MASTG GitHub repository, se
 
 Please consult the laws in your country before executing any tests against mobile apps by utilizing the MASTG materials. Refrain from violating the laws with anything described in the MASTG.
 
-Our [Code of Conduct] has further details: <https://github.com/OWASP/owasp-mastg/blob/master/.github/CODE_OF_CONDUCT.md>
+Our [Code of Conduct](https://github.com/OWASP/owasp-mastg/blob/master/.github/CODE_OF_CONDUCT.md) has further details.
 
 OWASP thanks the many authors, reviewers, and editors for their hard work in developing this guide. If you have any comments or suggestions, please connect with us: <https://mas.owasp.org/contact>
 

Document/0x05a-Platform-Overview.md

@@ -646,12 +646,21 @@ When an application is installed on the Android device, the Package Manager ensu
 
 ### APK Signing Schemes
 
-Android supports three application signing schemes. Starting with Android 9 (API level 28), APKs can be verified with APK Signature Scheme v3 (v3 scheme), APK Signature Scheme v2 (v2 scheme) or JAR signing (v1 scheme). For Android 7.0 (API level 24) and above, APKs can be verified with the APK Signature Scheme v2 (v2 scheme) or JAR signing (v1 scheme). For backwards compatibility, an APK can be signed with multiple signature schemes in order to make the app run on both newer and older SDK versions. [Older platforms ignore v2 signatures and verify v1 signatures only](https://source.android.com/security/apksigning/ "APK Signing").
+Android supports multiple application signing schemes:
+
+- **Below Android 7.0 (API level 24)**: applications can only use the JAR signing (v1) scheme which does not protect all parts of the APK. This scheme is considered insecure.
+- **Android 7.0 (API level 24) and above**: applications can use the **v2 signature scheme**, which signs the APK as a whole, providing stronger protection compared to the older v1 (JAR) signing method.
+- **Android 9 (API level 28) and above**: It's recommended to use both the **v2 and v3 signature schemes**. The v3 scheme supports **key rotation**, enabling developers to replace keys in the event of a compromise without invalidating old signatures.
+- **Android 11 (API level 30) and above**: applications can optionally include the **v4 signature scheme** to enable faster incremental updates.
+
+For backwards compatibility, an APK can be signed with multiple signature schemes in order to make the app run on both newer and older SDK versions.  For example, [older platforms ignore v2 signatures and verify v1 signatures only](https://source.android.com/security/apksigning/).
 
 #### JAR Signing (v1 Scheme)
 
 The original version of app signing implements the signed APK as a standard signed JAR, which must contain all the entries in `META-INF/MANIFEST.MF`. All files must be signed with a common certificate. This scheme does not protect some parts of the APK, such as ZIP metadata. The drawback of this scheme is that the APK verifier needs to process untrusted data structures before applying the signature, and the verifier discards data the data structures don't cover. Also, the APK verifier must decompress all compressed files, which takes considerable time and memory.
 
+This signature scheme is considered insecure, it is for example affected by the **Janus vulnerability (CVE-2017-13156)**, which can allow malicious actors to modify APK files without invalidating the v1 signature. As such, **v1 should never be relied on for devices running Android 7.0 and above**.
+
 #### APK Signature Scheme (v2 Scheme)
 
 With the APK signature scheme, the complete APK is hashed and signed, and an APK Signing Block is created and inserted into the APK. During validation, the v2 scheme checks the signatures of the entire APK file. This form of APK verification is faster and offers more comprehensive protection against modification. You can see the [APK signature verification process for v2 Scheme](https://source.android.com/security/apksigning/v2#verification "APK Signature verification process") below.

Document/0x05d-Testing-Data-Storage.md

@@ -39,23 +39,14 @@ Understanding each relevant data storage function is crucial for performing the
 
 ### Shared Preferences
 
-The [SharedPreferences](https://developer.android.com/training/data-storage/shared-preferences "Shared Preferences") API is commonly used to permanently save small collections of key-value pairs. Data stored in a SharedPreferences object is written to a plain-text XML file. The SharedPreferences object can be declared world-readable (accessible to all apps) or private.
-Misuse of the SharedPreferences API can often lead to exposure of sensitive data. Consider the following example:
+The [`SharedPreferences`](https://developer.android.com/training/data-storage/shared-preferences "Shared Preferences") API is commonly used to permanently save small collections of key-value pairs.
 
-Example for Java:
+Since Android 4.2 (API level 17) the `SharedPreferences` object can only be declared to be private (and not world-readable, i.e. accessible to all apps). However, since data stored in a `SharedPreferences` object is written to a plain-text XML file so its misuse can often lead to exposure of sensitive data.
 
-```java
-SharedPreferences sharedPref = getSharedPreferences("key", MODE_WORLD_READABLE);
-SharedPreferences.Editor editor = sharedPref.edit();
-editor.putString("username", "administrator");
-editor.putString("password", "supersecret");
-editor.commit();
-```
-
-Example for Kotlin:
+Consider the following example:
 
 ```kotlin
-var sharedPref = getSharedPreferences("key", Context.MODE_WORLD_READABLE)
+var sharedPref = getSharedPreferences("key", Context.MODE_PRIVATE)
 var editor = sharedPref.edit()
 editor.putString("username", "administrator")
 editor.putString("password", "supersecret")
@@ -74,14 +65,31 @@ Once the activity has been called, the file key.xml will be created with the pro
 </map>
 ```
 
-- `MODE_WORLD_READABLE` allows all applications to access and read the contents of `key.xml`.
+`MODE_PRIVATE` makes the file only accessible by the calling app. See ["Use SharedPreferences in private mode"](https://developer.android.com/privacy-and-security/security-best-practices#sharedpreferences).
 
-```bash
-root@hermes:/data/data/sg.vp.owasp_mobile.myfirstapp/shared_prefs # ls -la
--rw-rw-r-- u0_a118    170 2016-04-23 16:51 key.xml
-```
+> Other insecure modes exist, such as `MODE_WORLD_READABLE` and `MODE_WORLD_WRITEABLE`, but they have been deprecated since Android 4.2 (API level 17) and [removed in Android 7.0 (API Level 24)](https://developer.android.com/reference/android/os/Build.VERSION_CODES#N). Therefore, only apps running on an older OS version (`android:minSdkVersion` less than 17) will be affected. Otherwise, Android will throw a [SecurityException](https://developer.android.com/reference/java/lang/SecurityException). If an app needs to share private files with other apps, it is best to use a [FileProvider](https://developer.android.com/reference/androidx/core/content/FileProvider) with the [FLAG_GRANT_READ_URI_PERMISSION](https://developer.android.com/reference/android/content/Intent#FLAG_GRANT_READ_URI_PERMISSION). See [Sharing Files](https://developer.android.com/training/secure-file-sharing) for more details.
 
-> Please note that `MODE_WORLD_READABLE` and `MODE_WORLD_WRITEABLE` were deprecated starting on API level 17. Although newer devices may not be affected by this, applications compiled with an `android:targetSdkVersion` value less than 17 may be affected if they run on an OS version that was released before Android 4.2 (API level 17).
+You might also use [`EncryptedSharedPreferences`](https://developer.android.com/reference/androidx/security/crypto/EncryptedSharedPreferences), which is wrapper of `SharedPreferences` that automatically encrypts all data stored to the shared preferences.
+
+```kotlin
+var masterKey: MasterKey? = null
+masterKey = Builder(this)
+    .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
+    .build()
+
+val sharedPreferences: SharedPreferences = EncryptedSharedPreferences.create(
+    this,
+    "secret_shared_prefs",
+    masterKey,
+    EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+    EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
+)
+
+val editor = sharedPreferences.edit()
+editor.putString("username", "administrator")
+editor.putString("password", "supersecret")
+editor.commit()
+```
 
 ### Databases
 

Document/0x05h-Testing-Platform-Interaction.md

@@ -48,6 +48,9 @@ Independently from the assigned Protection Level, it is important to consider th
 | **CRITICAL**     | `android.permission.MOUNT_UNMOUNT_FILESYSTEMS`                  | signature         |
 | **CRITICAL**     | `android.permission.PROVIDE_DEFAULT_ENABLED_CREDENTIAL_SERVICE` | signature         |
 | **CRITICAL**     | `android.permission.PROVIDE_REMOTE_CREDENTIALS`                 | signature         |
+| **CRITICAL**     | `android.permission.THREAD_NETWORK_PRIVILEGED`                  | signature         |
+| **CRITICAL**     | `android.permission.RECORD_SENSITIVE_CONTENT`                   | signature         |
+| **CRITICAL**     | `android.permission.RECEIVE_SENSITIVE_NOTIFICATIONS`            | signature         |
 | **HIGH**         | `android.permission.INSTALL_GRANT_RUNTIME_PERMISSIONS`          | signature         |
 | **HIGH**         | `android.permission.READ_SMS`                                   | dangerous         |
 | **HIGH**         | `android.permission.WRITE_SMS`                                  | normal            |
@@ -72,6 +75,9 @@ Independently from the assigned Protection Level, it is important to consider th
 | **HIGH**         | `android.permission.MANAGE_ONGOING_CALLS`                       | signature         |
 | **HIGH**         | `android.permission.READ_RESTRICTED_STATS`                      | internal          |
 | **HIGH**         | `android.permission.BIND_AUTOFILL_SERVICE`                      | signature         |
+| **HIGH**         | `android.permission.WRITE_VERIFICATION_STATE_E2EE_CONTACT_KEYS` | signature         |
+| **HIGH**         | `android.permission.READ_DROPBOX_DATA`                          | signature         |
+| **HIGH**         | `android.permission.WRITE_FLAGS`                                | signature         |
 | **MEDIUM**       | `android.permission.ACCESS_COARSE_LOCATION`                     | dangerous         |
 | **MEDIUM**       | `android.permission.CHANGE_COMPONENT_ENABLED_STATE`             | signature         |
 | **MEDIUM**       | `android.permission.READ_CONTACTS`                              | dangerous         |
@@ -94,6 +100,9 @@ Independently from the assigned Protection Level, it is important to consider th
 | **MEDIUM**       | `android.permission.READ_MEDIA_AUDIO`                           | dangerous         |
 | **MEDIUM**       | `android.permission.READ_MEDIA_IMAGES`                          | dangerous         |
 | **MEDIUM**       | `android.permission.READ_MEDIA_VIDEO`                           | dangerous         |
+| **MEDIUM**       | `android.permission.REGISTER_NSD_OFFLOAD_ENGINE`                | signature         |
+| **MEDIUM**       | `android.permission.ACCESS_LAST_KNOWN_CELL_ID`                  | signature         |
+| **MEDIUM**       | `android.permission.USE_COMPANION_TRANSPORTS`                   | signature         |
 | **LOW**          | `android.permission.DOWNLOAD_WITHOUT_NOTIFICATION`              | normal            |
 | **LOW**          | `android.permission.PACKAGE_USAGE_STATS`                        | signature         |
 | **LOW**          | `android.permission.MASTER_CLEAR`                               | signature         |
@@ -105,6 +114,11 @@ Independently from the assigned Protection Level, it is important to consider th
 | **LOW**          | `android.permission.LOG_FOREGROUND_RESOURCE_USE`                | signature         |
 | **LOW**          | `android.permission.MANAGE_DEFAULT_APPLICATIONS`                | signature         |
 | **LOW**          | `android.permission.MANAGE_FACE`                                | signature         |
+| **LOW**          | `android.permission.REPORT_USAGE_STATS`                         | signature         |
+| **LOW**          | `android.permission.MANAGE_DISPLAYS`                            | signature         |
+| **LOW**          | `android.permission.RESTRICT_DISPLAY_MODES`                     | signature         |
+| **LOW**          | `android.permission.ACCESS_HIDDEN_PROFILES_FULL`                | signature         |
+| **LOW**          | `android.permission.GET_BACKGROUND_INSTALLED_PACKAGES`          | signature         |
 | **NONE**         | `android.permission.ACCESS_NETWORK_STATE`                       | normal            |
 | **NONE**         | `android.permission.RECEIVE_BOOT_COMPLETED`                     | normal            |
 | **NONE**         | `android.permission.WAKE_LOCK`                                  | normal            |

Document/0x05i-Testing-Code-Quality-and-Build-Settings.md

@@ -24,7 +24,7 @@ Three APK signing schemes are available:
 - APK Signature Scheme v3 (v3 scheme).
 
 The v2 signature, which is supported by Android 7.0 (API level 24) and above, offers improved security and performance compared to v1 scheme.
-The V3 signature, which is supported by Android 9 (API level 28) and above, gives apps the ability to change their signing keys as part of an APK update. This functionality assures compatibility and apps continuous availability by allowing both the new and the old keys to be used. Note that it is only available via apksigner at the time of writing.
+The V3 signature, which is supported by Android 9 (API level 28) and above, gives apps the ability to change their signing keys as part of an APK update. This functionality assures compatibility and apps continuous availability by allowing both the new and the old keys to be used. Note that it is only available via @MASTG-TOOL-0123 at the time of writing.
 
 For each signing scheme the release builds should always be signed via all its previous schemes as well.
 

Document/0x06i-Testing-Code-Quality-and-Build-Settings.md

@@ -51,7 +51,7 @@ Detecting the presence of [binary protection mechanisms](0x04h-Testing-Code-Qual
 Although Xcode enables all binary security features by default, it may be relevant to verify this for old applications or to check for compiler flag misconfigurations. The following features are applicable:
 
 - [**PIE (Position Independent Executable)**](0x04h-Testing-Code-Quality.md#position-independent-code):
-    - PIE applies to executable binaries (Mach-O type `MH_EXECUTE`).
+    - PIE applies to executable binaries (Mach-O type `MH_EXECUTE`) [source](https://web.archive.org/web/20230328221404/https://opensource.apple.com/source/cctools/cctools-921/include/mach-o/loader.h.auto.html).
     - However it's not applicable for libraries (Mach-O type `MH_DYLIB`).
 - [**Memory management**](0x04h-Testing-Code-Quality.md#memory-management):
     - Both pure Objective-C, Swift and hybrid binaries should have ARC (Automatic Reference Counting) enabled.

Document/index.md

@@ -25,6 +25,7 @@ Start exploring the MASTG:
 <a href="/MASTG/demos/" class="md-button md-button--primary" style="margin: 5px; min-width: 12em; text-align: center;">:material-flask-outline:  Demos</a>
 <a href="/MASTG/tools/" class="md-button md-button--primary" style="margin: 5px; min-width: 12em; text-align: center;">:octicons-tools-24:  Tools</a>
 <a href="/MASTG/apps/" class="md-button md-button--primary" style="margin: 5px; min-width: 12em; text-align: center;">:octicons-code-square-24:  Apps</a>
+<a href="/MASTG/best-practices/" class="md-button md-button--primary" style="margin: 5px; min-width: 12em; text-align: center;">:material-shield-check:  Best Practices (v2 Beta)</a>
 
 <span style="color: darkgray; font-size: small"> :blue_heart:{ .pump } Support the project by purchasing the [OWASP MASTG on leanpub.com](https://leanpub.com/owasp-mastg). All funds raised through sales of this book go directly into the project budget and will be used to for technical editing and designing the book and fund production of future releases.</span>
 

mitigations/android-use-secure-random.md → best-practices/MASTG-BEST-0001.md

@@ -1,5 +1,7 @@
 ---
-title: Use Secure Random Number Generators APIs
+title: Use Secure Random Number Generator APIs
+alias: android-use-secure-random
+id: MASTG-BEST-0001
 platform: android
 ---
 

mitigations/use-proguard.md → best-practices/MASTG-BEST-0002.md

@@ -1,8 +1,14 @@
 ---
-title: Use ProGuard to Remove Logging Code
+title: Remove Logging Code
+alias: remove-logging-code
+id: MASTG-BEST-0002
 platform: android
 ---
 
+Ideally, a release build shouldn't use any logging functions, making it easier to assess sensitive data exposure.
+
+## Using ProGuard
+
 While preparing the production release, you can use tools like @MASTG-TOOL-0022 (included in Android Studio). To determine whether all logging functions from the `android.util.Log` class have been removed, check the ProGuard configuration file (proguard-rules.pro) for the following options (according to this [example of removing logging code](https://www.guardsquare.com/en/products/proguard/manual/examples#logging "ProGuard\'s example of removing logging code") and this article about [enabling ProGuard in an Android Studio project](https://developer.android.com/studio/build/shrink-code#enable "Android Developer - Enable shrinking, obfuscation, and optimization")):
 
 ```default
@@ -57,3 +63,7 @@ SecureLog.v("Private key [byte format]: ", key);
 ```
 
 Then configure ProGuard to strip its calls.
+
+## Custom Logging
+
+You can implement a custom logging facility and disable it at once only for the release builds.

mitigations/comply-with-privacy-regulations.md → best-practices/MASTG-BEST-0003.md

@@ -1,5 +1,7 @@
 ---
 title: Comply with Privacy Regulations and Best Practices
+alias: comply-with-privacy-regulations
+id: MASTG-BEST-0003
 platform: android
 ---
 

best-practices/MASTG-BEST-0004.md

@@ -0,0 +1,11 @@
+---
+title: Exclude Sensitive Data from Backups
+alias: exclude-sensitive-data-from-backups
+id: MASTG-BEST-0004
+platform: android
+---
+
+For the sensitive files found, instruct the system to exclude them from the backup:
+
+- If you are using Auto Backup, mark them with the `exclude` tag in `backup_rules.xml` (for Android 11 or lower using `android:fullBackupContent`) or `data_extraction_rules.xml` (for Android 12 and higher using `android:dataExtractionRules`), depending on the target API. Make sure to use both the `cloud-backup` and `device-transfer` parameters.
+- If you are using the key-value approach, set up your [BackupAgent](https://developer.android.com/identity/data/keyvaluebackup#BackupAgent) accordingly.

best-practices/MASTG-BEST-0005.md

@@ -0,0 +1,12 @@
+---
+title: Use Secure Encryption Modes
+alias: use-secure-encryption-modes
+id: MASTG-BEST-0005
+platform: android
+---
+
+Replace insecure encryption modes with secure block cipher modes such as [AES-GCM or AES-CCM](https://csrc.nist.gov/pubs/sp/800/38/d/final) which are authenticated encryption modes that provide confidentiality, integrity, and authenticity.
+
+We recommend avoiding CBC, which while being more secure than ECB, improper implementation, especially incorrect padding, can lead to vulnerabilities such as padding oracle attacks.
+
+For comprehensive guidance on implementing secure encryption modes in Android, refer to the official Android Developers documentation on [Cryptography](https://developer.android.com/privacy-and-security/cryptography).

best-practices/MASTG-BEST-0006.md

@@ -0,0 +1,26 @@
+---
+title: Use Up-to-Date APK Signing Schemes
+alias: use-up-to-date-apk-signing-schemes
+id: MASTG-BEST-0006
+platform: android
+---
+
+Ensure that the app is signed with at least the v2 or v3 APK signing scheme, as these provide comprehensive integrity checks and protect the entire APK from tampering. For optimal security and compatibility, consider using v3, which also supports key rotation.
+
+Optionally, you can add v4 signing to enable faster [incremental updates](https://developer.android.com/about/versions/11/features#incremental) in Android 11 and above, but v4 alone does not provide security protections and should be used alongside v2 or v3.
+
+The signing configuration can be managed through Android Studio or the `signingConfigs` section in `build.gradle` or `build.gradle.kts`. To activate both the v3 and v4 schemes, the following values must be set:
+
+```default
+// build.gradle
+android {
+  ...
+  signingConfigs {
+    config {
+        ...
+        enableV3Signing true
+        enableV4Signing true
+    }
+  }
+}
+```