Nour833/Fcoin

FCOIN 是一个离线优先的工具包，用于检查和安全维护您拥有或获得明确授权测试的 MIFARE Classic 卡。它用结构化的包、确定性分析引擎、不可变快照、精确的访问条件解码、精准的变更计划、防篡改写入日志、写入后验证以及恢复规划，取代了原有的单脚本原型。 FCOIN 不会静默写入卡片，不会使用 `sudo` 安装软件包，不会上传 dump，也不会将启发式猜测视为事实。 ## 交互式控制中心 不带参数运行 FCOIN： ``` fcoin ``` 这将打开一个色彩丰富的全屏仪表板，而不是直接打印原始命令帮助。导航方式如下： - `↑` / `↓` 或 `j` / `k` 进行移动。 - `ENTER` 打开所选工作流。 - 数字键用于即时快捷操作。 - `b` 或 `ESC` 返回上一级。 - `q` 干净地退出。 仪表板提供以下引导式菜单： - 读卡器和已导入 dump 的备份。 - 实体卡检测（包含自动备份）、已保存备份的浏览、验证、比较和证据问题。 - 报告、转换、推断和清单管理。 - 自有实验室配置文件（profile）和值计划工作流。 - 事务准备、验证、恢复、历史记录和日志。 文件提示会自动列出当前目录下的兼容文件，并始终提供手动输入路径的选项。会话提示会显示 UID、事务状态、卡类型和会话 ID。 在终端中使用时，不完整的直接命令也会进入相应的向导： ``` fcoin inspect fcoin compare fcoin backup ``` 完全指定的命令保持不变，适用于脚本和自动化。同时也支持友好的别名，如 `fcoin --inspect` 和 `fcoin --doctor`。 ## 2.0 版本有哪些变更 | 领域 | 功能 | |---|---| | 备份 | 双重读取硬件采集、不可变快照、SHA-256 身份标识、`0600` 权限文件 | | 协议 | Mini、Classic 1K 和 Classic 4K 几何结构 | | 完整性 | 精确的值块冗余、BCC 指示、所有访问位补码 | | 分析 | 值块、文本、UTF-16、时间戳、重复块、熵、CRC 候选 | | 情报 | 跨 dump 推断、受控比较、基于证据的问题 | | 编辑 | 绑定 UID 的自有实验室配置文件、精确的十进制数学计算、感知镜像的精准计划 | | 事务 | 在执行外部块写入之前写入持久化的哈希链日志 | | 验证 | 目标字节验证，加上对每个附带块变更的检测 | | 恢复 | 从不可变可信快照生成的还原计划 | | 报告 | 带样式的终端、JSON 输出、自包含的 HTML 报告 | | 格式 | 二进制 MFD 和 Mifare Classic Tool 文本 dump 的相互转换 | | 操作 | 清单、历史记录、读卡器诊断、对自动化友好的 JSON | ## 安全边界 FCOIN 适用于： - 备份您拥有的卡片。 - 从意外的数据块损坏中恢复您拥有的卡片。 - 实验室卡片和合成测试装置。 - 授权的安全研究和格式逆向工程。 - 比较受控实验中的已知前态和已知后态。 可写的值配置文件必须： - 将 `lab_only` 设置为 `true`。 - 绑定到一个精确的 UID 前缀。 - 明确列出可写字段和块。 - 定义允许的最小值和最大值。 - 接收 CLI 要求的确切授权短语。 FCOIN 始终拒绝自动更改制造商块 0 和扇区块。它不提供不受限制的第三方支付、交通、访问控制或存储值更改。 ## 工作流 ``` ┌─────────────┐ │ ACQUIRE ×2 │ Two reads must match └──────┬──────┘ ▼ ┌───────────────────┐ │ IMMUTABLE SNAPSHOT│ SHA-256 + 0600 permissions └─────────┬─────────┘ ▼ ┌─────────────────────────┐ │ VALIDATE · INSPECT · DIFF│ Deterministic evidence └────────────┬────────────┘ ▼ ┌─────────────────────────┐ │ UID-BOUND CHANGE PLAN │ Exact blocks and preconditions └────────────┬────────────┘ ▼ ┌─────────────────────────┐ │ DURABLE WRITE JOURNAL │ Pending event persisted first └────────────┬────────────┘ ▼ ┌─────────────────────────┐ │ EXTERNAL BLOCK-WISE WRITE│ MCT or another authorized writer └────────────┬────────────┘ ▼ ┌─────────────────────────┐ │ READ ×2 · VERIFY ALL │ Target + collateral comparison └───────┬─────────┬───────┘ │ pass │ fail ▼ ▼ VERIFIED RECOVERY PLAN ``` ## 安装 FCOIN 本身没有第三方 Python 运行时依赖。 ``` git clone https://github.com/Nour833/Fcoin.git cd Fcoin python3 -m pip install -e . fcoin ``` 它也可以直接从代码检出（checkout）处运行： ``` ./fcoin.py ``` 硬件采集是可选的。在 Linux 上，需要时通过您的操作系统包管理器安装以下工具： - `mfoc`，用于授权的 MIFARE Classic 采集。 - `libnfc` 工具，用于 `nfc-list` 诊断。 FCOIN 会报告缺失的工具，但绝不会调用 `sudo` 或更改系统。 ## 快速开始 ### 1. 诊断读卡器 ``` fcoin doctor ``` ### 2. 创建不可变备份 使用 `mfoc` 采集两次；只有在两次读取匹配时才会接受快照： ``` fcoin backup --reader ``` 使用可选的、由用户管理的密钥字典： ``` fcoin backup --reader --keys ~/.config/fcoin/owned-lab.keys ``` 导入现有的 dump： ``` fcoin backup --from-dump card.mfd ``` 要求两个独立采集的导入相互匹配： ``` fcoin backup \ --from-dump read-1.mfd \ --confirmation read-2.mfd ``` 分析可以使用单个导入的 dump。但任何可写计划都需要一个基于两次相同的独立读取的会话。 快照存储在以下位置： ``` ~/.local/share/fcoin/sessions/-/ ``` 使用 `FCOIN_HOME` 或 `--home` 覆盖该位置。 ### 3. 检查和验证 打开引导式的检查（Inspect）源菜单： ``` fcoin inspect ``` 该菜单提供： - **立即读取卡片 + 自动备份：** 读取实体卡两次，要求两个镜像相匹配，创建不可变的会话备份，然后进行分析。 - **打开已保存的 FCOIN 备份：** 按 UID、状态、卡类型和会话 ID 浏览现有会话。 - **打开 dump 文件：** 从磁盘选择 MFD、dump 或二进制文件。 直接从 CLI 使用相同的源： ``` # Live card：两次读取，自动 secure backup，然后执行 inspection fcoin inspect --reader # 带有 owned key dictionary 的 Live card fcoin inspect --reader --keys ~/.config/fcoin/owned-lab.keys # 现有的 immutable backup fcoin inspect --session # 普通文件 fcoin inspect card.mfd ``` 实时检查将验证过的镜像存储在常规会话目录下，并在显示分析结果之前打印出会话 ID 和备份路径。 直接验证或检查文件： ``` fcoin validate card.mfd fcoin inspect card.mfd fcoin inspect card.mfd --all fcoin inspect card.mfd --json ``` 分析器会分开报告协议事实和候选项。结构有效的值块是事实；而将该值称为余额则需要可信的配置文件或受控证据。 默认的终端视图会隐藏常规的空块和有效的扇区块，以便重要的发现保持可读性。使用 `--all` 查看完整的取证表。 ### 4. 比较受控状态 ``` fcoin compare before.mfd after.mfd fcoin compare before.mfd after.mfd --json ``` 差异（diff）内容包括： - 更改的块和扇区。 - 确切更改的字节偏移量。 - 更改的位数。 - 更改前后的十六进制值。 - 当两种状态在结构上均有效时的值块解释。 ### 5. 从多次观察中推断结构 ``` fcoin infer baseline.mfd event-1.mfd event-2.mfd \ --output inference.json ``` 所有样本必须使用相同的卡几何结构和 UID 前缀。FCOIN 会识别每个样本中的有效值块，并记录哪些值发生了变化。 ### 6. 提出基于证据的问题 ``` fcoin ask card.mfd "what value blocks were found?" fcoin ask card.mfd "is anything corrupt?" fcoin ask card.mfd "show possible timestamps" ``` 该助手是确定性的、完全离线的，且不会将卡片数据发送到任何地方。 ### 7. 生成报告 ``` fcoin report card.mfd --format html --output report.html fcoin report card.mfd --format json --output report.json ``` HTML 报告是自包含的，可以与案件或实验室记录本一起归档。 ## MCT 转换 将完整的二进制 MFD dump 转换为 Mifare Classic Tool 文本格式： ``` fcoin convert card.mfd --from mfd --to mct --output card.mct ``` 将完整的 MCT 文本 dump 转换回二进制： ``` fcoin convert card.mct --from mct --to mfd --output card.mfd ``` 不完整的扇区图会被拒绝，因为它们不能作为可信的恢复快照。 ## 针对自有实验室卡的受保护值编辑 FCOIN 不会仅仅因为启发式判断“看起来像钱包”就去编辑某个值。可写操作需要一个经过审查且绑定到确切自有卡片的配置文件。 ### 1. 查找结构候选 ``` fcoin inspect owned-lab.mfd fcoin infer lab-before.mfd lab-after-controlled-event.mfd ``` ### 2. 创建配置文件模板 ``` fcoin profile-init owned-lab.mfd \ --block 4 \ --mirror 5 \ --output owned-lab.profile.json ``` 审查生成的文件： ``` { "name": "owned-lab-card", "description": "UID-bound profile for an owned laboratory card.", "lab_only": true, "allowed_uids": ["DEADBEEF"], "fields": [ { "name": "test_value", "type": "value_block", "block": 4, "mirrors": [5], "scale": 100, "unit": "test credits", "minimum": "0.00", "maximum": "100.00", "writable": true } ] } ``` ### 3. 创建精准计划 查找会话 ID： ``` fcoin history ``` 创建计划： ``` fcoin plan-value \ --session 20260622T120000.000000Z-DEADBEEF \ --profile owned-lab.profile.json \ --field test_value \ --value 50.00 \ --authorize "I OWN THIS LAB CARD" ``` 在接受计划之前，FCOIN 会验证： - 配置文件的 UID 与快照完全匹配。 - 每个主块和镜像块都是完整有效的 MIFARE 值块。 - 所有镜像值一致。 - 访问条件冗余有效。 - 该块没有被禁止写入。 - 请求的十进制数在配置的精度下是精确的。 - 编码后的有符号 32 位值在范围内。 - 该值在配置文件限制的范围内。 - 编码后的地址字节得到保留。 - 没有针对制造商块或扇区块的操作。 ### 4. 预览离线结果 ``` fcoin apply-plan \ ~/.local/share/fcoin/sessions//before.mfd \ ~/.local/share/fcoin/sessions//value-plan.json \ --output preview.mfd fcoin compare \ ~/.local/share/fcoin/sessions//before.mfd \ preview.mfd ``` 只有计划内的块允许存在差异。 ### 5. 准备写入事务 ``` fcoin prepare-write \ --session \ --plan ~/.local/share/fcoin/sessions//value-plan.json ``` 这将持久化创建： ``` write-plan.json Integrity-hashed plan intended.mfd Exact expected complete image write-instructions.json Minimal block/payload list journal.jsonl Append-only hash-chained event log ``` 在任何外部写入发生之前，每个块都会被记录为 `pending`。使用 MCT 或其他授权的按块写入工具，仅写入列出的数据块。 ### 6. 写入后验证 独立读取卡片两次，并提供两次匹配的采集结果： ``` fcoin verify-write \ --session \ --observed after-1.mfd \ --confirmation after-2.mfd ``` 或者采集两次相匹配的写入后读取： ``` fcoin verify-write --session --reader ``` 在以下情况下验证将失败： - UID 不同。 - 任何目标块与计划不同。 - 任何无关的块发生了改变。 - 最终的完整镜像与 `intended.mfd` 不同。 - 日志哈希链损坏。 ## 中断或损坏后的恢复 如果验证失败，请采集当前卡片并生成还原计划： ``` fcoin recover \ --session \ --current current-card.mfd \ --authorize "RESTORE MY OWN CARD" ``` 恢复计划将从 `before.mfd` 还原确切的数据块字节。当制造商块 0 或扇区块不同时，FCOIN 会拒绝自动恢复，因为更改密钥或访问条件需要单独的专门流程。 离线应用并检查恢复计划： ``` fcoin apply-plan \ current-card.mfd \ ~/.local/share/fcoin/sessions//recovery-plan.json \ --output recovery-preview.mfd fcoin compare current-card.mfd recovery-preview.mfd ``` 然后使用生成的块 payload 和授权的按块写入工具，并再次进行验证。 ## 事务日志 显示并加密验证事件链： ``` fcoin journal --session ``` 典型事件： ``` transaction_prepared block_pending block_pending block_verified block_verified transaction_verified ``` 失败的会话会保留观察到的镜像、块级别的失败事件、附带变更证据以及恢复计划引用。 ## 会话布局 ``` sessions/-/ ├── metadata.json ├── before.mfd ├── confirmation.mfd ├── acquisition.log ├── value-plan.json ├── write-plan.json ├── intended.mfd ├── write-instructions.json ├── journal.jsonl ├── after.mfd └── recovery-plan.json ``` 敏感工件使用权限模式 `0600`；会话目录使用 `0700`。Dump、密钥、会话、报告和计划会被 Git 忽略。 ## 命令参考 | 命令 | 用途 | |---|---| | `doctor` | 检查 `mfoc`、libnfc 工具和读卡器的可见性 | | `backup` | 创建不可变的导入或双重读取快照 | | `validate` | 验证几何结构、dump 大小、BCC 指示和访问位 | | `inspect` | 检查文件、已保存的备份或带有自动备份的实体卡 | | `compare` | 生成块级、字节级和位级的差异对比 | | `infer` | 关联受控样本之间的结构化值块 | | `ask` | 查询确定性分析证据 | | `report` | 创建 JSON 或自包含的 HTML 报告 | | `convert` | 转换完整的 MFD 和 MCT dump | | `inventory` | 递归或非递归地为 dump 文件建立索引 | | `history` | 列出快照和写入会话的状态 | | `profile-init` | 创建绑定确切 UID 的自有实验室配置文件模板 | | `plan-value` | 构建带有完整性哈希的精准值计划 | | `apply-plan` | 将计划应用于离线镜像并进行验证 | | `prepare-write` | 持久化预期状态、payload 和待处理的日志事件 | | `verify-write` | 验证目标块并检测附带变更 | | `recover` | 从不可变快照生成还原操作 | | `journal` | 验证并显示事务哈希链 | 每个面向分析的命令在适当的情况下都支持纯终端输出或 JSON。设置 `NO_COLOR=1` 或使用 `--no-color` 可获得非 ANSI 输出。 当您明确需要完整的非交互式 argparse 参考而不是仪表板时，请使用 `fcoin --help`。 ## 架构 ``` src/fcoin/ ├── geometry.py Mini / 1K / 4K memory mapping ├── access.py Access-bit and permission decoding ├── value.py Exact signed value-block codec ├── dump.py Validated immutable card images ├── acquisition.py mfoc and libnfc diagnostics adapters ├── analysis.py Explainable deterministic detectors ├── intelligence.py Cross-dump inference and evidence questions ├── compare.py Exact block, byte, and bit comparisons ├── formats.py MFD ↔ MCT conversion ├── profiles.py UID-bound laboratory schemas ├── plans.py Integrity-hashed surgical and recovery plans ├── journal.py Durable hash-chained operation records ├── transactions.py Prepare, verify, and recover workflows ├── storage.py Secure immutable session storage ├── reporting.py JSON and HTML reports ├── ui.py Dependency-free styled terminal interface └── cli.py Command orchestration ``` 有关实现细节，请参阅[架构](docs/ARCHITECTURE.md)和[配置文件 schemadocs/PROFILE_SCHEMA.md)。 ## 开发 运行完整的标准库测试套件： ``` PYTHONPATH=src python3 -m unittest discover -v python3 -m compileall -q src tests fcoin.py ``` 该测试套件涵盖： - Mini、1K 和 4K 几何结构。 - 每个访问条件三元组。 - 损坏的冗余访问位。 - 有符号值块的边界。 - 每个地址冗余字节。 - 精确的十进制缩放。 - MFD/MCT 往返转换。 - 可解释的检测和比较。 - UID/配置文件授权。 - 精准的附带保护。 - 计划哈希篡改。 - 快照权限和不匹配的读取。 - 日志篡改。 - 成功的验证和失败会话的恢复。 ## 重要限制 - 没有任何软件能够保证从物理卡故障或中断的扇区块更改中恢复。 - `mfoc` 仅在其攻击假设成立且至少满足一个可用的已知密钥的情况下才有效。 - 有效的 MIFARE 值块并不能证明该值代表金钱。 - 制造商的 BCC 指示是基于四字节 UID 前缀布局的；其他 UID 布局可能会将其显示为变体。 - FCOIN 会准备并验证按块写入，但不会隐藏外部写入工具的行为。请确认您选择的工具仅写入了列出的块。 ## 负责任的披露 请勿发布卡片 dump、密钥、个人身份数据或存在漏洞的在线系统的可重现细节。报告指南请参阅 [SECURITY.md](SECURITY.md)。 ## 许可证 MIT。请参阅 [LICENSE](LICENSE)。

标签：DOS头擦除, Homebrew安装, MIFARE Classic, NFC, Python, 多模态安全, 密码破解, 数字取证, 无后门, 智能卡, 自动化脚本