PrivacySentry Documentation

PrivacySentry is an Android privacy compliance detection tool designed to help developers avoid compliance issues during app store reviews. It uses compile-time bytecode instrumentation (based on the ASM + Booster framework) to ensure zero runtime performance overhead.

Key features include:

• Compile-time Bytecode Instrumentation: Zero runtime performance impact.
• Comprehensive Interception: Supports interception of 60+ sensitive APIs to cover MIIT (Ministry of Industry and Information Technology) compliance requirements.
• Automated Detection Reports: Generates detailed call records and statistical analysis in Excel format.
• Smart Caching: Multi-level memory/disk caching for optimized performance.
• Multi-process Support: Automatically handles multi-process scenarios with independent log output.
• Extensibility: Supports custom interception rules and blacklist configurations.

When replaceFileName is configured in the Gradle plugin, PrivacySentry generates a JSON file (e.g., privacy_hook.json) in your project root. This file provides a static map of all intercepted sensitive API calls.

File Structure

• hookServiceList: A list of services that were intercepted.
• replaceMethodMap: A mapping where keys are the intercepted sensitive methods (e.g., android.telephony.TelephonyManager.getDeviceId).
  • count: Number of times this method was intercepted.
  • originMethodList: A list of the actual code locations that called the sensitive method, containing originClassName and originMethodName.

Use Cases

1. Static Analysis: Perform offline audits of sensitive API usage.
2. Compliance: Provide evidence to security teams for privacy reviews.
3. Debugging: Verify that the plugin is correctly intercepting target methods.

{
    "hookServiceList": [
        "com.example.TestService"
    ],
    "replaceMethodMap": {
        "android.telephony.TelephonyManager.getDeviceId": {
            "count": 1,
            "originMethodList": [
                {
                    "originClassName": "com.example.DeviceManager",
                    "originMethodName": "getIMEI"
                }
            ]
        }
    }
}

PrivacySentry uses a four-layer architecture to perform Android privacy compliance detection through compile-time annotation, bytecode instrumentation, and runtime hooking:

1. Annotation Layer (privacy-annotation): Defines compile-time annotations used to mark methods, classes, or fields for interception. These annotations have @Retention(RetentionPolicy.CLASS), meaning they are available during compilation but not at runtime.
2. Plugin Layer (plugin-sentry): A Gradle plugin that performs bytecode transformation during the build process using ASM and the Booster framework.
3. Hook Layer (hook-sentry): The runtime SDK responsible for initialization, managing memory/disk caches, and collecting/outputting logs.
4. Proxy Layer (privacy-proxy): Contains the actual implementations for intercepting pre-defined APIs and uses annotations to declare interception rules.

PrivacySentry operates in three distinct phases:

1. Development/Compile Time:

   • Developers define proxy methods using @PrivacyClassProxy and @PrivacyMethodProxy.
   • The Gradle plugin (PrivacySentryPlugin) runs MethodProxyCollectTransform to scan for these annotations and MethodHookTransform to replace original API calls in the application bytecode with calls to your proxy methods.
   • A privacy_hook.json file is generated containing the mapping of hooked methods.

2. Runtime Initialization:

   • PrivacySentry.Privacy.init(...) must be called as early as possible (ideally in Application.attachBaseContext()).
   • When a user agrees to the privacy policy, call PrivacySentry.Privacy.updatePrivacyShow() to update the internal state.

3. Runtime Execution:

   • When the app calls a sensitive API (e.g., Build.getSerial()), the modified bytecode redirects the call to your PrivacyProxyCall method.
   • The proxy method checks inDangerousState() and either returns dummy data or the real value.
   • Intercepted calls are logged and can be exported to an Excel file.

PrivacySentry operates using a two-stage Gradle Transform architecture during the compilation process to intercept and redirect sensitive method calls to privacy proxies.

Stage 1: Pre-Transform (Collection)

In this stage, the plugin scans all .class and .jar files to collect interception rules.

• MethodProxyCollectTransform: Scans classes annotated with @PrivacyClassProxy. It looks for methods within those classes annotated with @PrivacyMethodProxy.
• It extracts metadata such as the originalClass, originalMethod, and originalOpcode from the annotations.
• The collected rules are stored in the HookMethodManager.

Stage 2: Transform (Execution/Replacement)

In this stage, the plugin performs the actual bytecode manipulation.

• MethodHookTransform: Iterates through all class files and searches for method calls (MethodInsnNode) that match the rules collected in Stage 1.
• When a match is found, the instruction is modified: the opcode is changed to INVOKESTATIC, and the owner, name, and desc are updated to point to the privacy proxy class and method.
• Reflection Hooking: If hookReflex is enabled, the plugin also scans for LdcInsnNode (loading constants) to intercept reflection-based calls.

Output

The process results in:

1. Modified .class files where sensitive calls are redirected.
2. A privacy_hook.json file containing the generated hook configurations.

编译期流程：
┌──────────────────────────────────┐
│  输入：所有 .class 文件和 Jar    │
└──────┬───────────────────────────┘
       │
┌──────▼─────────────┐
│  第一阶段（预处理） │
│  Pre-Transform     │
└──────┬─────────────┘
       │
    ┌──┴──────────────┐
    │                 │
┌───▼────────────────┐   ┌───▼──────────────────┐
│MethodProxy         │   │ ClassProxy           │
│ CollectTransform   │   │ CollectTransform     │
│ (收集方法拦截规则) │   │ (收集类替换规则)     │
└───┬────────────────┘   └───┬──────────────────┘
    │                         │
    │ 结果写入：            │
    │ HookMethodManager     │ ReplaceClassManager
    │                      │
        ┌──────▼────────────────┐
        │  第二阶段（执行替换） │
        │  Transform            │
        └──────┬─────────────┘
               │
    ┌──────────┼──────────────┬──────────────┐
    │          │              │              │
┌───▼───┐ ┌───▼───┐ ┌───────▼──┐ ┌────────▼───┐
│Method │ │Field  │ │ Class    │ │ Service    │
│Hook   │ │Proxy  │ │ Proxy    │ │ Hook       │
│       │ │       │ │          │ │            │
└───┬───┘ └───┬───┘ └───────┬──┘ └────────┬───┘
    │         │              │              │
    └─────────┴──────────────┴──────────────┘
               │
        ┌──────▼──────────┐
        │ FlushHookData   │
        │ Transform       │
        │ (生成hook配置)   │
        └────────┬────────┘
                 │
        ┌────────▼──────────────┐
        │ 输出：修改后的 .class 和  │
        │ privacy_hook.json     │
        └───────────────────────┘