01rabbit/Phasmid

# Phasmid  Phasmid 是一个用于仅本地、感知胁迫存储的现场评估原型。 它是 Janus Eidolon System 的参考实现，这是一种双插槽本地存储架构，旨在将可见披露与受保护的本地状态分离开来，以应对设备扣押、强制访问和过度披露等实际风险。 Phasmid 是研究软件。它不能替代全盘加密、硬件支持的密钥存储、经过审计的机密数据处理系统，也不是应对强制披露的完整解决方案。 ## 它的功能 - 创建加密的 `vault.bin` 容器。 - 在内部双插槽容器模型中存储受保护的条目。 - 提供具有静默待机（`active` / `standby` / `sealed` / `dummy_disclosure`）、预配置的披露支持内容工作流和本地合理性检查的胁迫安全延迟架构。 - 使用基于 ORB 的对象图像匹配作为操作访问提示。 - 可以选择在特性标志后评估实验性的轻量级本地对象模型。 - 使用 AES-GCM 和 Argon2id 派生密钥对 payload 进行加密。 - 将本地访问密钥混合到恢复过程中，因此仅靠 `vault.bin` 是不够的。 - 支持正常访问和受限恢复行为。 - 提供 CLI 和本地 WebUI v2。 - 提供所有者控制的受限操作，可以清除本地状态。 - 包括用于减少元数据副本审查的元数据风险检查工作流。 - 元数据检测和归约为尽力而为的操作。 Phasmid 并不承诺完美的可否认性。它通过分离访问条件、本地状态、物理对象提示和受限恢复行为，在某些强制访问场景中减少操作损害。 ## 安全声明与非声明 Phasmid 区分了四个经常被混淆的概念： - 软件存在隐藏：Phasmid 不作此声明。 - 数据存在可否认性：部分的，且取决于场景。 - 受控披露：主要的项目声明。 - 感知胁迫的回退行为：操作目标。 Phasmid 声明： - 将受保护的本地状态与强制披露输出路径分离； - 基于密码短语对指定本地条目的受控披露； - 默认情况下仅在本地运行，WebUI 旨在用于 localhost 或直接连接的 USB gadget 访问； - 通过混合的本地密钥材料减少对仅 `vault.bin` 的依赖。 Phasmid 不声明： - 向能力强大的取证检查员隐藏软件的存在； - 在所有对手模型下具有完美的可否认性； - 在闪存介质上保证安全删除； - 抵御实时内存捕获、受损主机或键盘记录器； - 任何形式的取证豁免。 工具发现、存储库发现、进程日志、shell 历史记录和主机工件可能会削弱操作可否认性。发现 Phasmid 本身并不能证明存在其他未披露的数据，但它确实缩小了模糊范围，应将其视为操作风险。 ## 理念 Phasmid 遵循一个简单的规则：不撒谎，不说出不必要的真相。 界面应报告用户完成当前操作所需的信息，但不应透露内部的披露模型、存储结构、尝试顺序或受限的恢复行为。 诚实的界面。静默的结构。 Phasmid 只有在使用现场测试程序和扣押审查清单在目标硬件上进行验证后，才能被认为是经过现场验证的。 ## 何时使用 Phasmid 当问题不仅是文件加密，而是涉及强制访问、设备扣押、过度披露、元数据风险或本地 UI/日志泄露时，请使用 Phasmid。 如果您唯一的需求是在受信任的设备上进行普通文件加密，那么成熟的全盘加密系统、密码管理器或经过审计的文件加密工具可能更合适。 Phasmid 是专门设计的。它并非旨在成为加密文件的最简单方法。 ## 从原型到解决方案 Phasmid 不应通过声称更多来成为一个更强大的产品。它通过使其操作边界可重复、可测试且无聊来变得更强大。 从现场评估原型到操作解决方案的路径是： 1. 保持范围为仅限本地； 2. 保持界面在捕获时的静默； 3. 提供可重现的设备部署； 4. 完成目标硬件现场测试； 5. 完成扣押审查测试； 6. 记录每个版本的验证结果； 7. 仅发布由测试或文档记录的限制所涵盖的声明。 通过设置 `PHASMID_FIELD_MODE=1` 在 Field Mode 下运行 WebUI。Field Mode 减少了在捕获可见工作流中的正常暴露，但 Field Mode 不是一个安全边界。 在目标硬件上完成这些验证关卡之前，Phasmid 应被描述为现场评估原型。在这些关卡完成并记录后，它可以被描述为用于已验证部署条件的本地感知胁迫存储设备。 Raspberry Pi Zero 2 W 远程 SSH 现场测试工具的实现已在 GitHub issues `#89` 到 `#94` 中跟踪，可运行的脚本位于 `scripts/pi_zero2w/` 下。工具的可用性本身并不证明目标硬件验证已经完成。 ## 硬件外形边界 目前的 Phasmid 硬件是一个评估原型，而不是随时准备接受恶意检查的现场外形。 评估原型（当前）： - 基于 Raspberry Pi Zero 2 W 的构建； - 可能存在可见的摄像头模块和面向开发的布线； - 旨在用于开发、基准测试、协议验证和受控的操作员培训。 未来的现场外形（在当前代码库中未解决）： - 适合操作环境的无害外部外观； - 没有视觉上明显的摄像头/安全硬件信号； - 持有合理性和交互模式不会引起不必要的检查。 这种区分是操作上的，而不是外观上的。在 Raspberry Pi Zero 2 W 上的验证本身并不能解决恶意检查下的物理合理性问题。 ## 安全使用边界 Phasmid 旨在用于对敏感材料进行合法的本地保护，适用于设备扣押、强制访问或过度披露构成现实风险的情况。 它适用于： - 来源保护工作流， - 临时现场笔记， - 研究材料， - 旅行敏感文件， - 仅限本地的受控披露实验， - 防御性安全研究。 它不适用于： - 隐蔽通信， - 规避监视， - 绕过审查， - 远程擦除， - 远程解锁， - 攻击性行动， - 恶意软件存储， - 非法隐瞒， - 替代组织的机密数据系统。 ## 政府和组织使用边界 Phasmid 不是经过批准的机密数据处理基础设施。它不能替代组织记录管理系统、经过认证的加密产品、支持 HSM 的密钥管理、全盘加密或正式的机密数据程序。 在政府或组织环境中使用 Phasmid 必须遵守适用的法律、政策、记录保留要求和分类规则。Phasmid 旨在用于本地现场评估和减少危害工作流，而不是作为批准的记录系统的替代品。 ## 存储加密 (LUKS 层) Phasmid 支持用于本地容器和状态路径的可选 LUKS2 存储层。 该层可以通过加密底层块存储直到被映射和挂载，从而减少离线文件系统暴露。 它不能替代 Phasmid 仅限本地的姿态，也不能提供针对受损主机、实时内存捕获或键盘记录的保护。 该层中与擦除相关的操作仍为尽力而为。 有关威胁模型限制、操作程序和部署说明，请参见 [`docs/LUKS_LAYER.md`](docs/LUKS_LAYER.md)。该层不能替代受信平台上的全盘加密。 ## 审阅者说明和已知限制 Phasmid 是刻意狭窄的。 配置参考： - [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) — `PHASMID_*` 环境变量的权威参考 - 常见示例：`PHASMID_FIELD_MODE`, `PHASMID_MIN_PASSPHRASE_LENGTH`, `PHASMID_ACCESS_MAX_FAILURES`, `PHASMID_ACCESS_LOCKOUT_SECONDS` - 实验性对象门控：`PHASMID_EXPERIMENTAL_OBJECT_MODEL=1` 启用仅限本地的辅助对象门控路径。默认情况下禁用，不影响密钥派生。 - 模型配置是显式的。Phasmid 不会在正常启动或访问尝试期间自动下载模型。 实验性模型获取流程： ``` python3 scripts/fetch_object_model.py export PHASMID_OBJECT_MODEL_PATH="$PWD/models/object_gate/mobilenet_v2_1.0_224_feature_vector.tflite" export PHASMID_EXPERIMENTAL_OBJECT_MODEL=1 ``` 威胁模型和安全审查文档： - [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md) — 权威威胁模型（对手、资产、攻击面、威胁场景、非目标） - [`docs/COERCION_SAFE_DELAYING.md`](docs/COERCION_SAFE_DELAYING.md) — 胁迫安全延迟架构（待机和披露支持工作流） - `docs/THREAT_ANALYSIS_STRIDE.md` — 与威胁模型交叉引用的完整 STRIDE 分析 - [`docs/CLAIMS.md`](docs/CLAIMS.md) — 具有验证状态的项目声明清单 - [`docs/NON_CLAIMS.md`](docs/NON_CLAIMS.md) — 明确的非声明及其理由 - [`docs/KEY_LIFECYCLE.md`](docs/KEY_LIFECYCLE.md) — 密钥材料生命周期审计摘要和持久性边界 - [`SECURITY.md`](SECURITY.md) — 漏洞披露策略 - [`CONTRIBUTING.md`](CONTRIBUTING.md) — 贡献范围、声明和审查纪律 - [`docs/BUS_FACTOR.md`](docs/BUS_FACTOR.md) — 维护者连续性说明 - [`docs/REPRODUCIBLE_BUILDS.md`](docs/REPRODUCIBLE_BUILDS.md) — 可重现的发布审查工件程序 - [`docs/DEPENDENCIES.md`](docs/DEPENDENCIES.md) — 依赖项固定和更新策略 - [`docs/VERSIONING.md`](docs/VERSIONING.md) — 版本控制和兼容性策略 - [`docs/OBJECT_CUE_LIGHTWEIGHT_AI_REEVALUATION.md`](docs/OBJECT_CUE_LIGHTWEIGHT_AI_REEVALUATION.md) — 用于对象提示匹配的离线轻量级 AI 重新评估计划 - [`CHANGELOG.md`](CHANGELOG.md) — 发布历史和安全影响说明 操作审查和部署指南可在以下文档中找到： - `docs/SOURCE_SAFE_WORKFLOW.md` - `docs/SEIZURE_REVIEW_CHECKLIST.md` - `docs/FIELD_TEST_PROCEDURE.md` - `docs/REVIEW_VALIDATION_RECORD.md` - `docs/SOLUTION_READINESS_PLAN.md` - `docs/JANUS_EIDOLON_SYSTEM.md` - `docs/PHASMID_ARCHITECTURE.md` - `docs/OPERATIONS.md` - `docs/RESTRICTED_ACTIONS.md` - `docs/STATE_RECOVERY.md` 针对 Raspberry Pi Zero 2 W 的目标硬件验证工作流实现已在 GitHub issues `#89` 到 `#94` 中跟踪。在结果记录到 `docs/REVIEW_VALIDATION_RECORD.md` 之前，验证仍视为未完成。 本 README 是权威设备部署指南和审查工作流的一部分。发布审查工件由 CI 流水线生成以支持审查。这不是经过验证的加密模块认证。 ### 发布审查工件 (Issue #16) 使用校验和清单和 CycloneDX SBOM 生成本地审查捆绑包： ``` python3 scripts/generate_release_artifacts.py --output-dir release/local --archive ``` 如果您需要用于发布审查的签名清单，请提供 Ed25519 私钥 PEM： ``` python3 scripts/generate_release_artifacts.py \ --output-dir release/local \ --archive \ --signing-key ./release-signing-private.pem ``` 当启用签名时，这将写入 `MANIFEST.sha256`、`sbom.cyclonedx.json`、`release-summary.json` 和 `MANIFEST.sha256.sig`。 Phasmid 的非声明维护在： - [`docs/NON_CLAIMS.md`](docs/NON_CLAIMS.md) ## 存储库布局 ``` . ├── main.py # Local CLI launcher ├── src/phasmid/ # Application package │ ├── cli.py # CLI entry point — routes to TUI by default │ ├── vault_core.py │ ├── ai_gate.py │ ├── web_server.py │ ├── tui/ # TUI Operator Console (textual) │ │ ├── app.py │ │ ├── banner.py │ │ ├── theme.py │ │ ├── screens/ # Home, Audit, Doctor, Guided, Inspect, ... │ │ └── widgets/ # VesselTable, VesselSummaryPanel, EventLog, WarningBox │ ├── services/ # Service layer (vessel, doctor, audit, guided, ...) │ ├── models/ # Data models (VesselMeta, DoctorResult, AuditReport, ...) │ └── templates/ ├── docs/ # Specification and threat model ├── scripts/ # Utility scripts ├── tests/ # Unit tests └── requirements.txt ``` 运行时文件如 `vault.bin`、`.state/` 和审计日志被 Git 故意忽略。 ## 安装 对于常规的存储库本地使用，请从以下步骤开始： ``` ./phasmid ``` 仓库包装器在首次使用时如果需要会创建 `.venv`，如果本地 `phasmid` 入口点缺失，它会将依赖项 安装到该环境中，然后启动 TUI。这是在此存储库中首次运行和后续运行 的推荐路径。 如果您需要手动管理虚拟环境，请使用： ``` python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt pip install -e . ``` 该手动路径将本地 `phasmid` 命令安装到活动的虚拟 环境中，以便 `phasmid --help` 和 CLI 子命令能如文档所述那样工作。 ### Raspberry Pi 引导 (Zero 2 W) 要获得可重现的 Raspberry Pi 设置（Bookworm/Bullseye 级别，USB gadget 操作，Picamera2/libcamera），请使用： #### 首次运行（全新安装） ``` ./scripts/bootstrap_pi.sh source .venv/bin/activate ./scripts/validate_pi_environment.sh ``` `bootstrap_pi.sh` 使用 `--system-site-packages` 创建 `.venv`，以便 apt 提供的 `python3-picamera2`/`python3-libcamera` 仍可从 virtualenv 中导入。 这在 Raspberry Pi 部署中是必需的，因为 Picamera2 是通过 受支持硬件栈中的 OS 包安装的。 #### 后续运行（正常操作） ``` source .venv/bin/activate phasmid ``` ## TUI 操作员控制台 ### 什么是 Vessel？ 在 Phasmid 中，**Vessel** 是一个无头的、可否认的容器文件。它承载一个或多个披露面，而不暴露元数据、魔术字节或明显的保管库结构。 ### 启动 TUI ``` ./phasmid ``` 不带参数运行 `phasmid` 将打开主操作员控制台。 ``` ┌─ PHASMID : JANUS EIDOLON SYSTEM ───────────────────────────┐ │ coercion-aware deniable storage │ │ one vessel / multiple faces / no confession │ ├───────────────────────┬─────────────────────────────────────┤ │ Vessels │ Vessel Summary │ │ Deniable containers │ │ │ │ Name travel.vessel │ │ > travel.vessel │ Size 512.0 MiB │ │ archive.vessel │ Header absent │ │ field-notes.vessel │ Magic Bytes absent │ │ │ Faces unknown │ │ │ Posture operational │ ├───────────────────────┴─────────────────────────────────────┤ │ o Open c Create i Inspect f Faces g Guided a Audit … q │ └─────────────────────────────────────────────────────────────┘ ``` ### T 命令 | 命令 | 描述 | |---|---| | `phasmid` | 打开主操作员控制台 | | `phasmid open ` | 打开一个 Vessel | | `phasmid create ` | 创建一个新的 Vessel | | `phasmid inspect ` | 检查一个 Vessel | | `phasmid guided` | 打开向导工作流 | | `phasmid audit` | 打开审计视图 | | `phasmid doctor` | 运行 Doctor 检查 | | `phasmid doctor --no-tui` | 在不带 TUI 的情况下打印 Doctor 输出 | ### 键盘快捷键 | 按键 | 操作 | |---|---| | `o` | 打开选定的 Vessel | | `c` | 创建新的 Vessel | | `i` | 检查选定的 Vessel | | `f` | 管理 Faces | | `g` | 向导工作流 | | `a` | 审计视图 | | `d` | Doctor | | `s` | 设置 | | `?` | 帮助 / 关于 | | `q` | 退出 | ### 向导工作流 向导工作流是用于教育、演示和操作员入职的循序渐进的交互式说明。它们可从主控制台 (`g`) 或直接访问： ``` phasmid guided ``` 可用的工作流： - **强制披露演练** — 逐步完成强制披露场景。 - **无头 Vessel 检查** — 查看外部观察者在检查 Vessel 时会发现什么。 - **多重披露面** — 演练多重披露面的概念。 - **操作员安全检查清单** — 审查操作控制和已知风险。 ### 审计视图 审计视图显示系统位置、加密控制、操作控制、日志策略、已知限制和非声明。它的存在是为了让安全研究人员、与政府相关的评估人员和机构利益相关者能够审查 Phasmid。 ``` phasmid audit ``` ### Doctor 视图 Doctor 视图在操作员的环境上运行结构化的本地风险检查。 ``` phasmid doctor ``` 检查包括：配置目录权限、shell 历史记录风险、临时目录策略、安全随机性可用性、swap 状态（尽力而为）、终端回滚通知和调试日志状态。 ### 安全限制 Phasmid 是一个**研究级原型**。它不声称： - 取证上不可验证的可否认性 - 抗胁迫的操作 - 无法检测的存储 - 不可破解的加密 - 保证安全的操作 可否认性是程序性的，并取决于操作环境。主机受损可能会破坏机密性。OS 工件可能会暴露使用情况。抗胁迫性并非绝对。 变砖和受限清除操作是逻辑访问破坏机制（密钥路径失效加尽力而为的覆盖）。它们不是闪存上的物理介质清理保证。 ## CLI 用法 初始化一个容器： ``` phasmid init ``` 存储一个文件： ``` phasmid store --entry a --file path/to/file phasmid store --entry b --file path/to/file ``` CLI 保留了一个紧凑的条目选择器。WebUI 使用基于中性条目的语言，在正常操作期间不会暴露内部存储模型。 检索一个文件： ``` phasmid retrieve --out output.bin ``` 清除本地访问路径： ``` phasmid brick ``` 本地操作检查： ``` phasmid verify-state phasmid verify-audit-log phasmid doctor phasmid export-redacted-log --out review-events.jsonl ``` 这些命令报告中立的就绪状态和审计审查状态，而不在正常输出中打印本地路径。 新的本地状态检查使用类型化的状态存储辅助程序进行原子写入、严格限制的权限和转换验证。现有的保管库和对象提示状态文件仍由其所属模块管理，直到有文档记录的状态迁移替换它们。 当启用审计日志记录时，新的审计记录包含用于本地审查的序列和完整性字段。审计日志记录默认保持禁用，因为审计记录可能会创建额外的本地元数据。 ## WebUI v2 本地 WebUI 通过 TUI 操作员控制台直接管理（按 `w` 以启动/停止）。这是推荐的方法，因为它包含一个**自动终止 计时器**，如果在 TUI 中 不活动达到 10 分钟，它会自动终止 WebUI。 要手动启动 WebUI： ``` python -m uvicorn phasmid.web_server:app --host 0.0.0.0 --port 8000 ``` 当使用 USB gadget Ethernet 时，请从笔记本电脑打开 `http://:8000/`。 WebUI v2 使用基于中性条目的术语。普通屏幕不显示内部存储标签、检索顺序或受限的本地状态行为。 通用 WebUI/API 措辞在可行之处被集中化，以便术语检查可以一致地审计捕获可见的消息。 ## 测试命令 ``` python3 -m unittest discover -s tests python3 -m black --check src tests scripts python3 -m bandit -r src ``` 静态检查命令： ``` python3 -m black --check src tests scripts python3 -m bandit -r src ``` 覆盖率命令： ``` python3 -m coverage run --source=src -m unittest discover -s tests python3 -m coverage report -m ``` 替代的短覆盖率命令： ``` coverage run -m unittest discover -s tests coverage report ``` 发布审查工件由 CI 流水线生成，并支持对当前分支的审查。 通过自动化测试并不能证明现场安全。它们仅验证预期的本地行为和回归边界。 ## 许可证 Phasmid 在 Apache License, Version 2.0 下授权。参见 [LICENSE](LICENSE)。 第三方依赖许可证列在 [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) 中。 Phasmid 是研究软件。该许可证授予软件使用权；它不意味着操作批准、现场验证、机密数据处理批准或对任何特定部署的适用性。

标签：AES-GCM, Argon2id, HTTP工具, JSONLines, PE 加载器, Streamlit, 人工智能安全, 前端WebUI, 双槽存储, 反胁迫存储, 可否认加密, 合规性, 子域名变形, 密码学, 库, 应急响应, 手动系统调用, 数据泄露防护, 数据销毁, 文件容器, 本地存储, 磁盘加密, 网络安全, 网络探测, 访问控制, 逆向工具, 防御性安全, 防篡改, 隐写术, 隐私保护, 隐蔽系统, 零信任