Reorganize overlay protection mechanisms and add HIDE_OVERLAY_WINDOWS permission

Co-authored-by: cpholguera <29175115+cpholguera@users.noreply.github.com>

Author: Copilot

best-practices/MASTG-BEST-0029.md

@@ -10,17 +10,23 @@ Apps should protect sensitive user interactions from overlay attacks by implemen
 
 ## Recommendation
 
-Implement touch filtering to prevent touch events when the app's UI is obscured by another app. Use one or more of the following mechanisms:
+Implement appropriate mechanisms to protect against overlay attacks. The following approaches are listed from most robust to least robust:
 
-1. **Set the layout attribute `android:filterTouchesWhenObscured="true"`** for sensitive views such as login buttons, payment confirmations, or permission requests. This filters touch events when the view is obscured.
+### Prevention Mechanisms
 
-2. **Call `setFilterTouchesWhenObscured(true)`** programmatically on sensitive views to enable touch filtering at runtime.
+These mechanisms prevent overlays from appearing or block touch events when overlays are detected:
 
-3. **Call `setHideOverlayWindows(true)`** on the window (API level 31+) to hide all non-system overlay windows while the activity is in the foreground. This provides stronger protection by preventing overlays entirely rather than just filtering touch events.
+1. **Use `HIDE_OVERLAY_WINDOWS` permission and `setHideOverlayWindows(true)`** (API level 31+): Declare the [`HIDE_OVERLAY_WINDOWS`](https://developer.android.com/reference/android/Manifest.permission#HIDE_OVERLAY_WINDOWS) permission in the manifest and call [`setHideOverlayWindows(true)`](https://developer.android.com/reference/android/view/Window#setHideOverlayWindows(boolean)) on the window to hide all non-system overlay windows while the activity is in the foreground. This is the most robust solution as it prevents overlays entirely rather than just filtering touch events.
 
-4. **Override `onFilterTouchEventForSecurity`** for more granular control and to implement custom security policies based on your app's specific requirements.
+2. **Set `android:filterTouchesWhenObscured="true"` or call `setFilterTouchesWhenObscured(true)`**: Set the layout attribute [`android:filterTouchesWhenObscured="true"`](https://developer.android.com/reference/android/view/View#attr_android:filterTouchesWhenObscured) in XML for sensitive views, or call [`setFilterTouchesWhenObscured(true)`](https://developer.android.com/reference/android/view/View#setFilterTouchesWhenObscured(boolean)) programmatically on sensitive views such as login buttons, payment confirmations, or permission requests. This filters touch events when the view is obscured by another visible window.
 
-5. **Check motion event flags** such as `FLAG_WINDOW_IS_OBSCURED` (API level 9+) or `FLAG_WINDOW_IS_PARTIALLY_OBSCURED` (API level 29+) in touch event handlers to detect obscured windows and respond appropriately.
+3. **Override `onFilterTouchEventForSecurity`**: Override the [`onFilterTouchEventForSecurity`](https://developer.android.com/reference/android/view/View#onFilterTouchEventForSecurity(android.view.MotionEvent)) method for more granular control and to implement custom security policies based on your app's specific requirements.
+
+### Detection Mechanisms
+
+These mechanisms detect when overlays are present but do not automatically prevent them. They allow the app to respond accordingly:
+
+- **Check motion event flags** such as [`FLAG_WINDOW_IS_OBSCURED`](https://developer.android.com/reference/android/view/MotionEvent#FLAG_WINDOW_IS_OBSCURED) (API level 9+) or [`FLAG_WINDOW_IS_PARTIALLY_OBSCURED`](https://developer.android.com/reference/android/view/MotionEvent#FLAG_WINDOW_IS_PARTIALLY_OBSCURED) (API level 29+) in touch event handlers to detect obscured windows and respond appropriately. Note that this approach requires custom implementation to decide how to handle detected overlays.
 
 Apply these protections selectively to security-sensitive UI elements where user confirmation is critical, such as:
 
@@ -53,8 +59,9 @@ Touch filtering mechanisms help ensure that user interactions occur with the int
 
 - Android Developer Documentation: [Tapjacking](https://developer.android.com/privacy-and-security/risks/tapjacking)
 - Android Developer Documentation: [View Security](https://developer.android.com/reference/android/view/View#security)
-- Android Developer Documentation: [setFilterTouchesWhenObscured](https://developer.android.com/reference/android/view/View#setFilterTouchesWhenObscured(boolean))
+- Android Developer Documentation: [HIDE_OVERLAY_WINDOWS](https://developer.android.com/reference/android/Manifest.permission#HIDE_OVERLAY_WINDOWS)
 - Android Developer Documentation: [setHideOverlayWindows](https://developer.android.com/reference/android/view/Window#setHideOverlayWindows(boolean))
+- Android Developer Documentation: [setFilterTouchesWhenObscured](https://developer.android.com/reference/android/view/View#setFilterTouchesWhenObscured(boolean))
 - Android Developer Documentation: [onFilterTouchEventForSecurity](https://developer.android.com/reference/android/view/View#onFilterTouchEventForSecurity(android.view.MotionEvent))
 - Android Developer Documentation: [FLAG_WINDOW_IS_OBSCURED](https://developer.android.com/reference/android/view/MotionEvent#FLAG_WINDOW_IS_OBSCURED)
 - Android Developer Documentation: [FLAG_WINDOW_IS_PARTIALLY_OBSCURED](https://developer.android.com/reference/android/view/MotionEvent#FLAG_WINDOW_IS_PARTIALLY_OBSCURED)

knowledge/android/MASVS-PLATFORM/MASTG-KNOW-0022.md

@@ -14,9 +14,14 @@ There are several types of overlay attacks affecting different Android versions:
 
 Android provides several defensive mechanisms that apps can use to protect against overlay attacks:
 
+**Prevention Mechanisms:**
+
+- [`HIDE_OVERLAY_WINDOWS`](https://developer.android.com/reference/android/Manifest.permission#HIDE_OVERLAY_WINDOWS) permission and [`setHideOverlayWindows`](https://developer.android.com/reference/android/view/Window#setHideOverlayWindows(boolean)) (since API level 31): Declare this permission in the manifest and call the method on the window to hide all non-system overlay windows while the activity is in the foreground. This provides the strongest protection by preventing overlays entirely.
+- [`android:filterTouchesWhenObscured`](https://developer.android.com/reference/android/view/View#attr_android:filterTouchesWhenObscured) attribute and [`setFilterTouchesWhenObscured`](https://developer.android.com/reference/android/view/View#setFilterTouchesWhenObscured(boolean)) method: Set this layout attribute to `true` in XML or call the method programmatically to filter touch events when the view is obscured by another visible window.
 - [`onFilterTouchEventForSecurity`](https://developer.android.com/reference/android/view/View#onFilterTouchEventForSecurity(android.view.MotionEvent)): Override this method for fine-grained control to implement custom security policies for views.
-- [`android:filterTouchesWhenObscured`](https://developer.android.com/reference/android/view/View#attr_android:filterTouchesWhenObscured): Set this layout attribute to `true` or call [`setFilterTouchesWhenObscured`](https://developer.android.com/reference/android/view/View#setFilterTouchesWhenObscured(boolean)) to filter touch events when the view is obscured by another visible window.
-- [`setHideOverlayWindows`](https://developer.android.com/reference/android/view/Window#setHideOverlayWindows(boolean)) (since API level 31): Call this method on the window to hide all non-system overlay windows while the activity is in the foreground. This provides a stronger protection by preventing overlays entirely rather than just filtering touch events.
+
+**Detection Mechanisms:**
+
 - [`FLAG_WINDOW_IS_OBSCURED`](https://developer.android.com/reference/android/view/MotionEvent#FLAG_WINDOW_IS_OBSCURED) (since API level 9): Check this flag to detect if the window is obscured.
 - [`FLAG_WINDOW_IS_PARTIALLY_OBSCURED`](https://developer.android.com/reference/android/view/MotionEvent#FLAG_WINDOW_IS_PARTIALLY_OBSCURED) (since API level 29): Check this flag to detect if the window is partially obscured.