amrudesh1/morf

GitHub: amrudesh1/morf

MORF 是一款直接扫描已发布的 Android APK 和 iOS IPA 二进制文件，检测并验证硬编码机密、生成 SBOM 并关联漏洞的开源移动安全侦察框架。

Stars: 80 | Forks: 9

MORF — Mobile Reconnaissance Framework
**唯一能够解析你 _发布_ 的应用 —— Android `.apk` **和** iOS `.ipa` —— 找出机密信息，并 _证明其有效_ 的 OSS 扫描器。**
[![CI](https://img.shields.io/github/actions/workflow/status/amrudesh1/morf/ci.yml?branch=main&style=flat-square&label=ci&labelColor=0F172A&color=2563EB)](https://github.com/amrudesh1/morf/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-Apache--2.0-2563EB?style=flat-square&labelColor=0F172A)](LICENSE) [![Go](https://img.shields.io/badge/go-1.25-2563EB?style=flat-square&labelColor=0F172A&logo=go&logoColor=white)](morf/go.mod) [![React](https://img.shields.io/badge/react-19-2563EB?style=flat-square&labelColor=0F172A&logo=react&logoColor=white)](frontend/) [![SARIF](https://img.shields.io/badge/SARIF-2.1.0-3FB950?style=flat-square&labelColor=0F172A)](docs/MASVS.md) [![MASVS](https://img.shields.io/badge/OWASP-MASVS-3FB950?style=flat-square&labelColor=0F172A)](docs/MASVS.md) [![SBOM](https://img.shields.io/badge/SBOM-CycloneDX%201.6-3FB950?style=flat-square&labelColor=0F172A)](docs/BENCHMARK.md) [![Arsenal](https://img.shields.io/badge/5%C3%97-BlackHat%20Arsenal-0F172A?style=flat-square&logo=hackthebox&logoColor=white)](#-会议认可) `APK + IPA` · `280+ 探测器` · `24 个实时验证器` · `SBOM + CVE` · `SARIF / MASVS` · `构建门禁` [**快速开始**](#-quick-start)  •  [**安装说明**](#-installation)  •  [**用法**](#-usage)  •  [**文档**](#-documentation)  •  [⭐ **星标**](https://github.com/amrudesh1/morf/stargazers)
## 📋 目录 - [💡 概述](#-overview) · [为什么选择 MORF](#why-morf) - [🔍 核心功能](#-key-features) - [🚀 快速开始](#-quick-start) - [📦 安装说明](#-installation) - [🖥️ 用法](#-usage) — [Web](#web-interface) · [CLI & CI](#command-line--ci) · [SBOM + CVE](#sbom--cve) · [MCP](#mcp-agent-server) - [🎯 检测与精度](#-detection--precision) - [🔴 验证](#-verification-opt-in-read-only) - [🛡️ SARIF 与 OWASP MASVS](#️-sarif--owasp-masvs) - [🏗️ 架构](#️-architecture) - [⛨ 安全态势](#-security-posture) · [◈ 基准测试](#-benchmark) - [📋 常见用例](#-common-use-cases) · [🛣️ 路线图](#️-roadmap) - [📚 文档](#-documentation) · [🏆 会议认可](#-conference-recognition) - [👨‍💻 作者](#-authors) · [📄 许可证](#-license) · [🙏 致谢](#-acknowledgments) ## 💡 概述 **MORF — 移动侦察框架** 是一款攻击性安全工具包，用于发现移动应用**构建产物** —— Android `.apk` 和 iOS `.ipa` —— 内部硬编码的机密和侦察信号，所有这些均由一个共享的检测核心提供支持。与源代码级的 SAST 或仓库机密扫描器不同，MORF 直接针对**发布的二进制文件**进行工作：它使用 apktool 反编译 APK 并用纯 Go 解析 Mach-O 可执行文件，然后在两者上运行相同的机密模式和精度引擎。 MORF 通过**同一个二进制文件**支持三种运行方式：可扩展的**服务**（基于 Redis 的作业队列 + worker pool，MySQL，Prometheus/Grafana，OpenTelemetry，React 19 Web UI），原生支持 CI 的 **CLI**，以及用于 LLM 智能体的 **MCP server**。 ### 为什么选择 MORF 源码 SAST 和仓库机密扫描器读取的是*可能*会发布的代码。**MORF 反汇编商店中确切的二进制文件**，并解答普通正则表达式扫描器无法做到的事情：
| | 源码/仓库扫描器 | **MORF** | |---|:---:|:---:| | 扫描**已发布的构建产物** (APK **&** IPA) | — | **✔** | | **验证**机密是否有效（只读） | — | **✔** | | **确定性**精度（无 LLM，无网络） | — | **✔** | | 每个应用独立的 **SBOM + CVE** (CycloneDX 1.6) | — | **✔** | | 针对仅*新*机密的构建**门禁** | — | **✔** | | 原生支持 **SARIF 2.1.0 + OWASP MASVS** | 部分 | **✔** | **548 个原始命中 → 9 个真实机密 → 0 个误报**  ·  *在内置基准测试语料库上的精度引擎表现。*
## 🔍 核心功能 | 功能 | 描述 | |---|---| | **🔐 机密与 API key 检测** | 将 280 多种限定平台的模式编译成单次 ripgrep 扫描，覆盖 smali、资源、原生 `.so`、Flutter/RN bundle、`assets/`、`resources.arsc`、嵌入式配置以及 Mach-O 字符串。 | | **✅ 实时验证** | **24** 个只读 provider 验证器可确认候选项是 `active` / `inactive` / `unknown` —— GitHub、GitLab、Slack、Stripe、GCP、**AWS SigV4 STS**、OpenAI、Anthropic、Datadog、Square、Notion、Figma 等。默认**关闭**。 | | **🎯 精度引擎** | Shannon 熵 + 结构验证器为每个候选项划定层级 `drop` / `info` / `keep` 并给出 `[0,1]` 的分数。确定性，无需网络，无需模型。 | | **🧾 SBOM + CVE** | 基于证据的每个被扫描应用专属的 **CycloneDX 1.6**（包含框架、dylib、原生库、Firebase —— 完成PURL映射，读取 lockfile 版本），并可选择将 **OSV/CVE** 关联结果写入 `vulnerabilities[]`。 | | **📱 组件与权限分析** | 提取 activities/services/receivers/providers、权限、deeplink 和 URL scheme、entitlements 以及应用元数据 —— 并附带映射到 MASVS 的**导出组件 / deeplink 暴露**和 **Firebase/GCP 配置错误**发现。 | | **🚦 CI 门禁** | `morf scan` / `morf gate`：策略退出代码，与已接受的基准相比，仅在出现**新**机密时失败。提供适用于 GitHub Actions、GitLab、Jenkins、CircleCI、pre-commit 的方案。 | | **🛡️ SARIF 2.1.0 + OWASP MASVS** | 适用于 GitHub Code Scanning 的合规 SARIF schema；发现结果附带 `MASVS-STORAGE / -CRYPTO / -NETWORK / -PLATFORM` ID；机密值会被掩码处理。 | | **🤖 MCP 智能体服务器** | `morf mcp` 通过 stdio 暴露 `scan_file`、`get_results`、`list_patterns`、`verify_secret`、`explain_finding` —— 所有输出均已掩码，无需 DB/Redis/HTTP。 | | **📊 版本比较** | `/compare` 对比两次扫描的差异（新增 / 移除 / 未改变），以跟踪不同构建间的机密卫生状况。 | | **⚙️ 可扩展服务** | Redis 可靠队列（DLQ + reaper）+ worker pool，规范化的 MySQL (GORM)，API key 认证 + 速率限制，Prometheus/Grafana，OpenTelemetry，S3/本地存储，K8s/KEDA。 | | **🖥️ React 19 Web UI** | Vite + Tailwind "Electric Slate" UI：拖拽上传，实时扫描步骤，按层级/平台分类的结果，`/compare`，PDF 导出。 | | **🔐 静态保护** | 默认对数值进行掩码处理；可选的静态 AES-256-GCM 加密；通过基于密钥的 HMAC **指纹**实现稳定身份验证（绝不使用明文）。 | ## 🚀 快速开始 MORF 作为 Docker Compose 技术栈运行 —— **MySQL + Redis + Go 后端 + React 前端**： ``` git clone https://github.com/amrudesh1/morf && cd morf # 选项 1 — 运行脚本（推荐）： ./run-local.sh start # 选项 2 — 直接运行 Docker Compose： docker compose up -d --build # Apple Silicon (arm64): 后端必须构建原生 arm64 — docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --build ```
| ◐ Web UI | ◑ API | ◒ 健康检查 | |:---:|:---:|:---:| | `http://localhost/` | `http://localhost:9092/api` | `…/api/health` |
## 📦 安装说明 ### 前置条件 - **Docker + Docker Compose**（推荐路径），**或者**对于本地构建： **Go 1.25**、**Node 20+**、**ripgrep**、**Java 11+**（仅用于反编译 APK），以及 **Redis** 和 **MySQL**。 ### 方法 1 — Docker（推荐） ``` git clone https://github.com/amrudesh1/morf && cd morf docker compose up -d --build # MySQL · Redis · backend · frontend docker compose logs -f morf-backend # follow logs docker compose down # stop ``` ### 方法 2 — 运行脚本 ``` ./run-local.sh start | status | logs | stop ``` ### 环境配置 复制示例环境变量文件，并在实际部署时覆盖凭证（`docker-compose.yml` 中内置了本地开发的回退配置，因此即使没有 `.env` 文件，`docker compose up` 也能正常工作）： ``` cp .env.example .env # macOS / Linux copy .env.example .env # Windows (CMD) Copy-Item .env.example .env # Windows (PowerShell) ``` 关键变量：`DATABASE_URL`、`REDIS_URL`、`MORF_REQUIRE_API_KEY`（默认**开启**）、`MORF_MASK_RESULTS`（默认**开启**）、`MORF_ENABLE_VERIFICATION`（默认**关闭**）、`MORF_SECRET_ENCRYPTION_KEY`、`MORF_FINGERPRINT_SALT`、`MORF_ENABLE_OSV`、`MORF_WEBHOOK_SECRET`。 ### 本地运行（无 Docker） ``` cd morf && go build -o morf . ../scripts/fetch-tools.sh # one-time: fetch apktool.jar for local APK scans ./morf scan ../app.ipa --sarif # iOS path is pure-Go (needs only ripgrep) ``` ## 🖥️ 用法 ### Web 界面 打开 `http://localhost/`，将 `.apk`/`.ipa` 拖到接收屏幕上，即可查看实时的扫描步骤。结果按**层级**（`keep`/`info`）和**平台**分组；**检测规则**视图可在运行时管理模式，`/compare` 可对比两次扫描的差异。支持导出为 **SARIF / JSON / CSV / PDF / CycloneDX**。*所有内容都在你的本地机器上进行分析 —— 不会向外部发送任何与应用相关的信息。* ### 命令行与 CI 由 worker 执行的扫描 → 精度分析 → 验证流水线完全相同，专为 CI 打造。 [docs/CI.md](docs/CI.md) 是标准的契约与可复用的方案。 ``` # Emit SARIF，仅在 live-verified secret 时使构建失败 (exit 4)： morf scan app.apk --sarif --out morf.sarif --fail-on=verified --verify # 仅报告 JSON，永不使构建失败： morf scan app.ipa --format=json --fail-on=none # Build-diff gate：仅在与接受的指纹基线相比为 NEW secrets 时失败： morf gate app.apk --baseline morf-baseline.json --fail-on=verified morf gate app.apk --baseline morf-baseline.json --update-baseline # accept current state ``` **退出代码：** `0` 通过 · `4` 策略命中（CI 拦截点） · `1` 操作错误。 **`--fail-on`：** `verified` · `keep` · `any` · `none`。所有 SARIF/JSON 的值均已掩码处理。 ``` # GitHub Actions — scan → 上传 SARIF → gate，一步完成： - uses: amrudesh1/morf/.github/actions/morf-scan@main with: { artifact: app.apk, fail-on: verified, verify: "true" } ``` ### SBOM + CVE ``` morf scan app.apk --format=cyclonedx-sbom --out sbom.json # evidence-based SBOM morf scan app.apk --format=cyclonedx-sbom --with-cve --out sbom.json # + OSV/CVE correlation ``` ### MCP 智能体服务器 ``` morf mcp # stdio MCP server — no DB/Redis/HTTP, every output masked ``` 工具：`scan_file` · `get_results` · `list_patterns` · `verify_secret` · `explain_finding`。 ## 🎯 检测与精度 一个共享的**检测核心** (`detect/`) 将 280 多种限定平台的 YAML 模式编译成单次 ripgrep 扫描，覆盖两个平台 —— 包括原生 `.so`、Flutter/RN bundle、`assets/`、`resources.arsc` 以及嵌入式配置（`google-services.json`、`GoogleService-Info.plist`）。随后，每个候选项都会流经**精度引擎**：熵与结构验证器会为其分配一个层级（`drop`/`info`/`keep`）—— **确定性分析，无需网络，无需模型** —— 从而确保广度不会重新引入噪音。只需通过 YAML 条目或 `/api/patterns` CRUD 即可添加探测器 —— 无需修改代码。 ## 🔴 验证（可选，只读） 确认候选项在其 provider 上是否*有效* —— **默认关闭**，受 `--verify` / `MORF_ENABLE_VERIFICATION=true` 控制，始终为只读模式（受速率限制，无重定向，结果会缓存，绝不记录原始机密）。**24 个验证器** 包含 GitHub · GitLab · Slack · Stripe · GCP · **AWS SigV4 STS** · OpenAI · Anthropic · Datadog · PagerDuty · Square ·oku · Figma · Notion · Airtable · Mapbox · Twilio · SendGrid · Cloudflare → `active`/`inactive`/`unknown`。 ## 🧾 SBOM + CVE 基于证据的、针对每个扫描构建产物的 **CycloneDX 1.6** SBOM —— iOS 框架/dylib（已解析版本）、Android 原生库（SHA-256）、Firebase —— 每个组件都带有 `evidence.identity` + 置信度以及符合规范的 **PURL**（`pkg:cocoapods` / `pkg:swift` / `pkg:maven` / `pkg:pub` / `pkg:npm`）。目录树中的 lockfile（`Podfile.lock`、`Package.resolved`、`pubspec.lock`、`package-lock.json`）用于细化版本信息。使用 `--with-cve` 时，组件 PURL 将与 **OSV** 进行关联比对，并写入 CycloneDX 的 `vulnerabilities[]` 数组中。 ## 🛡️ SARIF 与 OWASP MASVS 合规的 **SARIF 2.1.0** (`report/sarif.go`)：层级 → 级别（`keep`=error，`info`=note），所有机密均已掩码处理。发现结果 —— 包含机密**及**平台问题（导出组件、deeplink、Firebase/GCP 配置错误） —— 会在规则 `tags` 中携带 OWASP **MASVS** 控制 ID（`MASVS-STORAGE-1/-2`、`-CRYPTO-1`、`-NETWORK-1`、`-PLATFORM-1`）以及 `masvsId` 属性。详见 [docs/MASVS.md](docs/MASVS.md)。 ## 🏗️ 架构
MORF architecture — ingest → decode → shared detection core → persist/deliver, across service/CLI/MCP surfaces
**Go 1.25** 后端 + **React 19 / Vite / Tailwind** UI。相同的底层包（`detect`、`precision`、`verify`、`report`、`gate`、`osv`）同时为服务端、CLI 以及 MCP server 提供动力。→ [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) ## ⛨ 安全态势 ## ◈ 基准测试 完全封闭环境（仅使用 ripgrep，无网络依赖），可通过 **`morf benchmark`** 复现：
| 阶段 | 精度 | 召回率 | F1 | |:---|:---:|:---:|:---:| | 原始候选项 | `0.57 – 0.90` | `1.00` | — | | **精度引擎处理后** | **`1.00`** | **`1.00`** | **`1.00`** | **成功召回 16 个植入的机密 · 0 个误报 · 丢弃了 5 个诱饵。** [docs/BENCHMARK.md](docs/BENCHMARK.md)
## 📋 常见用例 | 用例 | 描述 | |---|---| | **🕵️ 发布前构建产物审计** | 扫描你发布的实际 `.apk`/`.ipa`，而不是源码树。 | | **⚙️ CI/CD 机密门禁** | `morf gate` 仅在对比已接受的基准发现新机密时才会导致构建失败。 | | **🛡️ GitHub Code Scanning** | 将 MORF SARIF 上传到安全标签页；发现结果带有 MASVS ID。 | | **🧾 供应链 / SBOM** | 为合规性生成带有 CVE 关联的、每个应用专属的 CycloneDX SBOM。 | | **🤖 智能体驱动的分类排查** | 将 LLM 智能体指向 `morf mcp` 以进行扫描、验证和解释发现结果。 | | **🔍 竞品 / 研究侦察** | 了解任何已发布应用的机密卫生状况与结构。 | ## 🛣️ 路线图 - [x] 双平台 APK + IPA 侦察 · 精度引擎 · SARIF/MASVS · CLI + 门禁 - [x] 实时验证（24 个 provider） · 静态加密 · MCP server - [x] 每个应用的 SBOM (CycloneDX 1.6) + OSV/CVE 关联 - [x] MASVS-PLATFORM 发现（导出组件、deeplink、Firebase/GCP 配置错误） - [ ] 在精度保护的支撑下，将探测器广度提升至 TruffleHog 级别 - [ ] 增加更多 provider 验证器（Azure、JWT 签名、Firebase 服务账号） - [ ] 用于 Android 库识别的 DEX/smali 类指纹识别（LibScout 风格） - [ ] 原生厂商导入（App Store Connect / TestFlight / Play） ## 📚 文档 | 文档 | | 文档 | | |---|---|---|---| | [ARCHITECTURE](docs/ARCHITECTURE.md) | 组件映射与数据流 | [CI](docs/CI.md) | CLI 契约与方案 | | [MASVS](docs/MASVS.md) | 控制映射 | [BENCHMARK](docs/BENCHMARK.md) | 精度/召回率方法 | | [INGESTION](docs/INGESTION.md) | 构建产物获取适配器 | [IOS_SCANNING](docs/IOS_SCANNING.md) | 纯 Go 实现的 Mach-O 内部机制 | | [SECURITY_ROADMAP](docs/SECURITY_ROADMAP.md) | 威胁模型与路线图 | | | ## 🏆 会议认可 **BlackHat Arsenal 2026** — MORF 以其 v2 安全态势回归：双平台 APK+IPA 二进制侦察、*经过验证的*机密、每个应用专属的 SBOM+CVE 以及 SARIF/MASVS CI 输出。
往届亮相 - **BlackHat Asia 2023** — Arsenal 首次亮相 - **BlackHat US 2023** — Arsenal - **BlackHat Europe 2024** — Arsenal - **BlackHat Asia 2025** — Arsenal
## 👨‍💻 作者 |
[**@amrudesh1**](https://github.com/amrudesh1) |
[**@abhi-r3v0**](https://github.com/abhi-r3v0) |
[**@himanshudas**](https://github.com/himanshudas) | |:---:|:---:|:---:|
**如果 MORF 帮你抓到了差点就发布出去的机密 —— 请 [⭐ 星标仓库](https://github.com/amrudesh1/morf/stargazers)。** ## 📄 许可证 基于 **Apache License 2.0** 发布 —— 详见 [LICENSE](LICENSE)。 ## 🙏 致谢 [secrets-patterns-db](https://github.com/mazen160/secrets-patterns-db) · [go-macho](https://github.com/blacktop/go-macho) · [OSV.dev](https://osv.dev)
标签：Android安全, EVTX分析, Go, iOS安全, Ruby工具, StruQ, 云安全监控, 对抗攻击, 搜索引擎查询, 敏感信息检测, 日志审计, 用户代理, 目录枚举, 移动安全, 自定义请求头, 请求拦截, 静态分析