# ADScope

**Repository Path**: jcifox/ADScope

## Basic Information

- **Project Name**: ADScope
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-07
- **Last Updated**: 2026-01-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ADScope - HTTP API常量提取工具

## 概述

`extract_domains.py` 是一个Python脚本，用于调用Java程序来提取AAR/JAR文件中的HTTP/HTTPS域名。该工具基于Soot静态分析框架，通过解析class文件常量池和Soot方法体分析，提取第三方SDK中的HTTP/HTTPS通信域名常量。

## 项目结构

```
ADScope/
├── ad_lib/              # 第三方SDK的AAR/JAR文件目录
│   ├── .gitignore       # 忽略目录内所有文件
│   ├── .gitkeep         # 保留目录结构
│   └── *.aar            # 第三方SDK的AAR文件
│
├── output/              # 提取结果输出目录
│   ├── .gitignore       # 忽略目录内所有文件
│   ├── .gitkeep         # 保留目录结构
│   └── [SDK名称]/       # 每个SDK对应一个子目录
│       └── domains.json # 提取到的HTTP/HTTPS域名JSON文件
│
├── src/                 # Java源代码目录
│   └── main/java/com/adscope/
│       ├── HttpDomainExtractor.java    # 主程序类
│       ├── ClassFileStringExtractor.java  # 常量池字符串提取器
│       ├── Extractor.java             # AAR/JAR 文件提取工具
│       ├── UrlValidator.java          # URL验证器
│       ├── JsonWriter.java           # JSON文件写入器
│       ├── StringConstantVisitor.java # 字符串常量访问器
│       └── ApiInfo.java              # API信息数据类
│
├── soot/                # Soot静态分析工具目录
│   └── sootclasses-trunk-jar-with-dependencies.jar  # Soot工具JAR文件
│
├── target/              # Maven编译输出目录
│   └── ad-scope-1.0.0-jar-with-dependencies.jar  # 编译后的可执行JAR
│
├── temp/                # 临时文件目录（自动创建，Git忽略）
│   └── adscope_*/       # 每次运行创建的临时目录
│
├── extract_domains.py   # Python调用脚本（推荐）
├── run.bat              # Windows批处理运行脚本（智能编译+运行）
├── run.sh               # Linux/Mac运行脚本（智能编译+运行）
├── pom.xml              # Maven项目配置文件
├── .gitignore           # Git忽略规则
└── README.md            # 项目说明文档
```

### 目录说明

- **`ad_lib/`**: 存放待分析的第三方SDK的AAR或JAR文件。目录会被提交到Git，但文件内容会被忽略。
- **`output/`**: 存放提取结果的JSON文件。每个SDK对应一个子目录，包含该SDK的域名提取结果。目录会被提交到Git，但JSON文件会被忽略。
- **`src/`**: Java源代码目录，包含所有工具类的实现。
- **`soot/`**: Soot静态分析工具的JAR文件目录。
- **`target/`**: Maven编译输出目录，包含编译后的class文件和打包的JAR文件。目录会被提交到Git，但编译产物会被忽略。
- **`temp/`**: 临时文件目录，用于存放解压的AAR文件和Soot分析过程中的临时文件。目录会被Git忽略。

## 前置要求

### 推荐环境

以下为推荐且已验证可用的环境，满足后文版本要求即可，不必完全一致。

| 组件 | 版本 | 说明 |
|------|------|------|
| **Java** | OpenJDK 11.0.2 | 如 `JAVA_HOME=D:\Programs\Scoop\apps\openjdk11\current`（Scoop `openjdk11`） |
| **Python** | 3.10.11 | 如 Scoop `python310`，`python` / `python3` 均可 |
| **Maven** | 3.9.11 | 独立安装或随 IntelliJ IDEA 插件，`mvn` 可用即可 |
| **操作系统** | Windows 10/11 (amd64) | Linux/macOS 未逐一验证，理论上兼容 |

> Java、Python 可通过 [Scoop](https://scoop.sh/) 安装；Maven 可单独安装或使用 IDE 自带。`run.bat` / `extract_domains.py` 已通过 `-Dfile.encoding=UTF-8` 减轻控制台编码（如 GBK）导致的乱码问题。

### Python环境

1. **Python版本**: Python 3.6 或更高版本
2. **安装方式**:
   - Windows: 从 [python.org](https://www.python.org/downloads/) 下载安装
   - Linux: `sudo apt-get install python3` 或 `sudo yum install python3`
   - Mac: `brew install python3` 或从官网下载
3. **验证安装**: 运行 `python --version` 或 `python3 --version` 检查版本
4. **添加到PATH**: 安装时勾选"Add Python to PATH"选项（Windows），或手动添加到系统PATH

### Java环境

1. **Java版本**: Java 8 (JDK 1.8) 或更高版本
2. **安装方式**:
   - Windows: 从 [Oracle JDK](https://www.oracle.com/java/technologies/downloads/) 或 [OpenJDK](https://adoptium.net/) 下载安装
   - Linux: `sudo apt-get install openjdk-8-jdk` 或 `sudo yum install java-1.8.0-openjdk-devel`
   - Mac: `brew install openjdk@8` 或从官网下载
3. **验证安装**: 运行 `java -version` 检查版本
4. **配置JAVA_HOME**:
   - Windows: 系统属性 → 环境变量 → 新建 `JAVA_HOME`，值为JDK安装路径（如 `C:\Program Files\Java\jdk1.8.0_xxx`）
   - Linux/Mac: 在 `~/.bashrc` 或 `~/.zshrc` 中添加：
     ```bash
     export JAVA_HOME=/usr/lib/jvm/java-8-openjdk
     export PATH=$JAVA_HOME/bin:$PATH
     ```
5. **添加到PATH**: 确保 `java` 和 `javac` 命令可以在命令行中直接使用

### Maven环境

1. **Maven版本**: Maven 3.6.0 或更高版本
2. **安装方式**:
   - Windows: 从 [Maven官网](https://maven.apache.org/download.cgi) 下载，解压到目录（如 `C:\Program Files\Apache\maven`）
   - Linux: `sudo apt-get install maven` 或 `sudo yum install maven`
   - Mac: `brew install maven`
3. **验证安装**: 运行 `mvn -version` 检查版本
4. **配置MAVEN_HOME**:
   - Windows: 系统属性 → 环境变量 → 新建 `MAVEN_HOME`，值为Maven安装路径（如 `C:\Program Files\Apache\maven`）
   - Linux/Mac: 在 `~/.bashrc` 或 `~/.zshrc` 中添加：
     ```bash
     export MAVEN_HOME=/usr/share/maven
     export PATH=$MAVEN_HOME/bin:$PATH
     ```
5. **添加到PATH**: 确保 `mvn` 命令可以在命令行中直接使用
6. **配置Maven仓库**（可选）: 编辑 `$MAVEN_HOME/conf/settings.xml` 配置镜像源（国内用户推荐使用阿里云镜像）

## 使用方法

### 方式1：使用 run.bat / run.sh（推荐，最简单）

**Windows系统：**
```bash
# 使用默认文件（ad_lib/csj.aar）
run.bat

# 指定单个文件
run.bat ad_lib\csj.aar

# 指定多个文件
run.bat ad_lib\csj.aar ad_lib\gdt_plugin.jar

# 使用通配符
run.bat ad_lib\*.aar ad_lib\*.jar
```

**Linux/Mac系统：**
```bash
# 添加执行权限（首次使用）
chmod +x run.sh

# 使用默认文件（ad_lib/csj.aar）
./run.sh

# 指定单个文件
./run.sh ad_lib/csj.aar

# 指定多个文件
./run.sh ad_lib/csj.aar ad_lib/gdt.aar

# 使用通配符
./run.sh ad_lib/*.aar
```

**特点：**
- ✅ **智能编译检查**：自动检测JAR文件是否存在，存在则跳过编译（快速模式），不存在则自动编译
- ✅ **命令行参数支持**：可以指定一个或多个AAR/JAR文件
- ✅ **跨平台**：Windows使用 `run.bat`，Linux/Mac使用 `run.sh`
- ✅ **简单易用**：无需Python环境，直接运行即可

### 方式2：使用 extract_domains.py（Python脚本，功能更丰富）

**基本用法：**
```bash
# 自动编译并提取域名
python extract_domains.py ad_lib/csj.aar ad_lib/gdt.aar

# 跳过编译步骤（如果已经编译过）
python extract_domains.py --no-compile ad_lib/csj.aar

# 使用通配符
python extract_domains.py ad_lib/*.aar
```

**高级用法：**
```bash
# 只显示结果摘要
python extract_domains.py --summary ad_lib/csj.aar ad_lib/gdt.aar

# 将多个文件的结果合并到一个JSON文件
python extract_domains.py --json merged_results.json ad_lib/*.aar
```

**命令行参数：**
- `files`: AAR或JAR文件路径（必需，支持多个文件和通配符）
- `--no-compile`: 跳过编译步骤
- `--summary`: 只显示结果摘要，不显示详细输出
- `--json <file>`: 将结果合并输出到指定的JSON文件

**特点：**
- ✅ **功能丰富**：支持结果摘要、JSON合并等高级功能
- ✅ **跨平台**：Python脚本，Windows/Linux/Mac通用
- ✅ **可编程**：可以在Python代码中导入使用

## 输出

程序会在 `output/` 目录下为每个输入文件创建子目录，包含以下文件：

- **`domains.json`**: 提取到的HTTP/HTTPS域名JSON文件
- **`analysis.log`**: 详细的分析日志文件（包含错误信息和调试信息）

### JSON格式

每个 `domains.json` 文件包含：

```json
{
  "source": "csj.aar",
  "extractTime": "Wed Jan 07 22:30:00 CST 2026",
  "totalCount": 51,
  "validCount": 49,
  "invalidCount": 2,
  "validApis": [
    {
      "url": "https://api.example.com",
      "domain": "api.example.com",
      "valid": true
    }
  ],
  "invalidApis": [
    {
      "url": "http://127.0.0.1",
      "domain": "127.0.0.1",
      "valid": false
    }
  ]
}
```

## 在Python代码中使用

```python
from extract_domains import extract_domains, load_json_results

# 提取域名
output_files = extract_domains(['ad_lib/csj.aar', 'ad_lib/gdt.aar'])

# 读取结果
for file_name, json_path in output_files.items():
    data = load_json_results(json_path)
    print(f"{file_name}: {data['validCount']} 个有效API")
```

## 环境配置检查清单

在运行程序前，请确保以下命令都能正常执行：

```bash
# 检查Python
python --version  # 或 python3 --version
# 应显示: Python 3.6.x 或更高版本

# 检查Java
java -version
# 应显示: java version "1.8.0_xxx" 或更高版本

# 检查Maven
mvn -version
# 应显示: Apache Maven 3.6.x 或更高版本
```

如果任何命令提示"未找到"或"不是内部或外部命令"，请：
1. 确认已正确安装对应软件
2. 检查是否已添加到系统PATH环境变量
3. 重启命令行窗口或终端（环境变量修改后需要重启）

## 运行方式对比

| 特性 | run.bat / run.sh | extract_domains.py |
|------|------------------|---------------------|
| **依赖环境** | Java + Maven | Python + Java + Maven |
| **编译检查** | ✅ 智能检查，自动编译 | ✅ 可配置（--no-compile） |
| **命令行参数** | ✅ 支持 | ✅ 支持 |
| **结果摘要** | ❌ | ✅ (--summary) |
| **JSON合并** | ❌ | ✅ (--json) |
| **Python集成** | ❌ | ✅ 可导入使用 |
| **跨平台** | ✅ (Windows/Linux/Mac) | ✅ (Windows/Linux/Mac) |
| **使用难度** | ⭐ 简单 | ⭐⭐ 中等 |

**推荐使用场景：**
- **快速测试/日常使用**：使用 `run.bat` 或 `run.sh`（最简单）
- **批量处理/自动化**：使用 `extract_domains.py`（功能更丰富）
- **集成到其他项目**：使用 `extract_domains.py`（可编程）

## 注意事项

1. **首次运行**: 
   - `run.bat`/`run.sh` 会自动编译Java项目（如果JAR不存在）
   - `extract_domains.py` 默认也会自动编译，可使用 `--no-compile` 跳过
   - 编译需要Maven，可能需要几分钟时间

2. **智能编译**: 
   - `run.bat`/`run.sh` 会检查JAR文件是否存在，存在则跳过编译（快速模式）
   - 如果代码已修改，需要手动运行 `mvn clean compile assembly:single` 重新编译
   - 或删除 `target/` 目录强制重新编译

3. **环境变量**: 确保Java和Maven已正确安装并添加到系统PATH

4. **路径处理**: 
   - Windows系统下路径分隔符会自动处理（`\` 或 `/` 都可以）
   - Linux/Mac系统使用 `/` 作为路径分隔符

5. **临时文件**: 
   - 临时文件会保存在项目目录下的 `temp/` 文件夹中（不再使用C盘）
   - 程序运行完成后会自动清理临时文件
   - `temp/` 目录会被Git忽略

6. **编译失败**: 
   - 如果编译失败，可以手动运行 `mvn clean compile assembly:single` 查看详细错误
   - 然后使用 `run.bat`（JAR已存在会跳过编译）或 `extract_domains.py --no-compile`

7. **网络问题**: 
   - Maven首次编译需要下载依赖，确保网络连接正常
   - 国内用户建议配置Maven镜像源（阿里云镜像）

8. **权限问题**: 
   - Linux/Mac系统可能需要使用 `chmod +x run.sh` 添加执行权限
   - 确保对项目目录有读写权限