3CH0F0RG3

Flipper Zero 的 AI 原生 payload 铸造工具。
自然语言 → 高级 BadUSB / Sub-GHz / IR / NFC payload。
面向授权红队行动的生产级安全架构。

捕获 • 分析 • 铸造 • 部署

## 为什么选择 3CH0F0RG3 Flipper Zero 是现代红队工作中能力最强的硬件平台 —— Sub-GHz、NFC、RFID、IR、BadUSB、BadBT、GPIO，集于一个钥匙扣大小的设备中。**3CH0F0RG3 是首个为其构建的 AI 原生操作员接口。** 您说自然语言，Claude 编写 payload，安全架构审计每一步，最后由 Flipper 执行。 这不是爱好者的玩具。它是一个专为授权行动设计的 payload 编写框架，具备使其能够胜任严肃工作的操作员问责基元。 ## 功能特性 | | 功能 | 描述 | | :-: | :---------------------------- | :------------------------------------------------------------------------------------------------------------------------- | | 🧠 | **AI 由 Claude Code 驱动** | Claude 是操作员的战力倍增器 —— 编写 payload、分析捕获数据、讲解实战技巧 | | 📡 | **直接设备通信** | 基于 USB-CDC 的自定义 Protobuf RPC 协议栈 —— 无需修改固件，兼容原厂和 Momentum 固件 | | 🛠️ | **智能 Payload 生成** | DuckyScript / `.sub` / `.ir` 编写，配备 22 条规则的 linter 和自然语言生成 | | 🔌 | **多协议支持** | BadUSB, Sub-GHz, IR, NFC, RFID, iButton, GPIO —— 每个 Flipper 基元都作为带类型的 MCP 工具暴露 | | 🎯 | **专为攻击性操作构建** | HIGH+hold 门控，哈希链审计，范围强制执行，用于行动交付物的 OPERATOR 模式全内容日志 | ## 架构 ``` flowchart LR OP([👤 Operator]) CC[🧠 Claude Agent SDK] SP{🛡 SafetyPolicy
assess + DiffSummary} FF[⚙ Flipper Facade
13 MCP tools] FZ[📡 Flipper Zero
via USB-CDC] TGT[🎯 Target
RF / HID / IR / NFC] AUD[(🔒 Audit DB
hash-chained)] OP <==> CC CC -- proposed action --> SP SP -- approval prompt --> OP OP -- hold-to-confirm --> SP SP -- gated --> FF FF -.Protobuf RPC.-> FZ FZ -.physical layer.-> TGT SP --> AUD CC --> AUD ``` 每一个会改变 Flipper 状态的操作都会经过以下流程： - **`SafetyPolicy.assess()`** —— 风险分类 (`LOW` / `MED` / `HIGH` / `BLOCKED`) - 每次写入的 **DiffSummary** —— 操作员在批准前可以看到具体的字节内容 - **`requires_hold`** 手势用于物理执行（BadUSB 运行，RF 发射）—— 不可逆操作需要按住确认，而不是轻触一下 - **哈希链审计数据库** —— 防篡改的记录，涵盖每一次操作、每一次批准和每一个结果 - **OPERATOR 模式捕获** —— 完整的 payload 字节被记录以供行动交付物使用（通过 `--audit-mode=operator` 启用）；HOBBYIST 模式出于隐私考虑仅保留哈希 ## 快速开始 ``` git clone https://github.com/ascensionstrategist/echoforge.git cd echoforge python -m venv .venv .venv\Scripts\activate pip install -e ".[dev]" # 拉取 Flipper protobuf 定义 + 生成 Python bindings python scripts/fetch_protos.py python scripts/build_protos.py # 运行 test suite (385 项测试, ~1.4s) pytest # 插入你的 Flipper。确认连接。 python -m echoforge.tools.ping # 启动 AI REPL — 自然语言 Flipper 控制 python -m echoforge.tools.repl ``` ## 60 秒演示 ``` $ python -m echoforge.tools.repl ╭────────────────────────────────────────────────╮ │ echoforge connected to Webcam on COM7 │ │ type /help for commands, /quit to exit │ ╰────────────────────────────────────────────────╯ you › what's on my SD card? ▸ list_directory(path='/ext') ✓ 64 entries in /ext [64 entries listed across badusb/, subghz/, infrared/, nfc/, ...] you › what's my battery level? ▸ get_power_info() ✓ battery=100% charging=charged voltage=4.117V temp=26°C you › blink the LED red three times ▸ led_control(color='r', level=255) ▸ led_control(color='r', level=0) ×3 you › /quit session ended. 4 turns, 4 actions logged. ``` 上面的每一行都是真实的 —— 捕获自与连接到 COM7 的 Flipper 进行的实时 REPL 会话。 ## MCP 工具接口 **13 个带类型的 payload 工具**，涵盖 Flipper Zero 的能力矩阵： | 域 | 工具 | | :--------- | :---- | | **BadUSB** | `payload_badusb_validate` • `payload_badusb_create` • `payload_badusb_run` | | **Sub-GHz** | `payload_subghz_list` • `payload_subghz_inspect` • `payload_subghz_retune` • `payload_subghz_import_capture` • `payload_subghz_tx` | | **Infrared** | `payload_ir_list` • `payload_ir_inspect` • `payload_ir_import_capture` • `payload_ir_transmit` | | **Library** | `payload_library_search` (跨类型搜索，附带 sidecar 漂移检测) | 另外还有 33 个较低级别的 Flipper 基元 —— 存储、系统、GPIO、应用程序、硬件 —— 用于直接控制。 完整的 schema、风险级别和 hold/diff 要求请参阅 [`docs/PHASE6_PAYLOAD_FORGE_API.md`](docs/PHASE6_PAYLOAD_FORGE_API.md)。 ## echoforge-flipper-mastery 技能包 附带一个包含 6 项技能的 Claude 插件，具备深厚的 Flipper 协议专业知识 —— 为 Claude 提供第一手知识，使其在第一次尝试时就能编写出有效的 payload，而不是通过反复试错： | 技能 | 域 | | :---- | :----- | | `echoforge-duckyscript` | DuckyScript 1.0/3.0 语法，Flipper 扩展，规范模式 | | `echoforge-subghz` | KeeLoq / Princeton / CAME / Nice Flo / Somfy / Security+ / Holtek | | `echoforge-ir` | NEC / RC5 / RC6 / Sony SIRC / Pronto / Kaseikyo / Samsung | | `echoforge-nfc-rfid` | MIFARE Classic+Ultralight+DESFire / HID Prox / iClass / EM4100 / iButton | | `echoforge-hardware-debug` | JTAG / SWD / UART 引脚定义与协议参考 | | `echoforge-payload-defender` | 分析模式 —— 解释未知 payload 的作用 | 安装： ``` cd skills\echoforge-flipper-mastery claude plugin marketplace add . claude plugin install echoforge-flipper-mastery ``` ## DuckyScript linter `echoforge-ducky-lint` —— 唯一能识别 Flipper 方言的 DuckyScript linter（我们已经验证过）。 ``` echoforge-ducky-lint /path/to/payload.txt # human output echoforge-ducky-lint --format=json /path/... # JSON for CI echoforge-ducky-lint --format=github /path/... # GitHub annotations echoforge-ducky-lint --list-rules # browse the 22 rules ``` 涵盖三个严重级别的 22 条规则 —— 错误 (E001–E007)、警告 (W001–W011)、信息 (I001–I004)。可通过 Claude 调用 `payload_badusb_validate(strict=True)` 使用。经验证，规范的 Hak5 / Flipper / Momentum payload 可达到零警告通过。 ## 文档 | 文档 | 用途 | | :------- | :------ | | [`PHASE6_DECISIONS.md`](docs/PHASE6_DECISIONS.md) | 锁定的设计决策（操作员覆盖、风险级别映射、sidecar schema） | | [`PHASE6_PAYLOAD_FORGE_API.md`](docs/PHASE6_PAYLOAD_FORGE_API.md) | MCP 工具清单、schema、错误分类 | | [`PHASE6_CONTENT_SAFETY.md`](docs/PHASE6_CONTENT_SAFETY.md) | 内容安全威胁模型（第 6 阶段） | | [`PHASE6_REDTEAM_RESEARCH.md`](docs/PHASE6_REDTEAM_RESEARCH.md) | 54 项前沿攻击研究条目 —— 论文、CVE、POC | | [`PHASE6_PAYLOAD_RESEARCH.md`](docs/PHASE6_PAYLOAD_RESEARCH.md) | 用于库镜像的顶级 Flipper payload 仓库 | | [`PHASE6_SKILL_RESEARCH.md`](docs/PHASE6_SKILL_RESEARCH.md) | Claude 技能生态系统审计 | | [`PHASE6_CODE_REVIEW.md`](docs/PHASE6_CODE_REVIEW.md) | 第 6 阶段强制代码审查记录 | | [`DUCKY_LINTER_CODE_REVIEW.md`](docs/DUCKY_LINTER_CODE_REVIEW.md) | DuckyScript linter 代码审查记录 | | [`PHASE7_FINSTRIKE_THREAT_MODEL.md`](docs/PHASE7_FINSTRIKE_THREAT_MODEL.md) | 第 7 阶段 阶段（FinStrike C2）威胁模型 + 安全集成 | ## 路线图 | 阶段 | 状态 | 亮点 | | :---- | :----- | :--------- | | **1–3** 传输层 + RPC + 安全 | ✅ 已完成 | USB-CDC, Protobuf RPC, 71 项测试的安全基线 | | **4** Claude Agent SDK | ✅ 已完成 | 在 COM7 上验证了实时工具使用 | | **4.5** 加固 | ✅ 已完成 | Stale-RPC 修复，operator 模式审计，捕获了潜在的安全门控绕过 bug | | **5** Textual TUI | ⏸ 已降级 | 目前 CLI 是更合适的交互界面 | | **6** Payload 铸造 | ✅ 已完成 | 13 个工具，22 条规则 linter，385 项测试，两轮审查 | | **7** FinStrike (C2 + Flipper 作为投递载体) | 🔬 设计中 | 威胁模型已记录在磁盘；架构待定 | | **7+** 多步组合器 + 前沿模板 | 📋 已排队 | Atoms + chains + compiler，用于自然语言组合的 payload | ## 为什么设计很重要 大多数 Flipper 工具完全依赖于操作员的自律 —— 在架构上没有对审计、范围或问责的强制执行。3CH0F0RG3 扭转了这一点： - 您未批准的操作**无法**运行，即使是 Claude 提出的也不行 - 您批准的操作**必须**被审计，并在操作员模式下捕获准确的字节内容 - 物理执行（打字、发射）**始终**需要按住确认，无论风险分类如何 —— 物理层面的副作用是不可逆的 - 审计跟踪是**哈希链**的 —— 篡改会以提示信息的形式暴露，而不是默默损坏数据 这些都是严肃的红队框架（Sliver、Mythic、Havoc、Caldera）所提供的基础特性 —— 经过适配，以应对 Flipper 所开启的物理层切入点。 ## 授权 ## 许可证 **GPL-3.0-or-later。** 继承自上游的 [V3SP3R](https://github.com/elder-plinius/V3SP3R)（Android/Kotlin 移植版 —— 同样为 GPL-3.0）。与 Flipper 固件本身兼容。 ## 致谢 - **上游：** 由 elder-plinius 开发的 [V3SP3R](https://github.com/elder-plinius/V3SP3R) —— 最初的 Flipper Zero Android/Kotlin AI 控制器 - **构建工具：** 由 Anthropic 提供的 [Claude Agent SDK](https://github.com/anthropics/anthropic-sdk-python) - **架构灵感：** Sliver, Mythic, Havoc, Caldera - **硬件目标：** 运行 [Momentum 固件](https://momentum-fw.dev/)的 [Flipper Zero](https://flipperzero.one/)

由 Claude Code 构建。通过代码审查加固。为严肃的工作而生。

标签：AI大模型, BadUSB, Flipper Zero, NFC, payload生成, Python, RFID, Sub-GHz, 反取证, 安全评估, 数据展示, 无后门, 硬件安全, 硬件黑客, 红外线, 红队, 网络安全, 自动化攻击, 隐私保护