🧠 APK AGI

AI 辅助的 Android 应用安全分析工具包

一个用于授权 Android APK 分析、静态安全审查、代码图谱探索和取证报告的开源研究与教育项目。

目的 • 负责任的使用 • 功能 • 架构 • 快速开始 • 路线图

## 🎯 目的 **APK AGI** 是一个采用 MIT 许可证的开源项目，专注于**负责任的 Android 应用安全分析**。 该项目将成熟的 Android 逆向工程工具与 AI 辅助工作流相结合，旨在帮助学生、开发者和安全研究人员了解 Android 应用程序的结构，以及在授权环境中如何识别常见的安全问题。 APK AGI 专为以下用户设计： - **学生**：学习 Android 安全、逆向工程和安全软件开发 - **开发者**：在发布前审查自己的 APK - **安全研究人员**：执行经授权的静态分析 - **教育工作者**：创建实用的移动安全实验室 - **开源贡献者**：探索用于开发者工具的代理式工作流（agentic workflows） ## 🔐 负责任的使用 APK AGI 必须仅用于**合法、符合道德且经授权的安全工作**。 ### 允许的用例 - 测试您拥有的 Android 应用程序 - 在获得明确书面许可的情况下审计 APK - 学术安全实验室和课程作业 - 在公布的范围内进行漏洞赏金研究 - 在受控实验室中对恶意软件样本进行防御性分析 - 出于教育目的了解 Android 应用程序的内部原理 ### 不允许的行为 本项目不得用于： - 盗版、破解或未经授权修改第三方应用程序 - 绕过付款、订阅、许可、DRM 或访问控制 - 去除您不拥有的应用程序中的广告 - 未经许可规避安全保护措施 - 未经授权重新打包或分发修改后的 APK - 任何违反法律、平台政策或软件许可的活动 APK AGI 是一款安全教育和研究工具，而不是盗版或滥用工具。任何修补或重构功能仅适用于您拥有的应用程序、受控实验室或明确授权的评估。 ## ✨ 功能 ### 核心能力 | 类别 | 能力 | |:--|:--| | **APK 反编译** | 使用 apktool、JADX 和 dex2jar 等工具检查 APK 结构、Smali、类似 Java 的输出以及 JAR 产物 | | **Manifest 审查** | 解析权限、导出组件、intent filter、网络安全设置和应用程序元数据 | | **静态安全分析** | 检测常见的安全模式，例如弱加密使用、硬编码 secrets、不安全的 WebView 设置、日志泄漏、动态代码加载和不安全的网络配置 | | **代码图谱探索** | 构建基于 NetworkX 的图谱，用于探索类、方法、调用者、被调用者和路径 | | **代码索引** | 为类、方法、字符串、包和相关产物创建可搜索的索引 | | **字符串与 Secret 审查** | 对 URL、类似 API 的 token、Base64 字符串、Firebase 样式的引用以及其他可疑常量进行分类 | | **原生与混合应用审查** | 识别 JNI 的使用、原生库加载、Flutter/React Native 桥接以及原生二进制文件清单 | | **证据笔记本** | 存储包含严重程度、类别、上下文和备注的调查结果，以确保长会话保持可审计性 | | **人工干预 (HITL) 审查** | 高影响力的更改在应用前应进行预览和批准 | | **报告生成** | 生成包含调查结果、方法论、局限性和证据摘要的 Markdown 报告 | ### AI 辅助工作流 APK AGI 使用代理式循环（agentic loop）来帮助组织长时间的安全分析会话： 1. 理解用户的授权分析目标 2. 规划调查步骤 3. 运行反编译和静态分析工具 4. 保存调查结果和证据 5. 构建代码图谱和索引 6. 审查可能存在的风险和局限性 7. 生成可重现的报告 AI 工作流旨在协助人工审查员。它不能替代专业的判断、人工验证或法律授权。 ## 🧭 安全模型 APK AGI 遵循**分析优先**的设计理念。 ### 现有的安全防护措施 - 本 README 中包含明确的负责任使用政策 - 用于可追溯性的证据日志记录 - 针对高影响力更改的人工审查流程 - 包含局限性和假设的报告章节 - 针对教育和授权测试的预期使用边界 ### 计划实现的安全防护措施 - `SAFE_MODE=analysis_only`，默认禁用修补/构建操作 - 项目范围文件，用于限制允许的 APK 哈希值、包名和路径 - 在执行任何修改或重构操作前提供更强有力的警告 - 针对安全敏感型工具的 CI 测试 - 对下载的外部工具进行 SHA256 验证 - 更小、模块化的工具文件，以便于审查 - 提供用于安全演示的示例性故意脆弱 APK 实验室 ## 🏗️ 架构 ``` flowchart TD A[User: authorized security goal] --> B[CLI / Rich UI] B --> C[LangGraph agent workflow] C --> D[Tool execution layer] D --> E[APK decompilation] D --> F[Manifest and static analysis] D --> G[Code graph and index] D --> H[Evidence notebook] H --> I[Markdown security report] G --> I F --> I ``` ### 主要组件 | 组件 | 作用 | |:--|:--| | `src/apk_agent/cli.py` | 交互式命令行界面 | | `src/apk_agent/config.py` | 环境和工具配置 | | `src/apk_agent/agent/graph.py` | LangGraph 状态机和路由 | | `src/apk_agent/agent/tools_def.py` | 工具注册层 | | `src/apk_agent/tools/` | Android 分析、图谱、证据、报告和构建辅助工具 | | `scripts/setup_tools.py` | 外部工具设置的辅助脚本 | | `Dockerfile` | 用于可重现使用的容器化环境 | ## 🔧 工具 APK AGI 集成了广泛使用的 Android 和 Python 生态工具。 ### Android 工具 | 工具 | 用途 | |:--|:--| | apktool | APK 资源解码、Smali 反汇编和重构支持 | | JADX | 将 DEX 反编译为类似 Java 的源代码 | | dex2jar | 将 DEX 转换为 JAR，用于 JVM 级别的检查 | | Android SDK Build Tools | 支持 `aapt2`、`zipalign` 和 `apksigner` | ### Python 和 AI 工具 | 库 | 用途 | |:--|:--| | LangGraph | 代理式状态机和工作流控制 | | LangChain | LLM 抽象和工具绑定 | | NetworkX | 代码图谱构建和遍历 | | Rich | 终端 UI 和格式化输出 | | Click | CLI 参数解析 | | python-dotenv | 加载 `.env` 配置 | | PyYAML | YAML 解析 | ## 🚀 快速开始 ### 前置条件 - Python 3.11+ - Java JDK/JRE 11+ - 用于签名和对齐功能的 Android SDK Build Tools - 来自与项目配置兼容的提供商的 LLM API 密钥 ### 安装 ``` git clone https://github.com/amenallahbarkaoui-github/APK_AGI.git cd APK_AGI pip install -e . python scripts/setup_tools.py ``` ### 配置 在项目根目录下创建一个 `.env` 文件： ``` API_KEY=your-api-key-here API_BASE_URL=https://your-compatible-provider.example/v1 MODEL_NAME=your-model-name # 可选的外部工具覆盖 # APKTOOL_PATH=tools/bin/apktool.jar # JADX_PATH=tools/bin/jadx/bin/jadx # APKSIGNER_PATH=tools/bin/build-tools/apksigner # ZIPALIGN_PATH=tools/bin/build-tools/zipalign ``` ### Docker ``` docker build -t apk-agi . docker run -it --env-file .env -v ./workspace:/workspace apk-agi ``` ## 💡 示例用法 ### 开始授权分析 ``` apk-agent path/to/owned-or-authorized-app.apk ``` ### 示例提示词 ``` Perform an authorized static security review of this APK and generate a report. ``` ``` Analyze the manifest, exported components, permissions, network security config, and hardcoded secrets. ``` ``` Build a code graph and identify security-relevant call paths for networking, WebView, cryptography, and dynamic loading. ``` ``` Generate a Markdown report with findings, evidence, severity, limitations, and recommended remediation steps. ``` ## 📄 报告输出 APK AGI 可以生成用于教育和授权安全审查的 Markdown 报告。 典型的报告包括： - 执行摘要 - 范围和授权说明 - 工具和方法论 - Manifest 和权限调查结果 - 网络安全观察结果 - 代码图谱洞察 - 潜在漏洞 - 证据参考 - 局限性和误报说明 - 建议的修复步骤 ## 🧪 项目状态 APK AGI 目前是一个**研究预览版**。 它可用于实验和学习，但不应将其视为完全经过验证的商业安全产品。在做出任何安全决策之前，应手动审查调查结果。 ### 已知的改进领域 - 添加自动化测试和 CI 工作流 - 添加可重现的示例实验室 - 将大型工具定义拆分为更小的模块 - 改进每个分析工具的文档 - 为外部二进制文件添加校验和/签名验证 - 统一 README、CLI 和包元数据中的项目版本控制 - 改进修补和重构相关的安全控制 ## 🛣️ 路线图 ### 短期 - [ ] 添加用于代码检查和测试的 GitHub Actions - [ ] 添加 `RESPONSIBLE_USE.md` - [ ] 添加 `SECURITY.md` - [ ] 添加 `CONTRIBUTING.md` - [ ] 添加安全的示例 APK 实验室文档 - [ ] 添加授权分析工作流的屏幕截图或演示 GIF ### 中期 - [ ] 添加 `SAFE_MODE=analysis_only` - [ ] 添加对 APK 包名和哈希的范围验证 - [ ] 添加工具下载的 SHA256 验证 - [ ] 将工具定义重构为更小的模块 - [ ] 为解析器和扫描器添加单元测试 - [ ] 使用故意脆弱的测试 APK 添加集成测试 ### 长期 - [ ] 创建教育性的 Android 安全课程 - [ ] 发布可重现的基准测试报告 - [ ] 支持基于插件的工具扩展 - [ ] 改进基于图谱的漏洞解释 - [ ] 为讲师构建更安全的课堂/实验室模式 ## 🛡️ 安全策略 如果您在 APK AGI 本身中发现漏洞，请提交一个不泄露敏感细节的最小化描述的 GitHub issue，或通过 GitHub 个人资料联系维护者。 请勿向此代码库提交真实的 secrets、专有 APK、私钥或未经授权的应用程序样本。 ## ⚖️ 法律与道德声明 此代码库仅用于教育和授权的安全研究。 用户有责任遵守所有适用的法律、软件许可、平台政策和授权要求。维护者不认可也不对滥用本项目的行为负责。 如果您不确定是否被允许分析或修改 APK，请勿对该 APK 使用此工具。 ## 📚 致谢与归属 APK AGI 建立在 Android 安全和开源生态系统的成果之上，包括： - apktool - JADX - dex2jar - Android SDK Build Tools - LangGraph - LangChain - NetworkX - Rich - Click 请参阅每个上游项目以了解其许可和文档。 ## 📄 许可证 本项目基于 MIT 许可证授权。有关详细信息，请参阅 [LICENSE](LICENSE) 文件。

由 Amenallah Barkaoui 用 ❤️ 构建

标签：AI Agent, Android安全, Python, 云安全监控, 云资产清单, 无后门, 漏洞检测, 目录枚举, 移动安全, 逆向工程, 静态分析