P1rate5ec/caesar-salad

`caesar-salad` 用于对 Caesar 密码进行编码、解码和**破解**。给定密文 且没有密钥的情况下，它会根据英语字母统计信息对全部 26 种可能的 偏移量进行评分，并提供最有可能的明文——附带置信度结论和 重合指数（Index-of-Coincidence）健全性检查，让你知道尝试破解 Caesar 密码 到底是不是正确的工具。 它的存在是为了让一个教训深入人心：**替换密码会将其结构 直接泄露到加密过程中。** 它是一个用于教学、CTF 准备和 演示的工具——而不是用于保密的工具。 ## 工作原理 Caesar 密码将每个字母移动固定的数量 *k*（mod 26）。解码 只需移动 *-k*。破解则是要在不被告知的情况下，判断使用了 *哪一个* *k*。 ``` ciphertext ──► for k in 0..25 ──► decode(text, k) ──► score each candidate ──► rank │ ┌───────────────────────────────┴───────────────┐ │ chi-squared vs. English letter frequencies │ lower = more English │ minus a bonus per common English word found │ ("the", "and", "is"…) └────────────────────────────────────────────────┘ ``` 三个信号驱动了该分析： 1. **卡方频率距离。** 每个候选明文的字母 分布会与标准英语频率进行比较。英语文本得分 *低*；混乱的偏移得分*高*。这是一个干净的统计量——没有截断， 因此强有力的候选者会保持其排序（以前的版本将分数 截断为零，从而丢失了正确猜测之间的排名）。 2. **常用词奖励。** 真实的单词（`the`、`and`、`is`、…）会在单词 边界上进行匹配，并从分数中扣除。真正的解码通常会在频率 *和*单词上双双胜出，因此这些信号会相互增强。 3. **重合指数（IoC）。** 两个随机抽取的 字母相等的概率。英语 ≈ 0.067，均匀随机 ≈ 0.038。至关重要的是， Caesar 偏移只是*重新标记*了字母，因此 **IoC 在密码下是不变的** ——在密文上计算时，它可以预先告诉你该文本是否 是合理的英语偏移（相对于随机的、多字母的或非英语的）。 **置信度**结论（`high`/`medium`/`low`）将分数相对于第二名的优势 与获胜者的单词计数混合在一起，并且对于 太短而不可信的样本（< 20 个字母），会降级为 `low`。 ### 数据模型 没有数据库。`CrackCandidate` 包含 `shift`、`score`、`plaintext`、 `explanation` 和 `word_hits`。`CrackReport` 使用 `letters`、`index_of_coincidence`、`ioc_verdict` 和 `confidence` 包装排名的候选者。两者 都可以序列化为纯 JSON，以便进行脚本化处理。 ## 安装与设置 ``` cd caesar-salad python -m venv .venv # Windows: .venv\Scripts\activate POSIX: source .venv/bin/activate pip install -r requirements.txt pip install -e . # optional: installs the `caesar-salad` command cp .env.example .env # optional: sets serve host/port ``` 没有可编辑安装？每个命令也可以通过 `PYTHONPATH=src python -m caesar_salad.cli …` 运行。 ## CLI 用法 全局：`--plain` / `--no-color` 强制使用无样式文本。当设置了 `NO_COLOR` 或 stdout 不是终端时，颜色也会自动禁用（因此管道保持干净）。 任何命令上的 `--json` 都会向 stdout 输出**纯 JSON**，没有任何修饰。 输入可以来自 `--text`、`--file PATH`（≤ 5 MiB）或**管道 stdin**。 ### `encode` / `decode` — 已知偏移量 ``` caesar-salad encode --text "meet at dawn" --shift 7 echo "meet at dawn" | caesar-salad encode --shift 7 caesar-salad decode --file secret.txt --shift 3 --json ``` 偏移量归一化为 mod 26（`--shift 29` ≡ `--shift 3` ≡ `--shift -23`）。JSON： ``` {"operation": "encoded", "shift": 7, "input_length": 12, "result": "tlla ha khdu"} ``` ### `crack` — 未知偏移量 ``` caesar-salad crack --text "wkh vhfuhw phhwlqj lv dw qrrq elg wkh eulgjh dw gdzq" caesar-salad crack --file intercept.txt --top 3 cat intercept.txt | caesar-salad crack --json caesar-salad crack --text "..." --all # show all 26 shifts ``` 终端输出示例： ``` ┌───────── 🥗 caesar-salad ─────────┐ │ crunchy classical cryptanalysis │ └───────────────────────────────────┘ ┌──────────────────────── cryptanalysis ─────────────────────────┐ │ letters analysed: 42 │ │ index of coincidence: 0.0697 (English-like distribution) │ │ confidence in top pick: HIGH │ └────────────────────────────────────────────────────────────────┘ │ shift │ score │ words │ plaintext ────┼────────┼─────────┼────────┼────────────────────────────────────────── ★ │ 3 │ -24.68 │ 5 │ the secret meeting is at noon bid the ... │ 15 │ 97.60 │ 0 │ hvs gsqfsh asshwbu wg oh bccb pwr hvs ... │ 18 │ 214.94 │ 0 │ esp dpncpe xppetyr td le yzzy mto esp ... ``` `--plain` 提供可用 grep 搜索的行： ``` # letters=42 ioc=0.0697 confidence=high (类似 English 的分布 ...) shift= 3 score=-24.680 words=5 the secret meeting is at noon bid the bridge at dawn shift=15 score= 97.600 words=0 hvs gsqfsh asshwbu wg oh bccb pwr hvs pfwrus oh rokb ``` ### `serve` — 本地浏览器工作区 ``` caesar-salad serve # http://127.0.0.1:5066 caesar-salad serve --host 127.0.0.1 --port 8080 ``` 一个单页工作区，用于交互式地编码 / 解码 / 破解，并显示 相同的 IoC 和置信度读数。 **内置的安全防护：** - 默认绑定到 `127.0.0.1`（环回接口）。任何其他主机都会打印警告—— 仅在您获得授权可以进行服务对外开放的网络上公开它。 - `--debug` 启用 Werkzeug 交互式调试器，这在任何回溯页面上都是 **远程代码执行**。它总是会发出警告，并且在 非环回主机上会被**拒绝**，除非您传递 `--unsafe-allow-remote-debug`。 - 请求体大小受限（256 KiB），分析的文本受限（20 000 个字符）； 非数字的偏移量输入会被强制转换，绝不会导致崩溃。 ## 退出代码 | 代码 | 含义 | | --- | --- | | `0` | 成功 | | `1` | 用户错误（输入错误、文件不可读、拒绝不安全的服务） | | `2` | argparse 使用错误（未知标志、缺少必需的参数） | | `130` | 被中断（Ctrl-C） | ## 测试 ``` cd caesar-salad PYTHONPATH=src python -m pytest -q ``` 快速且轻依赖：无网络，无休眠。涵盖了密码转换、 修正后的评分、偏移下的 IoC 不变性、置信度结论、CLI 输入 处理 / 大小限制 / JSON 输出、`serve` 安全拒绝，以及 Flask 应用的输入强化（非数字偏移量 → 200 而不是 500，超大请求体 → 413）。 ## 前置条件 Python 3.11+，以及 `flask`、`rich` 和 `pytest`（参见 `requirements.txt`）。 ## 🏷️ 为什么叫 "Caesar Salad"？ Caesar 的密码，被 tossing（抛拌）。它之所以配得上 *salad*（沙拉）这个名字，是因为只有 25 个错误答案和 1 个正确答案，而整个工作就是从碗中挑出那清脆爽口的部分。频率分析完成了挑选工作。接着，重合指数检查提出了一个直击要害的后续问题——*我们确定吗？*——这样当密文太短而无法判断时，该工具可以坦然承认，而不是自信满满地塞给你一堆废话。 ## 🔬 这个工具是如何构建的 **目的。** 一个频率分析 Caesar 密码破解器，被重新构想为 值得信赖的密码分析教学工具。给定密文且没有密钥的情况下，它 会对所有 26 种偏移量进行排名，告诉你它的置信度，而且——至关重要的是—— 在你费心之前就会告诉你该文本是否是一个合理的英语偏移。 **工作原理。** 对于每个偏移量 `k`，它会解码并根据 与英语字母频率的卡方距离（越低 = 越像英语）减去常用词 奖励来对候选者进行评分。它还会在 *密文*上计算重合指数：因为 Caesar 偏移只是重新标记了字母，IoC 在 密码下是不变的，所以它可以预先告诉你文本是类英语的 （≈0.067）、平坦/随机的（≈0.038），还是完全其他的东西。 **出色的 CLI。** 一个密码分析摘要面板（分析的字母、IoC + 结论、 一个带有颜色编码的置信度徽章），一个排名的候选表格，在 最佳选择上有一颗洋红色的星星，获胜行显示为绿色，使用 `--all` 显示所有 26 种偏移量，以及 stdin 管道。 **关键改进。** *功能性：* 修复了一个评分错误，该错误中卡方值 被截断为零（`max(0.0, ...)`），这压平了每个强有力的候选者并 破坏了排名顺序——现在是一个干净的、未截断的统计量，可以正确排序； 添加了 IoC 结论和高/中/低置信度混合（分数相对于 第二名的优势 × 获胜者的单词计数，在 20 个字母以下降级）。*安全性：* 文件/stdin 读取限制在 5 MiB，并使用 UTF-8 `errors='replace'`；Flask 应用 将请求体限制在 256 KiB，分析文本限制在 20k 字符，强制转换非数字偏移量 输入，而不是返回 500 错误，并且在脱离环回接口时拒绝 `--debug`。 **示例。** ``` PYTHONPATH=src python -m caesar_salad.cli crack \ --text "wkh vhfuhw phhwlqj lv dw qrrq elg wkh eulgjh dw gdzq" ``` ## ⚖️ 授权使用与安全准则 **这些是用于您拥有或 获得明确授权评估的系统、文件、网络和人员的防御性工具。** 在运行任何内容之前阅读此内容： - **授权不是可选项。** 钓鱼模拟、网络扫描、IP 信誉查询和 Web 应用探测都会触及他人的系统或 数据。请先获得书面授权。有几个工具*拒绝执行操作*，直到您 主张权限（`--yes`、`--authorized-training`、`--i-have-authorization`、 `--i-am-authorized` 等等）。 - **默认安全。** 每个 Web UI 都绑定到 `127.0.0.1`（环回接口）。出站流量、 实时发送和主动扫描都被置于显式标志之后——dry-run（试运行）、 被动或拒绝并警告始终是默认设置。 - **杜绝意外的危险操作。** Flask `--debug`（Werkzeug 交互式 调试器在任何回溯页面上都是远程代码执行）会受到响亮的警告，并且 在脱离环回接口时会被完全拒绝。不受信任的输入有大小限制、经过验证，并 被渲染为无害状态，因此恶意的文件或日志行不会导致崩溃——或接管—— 您的终端。 - **输出中不含机密。** API 密钥保留在请求头中，密码来自 环境变量，不会记录或打印任何敏感信息。 这些不是攻击性工具。它们不包含任何漏洞利用、凭证 收集器和 payload。如果某个工具*可能*被滥用，它在构建上就会 抵御这种滥用。 ## 🧪 开发 ``` python -m venv .venv && source .venv/bin/activate pip install -e . pytest -q # 26 tests, no network, no sleeps caesar-salad --help ``` ## 📄 许可证 在 **MIT License** 下发布。参见 [LICENSE](LICENSE)。

标签：Python, 凯撒密码, 动态分析, 古典密码分析, 安全规则引擎, 密码学, 手动系统调用, 无后门, 逆向工具, 频率分析