🪲 Beetle

攻击链驱动的移动应用安全平台

Android • iOS • Flutter • React Native • OWASP MASVS • 攻击链 • 源码导航 • SARIF • CycloneDX SBOM • 可选 AI • Docker

## 概述 **Beetle** 是一个离线优先的**应用安全情报平台**，用于分析 Android APK 和 iOS IPA，包括使用 **Flutter** 和 **React Native** 构建的应用。 它专为**渗透测试人员、移动安全工程师、开发人员、安全研究人员和审计员**而构建，将静态分析、可解释的安全情报、攻击链、源码导航、证据驱动的发现结果、专业报告以及可选的 AI 辅助整合到单一的分析师工作区中。 Beetle 是**离线优先**的：所有分析都在您自己的基础架构上本地运行，应用程序二进制文件和源代码永远不会上传到外部服务。确定性的情报引擎无需网络和 AI 提供商即可完成完整的扫描。 ## 为什么选择 Beetle？ 现代移动应用程序可能会产生数百个安全发现。Beetle 的设计围绕分析师的工作流程——帮助您决定*什么是漏洞、为什么它很重要，以及攻击者如何将这些弱点组合起来*——而不是仅仅为您提供一份毫无区分的列表。 * **可解释的发现结果** —— 每个分数和判定都附有易于理解的人工可读原因 * **证据先于假设** —— 发现结果基于具体的工件（代码、manifest、证书、二进制文件） * **攻击链** —— 将孤立的发现结果关联成真实的、有证据支撑的攻击路径 * **源码导航** —— 每个发现结果都直接链接到其确切的文件和行号 * **标准映射** —— 覆盖 OWASP MASVS 并与 OWASP 移动 Top 10 对齐 * **离线优先** —— 无需网络和 AI 提供商即可完成分析 * **可选 AI** —— 在上下文中解释发现结果、对证据进行推理以及回答安全问题 * **专业报告** —— 提供高管、技术和合规报告，以及机器可读的导出文件 ## 核心功能 * **静态分析** —— Android APK + iOS IPA 反编译、manifest/plist、证书、entitlements 和原生二进制文件 * **可解释的情报引擎** —— 归属、置信度、证据选择、发现融合、机密情报等——每一个都会添加元数据，而绝不会删除发现结果 * **攻击链** —— 将发现结果关联成真实的、有证据支撑的攻击路径 * **源码导航** —— 使用功能丰富的代码查看器，从任何发现跳转到其确切的源码位置 * **标准映射** —— OWASP MASVS 覆盖率和 OWASP 移动 Top 10 * **AI 安全（可选）** —— AI 助手和 AI 操作用于增强（而非取代）确定性分析（[详情见下](#ai-security-optional)） * **报告与集成** —— PDF、SARIF、CycloneDX SBOM、JSON、webhooks 以及 CI/CD 策略门控 ## AI 安全（可选） Beetle 使用确定性情报引擎在**本地执行所有安全分析**。AI 在该分析之上是一个完全**可选**的层。 其设计理念是经过深思熟虑的：检测和评分必须是确定性的、可重现的和可解释的，因此它们永远不会委托给模型。AI 被严格定位为一种解释辅助工具，可帮助分析师更快地处理 Beetle 已经生成的结果。 AI 可帮助： * 用通俗易懂的语言**解释发现结果**，包括它们为什么重要 * **解释发现结果背后的**证据 * **回答有关**发现结果、控制和攻击场景的**安全问题** * 根据发现结果的证据，**建议修复措施** * 从 Beetle 的发现结果和汇总数据中**生成高管摘要** * **协助调查**跨多个发现结果或攻击路径的事件 如果**未**配置 AI 提供商： * Beetle 仍会执行**完整的安全分析**。 * 调查、报告和所有确定性情报引擎将继续正常工作。 * 只有 AI 增强功能才需要 AI 提供商。 **支持的提供商：** * Claude * OpenAI * Gemini * DeepSeek * Ollama（本地 / 完全本地部署） AI 功能需要配置提供商——在设置之前它们不可用。 ## 功能特性 ### 移动安全情报 * Android 安全情报 * iOS 安全情报 * Flutter 安全情报 * React Native 安全情报 ### 情报引擎 * 机密情报 v2 * 网络情报 * 云配置情报 * APKLeaks 集成 * Semgrep 情报 * 归属引擎 * 置信度引擎 * 证据选择引擎 * 发现融合引擎 * 攻击链情报 * MASVS 情报 ### 调查工作区 * 工程工作区 * 调查仪表板 * 源码资源管理器 * 安全资源管理器 * 富代码查看器 * 源码解析 * 信任评分 * 安全评分 * AI 助手 * AI 操作 ### 报告与导出 * 高管 PDF * 技术 PDF * 合规报告 * SARIF 导出 * CycloneDX SBOM * JSON 导出 ## 截图 ### 工程工作区 主页工作区——您查看扫描目标、最近活动和进行调查的入口。  ### 扫描概览 扫描应用程序的高级概览：一目了然地查看评分、发现结果汇总和平台情报。  ### 安全发现结果 发现结果视图——证据驱动、置信度评分并映射到标准。  ### 打开发现结果 一个包含其证据、归属、置信度和修复上下文的单独发现结果。  ### 源码导航 使用富代码查看器，从任何发现跳转到其确切的文件和行号。  ### 源码资源管理器 浏览应用程序完整的反编译和解析后的源码树。  ### MASVS 覆盖率 跨分析应用程序的 OWASP MASVS 覆盖率映射。  ### AI 分析 可选的、基于证据的 AI 分析，用于解释发现结果和攻击路径。  ### AI 助手 基于您的扫描结果进行对话式、具有上下文感知能力的安全问答。  ## 架构 Beetle 接收扫描目标，对其进行注册，运行相应的平台分析器和检测引擎以输出规范的发现结果，然后通过一系列可解释的情报引擎丰富这些发现结果，最后将它们关联成攻击链，并渲染到报告和调查仪表板中。 ``` flowchart TD A[Scan Target] --> B[Scan Target Registry] B --> C[Platform Analyzer] C --> D[Intelligence Engines] D --> E[Canonical Findings] E --> F[Ownership] F --> G[Confidence] G --> H[Evidence Selection] H --> I[Finding Fusion] I --> J[Attack Chains] J --> K[Reports] J --> L[Investigation Dashboard] ``` ## 文档 Beetle 包含全面的技术文档。**Beetle 宝典**是唯一的权威参考——它记录了每个功能的作用、它存在的原因、它的内部工作原理，以及分析师应该如何解释其输出。 * **[Beetle 宝典](docs/beetle-bible/README.md)** —— 完整的技术参考（架构、引擎、评分、报告、FAQ、词汇表） * **[架构指南](ARCHITECTURE.md)** —— 系统架构与 pipeline * **[功能清单](FEATURE_INVENTORY.md)** —— 已实现功能的完整清单 * **[项目概述](PROJECT_OVERVIEW.md)** —— 高级项目导览 ## 快速入门 ### 克隆仓库 ``` git clone https://github.com/f3rb123/beetle.git cd beetle ``` ### 配置 Beetle 创建一个 `.env` 文件（或导出环境变量），至少包含： ``` SECRET_KEY= CORTEX_ADMIN_PASS= ``` 可选集成： ``` ANTHROPIC_API_KEY=... VIRUSTOTAL_API_KEY=... ``` ### 构建容器 ``` docker compose build ``` ### 启动 Beetle ``` docker compose up ``` 首次启动可能需要几分钟时间，因为 Docker 需要构建和初始化环境。请查看启动日志，直到 Beetle 报告后端已成功启动，然后打开： ``` http://localhost:9005 ``` 初始管理员账户会在首次启动时自动创建。您可以选择使用 `CORTEX_ADMIN_PASS` 设置密码；否则 Beetle 将生成一个安全的随机密码。在这两种情况下，管理员用户名和密码都会在初始化期间打印在容器日志中。 随时按 `Ctrl + C` 停止 Beetle。 ### 扫描持续时间 典型扫描时间： * 小型应用程序：**5–10 分钟** * 大型应用程序：**10–20 分钟以上** 实际持续时间取决于： * CPU * 可用 RAM * 存储性能 * 应用程序大小 * 资源复杂度 扫描时间不是固定的——它们会随着主机系统和被分析的应用程序而变化。 ## 故障排除 ### 未显示管理员密码 这通常是因为 Docker 卷中已经包含了已初始化的 Beetle 数据库。当数据库已经存在时，初始化不会再次运行，因此不会生成或打印新的管理员凭证。 要完全重置 Beetle： ``` docker compose down -v docker compose up ``` 初始化完成后，检查日志： ``` docker compose logs backend ``` 管理员用户名和生成的密码会在**初始化完成后**打印。 ## 支持的格式 | 平台 | 支持 | | ------------ | --------- | | Android | APK | | iOS | IPA | | Flutter | APK / IPA | | React Native | APK / IPA | ## 当前功能 * Android、iOS、Flutter 和 React Native 安全情报 * 机密情报 v2 * 网络情报 * 云配置情报 * APKLeaks 集成 * Semgrep 情报 * 归属引擎 * 置信度引擎 * 证据选择引擎 * 发现融合引擎 * 攻击链情报 * MASVS 情报和 OWASP 移动 Top 10 映射 * 工程工作区和调查仪表板 * 源码资源管理器和安全资源管理器 * 富代码查看器和源码解析 * 信任评分和安全评分 * AI 助手和 AI 操作（可选） * 扫描目标架构 * 高管、技术和合规报告 * SARIF 导出和 CycloneDX SBOM ## 路线图 以下功能计划在未来的版本中推出： * AI 安全情报 * 基础设施即代码情报 * 动态安全情报 * 云安全情报 * 企业仪表板 * 团队协作 * 插件 SDK ## 设计原则 * 离线优先架构 * 证据先于假设 * 可解释的发现结果 * 以分析师为中心的工作流程 * 基于标准的安全分析 * Docker 原生部署 * 可扩展架构 ## 贡献 欢迎提交 Bug 报告、功能请求、文档改进和 Pull Request。 在提交大型功能更改之前，请先提一个 issue，以便事先讨论实现方案。 ## 致谢 Beetle 建立在开源移动安全生态系统的基础之上并从中受益，相关项目包括： * JADX * apktool * LIEF * Semgrep * APKLeaks * OWASP 移动应用安全验证标准 (MASVS) * OWASP 移动安全测试指南 (MSTG) 他们的工作极大地推动了移动应用安全的发展，并使像 Beetle 这样的工具成为可能。

标签：AV绕过, FastAPI, OWASP MASVS, React, Syscalls, 攻击链分析, 移动应用安全, 请求拦截, 逆向工具, 错误基检测, 静态代码分析