ASRL 是面向 Android Framework、安全研究与漏洞分析的长期实验平台。它不是 AOSP 源码镜像;AOSP 工作区可以重新获取,研究记录、知识与自动化才是长期资产。
- 统一命令入口:
bin/lab - Go CLI、配置解析、路径保护和工具链检测
- Ubuntu 24.04 环境检查:
lab doctor、lab doctor --json - 共享工具清单:Doctor 与 Bootstrap 使用同一份
config/tools.conf - 安装计划与 apt 安装:
lab bootstrap plan、lab bootstrap --apply - 本地实验室配置模板与配置校验
- Go 单元测试与 CLI 二进制冒烟测试
- ADB 设备发现、状态读取与启动完成等待
- 以 Git submodule 集成 DroidForge 模拟设备工具链
多 Workspace、Repo status|init|sync|branch|patch、AOSP Build、ADB 设备管理和 Research 项目管理均已实现。
项目 CLI、Doctor、Bootstrap 计划、Workspace、Repo、Build 和 Device 工作流已使用 Go。
bootstrap --apply 与加载 AOSP envsetup.sh、执行 lunch/m 的适配继续保留 Shell。
git submodule update --init --recursive
./scripts/build-all.sh
./tests/run.sh
./bin/lab doctorbuild-all.sh 会初始化 tools/DroidForge,构建 ASRL 的 bin/lab,并构建
tools/DroidForge/bin/droidforge。它要求 Go 1.22+。仅构建 ASRL CLI 时仍可使用
./scripts/build-go.sh。ASRL 的 lab 不会直接调用 DroidForge;DroidForge 负责
模拟设备生命周期,ASRL 通过标准 ADB 接口使用已启动设备。两个二进制均不受 Git 管理。
cmd/lab + internal/*
-> go build
-> bin/lab (Go CLI)
-> scripts/bootstrap-apt.sh (仅显式安装)
bin/:存放本机 Go 编译产物。cmd/与internal/:Go CLI、基础能力与领域工作流。scripts/:Go 构建及必须保留的 Shell 适配。config/:唯一配置来源。tests/:不依赖 AOSP 工作区的自动化测试。
完整说明见 docs/README.md。
所有命令应在 Ubuntu 24.04 中执行:
./bin/lab help
./bin/lab doctor
./bin/lab bootstrap plan
./bin/lab device list
./bin/lab research new case-001 --title "Research case"首次克隆推荐同时获取 DroidForge:
git clone --recurse-submodules https://github.com/Patzilla0o7/android-security-research-lab.git
cd android-security-research-lab
./scripts/build-all.sh确认 Bootstrap 计划后,才执行会修改主机的安装操作:
./bin/lab bootstrap --apply
./bin/lab doctor先创建一个独立的 AOSP Workspace 档案:
./bin/lab workspace add android-14 \
--path /data/aosp/android-14 \
--manifest https://android.googlesource.com/platform/manifest \
--branch android-14.0.0_r75 \
--target aosp_x86_64-eng \
--java-home /usr/lib/jvm/java-17-openjdk-amd64
./bin/lab workspace use android-14
./bin/lab workspace initworkspace add 参数:
| 参数 | 必需 | 默认值 | 说明 |
|---|---|---|---|
<name> |
是 | 无 | 档案名称;只允许字母、数字、-、_ |
--path |
是 | 无 | AOSP 源码目录,必须是安全的绝对路径 |
--manifest |
否 | https://android.googlesource.com/platform/manifest |
Repo manifest 仓库地址 |
--branch |
否 | android-latest-release |
Repo manifest 分支或 Android tag |
--target |
否 | aosp_x86_64-eng |
传给 lunch 的默认构建目标 |
--java-home |
否 | 空 | 该 Workspace 使用的 JDK 路径 |
--target 会保存到档案的 ANDROID_BUILD_TARGET,作为 Build 工作流的默认构建目标。CCACHE_DIR 无需传入,系统会按档案名称自动生成独立路径。
管理多个版本:
./bin/lab workspace add android-15 \
--path /data/aosp/android-15 \
--branch android-15.0.0_r1 \
--target aosp_x86_64-eng
./bin/lab workspace list
./bin/lab workspace use android-15
./bin/lab workspace current
./bin/lab workspace status android-14
./bin/lab workspace init android-14| 文件 | 用途 |
|---|---|
config/workspaces/<name>.conf |
当前正式的多 Workspace 配置;保存源码路径、manifest、分支、构建目标、Java 和 ccache 路径 |
.local/active-workspace |
保存 workspace use 选择的活动档案名称 |
config/lab.conf |
旧单 Workspace/本机全局配置的兼容文件,不用于多 Workspace 的选择和切换 |
config/lab.conf.example |
旧配置格式模板;新增 AOSP 版本应优先使用 workspace add |
Workspace 档案与活动选择都是机器本地数据,已被 Git 忽略。workspace use 只切换活动配置,不会同步、构建或删除源码。不要将 token、密码、私钥或研究中的敏感证据提交到仓库。
Repo 命令默认操作活动 Workspace,也可以通过 --workspace <name> 指定档案:
./bin/lab repo status
./bin/lab repo init --workspace android-14 --partial-clone --no-use-superproject
./bin/lab repo init --workspace android-14 --partial-clone --no-use-superproject --apply
# 只显示同步计划,不访问网络
./bin/lab repo sync --workspace android-14 --jobs 8
# 显式执行同步
./bin/lab repo sync --workspace android-14 --jobs 8 --apply实际 repo init 和同步的日志保存在 output/repo/<workspace>/。repo sync 未指定
--jobs 时默认使用主机逻辑 CPU 数;未指定 --apply 时不会修改 Workspace。
交互式终端运行时会显示 Repo/Git 的项目级进度,以及当前 fetch 的对象数、百分比
和已接收字节。由于 Git 对象数量和压缩复用是动态的,无法在开始前准确显示所有
项目最终需要下载的总字节数。Partial Clone 仅对新初始化的 Workspace 生效;
--clone-filter 必须与 --partial-clone 一起使用。
选择项目和增强重试:
./bin/lab repo sync --workspace android-14 \
--project frameworks/base \
--project system/core \
--retry-fetches 3 \
--no-clone-bundle \
--jobs 4 \
--apply--project 可以重复;不指定时同步 manifest 中的所有项目。还支持 --force-sync,
它会在必要时覆盖指向不同 object directory 的 Git 目录并可能丢失 refs,只应在
明确理解影响时使用。
Build 默认只检查环境并显示计划,不执行编译:
./bin/lab build --workspace android-14完整构建需要显式指定 --apply:
./bin/lab build \
--workspace android-14 \
--jobs 16 \
--apply构建指定模块时可以重复 --module:
./bin/lab build \
--workspace android-14 \
--target aosp_x86_64-userdebug \
--module framework-minus-apex \
--module services \
--jobs 16 \
--apply--target 临时覆盖 Workspace 的默认构建目标,不修改档案。省略 --module
时执行完整 target;指定模块时执行模块构建。构建前会检查 Workspace、Repo、
build/envsetup.sh、target、磁盘空间、Java 和 ccache 配置。Go 负责参数、
路径保护、日志和状态;scripts/aosp-build.sh 只负责加载 AOSP Shell 环境并
执行 lunch、m。
查看最近一次结果:
./bin/lab build status --workspace android-14日志、历史元数据和 latest.json 保存在
output/build/<workspace>/。详细说明见 Build 工作流。
Branch 用于在一个或多个 AOSP Git 项目中创建同名研究分支,隔离漏洞复现、 补丁移植和实验修改。它不会切换 Android 版本;Android 版本仍由 Workspace 档案中的 manifest branch/tag 决定。
开始前确认 Workspace 已完成 Repo 初始化,并检查当前状态:
./bin/lab workspace status android-14
./bin/lab repo status --workspace android-14Branch 和 Patch 命令默认使用活动 Workspace;以下示例显式指定
--workspace android-14,避免在多个版本间误操作。
./bin/lab repo branch list --workspace android-14该命令在 Workspace 根目录执行 repo branches,只读取各项目的分支状态。
先查看计划,不修改源码:
./bin/lab repo branch create binder-cve \
--workspace android-14 \
--project frameworks/base \
--project frameworks/native确认项目范围后显式创建:
./bin/lab repo branch create binder-cve \
--workspace android-14 \
--project frameworks/base \
--project frameworks/native \
--apply实际等价于:
repo start binder-cve frameworks/base frameworks/native
--project 可以重复。不指定任何 --project 时,Repo 会对 manifest 中的全部
项目创建同名分支,范围很大,建议研究时明确列出项目。Branch 名称会经过 Git
兼容性检查。当前不提供高风险的 branch delete。
只导出工作树中已跟踪文件的未提交修改:
./bin/lab repo patch export \
--workspace android-14 \
--project frameworks/base同时导出最近两个已提交修改:
./bin/lab repo patch export \
--workspace android-14 \
--project frameworks/base \
--commits 2可以重复 --project,一次导出多个项目:
./bin/lab repo patch export \
--workspace android-14 \
--project frameworks/base \
--project frameworks/native \
--commits 1导出结构:
output/repo/android-14/patches/<timestamp>/
frameworks__base/
0001-example.patch # git format-patch 生成的已提交修改
working-tree.diff # git diff --binary HEAD 生成的未提交修改
metadata.json # Workspace、项目、manifest branch、基线 commit
SHA256SUMS # bundle 文件完整性校验
--commits 0 或不指定时不生成提交 Patch。当前未跟踪文件不会自动包含在
working-tree.diff 中;如需导出新文件,先在对应项目执行 git add <file>,
再运行 export。Patch bundle 位于可清理的 output/,重要研究成果应复制到
research/<case>/ 长期资产目录。
验证导出文件:
cd output/repo/android-14/patches/<timestamp>/frameworks__base
sha256sum -c SHA256SUMS普通工作树 diff 默认只检查,不修改目标 Workspace:
./bin/lab repo patch import \
--workspace android-15 \
--project frameworks/base \
--file /absolute/path/to/working-tree.diff输出 Patch check passed 后,再显式应用:
./bin/lab repo patch import \
--workspace android-15 \
--project frameworks/base \
--file /absolute/path/to/working-tree.diff \
--apply导入 git format-patch 文件:
./bin/lab repo patch import \
--workspace android-15 \
--project frameworks/base \
--file /absolute/path/to/0001-example.patch \
--apply导入行为:
| 文件类型 | 检查 | --apply 行为 |
|---|---|---|
*.patch |
git apply --check |
git am,保留作者、提交说明和提交元数据 |
| 其他 diff | git apply --check |
git apply,只修改工作树,不自动创建提交 |
导入失败时不会自动使用 --3way、--reject 或强制覆盖。应先检查目标项目的
本地修改和冲突,再手动处理。patch import 每次只接受一个 --project 和一个
--file,避免 Patch 被错误应用到多个仓库。
同步干净的 Android 14 Workspace
-> 为相关项目创建 binder-cve 研究分支
-> 修改源码并完成复现/修复实验
-> 导出已提交 Patch 和未提交 diff
-> 校验 SHA256SUMS 并归档研究资产
-> 在 Android 15 Workspace 中先检查 Patch
-> 显式导入、构建并验证跨版本影响
完整 Repo 说明见 Repo 工作流。