Introduction to Android SELinux and Policy Challenges

Android’s security model heavily relies on Security-Enhanced Linux (SELinux), a mandatory access control (MAC) system that dictates what processes can access which resources. Every action on an Android device is subject to SELinux policy, ensuring that even privileged processes adhere to a predefined set of rules. While this provides robust security, developing and customizing these policies can be notoriously complex. Developers often face challenges when introducing new services, applications, or hardware, as these components might trigger SELinux Access Vector Cache (AVC) denials.

Understanding and debugging these denials, then translating them into secure, precise policy rules, is a critical skill for Android system developers and security engineers. This article will guide you through mastering two indispensable tools in this process: audit2allow and sepolicy-inject, demonstrating how to use them together to streamline your Android SELinux policy development workflow.

The Role of audit2allow: Initial Policy Generation

audit2allow is a powerful utility designed to generate SELinux policy rules based on AVC denial messages found in system logs. It acts as an excellent starting point for understanding what permissions a process is being denied. By analyzing these denials, audit2allow suggests corresponding allow rules that, if implemented, would resolve the observed access violations.

How to Use audit2allow

First, ensure you have adb installed and configured to connect to your Android device (physical or emulator) with root access. Also, you’ll need the audit2allow tool, typically found in the SELinux userspace utilities package on Linux distributions (e.g., selinux-policy-devel or checkpolicy packages).

1. Reproduce the Issue: Perform the action on your Android device that is causing the SELinux denial. For example, if a custom service is failing to write to a specific file, try to start that service.

2. Capture AVC Denials: Use adb logcat to capture the system logs, filtering for SELinux AVC denials. This will show messages indicating permission failures.

   adb shell su -c 'dmesg | grep avc'

   Alternatively, if you’re actively debugging and want real-time output:

   adb logcat | grep avc

   You will see output similar to this:

   avc: denied { read } for pid=1234 comm="myservice" name="some_file" dev="tmpfs" ino=5678 scontext=u:r:myservice_t:s0 tcontext=u:object_r:tmpfs:s0 tclass=file permissive=0

3. Generate Policy Rules: Pipe the captured AVC denials directly into audit2allow. It will parse the denials and suggest policy rules.

   adb shell su -c 'dmesg | grep avc' | audit2allow

   Or, if you saved the denials to a file:

   cat avc_denials.log | audit2allow

   audit2allow will output suggested rules, for example:

   #============= myservice_t ==============allow myservice_t tmpfs:file { read write };

4. Review and Refine: The output from audit2allow serves as a starting point. It’s crucial to review these suggestions carefully. While they resolve the immediate denial, they might be overly broad. For instance, granting write access when only read was needed would violate the principle of least privilege.

Limitations of audit2allow

• Over-permissiveness: It tends to generate broad rules (e.g., allow source_t target_t:class { read write };) that might grant more permissions than strictly necessary.
• Doesn’t account for policy structure: It doesn’t inherently understand the overall SELinux policy architecture, types, and domains, which means its generated rules might not align perfectly with existing policy best practices.
• Requires recompilation: The generated rules must be integrated into your policy source (`.te` files) and then the entire policy must be recompiled and flashed to the device, which can be time-consuming.

Introducing sepolicy-inject: Precise Policy Injection

sepolicy-inject is a utility that allows direct modification of a compiled SELinux policy file (`sepolicy`) without requiring a full recompilation of the AOSP source. This significantly speeds up the development and testing cycle, especially when making small, targeted adjustments or experimenting with different rules. It works by understanding the Common Intermediate Language (CIL) representation of SELinux policy.

Setting up sepolicy-inject

sepolicy-inject is part of the AOSP source tree (external/sepolicy/tools/sepolicy-inject). You typically need to build it from source or obtain a pre-compiled binary. Once built, ensure it’s in your system’s PATH or invoke it directly.

How to Use sepolicy-inject for Targeted Modifications

1. Extract Current Policy: Retrieve the `sepolicy` file from your device. It’s usually located at /sys/fs/selinux/policy or in the root partition (e.g., /system/etc/selinux/precompiled_sepolicy on some older versions, or baked into boot.img/vendor_boot.img).

   adb pull /sys/fs/selinux/policy ./sepolicy_orig

2. Convert to CIL (Optional but Recommended for Inspection): To understand the existing policy better, you can convert the binary `sepolicy` into CIL format using sepolicy-inject.

   sepolicy-inject -s ./sepolicy_orig -o ./sepolicy_orig.cil -P

3. Craft Your CIL Snippet: Based on the audit2allow output and your security review, write a precise CIL policy snippet. For instance, if audit2allow suggested allow myservice_t tmpfs:file { read write }; but you only need read, your CIL snippet (e.g., my_rules.cil) would be:

   (allow myservice_t tmpfs (file (read)))

   Note the CIL syntax: S-expressions are used to define rules. You can also define types, attributes, or other policy constructs here.

4. Inject the Policy Snippet: Use sepolicy-inject to apply your CIL rules directly into the binary `sepolicy` file.

   sepolicy-inject -s ./sepolicy_orig -o ./sepolicy_new -i ./my_rules.cil

   • -s ./sepolicy_orig: Specifies the source binary policy file.
   • -o ./sepolicy_new: Specifies the output path for the modified binary policy.
   • -i ./my_rules.cil: Specifies the CIL file containing your new rules to inject.

5. Push and Load the New Policy: Push the modified `sepolicy_new` back to the device. This typically requires root privileges and, importantly, the device must be in permissive mode or have a kernel capable of loading a new policy without a reboot. If you are developing on an engineering or userdebug build, you can often push it to /data/misc/selinux and reboot to load it, or use `setenforce 0` temporarily if available.

   adb rootadb disable-verityadb remountadb push ./sepolicy_new /vendor/etc/selinux/precompiled_sepolicy # or /sepolicy, /system/etc/selinux/precompiled_sepolicy etc. depending on deviceadb reboot

   On newer Android versions, the `sepolicy` might be part of the `vendor_boot.img` or `boot.img` and requires flashing the modified image. For live testing, you might need to enable permissive mode for the relevant domain:

   adb shell 'echo 0 > /sys/fs/selinux/enforce' # WARNING: This disables SELinux enforcement system-wide! Use with extreme caution.

   A more targeted approach in userdebug builds:

   adb shell 'setenforce 0' # if availableadb push ./sepolicy_new /data/misc/selinux/mypolicy # Push to a writable locationadb shell 'setprop selinux.reload_policy 1' # Some kernels allow reloading from /data/misc/selinux

6. Test and Iterate: Test the functionality that previously triggered the denial. Observe `logcat` for new denials. If issues persist, refine your CIL rules and repeat the injection process.

Combining the Tools for an Efficient Workflow

The real power comes from combining these tools:

1. Initial Assessment with `audit2allow`: When a new feature or application encounters AVC denials, use audit2allow to quickly get a first glance at the missing permissions. This helps you identify the involved SELinux types and classes.

2. Precise Rule Crafting: Instead of blindly applying audit2allow output, use its suggestions as a guide to handcraft minimal and secure CIL rules. This involves understanding the specific operation being denied and granting only that permission.

3. Rapid Iteration with `sepolicy-inject`: Use sepolicy-inject to apply these refined CIL rules to your device’s live policy. This allows for quick testing and debugging without the lengthy compile-and-flash cycle.

4. Policy Integration: Once you have a stable, minimal set of rules that resolve the issue without introducing new vulnerabilities, integrate them into your project’s `.te` files (e.g., in AOSP’s external/sepolicy or device-specific policy directories). This ensures your changes are persistent and follow the standard build process.

Best Practices for SELinux Policy Development

• Principle of Least Privilege: Always grant the minimum necessary permissions. Avoid wildcards or overly broad access.
• Understand Contexts: Pay attention to source and target contexts (`scontext` and `tcontext` in AVC denials). This helps you correctly identify the involved processes and resources.
• Iterative Development: Start with a minimal rule, test, and gradually add more if new denials appear.
• Documentation: Document why each rule was added, especially for complex or potentially sensitive permissions.
• Never Disable SELinux in Production: Running in permissive mode or disabling SELinux globally compromises device security. It should only be done for debugging purposes in controlled environments.

Conclusion

Mastering audit2allow and sepolicy-inject transforms the often-frustrating task of Android SELinux policy development into a more efficient and secure workflow. audit2allow provides a crucial starting point for identifying problematic denials, while sepolicy-inject offers an unparalleled ability to rapidly test precise policy changes on-device. By judiciously combining these tools, developers can ensure their Android systems remain secure while seamlessly integrating new features and functionalities.