mjbommar/celatim

# Celatim Celatim 是一个强类型的 Python 3.14+ 包，用于在 IETF 协议字段中进行针对隐蔽通道和隐写载体的认证文件传输和可复现研究。它提供了一个基于 offer 的传输 CLI 和异步 SDK，并附带通道编解码器、协议数据单元实现、受控的 endpoint 传输、容量模型、检测器和数据擦除指南、场景执行以及证据工件。 该项目伴随一篇调查与测量论文。其通道和防御实现被一并发布，以便研究人员能够复现测量结果、检查假设，并评估通信和规范化行为。 请仅在受控环境中以及您被授权测试的系统和网络上使用 Celatim。 0.2.x 版本中的传输接口仍处于实验阶段。其网络路径已加密并拒绝模糊的完成状态，但独立的安全审查门仍处于开放状态；请参阅[兼容性策略](docs/transfer-compatibility-policy.md)和[当前验证记录](docs/file-transfer-validation-20260710.md)。 ## 环境要求 - CPython 3.14 或更高版本。 - Linux，用于支持 AF_PACKET、网络命名空间、tcpdump 和 QEMU/TAP 工作流。 - 基础包不会导入任何可选的协议栈。 ## Hello world：Alice 与 Bob 在两台机器上安装 transfer 扩展依赖： ``` python -m pip install 'celatim[transfer]' ``` Bob 启动一个接收器，并将一个短期有效的 offer 写入文件： ``` bob$ celatim transfer listen \ --output-dir ~/Downloads \ --host 0.0.0.0 \ --advertise-host 192.0.2.20 \ --offer-out bob.offer Ready: celatim://v1/eyJ... ``` Bob 通过他们已经在使用的通道将 `bob.offer` 发送给 Alice。Alice 使用该 offer 发送一个文件： ``` alice$ celatim transfer send report.pdf --to-file bob.offer Complete: 193024 bytes, authenticated, acknowledged, and verified ``` ## Hello world：应用开发者 CLI 和 SDK 使用相同的强类型传输核心： ``` from pathlib import Path from celatim.transfer import TransferClient, TransferOffer async def send_report(invite: str) -> None: offer = TransferOffer.parse(invite) async with TransferClient.open_default() as client: operation = await client.send_file(Path("report.pdf"), offer) async for event in operation.events(): print(event.status.value, event.bytes_transferred) receipt = await operation.result() assert receipt.authenticated assert receipt.acknowledged assert receipt.verified ``` `TransferServer`、`TransferOperation`、带版本号的 offer/manifest/receipt/event、结构化的 `TransferFailure` 值、通过 `celatim.providers` 进行的 provider 发现，以及可复用的 provider 一致性测试套件，均在 `celatim.transfer` 下公开。 `send_stream()` 接受字节块的异步可迭代对象，数据通过受限的私有磁盘缓冲区处理；`send_bytes()` 是内存中处理的便捷形式。 ## Hello world：学术研究人员 无需安装 transfer 扩展依赖即可使用研究 API： 这是内存中的编解码器/会话结果，而非原生栈网络证据。在进行实证声明时，请使用打包的场景并检查每个结果的证据标签。 ## 安装 ``` python -m pip install celatim celatim --help ``` 该 wheel 包安装了一个主要命令 `celatim`，以及来自同一代码库的四个确定性报告生成器： - `celatim-paper-figures` - `celatim-paper-macros` - `celatim-paper-tables` - `celatim-support-matrix` ## 安装配置 可选依赖项按功能进行分组： | Extra | 功能 | |---|---| | `celatim[transfer]` | TLS 1.3 文件传输、offer 锁定和加密的载体记录 | | `celatim[packet]` | Scapy 数据包构造、解析和 pcap 集成 | | `celatim[crypto]` | ECDSA 和 RSA-PSS 交互实验 | | `celatim[daemon]` | hyper-h2 和 aioquic 生产栈路径 | | `celatim[dns]` | dnspython 消息路径 | | `celatim[ssh]` | Paramiko SSH 消息路径 | | `celatim[iot]` | aiocoap 和 paho-mqtt 消息路径 | | `celatim[realtime]` | WebSocket 消息路径 | 例如： ``` python -m pip install 'celatim[packet,crypto,daemon]' ``` ## 研究 Python API 机制发现可公开可执行的传输元数据，而无需导入可选的协议栈： ``` from celatim import MechanismProfile profile = MechanismProfile.from_catalog("http2-ping-opaque") print([path.kind.value for path in profile.adapter.paths]) ``` 公共 API 还包括场景发现、证据生成、pcap 解码和 scrub 辅助工具、时间扫描、安装检查、测试平台要求以及打包的文档/schema 检查。较低级别的编解码器、PDU 实现、检测器规则和传输类仍可通过专门的 `celatim.*` 子模块使用。 ## 命令行 检查机制和打包的契约： ``` celatim mechanism list celatim mechanism show http2-ping-opaque celatim scenario list celatim docs list celatim schema list celatim testbed requirements ``` 在内存中运行二进制 payload 的往返测试： ``` celatim roundtrip \ --mechanism http2-ping-opaque \ --hex "00 ff 80 41" ``` 运行打包的非特权 pcap 场景并写入证据： ``` celatim scenario run \ --scenario-id http2-ping-opaque-real-pdu-smoke \ --artifact-dir out/carriers \ --pcap-dir out/pcaps \ --log-dir out/logs \ --output out/evidence.json ``` 生成防御性工件： ``` celatim detector rules \ --output-dir out/detector-rules \ --output out/detector-rules.json celatim guidance generate --output out/detector-scrub-guidance.md celatim guidance windows-capture --output out/windows-capture-guidance.md ``` ## 架构 Celatim 是一个 PEP 621 项目，包含一个 `celatim` 包： - `celatim.channel`：位打包、编解码器、组帧和传输无关的驱动程序。 - `celatim.pdu`：解析器可见的协议数据单元实现。 - `celatim.transports`：内存中、文件、pcap、定时和生产路径传输。 - `celatim.testbed`：netns/veth、AF_PACKET、daemon、tcpdump 和 QEMU/TAP 辅助工具。 - `celatim.detect`：检测器谓词、可执行重放和离线 scrub 支持。 - `celatim.metrics`：分离的存储、定时和阈下容量模型。 - `celatim.report`：确定性表格、图表、矩阵和防御性指导。 - `celatim.scenario`：带版本号的场景加载和受控执行。 - `celatim.transfer`：安全的 offer、客户端、服务端、provider、状态、回执和权限分离的数据包 I/O。 该 wheel 包含其默认目录、协议速率假设、JSON Schema、场景定义和操作文档。CLI 默认使用 `importlib.resources` 解析这些资源，因此安装后的命令不依赖于源代码检出。 仅在选择其传输方式时才会导入可选集成。已安装的包冒烟测试验证了基础导入不会加载 Scapy、cryptography、aioquic、dnspython、Paramiko、aiocoap、paho-mqtt 或 WebSockets。 ## 证据边界 Celatim 区分了结构化能力与已执行的证据： - 存储载体报告字段宽度，以及相对于 header 的密度和在线密度。 - 定时/计数载体使用单独的速率模型。 - 阈下加密载体使用单独的熵界限。 - 证据记录标识传输、解析器验证、控制、endpoint 拓扑、工件哈希和声明状态。 - 公共索引包含哈希值和分类，而不是敏感的 payload、交互记录、主机路径或仅限审查者使用的工件。 特权实验位于 `experiments/` 目录下。它们需要明确的操作员操作，不会在正常安装、导入或非特权 CI 期间运行。 选定 nonce 的 ECDSA 交互路径同样仅用于研究。它为每个本地记录创建一个新的临时密钥，使用 `cryptography`/OpenSSL 进行曲线操作和验证，且绝不能用于生产环境或长期有效的签名密钥。 伴随的 [`rfc-tunnel-survey`](https://github.com/mjbommar/rfc-tunnel-survey) 仓库与论文、RFC 语料库、生成的图表和证据索引一起，包含了该项目的经过 manifest 验证的快照。此仓库是标准的包和 PyPI 发布源。 ## 开发 安装锁定好的开发环境并运行每个包检查门： ``` make ci ``` 该目标会运行： 1. `uv sync --locked --all-groups` 2. `uv lock --check` 3. `uv run ruff format --check .` 4. `uv run ruff check .` 5. `uv run ty check` 6. `uv run pytest` 7. `scripts/installed_wheel_smoke.py` 8. 针对每个锁定的开发和可选依赖项运行 `pip-audit` 类型检查门覆盖了该包、测试、发布脚本和生产实验驱动程序。没有目录范围的类型检查排除项；可选栈边界使用其具体的库模块，因此它们保持静态可解析。 GitHub 会在推送、拉取请求、手动调度和每周计划上运行相同的检查门，以便在新发布的依赖项公告出现时即刻被检测到，而无需等待源代码更改。 已安装的 wheel 冒烟测试会构建一个 sdist，从该 sdist 构建 wheel 包，将其（不带依赖项）安装到一个新的虚拟环境中，切换到检出目录之外的目录，并测试所有五个控制台入口点以及具有代表性的公共 API、二进制 payload 和双进程 Alice/Bob 工作流。在证明基础导入不会加载可选栈之后，它会将所有 wheel 声明的扩展依赖安装到隔离环境中，导入每个集成依赖项，并记录解析出的版本。 使用以下命令构建并验证发布分发版： ``` uv build --out-dir dist uvx twine check dist/* uvx check-wheel-contents dist/*.whl ``` ## 发布工作流 GitHub 发布会触发 `.github/workflows/release.yml`。该工作流需要一个与 `v` 完全匹配的标签，重新运行完整的 CI 和已安装包检查门，验证 wheel 元数据和内容，并将经过验证的工件传递给单独的 PyPI 发布作业。 只有最后一个作业会获得 `id-token: write` 权限，使用受保护的 `pypi` 环境，并交换 GitHub 的 OIDC 身份以获取短期有效的 PyPI 凭证。存储库中不存储任何 PyPI token。有关受信任的发布者身份和发布流程，请参阅 [`RELEASING.md`](RELEASING.md)。 Celatim 采用 [Apache License 2.0](LICENSE) 授权。发布验证要求在 wheel 中包含精确的 SPDX 表达式和打包的许可证文件。

标签：Python, 内核驱动, 数据隐写, 文件传输, 无后门, 网络信息收集, 网络协议, 网络安全, 隐私保护, 隐蔽信道