[GH-ISSUE #3640] [Feature] CODESYS and IEC 61131-3 reverse engineering: POUs, task schedules, symbol tables, and PLC logic reconstruction #1360

New issue

Open

opened 2026-10-16 21:04:40 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:04:40 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3640

Summary

In industrial automation, critical infrastructure (energy grids, water treatment, transportation, manufacturing), and Operational Technology (OT), CODESYS (by CODESYS Group) is the de facto hardware-independent runtime and engineering platform compliant with IEC 61131-3. It is deployed across hundreds of programmable logic controller (PLC) vendors worldwide, including WAGO, Beckhoff (TwinCAT 2/3), Schneider Electric (Machine Expert / SoMachine), Eaton, Festo, ABB, and Bosch Rexroth.

While issue #3494 addresses static format inspection for Rockwell / Allen-Bradley RSLogix 500 .RSS files, the European and global industrial automation ecosystem heavily relies on CODESYS. In incident response, security auditing (identifying malicious logic injections, Stuxnet/Industroyer-style tampering), and industrial digital preservation, security researchers need to analyze PLC programs offline without installing proprietary vendor programming IDEs.

This feature proposal introduces dedicated CODESYS & IEC 61131-3 Reverse Engineering to REA, enabling static unpacking of CODESYS V2 (.pro) and V3 (.project / .app) containers, extraction of Program Organization Units (POUs), symbol database parsing, I/O hardware mapping, and logic reconstruction across Structured Text (ST), Ladder Diagram (LD), and Function Block Diagram (FBD).

Technical Capabilities & Architecture

                                    +-----------------------------------------+
                                    | Input: CODESYS Project (.pro, .project) |
                                    |        or Controller Image (.app, .boot)|
                                    +--------------------+--------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                                                               |
                         v                                                               v
           +---------------------------+                                   +---------------------------+
           | CODESYS V2 / V3 Container |                                   | Device Tree & Hardware    |
           | Unpacker (OPC ZIP & OLE)  |                                   | Mapping (EtherCAT/Modbus) |
           +-------------+-------------+                                   +-------------+-------------+
                         |                                                               |
                         +-------------------------------+-------------------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | Symbol Database & GVL Parser          |
                                     | (.sdb, .sym, .xml, memory offsets)    |
                                     +-------------------+-------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                               |                               |
                         v                               v                               v
           +---------------------------+   +---------------------------+   +---------------------------+
           | POU Logic Reconstruction  |   | Task Scheduler & Cyclic   |   | Compiled Runtime Binary   |
           | (ST, Ladder, FBD, SFC)    |   | Execution Configuration   |   | Analysis (.app / libRTS)  |
           +-------------+-------------+   +-------------+-------------+   +-------------+-------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | REA Evidence: Reconstructed PLC Logic,|
                                     | I/O Tags, Task Configuration & Graph  |
                                     +---------------------------------------+

1. Project Container Unpacking (.pro, .project, .app)

CODESYS V2.3 Projects (.pro): Parse legacy binary project structures, extracting embedded source pools, configuration files, and compile info.
CODESYS V3.x Projects (.project): Parse modern Open Packaging Conventions (ZIP) archives, extracting projectinfo.xml, device descriptors, library references, and XML POU definitions.
Target Boot Applications (.app / .boot): Parse compiled controller binary images deployed directly to the PLC filesystem, extracting header metadata, segment tables, and program memory sections.

2. Symbol Database & Global Variable Lists (GVL)

Symbol Files (.sym, .sdb, .xml): Parse CODESYS symbol tables to extract:
- Global Variable Lists (GVLs) and Persistent / Retain variables (VAR_GLOBAL RETAIN).
- Physical memory address mappings (%IX input bits, %QX output bits, %MX memory markers, byte/word/dword offsets).
- User-defined data types (TYPE ... STRUCT, ENUM, subranges).
- Network export configurations (OPC UA nodes, Modbus registers, CANopen object dictionaries).

3. Program Organization Unit (POU) Logic Reconstruction

POU Classification: Categorize organizational units into PROGRAM, FUNCTION_BLOCK, and FUNCTION.
Multi-Language Logic Inversion:
- Structured Text (ST): Parse and format high-level algorithmic control logic (IF/THEN/ELSE, CASE, FOR, WHILE, arithmetic expressions, and function calls).
- Ladder Diagram (LD): Reconstruct rungs, parallel branches, normally-open/normally-closed contacts, set/reset coils, timers (TON, TOF), and counters (CTU, CTD).
- Function Block Diagram (FBD): Reconstruct connected functional blocks, dataflow lines, negation flags, and feedback loops.
- Sequential Function Chart (SFC): Reconstruct finite state machine steps, initial steps, transitions, transition conditions, and action qualifiers (N, S, R, P).

4. Task Scheduling & Execution Architecture

Task Configuration: Extract cyclic task intervals (cycle time in ms), priority levels (0–31), watchdog timeouts, and sensitivity settings.
Event & External Triggers: Identify event-driven tasks, hardware interrupt handlers, and freewheeling background tasks.
POU Call Tree: Map the root execution order of POUs assigned to each task.

5. Hardware I/O & Fieldbus Topology

Device Tree: Parse controller hardware configuration, bus masters, and slave devices.
Fieldbus Integration: Map variables mapped to fieldbus networks: EtherCAT PDOs/SDOs, Profinet I/O modules, CANopen, and Modbus TCP/RTU slave registers.

Acceptance Criteria

Introduce analyze_codesys_project in REA CLI and MCP contracts, accepting .project, .pro, and .app files.
Safely unpack CODESYS V3 .project archives and extract all POU XML nodes.
Reconstruct Structured Text (ST) and Ladder (LD) rungs into structured JSON representations.
Extract symbol tables mapping memory addresses (%IX, %QX, %MX) to variable names and types.
Output task scheduling parameters (interval ms, priority) and POU call graphs in structured evidence.

#3494 [Feature] Static format inspection for RSLogix 500 .RSS files
#3153 [Feature] Inventory Windows Installer (.msi / OLE CFB) packages read-only
#3628 [Feature] Microsoft Office reverse engineering

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3640 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Game & Engine RE](https://img.shields.io/badge/domain-game_&_engine_RE-green.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ## Summary In industrial automation, critical infrastructure (energy grids, water treatment, transportation, manufacturing), and Operational Technology (OT), **CODESYS** (by CODESYS Group) is the de facto hardware-independent runtime and engineering platform compliant with **IEC 61131-3**. It is deployed across hundreds of programmable logic controller (PLC) vendors worldwide, including WAGO, Beckhoff (TwinCAT 2/3), Schneider Electric (Machine Expert / SoMachine), Eaton, Festo, ABB, and Bosch Rexroth. While issue #3494 addresses static format inspection for Rockwell / Allen-Bradley RSLogix 500 `.RSS` files, the European and global industrial automation ecosystem heavily relies on CODESYS. In incident response, security auditing (identifying malicious logic injections, Stuxnet/Industroyer-style tampering), and industrial digital preservation, security researchers need to analyze PLC programs offline without installing proprietary vendor programming IDEs. This feature proposal introduces dedicated **CODESYS & IEC 61131-3 Reverse Engineering** to REA, enabling static unpacking of CODESYS V2 (`.pro`) and V3 (`.project` / `.app`) containers, extraction of Program Organization Units (POUs), symbol database parsing, I/O hardware mapping, and logic reconstruction across Structured Text (ST), Ladder Diagram (LD), and Function Block Diagram (FBD). --- ## Technical Capabilities & Architecture ``` +-----------------------------------------+ | Input: CODESYS Project (.pro, .project) | | or Controller Image (.app, .boot)| +--------------------+--------------------+ | +-------------------------------+-------------------------------+ | | v v +---------------------------+ +---------------------------+ | CODESYS V2 / V3 Container | | Device Tree & Hardware | | Unpacker (OPC ZIP & OLE) | | Mapping (EtherCAT/Modbus) | +-------------+-------------+ +-------------+-------------+ | | +-------------------------------+-------------------------------+ | v +---------------------------------------+ | Symbol Database & GVL Parser | | (.sdb, .sym, .xml, memory offsets) | +-------------------+-------------------+ | +-------------------------------+-------------------------------+ | | | v v v +---------------------------+ +---------------------------+ +---------------------------+ | POU Logic Reconstruction | | Task Scheduler & Cyclic | | Compiled Runtime Binary | | (ST, Ladder, FBD, SFC) | | Execution Configuration | | Analysis (.app / libRTS) | +-------------+-------------+ +-------------+-------------+ +-------------+-------------+ | v +---------------------------------------+ | REA Evidence: Reconstructed PLC Logic,| | I/O Tags, Task Configuration & Graph | +---------------------------------------+ ``` ### 1. Project Container Unpacking (.pro, .project, .app) - **CODESYS V2.3 Projects (`.pro`):** Parse legacy binary project structures, extracting embedded source pools, configuration files, and compile info. - **CODESYS V3.x Projects (`.project`):** Parse modern Open Packaging Conventions (ZIP) archives, extracting `projectinfo.xml`, device descriptors, library references, and XML POU definitions. - **Target Boot Applications (`.app` / `.boot`):** Parse compiled controller binary images deployed directly to the PLC filesystem, extracting header metadata, segment tables, and program memory sections. ### 2. Symbol Database & Global Variable Lists (GVL) - **Symbol Files (`.sym`, `.sdb`, `.xml`):** Parse CODESYS symbol tables to extract: - Global Variable Lists (GVLs) and Persistent / Retain variables (`VAR_GLOBAL RETAIN`). - Physical memory address mappings (`%IX` input bits, `%QX` output bits, `%MX` memory markers, byte/word/dword offsets). - User-defined data types (`TYPE ... STRUCT`, `ENUM`, subranges). - Network export configurations (OPC UA nodes, Modbus registers, CANopen object dictionaries). ### 3. Program Organization Unit (POU) Logic Reconstruction - **POU Classification:** Categorize organizational units into `PROGRAM`, `FUNCTION_BLOCK`, and `FUNCTION`. - **Multi-Language Logic Inversion:** - **Structured Text (ST):** Parse and format high-level algorithmic control logic (`IF/THEN/ELSE`, `CASE`, `FOR`, `WHILE`, arithmetic expressions, and function calls). - **Ladder Diagram (LD):** Reconstruct rungs, parallel branches, normally-open/normally-closed contacts, set/reset coils, timers (`TON`, `TOF`), and counters (`CTU`, `CTD`). - **Function Block Diagram (FBD):** Reconstruct connected functional blocks, dataflow lines, negation flags, and feedback loops. - **Sequential Function Chart (SFC):** Reconstruct finite state machine steps, initial steps, transitions, transition conditions, and action qualifiers (N, S, R, P). ### 4. Task Scheduling & Execution Architecture - **Task Configuration:** Extract cyclic task intervals (cycle time in ms), priority levels (0–31), watchdog timeouts, and sensitivity settings. - **Event & External Triggers:** Identify event-driven tasks, hardware interrupt handlers, and freewheeling background tasks. - **POU Call Tree:** Map the root execution order of POUs assigned to each task. ### 5. Hardware I/O & Fieldbus Topology - **Device Tree:** Parse controller hardware configuration, bus masters, and slave devices. - **Fieldbus Integration:** Map variables mapped to fieldbus networks: EtherCAT PDOs/SDOs, Profinet I/O modules, CANopen, and Modbus TCP/RTU slave registers. --- ## Acceptance Criteria 1. Introduce `analyze_codesys_project` in REA CLI and MCP contracts, accepting `.project`, `.pro`, and `.app` files. 2. Safely unpack CODESYS V3 `.project` archives and extract all POU XML nodes. 3. Reconstruct Structured Text (ST) and Ladder (LD) rungs into structured JSON representations. 4. Extract symbol tables mapping memory addresses (`%IX`, `%QX`, `%MX`) to variable names and types. 5. Output task scheduling parameters (interval ms, priority) and POU call graphs in structured evidence. --- ## Related - #3494 [Feature] Static format inspection for RSLogix 500 .RSS files - #3153 [Feature] Inventory Windows Installer (.msi / OLE CFB) packages read-only - #3628 [Feature] Microsoft Office reverse engineering

bsakaguchi referenced this issue

2026-10-17 21:10:44 +00:00

[PR #1360] [MERGED] fix(cli): stream JSON inputs beyond the whole-document string limit #2826

bsakaguchi referenced this issue

2026-11-01 21:11:26 +00:00

[GH-ISSUE #8190] [Design] Investigate partial outgoing data-reference evidence for Kuna functions #6474