Adilx05/StegoForge
GitHub: Adilx05/StegoForge
一款模块化的 .NET 隐写术平台，支持在图像和音频文件中嵌入、提取隐藏数据，提供 CLI 和 WPF 双界面。
Stars: 0 | Forks: 0
# StegoForge
_最后核对源码日期：2026-03-07 (`0fd7c07`)。_
StegoForge 是一个模块化的 .NET 隐写术平台，用于跨图像和音频载体的可靠、可测试的嵌入与提取工作流。该仓库目前包含可工作的应用服务、生产级格式处理器 (PNG/BMP/WAV)、可用的 CLI 界面、可用的 WPF 桌面工作流以及多项目测试套件。
## 项目概览
该解决方案围绕清晰的边界进行组织：
- **核心契约 (`StegoForge.Core`)**：共享模型、服务抽象和错误契约。
- **应用层 (`StegoForge.Application`)**：用于嵌入/提取/容量/信息查询及策略验证的编排服务。
- **提供者实现**：
- 格式 (`StegoForge.Formats`)
- 加密 (`StegoForge.Crypto`)
- 压缩 (`StegoForge.Compression`)
- 基础设施 (`StegoForge.Infrastructure`)
- **交付应用**：CLI (`StegoForge.Cli`) 和桌面 GUI (`StegoForge.Wpf`)。
- **测试**：单元、集成、CLI 和 WPF 测试项目。
这种结构允许添加新的格式/提供者，而无需将传输/UI 逻辑与隐写术内部细节耦合。
## 支持的格式（当前）
目前已实现并接入嵌入/提取/容量/信息流程：
- PNG (`png-lsb-v1`, `PngLsbFormatHandler`)
- BMP (`bmp-lsb-v1`, `BmpLsbFormatHandler`)
- WAV (`wav-lsb-v1`, `WavLsbFormatHandler`)
这些处理器在 `src/StegoForge.Formats/FormatServiceCollectionExtensions.cs` 中注册，并由 `tests/StegoForge.Tests.Unit/` 和 `tests/StegoForge.Tests.Integration/` 中的单元测试和集成测试覆盖。
未来的格式扩展仍记录在 `docs/roadmap.md` 中。
## 架构概要
采用分层架构：
1. **UI/入口点** (CLI/WPF) 收集用户输入并显示结果。
2. **应用服务** 验证请求并协调编排。
3. **核心抽象/模型** 定义嵌入/提取/容量/信息契约。
4. **提供者实现** (格式/加密/压缩/基础设施) 执行载荷处理和载体字节操作。
参见：
- `docs/architecture.md` 了解组件级详情。
- `docs/payload-format.md` 了解载荷信封结构和版本控制。
## 版本控制基础
StegoForge 现在将 **MinVer** 作为所有项目中语义版本解析的唯一来源。
- 带前缀 `v` 的标签驱动官方版本（例如 `v1.2.0` 或 `v1.3.0-beta.1`）。
- `Version` 根据 `$(MinVerVersion)` 设置，以保持包/显示的一致性。
- `AssemblyVersion` 特意稳定为 `Major.Minor.0.0`，以减少程序集绑定冲突。
- `FileVersion` 是数字型的，映射为 `Major.Minor.Patch.0`，用于 Windows 文件元数据。
- `InformationalVersion` 设置为解析后的语义 `Version`，用于运行时显示界面。
- `AssemblyVersion`/`FileVersion` 是通过解析 `Version` (`X.Y.Z`) 派生的，以便即使在早期评估中 MinVer 组件属性不可用时，也能保持 WPF/WindowsDesktop 构建的稳定性。
在本地构建时 **如果没有匹配的发布标签**，MinVer 会输出一个合理的预发布/开发版本（使用默认的预发布标识符 `alpha.0`），以便贡献者无需手动编辑版本即可进行构建和测试。
## 构建前提条件
- .NET SDK **10.0.100**（固定在 `global.json` 中；CI 使用 `10.0.x` 并启用了预发布功能）。
- Git。
- 构建/运行 WPF (`src/StegoForge.Wpf`) 和 WPF 测试需要 **Windows**。
## 贡献者快速入门
有关完整的贡献流程和策略要求，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 网站文档和部署
基于 Astro 的项目网站位于 [`website/`](website/)。有关本地开发、内容编辑（英雄区/功能/路线图/链接）以及部署/基础路径详情，请参阅 [`website/README.md`](website/README.md)。
GitHub Pages 部署由 [`.github/workflows/pages.yml`](.github/workflows/pages.yml) 处理，该工作流从 `actions/configure-pages` 设置 `BASE_PATH`，以便生产构建自动使用正确的仓库子路径。对于自定义域，请设置 `BASE_PATH=/`。
从仓库根目录运行。
### 仅 CLI / 核心（跨平台）
此代码块与 CI `core-cli` 使用的还原/构建/测试流程相同。
```
# 恢复
dotnet restore src/StegoForge.Core/StegoForge.Core.csproj
dotnet restore src/StegoForge.Application/StegoForge.Application.csproj
dotnet restore src/StegoForge.Cli/StegoForge.Cli.csproj
dotnet restore tests/StegoForge.Tests.Unit/StegoForge.Tests.Unit.csproj
dotnet restore tests/StegoForge.Tests.Integration/StegoForge.Tests.Integration.csproj
dotnet restore tests/StegoForge.Tests.Cli/StegoForge.Tests.Cli.csproj
# 构建
dotnet build src/StegoForge.Core/StegoForge.Core.csproj --configuration Release --no-restore
dotnet build src/StegoForge.Application/StegoForge.Application.csproj --configuration Release --no-restore
dotnet build src/StegoForge.Cli/StegoForge.Cli.csproj --configuration Release --no-restore
dotnet build tests/StegoForge.Tests.Unit/StegoForge.Tests.Unit.csproj --configuration Release --no-restore
dotnet build tests/StegoForge.Tests.Integration/StegoForge.Tests.Integration.csproj --configuration Release --no-restore
dotnet build tests/StegoForge.Tests.Cli/StegoForge.Tests.Cli.csproj --configuration Release --no-restore
# 测试
dotnet test tests/StegoForge.Tests.Unit/StegoForge.Tests.Unit.csproj --configuration Release --no-build
dotnet test tests/StegoForge.Tests.Integration/StegoForge.Tests.Integration.csproj --configuration Release --no-build
dotnet test tests/StegoForge.Tests.Cli/StegoForge.Tests.Cli.csproj --configuration Release --no-build
```
### 仅 WPF（仅限 Windows）
此代码块与 CI `wpf` 使用的还原/构建/测试流程相同。
```
# 恢复
dotnet restore src/StegoForge.Wpf/StegoForge.Wpf.csproj
dotnet restore tests/StegoForge.Tests.Wpf/StegoForge.Tests.Wpf.csproj
# 构建
dotnet build src/StegoForge.Wpf/StegoForge.Wpf.csproj --configuration Release --no-restore
dotnet build tests/StegoForge.Tests.Wpf/StegoForge.Tests.Wpf.csproj --configuration Release --no-restore
# 测试
dotnet test tests/StegoForge.Tests.Wpf/StegoForge.Tests.Wpf.csproj --configuration Release --no-build
```
### 完整解决方案（仅限 Windows）
`StegoForge.sln` 包含 WPF 项目/测试，因此请在 Windows 上使用此选项。
```
dotnet restore StegoForge.sln
dotnet build StegoForge.sln --configuration Release
dotnet test StegoForge.sln --configuration Release
```
## CI/发布命令映射
| 本地命令集 | 工作流映射 |
| --- | --- |
| 上方的 CLI/核心 还原/构建/测试代码块 | `.github/workflows/ci.yml` → `core-cli` (`Restore core/CLI projects`, `Build core/CLI projects`, `Test core/CLI projects`) |
| 上方的 WPF 还原/构建/测试代码块 | `.github/workflows/ci.yml` → `wpf` (`Restore WPF projects`, `Build WPF projects`, `Test WPF smoke project`) |
| `dotnet publish src/StegoForge.Cli/StegoForge.Cli.csproj --configuration Release --output artifacts/cli` | `.github/workflows/release.yml` → `package-cli` → `Publish CLI` |
| `dotnet publish src/StegoForge.Wpf/StegoForge.Wpf.csproj --configuration Release --output artifacts/wpf` | `.github/workflows/release.yml` → `package-wpf` → `Publish WPF` |
| `sha256sum ` / `Get-FileHash -Algorithm SHA256` | `.github/workflows/release.yml` → `package-cli` / `package-wpf` → 校验和清单生成 + 上传前验证 |
| `cosign sign-blob ...` + `cosign verify-blob ...` | `.github/workflows/release.yml` → `package-cli` / `package-wpf` → 分离签名生成 + 上传前签名验证 |
环境注意事项：
- WPF 构建/测试/发布需要 Windows。
- 全面加固模糊测试活动 (`Campaign=Fuzz-Full`) 在 CI 中特意设为仅计划执行，在本地运行可能耗时较长。
## 发布流程
StegoForge 对所有带标签的发布使用 **语义版本控制**。
### 版本号递增规则 (SemVer 策略)
- **主版本号 (`X.0.0`)**：在引入破坏性的 API/契约/行为更改时递增（包括 CLI 契约中断、载荷格式不兼容或不兼容的默认值）。
- **次版本号 (`X.Y.0`)**：在向后兼容的功能和新增能力时递增。
- **修订号 (`X.Y.Z`)**：在向后兼容的错误修复、加固和不改变公共契约的仅文档发布调整时递增。
如果在 MINOR/PATCH 之间不确定，仅当增加了用户可观察到的能力时才默认为 MINOR；否则使用 PATCH。
### 标签格式
- 发布标签 **必须** 使用确切格式 `vX.Y.Z`（例如：`v1.2.3`）。
- 工作流会验证标签和版本元数据，如果 `tag != v{version}` 则会失败。
### 变更日志要求
- 每次发布必须在打标签前更新 `CHANGELOG.md`。
- 为发布版本和日期添加专门的标题，并附上分类要点（如适用，包括 Added/Changed/Fixed/Security）。
- 为每个发布包含一个 **迁移说明** 小节；如果不需要任何操作，请明确说明 `None`。
- 发布工作流会验证发布版本在 `CHANGELOG.md` 中是否有对应的部分，并且已提供变更日志摘要作为工作流元数据。
### 发布工件完整性验证
每次发布会发布确定性的工件名称、校验和清单和分离签名：
- `stegoforge-cli-vX.Y.Z-linux-x64.tar.gz`
- `stegoforge-cli-vX.Y.Z-linux-x64.sha256`
- `stegoforge-cli-vX.Y.Z-linux-x64.tar.gz.sig`
- `stegoforge-cli-vX.Y.Z-linux-x64.sha256.sig`
- `stegoforge-wpf-vX.Y.Z-windows-x64.zip`
- `stegoforge-wpf-vX.Y.Z-windows-x64.sha256`
- `stegoforge-wpf-vX.Y.Z-windows-x64.zip.sig`
- `stegoforge-wpf-vX.Y.Z-windows-x64.sha256.sig`
- `stegoforge-cosign.pub`
验证校验和：
```
sha256sum --check stegoforge-cli-vX.Y.Z-linux-x64.sha256
```
```
$line = Get-Content .\stegoforge-wpf-vX.Y.Z-windows-x64.sha256 -Raw
$parts = $line.Split('*', 2)
$expected = $parts[0].Trim().ToLowerInvariant()
$actual = (Get-FileHash -Path $parts[1].Trim() -Algorithm SHA256).Hash.ToLowerInvariant()
if ($expected -ne $actual) { throw "Checksum verification failed." }
```
验证签名：
```
cosign verify-blob --key stegoforge-cosign.pub --signature stegoforge-cli-vX.Y.Z-linux-x64.tar.gz.sig stegoforge-cli-vX.Y.Z-linux-x64.tar.gz
cosign verify-blob --key stegoforge-cosign.pub --signature stegoforge-cli-vX.Y.Z-linux-x64.sha256.sig stegoforge-cli-vX.Y.Z-linux-x64.sha256
```
```
cosign verify-blob --key .\stegoforge-cosign.pub --signature .\stegoforge-wpf-vX.Y.Z-windows-x64.zip.sig .\stegoforge-wpf-vX.Y.Z-windows-x64.zip
cosign verify-blob --key .\stegoforge-cosign.pub --signature .\stegoforge-wpf-vX.Y.Z-windows-x64.sha256.sig .\stegoforge-wpf-vX.Y.Z-windows-x64.sha256
```
信任锚和密钥轮换指南：
- `stegoforge-cosign.pub` 是分离签名的发布验证信任锚。
- 在信任新密钥之前，请验证发布说明中公布的密钥指纹是否与 `stegoforge-cosign.pub` 匹配。
- 在密钥轮换期间，至少在一个发布周期内保持重叠（发布旧密钥 + 新密钥），然后在随后的发布说明中停用旧密钥。
- 如果发生紧急密钥撤销，请将被撤销密钥的签名视为不受信任，并仅依赖使用替换密钥重新签名的工件。
特定平台的签名限制：
- Windows Authenticode 签名（通过仓库机密配置时）仅覆盖已签名的 Windows 可执行文件，不证明 Linux/macOS 工件。
- 跨平台完整性由 SHA-256 清单和针对工件及校验和文件的 cosign 分离签名提供。
## CLI 命令状态
已实现的根命令：
- `embed`
- `extract`
- `capacity`
- `info`
- `version`
- `help`
快速示例：
```
# 将 payload 嵌入 carrier
dotnet run --project src/StegoForge.Cli -- embed --carrier in.png --payload secret.bin --out out.png
# 提取 payload
dotnet run --project src/StegoForge.Cli -- extract --carrier out.png --out recovered.bin
# 估算容量和 embeddability
dotnet run --project src/StegoForge.Cli -- capacity --carrier in.png --payload 1024
# 检查 carrier metadata
dotnet run --project src/StegoForge.Cli -- info --carrier out.png
# 打印版本/help
dotnet run --project src/StegoForge.Cli -- version
dotnet run --project src/StegoForge.Cli -- help
```
诊断模式：
- `--quiet` 用于最少的面向用户输出。
- `--verbose` 用于扩展的操作细节。
- `--json` 用于机器可读的诊断/错误契约。
格式错误/损坏的输入处理是确定性的：失败映射到稳定的 `StegoErrorCode` 值和可预测的进程退出代码，因此脚本可以根据格式错误的头部/载荷条件可靠地进行分支。
## WPF 状态（当前）
**现已可用（里程碑 11）：**
- 嵌入和提取视图已实现并连接到应用服务。
- WPF 测试覆盖了验证、命令启用、进度生命周期和确定性错误映射。
- Windows CI 会还原/构建/测试 WPF 应用和测试项目。
**发布就绪范围（当前）：**
- 里程碑 14 关于发布流程加固和打包/签名验证指南的文档已在 `README.md`、`docs/building.md` 和 `docs/testing.md` 中完成。
- 超出当前嵌入/提取工作流的未来 UX 扩展仍由路线图驱动。
详情请参阅 `docs/gui.md` 和 `docs/roadmap.md`。
## 按里程碑划分的当前状态
与 `docs/roadmap.md` 检查清单对齐：
| 里程碑 | 状态摘要 |
| --- | --- |
| 1 — Solution scaffolding | ✅ 完成 |
| 2 — Core contract finalization | ✅ 完成 |
| 3 — Payload envelope v1 | ✅ 完成 |
| 4 — Compression provider integration | ✅ 完成 |
| 5 — Crypto provider integration | ✅ 完成 |
| 6 — PNG format handler (v1) | ✅ 完成 (`png-lsb-v1`) |
| 7 — BMP format handler | ✅ 完成 (`bmp-lsb-v1`) |
| 8 — WAV format handler | ✅ 完成 (`wav-lsb-v1`) |
| 9 — Application orchestration and policy rules | ✅ 完成 |
| 10 — CLI command surface v1 | ✅ 完成 |
| 11 — WPF GUI v1 | ✅ 完成 |
| 12 — Hardening and robustness | ✅ 大部分已实现并积极测试中 |
| 13 — Documentation and developer experience | ✅ 完成 |
| 14 — Release readiness (v1.0) | ✅ 文档和发布门控标准已定稿 |
## 里程碑 12：加固和安全诊断
里程碑 12 将质量关口从正确性扩展到了对抗弹性和操作员安全诊断。
### 模糊测试和负面路径范围
- 序列化器、载荷信封和载体处理器的模糊测试活动包括确定性的有界 PR 覆盖率和更深入的夜间活动。
- 负面路径覆盖率明确针对截断、损坏的长度字段、无效标志、不支持的格式组合和取消行为。
- 加固测试同时断言类型化异常类和映射的 `StegoErrorCode` 结果，以实现确定性的失败语义。
### 资源使用限制和可配置保障措施
- 处理限制（`MaxPayloadBytes`、`MaxBytes`、`MaxEnvelopeBytes`、可选的 `MaxCarrierSizeBytes`）被视为一等安全控制，而非可选的附加项。
- 限制检查发生在昂贵的分配/解压缩路径之前，以减少因格式错误的载体而导致的内存压力和拒绝服务风险。
- 贡献者应渐进地调整限制，并保持 CI 默认值保守；更大的阈值应属于专用的压力/模糊测试环境。
### 秘密安全诊断策略
- 诊断默认经过清理，同时保留操作上下文和关联标识符以提供支持能力。
- 敏感材料（密码、明文载荷字节、派生密钥）始终从 CLI/UI/日志输出中删除。
- 面向用户的错误保持可操作性但不包含秘密，内部故障通过稳定的代码/消息契约呈现。
交叉参考：[docs/testing.md#ci-hardening-strategy](docs/testing.md#ci-hardening-strategy)、[docs/testing.md#hardening-and-cancellation-test-guidance](docs/testing.md#hardening-and-cancellation-test-guidance)、[docs/architecture.md#processing-hardening-limits](docs/architecture.md#processing-hardening-limits) 以及 [docs/architecture.md#security-logging-policy](docs/architecture.md#security-logging-policy)。
## 安全与滥用说明
StegoForge 严格 intended 用于合法用途，例如水印、数据溯源、安全归档工作流程和教育研究。项目范围不包括恶意软件隐藏和未经授权的逃避活动。
### 允许/预期用途
- 在合法授权下保护敏感信息。
- 嵌入可追溯的所有权/来源标记。
- 经明确许可进行的内部测试和红队演习。
### 禁止/滥用场景
- 隐藏恶意软件、命令和控制指令或数据外泄载荷。
- 绕过法律控制、策略控制或取证监控。
- 任何非法监视、骚扰或未经授权的数据访问。
### 设计护栏
- 确定性的错误契约和显式的失败模式。
- 对提取载荷的完整性验证。
- 版本化的载荷帧结构，用于安全的向后兼容性处理。
- CLI/UI 工作流中的审计友好命令日志（在可行的情况下）。
有关质量和治理里程碑，请参阅 `docs/testing.md` 和 `docs/roadmap.md`。
## 文档验证
- 文档验证发布版本：**2026-03-07T00:00:00Z**（里程碑 14 文档完成通过，涵盖 `README.md` 和 `docs/`）。
标签：BMP处理, DNS 反向解析, DNS枚举, DNS解析, LSB隐写, PNG处理, Steganography, StegoForge, WAV处理, WPF, 信息隐藏, 图片隐写, 开源项目, 数据嵌入, 文件隐藏, 文档结构分析, 桌面应用, 网络安全, 网络安全工具, 隐写术, 隐私保护, 音频隐写