# package-privacy

**Repository Path**: stonehill-2345/package-privacy

## Basic Information

- **Project Name**: package-privacy
- **Description**: 基于包的安卓静态隐私合规检测工具，结合AI大模型能力与MCP服务，辅助分析Android应用和SDK中的隐私相关行为。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2025-12-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PackagePrivacy

这个项目是一个静态隐私合规检测工具，用于分析Android应用和SDK中的隐私相关行为，包括下载、反编译、代码分析和隐私合规报告生成功能。

## 功能概述

- **文件获取**: 支持从Maven仓库、URL或本地文件获取Android应用和SDK
- **反编译分析**: 使用JADX将JAR/AAR/APK文件反编译为可读的Java源码
- **隐私行为检测**: 静态分析代码中的隐私敏感API调用
- **报告生成**: 生成详细的隐私合规分析报告
- **MCP接口**: 提供与大模型交互的MCP接口支持

## 工具列表
### 1. Maven库下载工具 (`download/download_maven_lib.py`)

用于从Maven仓库下载jar或aar文件到指定路径。

#### 功能特点：
- 支持自动检测jar和aar格式
- 支持完整的Maven依赖格式
- 命令行参数配置
- 详细的下载进度和错误信息

#### 使用方法：

```bash
# 基本用法
python -m download.download_maven_lib --repo <仓库地址> --lib <库依赖> --output <输出目录>

# 示例：下载jar文件
python -m download.download_maven_lib \
  --repo https://repo1.maven.org/maven2/ \
  --lib org.apache.commons:commons-lang3:3.12.0 \
  --output ./workspace/downloads/ \
  --verbose
```

#### 参数说明：
- `--repo`: Maven仓库地址
- `--lib`: Maven库依赖 (格式: groupId:artifactId:version[:packaging[:classifier]])
- `--output`: 输出目录路径
- `--verbose`: 显示详细输出

### 2. JADX反编译工具 (`decompile/decompile_with_jadx.py`)

用于使用JADX反编译jar或aar文件。

#### 功能特点：
- 支持jar和aar文件反编译
- 自动检测JADX安装状态
- 支持jadx和jadx-gui两种模式
- **文件格式检查**：反编译前自动检查文件格式，只支持 JAR、AAR、APK
- **无界面模式**：避免打开GUI界面，在后台运行
- **SDK名称组织**：按照SDK名称自动组织输出目录结构
- 详细的错误处理和解决方案

#### 使用方法：

```bash
# 基本用法
python -m decompile.decompile_with_jadx --input <输入文件> --output <输出目录>

# 示例：使用无界面模式反编译aar文件
python -m decompile.decompile_with_jadx \
  --input ./workspace/downloads/feedback-1.9.7-oldUI.aar \
  --output ./workspace/decompiled/ \
  --use-gui \
  --no-gui \
  --verbose

# 示例：指定Java路径反编译
python -m decompile.decompile_with_jadx \
  --input ./workspace/downloads/feedback-1.9.7-oldUI.aar \
  --output ./workspace/decompiled/ \
  --java-path /opt/homebrew/opt/openjdk@17 \
  --verbose

# 示例：反编译jar文件
python -m decompile.decompile_with_jadx \
  --input ./workspace/downloads/commons-lang3-3.12.0.jar \
  --output ./workspace/decompiled/ \
  --verbose
```

#### 参数说明：
- `--input`: 输入的jar或aar文件路径
- `--output`: 输出目录路径
- `--verbose`: 显示详细输出
- `--install-jadx`: 尝试自动安装JADX
- `--skip-check`: 跳过JADX可用性检查
- `--use-gui`: 使用jadx-gui而不是jadx进行反编译
- `--no-gui`: 避免打开GUI界面，在后台运行
- `--java-path`: 指定Java安装路径

#### 输出目录结构：
```
workspace/decompiled/
└── 3dmap-location-search-10.1.600_loc6.5.1_sea9.7.4/          # SDK名称（自动提取）
    ├── sources/           # Java源代码
    └── resources/         # 资源文件
```

### 3. 通用信息分析工具 (`analysis/common/analysis_common_info.py`)

用于分析 JAR、AAR、APK 文件的基本信息和 Android 清单文件。

#### 功能特点：
- 支持 JAR、AAR、APK 文件格式
- 解析 AndroidManifest.xml 基本信息
- **JNI 库检测**：检测 JAR 文件中的 JNI 库文件（.so 文件）
- **全面 .so 文件检测**：检测所有类型文件中的 .so 文件，支持多种路径格式
- 支持架构检测（arm64-v8a、armeabi-v7a、x86、x86_64）
- 权限、Activity、Service 等组件信息提取
- 详细的解析报告

#### 使用方法：

```bash
# 基本用法
python -m analysis.common.analysis_common_info --input <输入文件>

# 示例：分析包含 JNI 库的 JAR 文件
python -m analysis.common.analysis_common_info \
  --input ./workspace/downloads/3dmap-location-search-10.1.300_loc6.4.9_sea9.7.4.jar

# 示例：分析 AAR 文件
python -m analysis.common.analysis_common_info \
  --input ./workspace/downloads/feedback-1.9.7-oldUI.aar

# 示例：分析 APK 文件
python -m analysis.common.analysis_common_info \
  --input ./workspace/downloads/app-release.apk
```

#### 参数说明：
- `--input`: 输入文件路径（JAR、AAR、APK）
- `--verbose`: 显示详细输出

#### 输出信息：
- 文件基本信息（文件名、大小）
- 支持的 CPU 架构
- **.so 文件列表**（按架构分组，包括标准 JNI 库和其他位置的 .so 文件）
- Android 包名和版本信息
- 权限列表
- Activity、Service、Receiver 等组件信息

### 4. 隐私API调用分析模块 (`analysis/code/analysis_code_invoke_info.py`)

用于分析反编译后的代码中的隐私敏感API调用。

#### 功能特点：
- 支持多种隐私相关API的检测
- 基于规则配置的灵活检测机制
- 详细的调用位置和上下文信息
- 按隐私类别组织的分析结果
- 生成JSON格式的详细分析报告

#### 使用方法：

```bash
# 基本用法
python -m analysis.code.analysis_code_invoke_info \
  --decompiled_dir ./workspace/decompiled/sdk_name \
  --output_dir ./workspace/reports \
  --sdk_name example_sdk
```

#### 参数说明：
- `--decompiled_dir`: 反编译后的源码目录
- `--output_dir`: 分析报告输出目录
- `--sdk_name`: SDK名称（用于组织报告）

### 5. 报告生成模块 (`analysis/generate_analysis_report.py`)

整合通用信息和隐私分析结果，生成完整的Markdown格式报告。

#### 功能特点：
- 生成结构化的Markdown报告
- 汇总隐私行为分析结果
- 提供合规建议
- 详细的API调用清单

#### 使用方法：

```bash
# 基本用法
python -m analysis.generate_analysis_report \
  --sdk_name example_sdk \
  --reports_dir ./workspace/reports
```

#### 参数说明：
- `--sdk_name`: SDK名称
- `--reports_dir`: 报告存储根目录

### 6. 统一工作流工具 (`main.py`)

整合下载、反编译、分析等功能的统一入口。

#### 功能特点：
- 支持多种输入方式（Maven 依赖、URL、本地文件）
- **文件格式检查**：在执行反编译前自动检查文件格式
- 自动化工作流程
- 统一的报告输出
- 支持 JNI 库检测和分析

#### 工作流程：
1. **步骤1**：获取输入文件（本地文件、URL下载、Maven下载）
2. **步骤1.5**：检查文件格式（仅当需要反编译时）
3. **步骤2**：反编译文件（可选）
4. **步骤3**：分析通用信息（清单文件、权限、JNI库等）
5. **步骤4**：分析代码调用（隐私敏感API调用检测）
6. **步骤5**：生成分析报告（Markdown格式）

#### 使用方法：

```bash
# 从 Maven 仓库下载并分析
python main.py \
  --lib com.amap.api:3dmap-location-search:10.1.600_loc6.5.1_sea9.7.4 \
  --repo https://maven.aliyun.com/repository/public/ \
  --verbose

# 从 URL 下载并分析
python main.py \
  --url https://example.com/sdk.aar \
  --verbose

# 分析本地文件
python main.py \
  --input ./workspace/downloads/sdk.aar \
  --verbose

# 跳过反编译步骤
python main.py \
  --input ./workspace/downloads/sdk.jar \
  --no-decompile \
  --verbose
```

#### 参数说明：
- `--lib`: Maven 依赖
- `--url`: 文件下载 URL
- `--input`: 本地文件路径
- `--repo`: Maven 仓库 URL
- `--no-decompile`: 跳过反编译步骤
- `--no-analyze`: 跳过分析步骤
- `--verbose`: 显示详细输出


## Maven仓库配置

项目使用JSON格式的配置文件来管理Maven仓库设置，配置文件位于 `configs/maven_config.json`。

### 配置文件结构
```json
{
  "repositories": [
    {
      "alias": "aliyun_public",
      "url": "https://maven.aliyun.com/repository/public/",
      "desc": "公共仓库（central + jcenter 聚合）"
    },
    {
      "alias": "maven_central",
      "url": "https://repo1.maven.org/maven2/",
      "desc": "Maven Central 官方仓库"
    },
    {
      "alias": "google",
      "url": "https://maven.google.com/",
      "desc": "Google Maven 仓库"
    }
  ],
  "default_repository": "aliyun_public"
}
```

### 支持的仓库别名
- `aliyun_public`: 阿里云公共仓库（推荐，国内访问速度快）
- `aliyun_google`: 阿里云Google镜像
- `aliyun_gradle_plugin`: 阿里云Gradle插件仓库
- `aliyun_spring`: 阿里云Spring仓库
- `aliyun_apache_snapshots`: 阿里云Apache快照仓库
- `maven_central`: Maven Central 官方仓库
- `google`: Google Maven 仓库
- `jitpack`: JitPack 仓库
- `apache`: Apache 发布仓库
- `sonatype`: Sonatype 发布仓库

### 使用方式
```bash
# 使用仓库别名
python main.py --lib com.example:library:1.0.0 --repo aliyun_public

# 使用完整URL
python main.py --lib com.example:library:1.0.0 --repo https://maven.aliyun.com/repository/public/
```

### 8. MCP服务器 (`mcp_server/`)

提供与大模型交互的MCP接口，支持完整的隐私合规分析工作流。

#### 功能特点：
- 支持Claude、GPT等大模型的MCP接口
- 提供完整的隐私分析工具集（16个工具）
- 支持交互式分析和报告生成
- **MCPResultDisplay**：专用的结果展示器，优化MCP响应格式
- 详细的错误处理和用户反馈
- 支持报告格式转换（Markdown ↔ JSON）
- 支持文件浏览和代码查看功能

#### 核心工具：
- **文件获取**: Maven下载、URL下载
- **代码分析**: 反编译、通用信息分析、隐私代码分析
- **报告生成**: 完整分析报告、合规性分析
- **完整分析**: 支持进度显示的完整工作流
- **文件浏览**: 下载文件、反编译项目、代码浏览
- **规则查看**: 检测规则列表和详情
- **格式转换**: 报告格式转换（Markdown ↔ JSON）
- **工作空间管理**: 一键打开workspace目录

#### 使用方法：

```bash
# 进入MCP服务器目录
cd mcp_server

# 安装依赖
uv sync

# 启动MCP服务器
uv run privacy-check-mcp
```

更多详细信息请参考 `mcp_server/README.md`

## 环境要求

### 依赖包
```bash
pip install -r requirements.txt
```

主要依赖包括：
- `requests>=2.25.0` - HTTP请求库
- `pathlib` - 路径处理
- `typing-extensions` - 类型注解扩展
- `httpx>=0.25.0` - 异步HTTP客户端（MCP服务器需要）
- `mcp>=1.0.0` - MCP协议支持（MCP服务器需要）

### JADX安装
```bash
# 使用Homebrew安装JADX
brew install jadx

# 或者手动安装
# 1. 访问 https://github.com/skylot/jadx/releases
# 2. 下载最新版本的jadx
# 3. 解压并添加到PATH环境变量
```

### Java版本
推荐使用Java 17或更高版本：
```bash
# 安装Java 17
brew install openjdk@17

# 设置Java路径
export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"
```

## 完整工作流程示例

```bash
# 1. 下载包含 JNI 库的 JAR 文件
python -m download.download_maven_lib \
  --repo https://repo1.maven.org/maven2/ \
  --lib com.amap.api:3dmap-location-search:10.1.300 \
  --output ./workspace/downloads/ \
  --verbose

# 2. 检查文件格式（独立使用）
python -m download.file_format_checker ./workspace/downloads/3dmap-location-search-10.1.300_loc6.4.9_sea9.7.4.jar

# 3. 分析 JAR 文件（检测 .so 文件）
python -m analysis.common.analysis_common_info \
  --input ./workspace/downloads/3dmap-location-search-10.1.300_loc6.4.9_sea9.7.4.jar

# 4. 分析 APK 文件（检测 .so 文件）
python -m analysis.common.analysis_common_info \
  --input ./workspace/downloads/抖音.apk

# 5. 反编译下载的文件（无界面模式）
python -m decompile.decompile_with_jadx \
  --input ./workspace/downloads/3dmap-location-search-10.1.300_loc6.4.9_sea9.7.4.jar \
  --output ./workspace/decompiled/ \
  --use-gui \
  --no-gui \
  --verbose

# 6. 使用统一工具进行完整分析（包含文件格式检查）
python main.py \
  --input ./workspace/downloads/3dmap-location-search-10.1.300_loc6.4.9_sea9.7.4.jar \
  --verbose

# 7. 查看分析结果
cat workspace/reports/3dmap-location-search-10.1.300_loc6.4.9_sea9.7.4/common_info.json
```

## 故障排除

### JADX相关问题
如果遇到JADX启动问题，可以尝试：
1. 使用 `--use-gui` 参数使用jadx-gui
2. 使用 `--no-gui` 参数避免打开GUI界面
3. 使用 `--skip-check` 参数跳过检查
4. 检查Java版本兼容性
5. 设置JAVA_HOME环境变量
6. 使用 `--java-path` 参数指定Java路径

### 下载问题
如果下载失败，可以：
1. 检查网络连接
2. 验证Maven依赖格式
3. 确认仓库地址正确
4. 使用 `--verbose` 参数查看详细错误信息

### 反编译问题
如果反编译失败，可以：
1. 检查文件格式是否支持（只支持 JAR、AAR、APK）
2. 检查文件是否损坏
3. 尝试不同的Java版本
4. 使用 `--verbose` 参数查看详细错误信息
5. 某些混淆的代码可能无法完全反编译

## 文件结构

```
PackagePrivacy/
├── main.py                          # 主工具，统一入口
├── workflow_manager.py              # 工作流管理器
├── requirements.txt                 # Python依赖
├── README.md                        # 项目说明文档
├── util/                            # 工具类模块
│   ├── __init__.py
│   └── result_display.py            # 结果展示器
├── configs/                         # 配置相关模块
│   ├── __init__.py
│   ├── config_manager.py            # 配置管理器
│   ├── maven_config.py              # Maven配置管理
│   └── maven_config.json            # Maven仓库配置文件
├── download/                        # 下载相关模块
│   ├── __init__.py
│   ├── download_url_file.py         # URL文件下载工具
│   ├── download_maven_lib.py        # Maven库下载工具
│   └── file_format_checker.py       # 文件格式检查模块
├── decompile/                       # 反编译相关模块
│   ├── __init__.py
│   └── decompile_with_jadx.py       # JADX反编译工具
├── analysis/                        # 分析相关模块
│   ├── __init__.py
│   ├── generate_analysis_report.py  # 生成分析报告
│   ├── common/                      # 通用分析模块
│   │   ├── __init__.py
│   │   └── analysis_common_info.py  # 通用信息分析工具
│   └── code/                        # 代码分析模块
│       ├── __init__.py
│       ├── analysis_code_invoke_info.py  # 代码调用分析
│       ├── analysis_code_rule.json       # 代码分析规则
│       ├── analysis_invoke_rule.py       # 调用规则分析
│       ├── analysis_rule_loader.py       # 规则加载器
│       └── invoke_rule_config.py         # 调用规则配置
├── mcp_server/                      # MCP服务器模块
│   ├── pyproject.toml               # 项目配置
│   ├── README.md                    # MCP服务器说明文档
│   ├── src/                         # 源代码
│   │   └── privacy_check_mcp/       # MCP实现
│   │       ├── __init__.py
│   │       ├── __main__.py
│   │       └── server.py            # MCP服务器实现
│   ├── start_mcp.sh                 # 启动脚本
│   └── uv.lock                      # UV依赖锁文件
└── workspace/                       # 工作空间目录
    ├── downloads/                   # 下载文件存储目录
    ├── decompiled/                  # 反编译输出目录
    └── reports/                     # 分析报告输出目录
        └── sdk_name/                # 按SDK名称组织的报告
            ├── analysis_report.md   # 完整分析报告
            ├── common_info.json     # 基本信息报告
            ├── privacy_info.json    # 隐私信息汇总
            └── privacy_info_detail/ # 详细隐私信息
                └── privacy_info_*.json  # 按类别组织的详细信息
```

## 更新说明

查看项目的版本更新记录和功能变更：

- **[CHANGELOG](CHANGELOG.md)** - 详细的版本更新日志

## 贡献指南

欢迎所有形式的贡献！无论是代码、文档、问题反馈还是功能建议，都能帮助项目变得更好。

### 贡献方式

#### 1. 问题反馈
- **Bug报告**：发现功能异常或崩溃问题
- **使用问题**：环境配置或使用方法咨询
- **功能建议**：新功能需求或现有功能改进建议

#### 2. 代码贡献
- **Bug修复**：修复已知问题
- **功能开发**：实现新功能或改进现有功能
- **代码优化**：性能优化、代码重构等
- **测试用例**：添加或完善测试代码

#### 3. 文档改进
- **代码注释**：改进代码注释和文档
- **示例代码**：提供使用示例和最佳实践

### 贡献流程

1. **Fork项目**：Fork本仓库到您的GitHub账户
2. **创建分支**：创建新的功能分支 (`git checkout -b feature/AmazingFeature`)
3. **提交更改**：提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
4. **推送分支**：推送到您的分支 (`git push origin feature/AmazingFeature`)
5. **创建PR**：在GitHub上创建Pull Request

### 代码规范

- 遵循项目的代码风格和命名规范
- 提交信息请遵循[提交信息规范](docs/commit_convention.md)
- 确保代码通过所有测试
- 添加必要的注释和文档

## 许可证

本项目采用 [Apache 2.0 许可证](LICENSE)。