YAMRAJ13y/Yamlok

# Yamlok [](https://github.com/YAMRAJ13y/Yamlok/actions/workflows/ci.yml)     **针对已退役数字资产的防篡改停用签核。** 当你退役一项服务、一台服务器或一组凭据时，几乎没有任何东西能产生 *持久的证明*来证实它确实已被终结且未死灰复燃。Yamlok 生成了这种 证明：将其指向已死资产的残留文件（理想情况下还包括你扫描器的 输出），它就会生成一份**死亡证明** —— 每个证据文件都与它的 SHA-256 绑定，包括运行的扫描器、类型化的残留配置文件，以及一个确定性的 判定结果 —— 并将其附加到经过哈希链和 HMAC 签名的账本中。`yamlok verify` 会重放 该链条并重新推导哈希值，以证明在签核之后没有任何内容被篡改。 ``` $ yamlok certify --asset billing-api-v1 --evidence ./leftovers ┌─ YAMLOK DEATH CERTIFICATE ────────────────────────────── │ asset : billing-api-v1 │ verdict : 💀 UNDEAD │ fate : Preta — UNDEAD (live residue; not retired) │ rationale : 1 high-severity finding(s): a live credential or key format remains. │ residue : HIGH=1 MEDIUM=1 LOW=1 │ evidence : 2 file(s), each bound to SHA-256 │ scanners : yamlok-builtin │ cert id : 9b1f3c2a7e4d8f06… (seq 0) └──────────────────────────────────────────────────────── ``` ## 它是什么 —— 以及它不是什么 Yamlok **不是另一个扫描器。** 资产发现技术已经成熟（如 runZero、Censys）；密钥 检测技术也已成熟（如 gitleaks、trufflehog）。*尚未* 解决的是 **签核**：针对已死资产残留物的一份经过签名且可重现的判定，审计员 —— 或未来的你 —— 只需一条命令即可重新核查。 因此，预期的工作流是**自带扫描器**： ``` gitleaks detect --no-git --source ./leftovers --report-format json --report-path gl.json yamlok certify --asset billing-api-v1 --evidence ./leftovers --scan-report gl.json --no-builtin-scan ``` 或者使用辅助脚本（bash 或 PowerShell）一步完成： ``` ./scripts/scan_with_gitleaks.sh billing-api-v1 ./examples/dead-billing-api ``` Yamlok 会摄取 gitleaks/trufflehog 的输出（自动检测格式），应用 确定性的退役判定，并将其封存为可重新验证的证明。 仓库中包含一份示例报告，让你无需安装任何扫描器即可尝试封装路径： ``` yamlok certify --asset billing-api-v1 \ --evidence examples/dead-billing-api \ --scan-report examples/gitleaks-report.json --no-builtin-scan ``` 针对零配置场景，我们提供了一个微型的内置基准检测器，但它 仅仅是一个基准 —— 对于任何正式操作，请为其提供专用扫描器的输出。 ## 安装 ``` pipx install yamlok # users (once published to PyPI) pip install -e . # from a clone (devs); standard library only, no runtime deps ``` ## 快速入门 ``` yamlok demo # self-contained: certify, verify, then prove tampering is caught yamlok certify --asset svc --evidence ./dir # certify one retired asset yamlok verify # replay the ledger chain + mirror yamlok verify --asset svc --evidence ./dir # also re-bind the cert to the bytes on disk yamlok list # every asset's current fate yamlok show --asset svc # one asset's full certification timeline ``` 退出代码与判定结果一一对应，以便 CI 可以据此进行拦截：`certify` 返回 `0` 表示 REST， `1` 表示 QUARANTINE，`2` 表示 UNDEAD；如果链条、镜像或 证据绑定失败，`verify` 将返回非零值。 ## 死亡注册表 随着时间推移对相同或不同的资产进行签核，Yamlok 会维护一个可查询的 **案件** 注册表 —— 每项资产对应一个案件，记录其当前归属和完整历史： ``` $ yamlok list ASSET FATE CERTS HAUNTED ──────────────────────────────────────────────────────── auth-service 🕊 REST 1 billing-api-v1 🕊 REST 2 once-undead ──────────────────────────────────────────────────────── 2 case(s): 💀 0 undead · ⚠ 0 quarantine · 🕊 2 rest ``` `once-undead` 具有粘性：曾经被标记为 UNDEAD 的资产即使在后来 通过干净的重认证后也会保持标记 —— 一个未能彻底终结的“再次击杀”正是 你需要注意的情况。`yamlok show --asset X` 会打印出时间线，每一行都链接回 其账本记录。 该注册表是一个**纯投影**：它在每次 调用时都从账本重建且从不缓存，因此不会发生数据漂移。它也是 **验证优先** 的 —— 它拒绝从被篡改的账本中提供数据，因此绝对不会在 账本显示为 `UNDEAD` 的情况下，对外呈现该资产为 `REST`。（没有使用第二个数据库；在这种规模下，对一个仅追加文件的 内存重放 *本身就是* 索引。） 在认证时，一个稳定的 `asset_id` 会被写入不可变账本记录中 （操作员通过 `--asset-id` 指定，或使用名称的 slug），因此即使发生重命名，案件依然存在， 且注册表始终是账本的纯函数。 ## 三种命运 | 判定 | 神话 | 含义 | |---|---|---| | `REST` | Svarga | 无残留物。资产干净地消亡了 —— 让它安息吧。 | | `QUARANTINE` | Naraka | 低/中等残留物（占位符、高熵值、未验证的命中项）。需要隔离并审查。 | | `UNDEAD` | Preta | 高危残留物（真实的凭据/密钥）。“已死”的资产仍然携带着活跃威胁 —— **尚未退役。** | 判定规则被刻意精简为一句话：*最严重的发现决定了命运。* Yamlok 提供的核心价值是经过签名且可重现的签核 —— 而非某种自作聪明的评分系统。 ## 证明书到底证明了什么（请阅读本节） 对于安全工具而言，诚实比营销更重要，因此其边界定义非常明确： - ✅ **记录的完整性** —— `verify` 可证明没有任何证明在签名后被编辑、 重新排序、拼接或截断（SHA-256 链 + HMAC + 序列绑定 + 镜像副本）。 - ✅ **与字节的绑定** —— Yamlok 直接对证据本身进行哈希处理，因此该 证明背书的是实际的文件，而不是操作员对这些文件的单方面声明。 - ❌ **证据的完整性** —— Yamlok 无法对你从未 提供的遗留物做出判断。*完整性由操作员背书；完整性由密码学保证。* 不要 将两者混为一谈。 - ⚠️ **密钥保管** —— 只有当密钥远离攻击者时，HMAC 才能发挥作用。 默认情况下，它将密钥存储在附属文件中（防范后续仅针对文件的篡改 —— 这是 最常见的情况）。如果攻击者在写入时控制了主机，请将密钥放入 KMS/HSM 或存放在独立的主机上。验证路径 完全相同；仅仅是密钥位置的改变影响了其安全强度。 ## 名称的含义 Yamlok 是印度宇宙观中的死者之境。这种映射并非纯粹的装饰 —— 神话 *本身就是* 架构：**Chitragupt** 将每一项行为记录到不可变的 **Agrasandhani** 账本中；**Yama** 称量记录并引导灵魂；而 **Preta** 则指那些从未安息、至今仍在纠缠生者的亡魂。 一个携带活动密钥的退役系统正是一个 Preta。这种宇宙观渗透在事物的 命名之中；而你调用的 API 则是纯英文的（`certify`、`verify`）。 这是一个主题安全工具包中的首个工具。它刻意保持轻量 —— 一项资产，一个残留物领域，一份签核判定 —— 它将通过发布这个模块来争取下一个模块的诞生。 ## 开发 ``` pip install -e ".[dev]" pytest # 67 tests ruff check . && ruff format --check . && mypy src/yamlok ``` 该账本的测试套件在设计上是对抗性的（包括编辑、截断、拼接、 重新排序、剥离签名、镜像偏差）—— 一个防篡改存储的价值完全取决于它的测试。CI 会在 Python 3.9–3.13 上运行 lint、类型检查以及覆盖率检查门控。 ## 更多 - [SECURITY.md](SECURITY.md) — 如何报告漏洞；威胁模型的简要说明。 - [CHANGELOG.md](CHANGELOG.md) — 更新日志。 - [docs/PLAN.md](docs/PLAN.md) — 构建计划和已锁定的技术决策。 - [docs/CASE-STUDY.md](docs/CASE-STUDY.md) — 针对真实退役资产运行 Yamlok 的案例研究。 - [RELEASING.md](RELEASING.md) — 版本发布方式（PyPI Trusted Publishing）。 ## 许可证 MIT。

标签：Blue Team, CVE, IT资产管理, Python, 哈希链, 安全规则引擎, 数字签名, 无后门, 系统下线, 运维审计, 逆向工具, 防篡改证明