DreadpiratePickles/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 (类似英语的分布 ...) 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` | 用户错误（输入错误、文件不可读、拒绝不安全的 serve） | | `2` | argparse 使用错误（未知标志、缺少必需参数） | | `130` | 被中断 (Ctrl-C) | ## 测试 ``` cd caesar-salad PYTHONPATH=src python -m pytest -q ``` 快速且依赖轻量：无网络、无 sleep。涵盖了密码转换、 修正后的评分、位移下的 IoC 不变性、置信度判定、CLI 输入 处理 / 大小限制 / JSON 输出、`serve` 安全拒绝，以及 Flask 应用的输入加固（非数字位移 → 200 而非 500，超大请求体 → 413）。 ## 前置条件 Python 3.11+，以及 `flask`、`rich` 和 `pytest`（参见 `requirements.txt`）。 ## 🏷️ 为什么叫 "Caesar Salad"？ Caesar 的密码，被拌入了沙拉。它之所以能赢得 *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` (环回接口)。出站流量、 实时发送和主动扫描都受显式标志控制——空运行、 被动模式，或者拒绝并警告始终是默认行为。 - **无意外的隐患。** 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)。

标签：CTF工具, Python, 凯撒密码, 密码分析, 密码学, 手动系统调用, 教学工具, 无后门, 漏洞搜索, 逆向工具, 频率分析