PrivacySentry CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

PrivacySentry 是一个 Android 隐私合规检测工具,通过 ASM 字节码插桩技术在编译期和运行期拦截敏感 API 调用,帮助开发者规避应用市场上架时的隐私合规检测问题。

核心架构

三层架构设计

1. plugin-sentry (Gradle 插件层)

   • 基于 AGP 8.0+ 和 Booster 框架的 Gradle 插件
   • 负责在编译期进行字节码转换 (Transform)
   • 两阶段 Transform:
     • 第一阶段: 收集需要拦截的敏感函数 (MethodProxyCollectTransform, ClassProxyCollectTransform)
     • 第二阶段: 替换敏感函数调用 (MethodHookTransform, FieldProxyTransform, ClassProxyTransform)
   • 关键类: PrivacySentryPlugin.kt, PrivacyTransformTask.kt

2. privacy-annotation (注解层)

   • 定义编译期注解用于声明需要拦截的方法和字段
   • 核心注解:
     • @PrivacyMethodProxy: 标记需要代理的方法
     • @PrivacyFieldProxy: 标记需要代理的字段
     • @PrivacyClassProxy: 标记包含代理方法的类
     • @PrivacyClassBlack: 标记不需要拦截的黑名单类

3. hook-sentry (运行时 Hook 层)

   • 提供运行时的 SDK 初始化和日志收集功能
   • 支持三种缓存策略: 内存缓存 (MemoryCache)、时效性磁盘缓存 (TimeLessDiskCache)、永久磁盘缓存 (DiskCache)
   • 日志输出到文件 (.xls 格式)
   • 关键类: PrivacySentry.kt, PrivacySentryBuilder.kt

4. privacy-proxy (预置代理实现)

   • 提供常用敏感 API 的拦截实现
   • 通过注解声明拦截规则,由插件在编译期自动收集
   • 关键类: PrivacyProxyCall.kt, PrivacyTelephonyProxy.kt, PrivacySensorProxy.kt

工作原理

1. 编译期: 插件扫描所有 @PrivacyMethodProxy 注解,收集需要拦截的方法列表
2. 字节码转换: 将目标方法调用替换为代理方法调用
3. 运行期: 代理方法执行实际逻辑,并记录调用堆栈和时机到日志文件

常用命令

构建项目

./gradlew clean build

编译调试 (本地依赖模式)

修改 config.gradle:

build = [
    local_debug: true,
    local_debug_dir : "${rootProject.projectDir}/local"
]

发布到本地 Maven

./gradlew publishToMavenLocal

运行测试应用

./gradlew :app:installDebug

项目模块说明

• app: 示例应用,演示如何集成和使用 PrivacySentry
• plugin-sentry: Gradle 插件,负责字节码转换
• hook-sentry: 运行时 SDK 核心库
• privacy-annotation: 注解定义模块
• privacy-proxy: 预置的敏感 API 拦截实现
• privacy-replace: 类替换功能 (已废弃,不再维护)
• privacy-test: 测试模块

版本兼容性

• 当前版本 (1.3.7_v820_beta4): 支持 AGP 8.0+
• 旧版本 (1.3.6): 支持 AGP 8.0 以下版本
• 最低 Android SDK: minSdkVersion 19
• 编译 SDK: compileSdkVersion 34
• Kotlin: 1.8.10