一个针对 **CODESYS V3 运行时协议**（TCP 11740）的开放式、净室设计（clean-room）客户端——无需专有且仅支持 Windows 的工程 IDE，即可连接、诊断并备份大量基于 CODESYS 的 PLC 和运动控制器。
本项目没有任何内容衍生自 CODESYS 的二进制文件、源代码或密钥。该协议是通过针对操作员自有硬件的被动流量捕获来记录的。请参阅[合法性](#legality)。
## 缘由
CODESYS 运行时可在 Linux 上运行，并预装在来自 500 多家供应商的 1000 多种设备型号中。与其进行通信的工程系统仅支持 Windows——因此，维护、诊断、改造和备份都需要 Windows 虚拟机。一个能够处理运行时协议的轻量级客户端消除了对最重要操作的这一依赖：身份验证、浏览设备文件系统、读写文件、启动/停止应用程序以及提取完整备份。
## 抓包验证
数据帧格式和设备身份握手是使用 [`tools/decode_capture.py`](tools/decode_capture.py)（无依赖项），针对运行 3.5.14.10 版本运行时的控制器，从实时捕获中**逐字节**解码出来的——绝非臆测。
## 路线图
| 层级 | 功能 | 状态 |
| --- | --- | --- |
| Block driver | TCP 帧封装（magic `0xE8170100` + length） | 已解码 |
| Datagram | 节点地址/名称解析，设备信息回复 | 已解码 |
| Services | `protocol_id` 检测（`0xCD55` 明文） | 已确认 |
| Channel | 打开通道，可靠的 BLK 传输 | 进行中 |
| `CmpDevice` | 登录/会话 | 计划中 |
| `CmpFileTransfer` | 列出并拉取文件——备份路径 | 已捕获，待解码 |
| `CmpApp` | 应用程序列表，启动/停止 | 计划中 |
非目标：重新实现 IDE 或运行时。如需开放式 PLC 工具链，请使用 **Beremiz**、**OpenPLC** 或 **RuSTy**。
## 快速开始
```
# 在一个连接到 controller 的主机 NIC 上抓取实时会话，然后解码它：
python3 tools/decode_capture.py capture/codesys-live-*.pcap
# -> block-driver 帧、0xCD55 服务标记，以及 controller 的 Type / Id / Version / name
```
## 布局
```
docs/protocol-notes.md protocol map: layers, headers, services, tags, sources
docs/decoded-handshake.md capture-verified decode (framing + device identity) with annotated hex
docs/re-playbook.md methodology for RE'ing similar PLC / controller platforms
docs/img/ diagrams: protocol stack, decoded handshake, device-identity access
tools/decode_capture.py dependency-free pcap decoder (framing + device-info)
capture/ passive capture harness and notes on existing dissectors
src/codesys_client/ client library (protocol constants; wire I/O pending)
samples/ sanitized example captures (real pcaps are git-ignored)
```
## 先前研究
本项目建立在公开研究的基础之上；但并未照搬其内容。
- **Kaspersky ICS-CERT** — *Security research: CODESYS Runtime* — 最深入的公开协议映射。
- **Rapid7** — *A Deep Dive into Reversing CODESYS*；Wireshark 插件和 Nmap NSE。
- **Microsoft CoDe16** — V3 协议的 Wireshark 解析器。
- **fridgebuyer/codesys3-dissector** — Lua 解析器。
- **reidmefirst/codesys-controllers** — 已知设备、端口和版本。
## 合法性
IEC 61131-3 是一项开放的 ISO/IEC 标准。这是为了与操作员自有硬件实现**互操作性**而进行的净室协议逆向工程，这在很大程度上受法律保护（例如欧盟软件指令中的互操作性条款）。请勿复制或重新分发 CODESYS 的二进制文件、代码或密钥。仅限对您拥有授权访问权限的设备使用。
## 许可证
**Apache-2.0** — 参见 [`LICENSE`](LICENSE)。该许可宽松自由，并包含在工业自动化领域至关重要的明确专利授权。贡献内容将按同一许可证接受。