MichaelWeissDEV/pychef
GitHub: MichaelWeissDEV/pychef
CyberChef recipe 模型和数据转换操作的纯 Python 无依赖实现，适用于脚本、测试、服务和离线工具。
Stars: 0 | Forks: 0
# PyChef
[](https://cyberchef-py.readthedocs.io/en/latest/?badge=latest)
PyChef 是 CyberChef 的 recipe 模型和数据转换操作的非官方、无依赖、纯 Python 实现。它适用于在运行时不能依赖 Node.js 或 JavaScript 的脚本、测试、服务和离线工具。
## 安装
PyPI 发行版名为 `cyberchef-py`；Python 导入名为 `pychef`。
```
python -m pip install cyberchef-py
```
使用 uv：
```
uv add cyberchef-py
```
需要 Python 3.10 或更高版本。已发布的 package 没有运行时依赖。
在 repository 检出目录下运行完整的本地示例：
```
uv sync --locked
uv run python examples/quickstart.py
```
## 文档
Sphinx 文档包含新手指南、recipe、pipeline、CTF 和 packet 工具、公共 Python API、兼容性边界，以及为每个注册操作提供的独立参考页面。请访问 [cyberchef-py.readthedocs.io](https://cyberchef-py.readthedocs.io/en/latest/) 阅读文档；其源码位于 [docs](docs/index.rst)。
构建 Read the Docs 和 CI 所使用的严格的 HTML 文档：
```
uv sync --locked --group docs
uv run python docs/_scripts/generate_operation_docs.py --check
uv run sphinx-build -W --keep-going -b html docs docs/_build/html
```
Repository 包含一个版本 2 的 `.readthedocs.yaml`；将 GitHub repository 导入 Read the Docs 即可直接使用指定的 uv 环境和 Sphinx 配置。
## 快速开始
```
from pychef import bake
result = bake(
"Hello, World!",
[
{"op": "To Base64", "args": ["A-Za-z0-9+/="]},
{"op": "Reverse", "args": ["Character"]},
],
)
assert result == b"==QIkxmcvdFIs8GbsVGS"
```
二进制操作保留 `bytes`；文本操作返回 `str`。设置 `return_type="bytes"` 或 `return_type="str"` 以请求最终类型转换。
Recipe 接受与 CyberChef 相同的 `{"op": ..., "args": [...]}` 结构，以及用于无参数步骤的操作名称字符串。
```
from pychef import Chef, Recipe
recipe = Recipe(["Gunzip", {"op": "Decode text", "args": ["UTF-8 (65001)"]}])
result = Chef().bake(compressed_data, recipe)
```
## 链式 pipeline
`Pipeline` 构建不可变的、可重用的转换流程。使用 `.then()` 调用任何已注册的 CyberChef 操作，或使用针对常见 CTF 工作流的类型化便捷方法。Pipeline 可以使用 `|` 组合；值也可以被 pipe 到其中。
```
from pychef import Pipeline
decode = Pipeline().from_hex().xor(b"\x42").decode()
assert decode("0a272e2e2d") == "Hello"
assert "0a272e2e2d" | decode == "Hello"
base64_decode = Pipeline().from_base64()
combined = decode | Pipeline().to_base64()
results = combined.transform_many(["0a272e2e2d", "152d302e26"])
```
分支接收相同的当前值。只要所有分支返回与分隔符相同的类型，它们的输出就可以被拼接：
```
hash_line = Pipeline().concat(
Pipeline().digest("md5"),
Pipeline().digest("sha256"),
separator=":",
)
print(hash_line(b"flag"))
trace = decode.trace("0a272e2e2d")
print([(step.name, step.output) for step in trace])
```
Python 可调用对象和结构化数据也是有效的阶段。`.select()` 会遍历嵌套的字典键和序列索引。仅包含 CyberChef 操作的 pipeline 可以通过 `.recipe` 恢复。
## CTF 和二进制辅助工具
顶层 API 包含 pwntools 风格的整数打包、显式字节序变体、按字节 XOR、de Bruijn 模式、转储、哈希和平坦化处理：
```
from pychef import cyclic, cyclic_find, flat, p32, p32be, sha256, u64
payload = flat(b"A" * 40, p32(0xDEADBEEF), p32be(0x1337))
address = u64(leaked_bytes)
offset = cyclic_find(crashed_value)
fingerprint = sha256(payload)
```
`p8`、`p16`、`p32` 和 `p64` 默认使用小端序；`p16le`/`p16be`、`p32le`/`p32be`、`p64le`/`p64be` 以及对应的 `u*` 函数则是显式指定的。`pack()` 和 `unpack()` 支持任意字节对齐宽度和有符号整数。`swap_endian()` 反转每个固定宽度的字。
AES 辅助工具支持 CBC、ECB、CFB、OFB、CTR 和带有身份验证的 GCM。非 ECB 模式需要显式指定 IV/nonce。GCM 默认附加其 16 字节的 tag；detached tag 可以通过 `aes_gcm_encrypt()` 使用：
```
from pychef import Pipeline, aes_decrypt, aes_encrypt, aes_gcm_encrypt
ciphertext = aes_encrypt(data, key, mode="CBC", iv=iv, padding="pkcs7")
assert aes_decrypt(ciphertext, key, mode="CBC", iv=iv) == data
ciphertext, tag = aes_gcm_encrypt(data, key, iv=nonce, aad=b"header")
round_trip = (
Pipeline()
.aes_encrypt(key, mode="GCM", iv=nonce, aad=b"header")
.aes_decrypt(key, mode="GCM", iv=nonce, aad=b"header")
)
assert round_trip(data) == data
```
默认情况下，密钥、IV 和 tag 均为原始 bytes。传入 `key_format="hex"`、`iv_format="hex"` 或 `tag_format="hex"` 可使用文本形式的十六进制素材。
## Packet 和捕获文件
`parse_capture()` 会自动检测经典的 PCAP 和 PCAPNG 格式，并返回普通的 Python 字典。Ethernet/VLAN、Linux cooked captures、loopback/raw IP、ARP、IPv4、IPv6 extension headers、ICMP、TCP options、UDP、DNS 以及可识别的 HTTP/TLS 记录都会被递归解码。不支持的链路层或应用层数据仍以 bytes 形式保留。
```
from pychef import Pipeline, parse_capture, read_capture
capture = read_capture("challenge.pcap")
first_packet = capture["packets"][0]["decoded"]
source = (Pipeline().parse_capture().select("packets", 0, "decoded", "network", "source"))(
pcap_bytes
)
```
解析器强制执行 packet 数量、packet 大小和文件大小限制。`json_safe()` 或 `packet_json()` 会将保留的 byte string 转换为 `{hex, length}` 对象，以便在 JSON 输出时不丢失其大小。
## 兼容性状态
指定的参考标准是 commit `c56dd23358e948aff9f3f98913818e544227da13` 处的 CyberChef 11.3.0。
此 alpha 版本注册了全部 502 个上游操作名称（100% 名称覆盖率）。每个已注册的操作都在 `pychef.operations.by_operation` 下拥有自己的公共 Python 模块；结构测试可防止操作通过共享的 catch-all 模块进行注册。在多个操作使用相同原语的情况下，共享的算法核心会被分开维护。详尽的逐项名称对照矩阵位于 [COMPATIBILITY.md](COMPATIBILITY.md)。
也可以在 Python 中检查兼容性：
```
from pychef import compatibility_report
report = compatibility_report()
print(len(report.implemented), len(report.missing), report.complete)
```
清单中的“已实现”意味着该操作是可调用的。精确的选项级对等性通过移植到 pytest 的官方 CyberChef 向量逐步建立。当前的测试套件涵盖了确定性编码、压缩、哈希、古典和现代密码、二进制序列化、recipe 流程控制、公钥操作、光栅图像、媒体元数据、图表、坐标、网络请求、Argon2/Bcrypt、SM2、PGP 工作流、机器码检查、JSON 查询语言、OCR 和 YARA 规则。
名称覆盖率被刻意与参考对等性区分开来。部分可调用操作是无依赖的兼容性回退方案，或仅支持有文档记录的格式子集。剩余的广泛对等性边界包括：解码任意 QR 符号；palette/interlaced PNG、progressive/CMYK JPEG 和 compressed TIFF；完整的 Typex/SIGABA/Lorenz 机器预设；完整的 JavaScript/Jq/Jsonata 和 YARA 语法；通用 OCR；完整的指令解码；AMF3 externalizable 值；以及可互操作的 OpenPGP 数据包。目前，MD6、Snefru、Streebog、Whirlpool、RIPEMD、Twofish、GOST、CTPH、SSDEEP、CRC、JPEG baseline、GIF 首帧以及 uncompressed TIFF 路径均已拥有真实的 Python 实现和官方向量，而不仅仅是兼容性占位符。
## 安全与性能
- 没有运行时依赖，也没有 subprocess 或 JavaScript bridge。
- 该 package 在导入时不执行网络访问。只有显式的 `HTTP request` 和 `DNS over HTTPS` 操作会访问网络；它们拒绝 URL 中的凭据以及本地/私有/保留目标地址。
- JWT 验证仅接受受支持的 HMAC 算法，并拒绝 unsigned 或非对称算法混淆。
- 随机数生成器使用 Python 的 `secrets` 模块。
- 解析器会验证长度，并通过 `OperationError` 报错，而不是默默地返回损坏的数据。
- PCAP/PCAPNG 读取器会限制文件、packet 和 packet 数量大小，并保留每个 packet 的解码错误，而不是丢弃捕获的 bytes。
- `Recipe` 可以构造一次并重复使用，以避免重复解析。
- `Pipeline` 是不可变的，同样可以构造一次并重复使用。
提供的纯 Python 加密实现仅用于兼容性和测试；在生产环境进行密钥保护或协议安全防护时，请使用经过专业审计的加密 package。
## 开发
开发环境仅需要 Python 3.10 或更高版本以及 [uv](https://docs.astral.sh/uv/)：
```
uv sync --dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run ty check
uv build
```
Pytest 强制要求至少 75% 的分支覆盖率；当前套件包含超过 850 个测试，并报告了 84% 的分支覆盖率。Ruff 负责格式化和 linting，`ty` 负责检查类型化的公共 API。已发布的 wheel 没有运行时依赖。
PyChef 是一个独立的 Python 移植版本。CyberChef 版权属于 Crown copyright 2016, GCHQ，并根据 Apache License 2.0 获得许可。请参阅 [NOTICE](NOTICE)、[THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) 和 [LICENSE](LICENSE)。
标签：CyberChef, Python, 安全规则引擎, 开源库, 搜索引擎爬虫, 数据转换, 无后门, 编码解码, 逆向工具