android-intent-security

Files (1)

• SKILL.md

SKILL.md (first lines)

This skill provides guidelines and patterns to secure Android components
(Activities, Services, Broadcast Receivers, Content Providers) and handle
Intents safely, preventing privilege escalation and unauthorized access.

## Glossary

- **Intent:** An asynchronous messaging object used to request an action from another app component.
- **Exported component:** A component (`android:exported="true"`) that can be launched by other apps on the device.
- **Sticky intent:** A broadcast intent that remains in the system cache after it's sent, allowing any app to retrieve its contents.
- **Signature permission:** A permission whose protection level is set to `signature`, granted only to apps signed with the same developer key.
- **onNewIntent:** An activity lifecycle callback invoked when an activity is launched with `FLAG_ACTIVITY_SINGLE_TOP` and is already running at the top of the history stack.
- **PendingIntent:** A token granted to a foreign application (for example, system services) allowing it to execute a predefined Intent with the creator's permissions.
- **Mutable PendingIntent:** A PendingIntent whose underlying Intent parameters can be modified by the receiving application.
- **ContentProvider:** A component that encapsulates data and provides it to other applications via standard query/insert interfaces.
- **IntentSanitizer:** A utility class in AndroidX Core used to build a safe, sanitized copy of an incoming Intent by filtering out unauthorized components, actions, or extras.
- **Intent redirection (forwarding):** A vulnerability where an application receives an intent from an untrusted source and uses it to launch a private, non-exported component.

## Prerequisites

- The agent **MUST** be able to describe the function and security implications of `onCreate`, `onNewIntent`, and the `singleTop` launch mode.
- The agent **MUST** be able to declare `<activity>`, `<service>`, `<receiver>`, and `<provider>` tags in `AndroidManifest.xml` and define their `android:exported` and `android:permission` attributes.
- The agent **MUST** be able to implement signature verification checks using `PackageManager`.

## Limitations

- This skill focuses on local inter-component and inter-app communication security on the Android platform.
- This skill **doesn't** cover network security, web integration, or host-to-server security.

## Setup and dependencies

- **Android SDK:** Minimum API Level 23 (Android 6.0) is required for standard hardware-backed keystore operations and component validation.
- **AndroidX Core Library:** `androidx.core:core:1.9.0` or higher is **mandatory** to leverage `IntentSanitizer`.
- **Standard API access:** Standard Android `PackageManager` APIs are required for runtime component verification.

*** ** * ** ***

## Intent security logic and decisions

### 1. Intent routing comparison

Evaluate the security features of different intent delivery methods:

| Intent Delivery Method | Scope | Recommended Use Case |
|---|---|---|
| Explicit Intent (Internal) | App Private | Launching internal activities/services |
| Implicit Intent | System Wide | Launching system camera, dialer, or sharing |
| Local Broadcasts (LocalBroadcastManager) (DEPRECATED) | App Private | Internal asynchronous event routing. **Deprecated**: Use in-app observers like Kotlin Flows/SharedFlow, LiveData, or reactive patterns instead. |
| System Broadcasts | System Wide | Receiving system events (NFC, Bluetooth) |

### 2. PendingIntent mutability flag options

Evaluate the security implications of PendingIntent mutability flags:

| Flag Name | Mutability | Recommended Use Case |
|---|---|---|
| `PendingIntent.FLAG_IMMUTABLE` | Immutable | Default for almost all PendingIntents, such as alarms and notifications |
| `PendingIntent.FLAG_MUTABLE` | Mutable | Inline notifications replies, slice actions (requires explicit target intent) |

### 3. Intent handling and redirection logic

IF (the component receives a nested Intent as an extra) {
IF (AndroidX Core 1.9.0+ and higher is available) {
MUST construct an `IntentSanitizer` to explicitly allowlist components, actions, data, and extras.
MUST call `sanitizeByThrowing()` or `sanitizeByFiltering()` before launching.
} ELSE {
MUST verify that the nested Intent's target package matches the current application package.
MUST verify that the target component of the nested Intent is publicly exported.
}
NEVER launch the nested Intent directly without validation.
} ELSE IF (the component handles broadcasts) {
MUST rely on the system's Protected Broadcast mechanism for system events (which guarantees the sender is the system framework).
MUST protect custom receivers with signature-level permissions or use `RECEIVER_NOT_EXPORTED` for dynamic receivers to restrict the sender.
IF (using `ContextCompat.registerReceiver` with `RECEIVER_NOT_EXPORTED` AND `minSdk < 33`) {
MUST verify `<permission android:name="${applicationId}.DYNAMIC_RECEIVER_NOT_EXPORTED_PERMISSION" android:protectionLevel="signature" />` and `<uses-permission android:name="${applicationId}.DYNAMIC_RECEIVER_NOT_EXPORTED_PERMISSION" />` are declared in `AndroidManifest.xml`.
}
}

### 4. PendingIntent security logic

IF (a PendingIntent is created for delivery to another application) {
MUST use `PendingIntent.FLAG_IMMUTABLE` by default.
IF (the PendingIntent must be mutable) {
MUST set the explicit target component or package name on the base `Intent`.
NEVER create an implicit, mutable `PendingIntent`.
}
}

### 5. ContentProvider security logic

IF (the ContentProvider is only for internal app use) {
MUST set `android:exported="false"`.
} ELSE {
MUST protect it with `android:readPermission` and `android:writePermission`.
MUST set `android:grantUriPermissions="false"` unless temporary URL access is strictly required.
}

### 6. Service caller verification logic

IF (an exported service communicates with trusted sister/partner apps) {
MUST retrieve the calling UID using `Binder.getCallingUid()` and resolve it to package names using `PackageManager.getPackagesForUid()`.
MUST verify that the calling package signature fingerprint matches your trusted certificate hash.
}

*** ** * ** ***

## Code and configuration patterns

### 1. Safe intent redirection (manual verification)

Validate the target of a nested intent before launching it when modern
sanitization libraries are unavailable.

- **Expected Inputs:**
  - An incoming `Intent` containing a nested `Intent` extra named `EXTRA_NESTED_INTENT`.
- **Expected Outputs:**
  - Launches the target component if safe; throws `SecurityException` if validation fails.


```kotlin

From IsKenKenYa/skills, GPL-3.0.

More from IsKenKenYa/skills