From c1e0a80f90b97918449913d874c19751b96f0582 Mon Sep 17 00:00:00 2001 From: Sharang Parnerkar <30073382+mighty840@users.noreply.github.com> Date: Thu, 16 Jul 2026 23:52:47 +0200 Subject: [PATCH] docs(plc): add soft-PLC architecture + CODESYS/Yocto lifecycle diagram MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A CODESYS controller is not a monolithic appliance — it's a SoC + Linux + software runtime + control app, built along two independent tracks (the Yocto device platform by the OEM, the IEC 61131-3 control application by the machine builder). Add an "Anatomy" section to the PLC guide: the classic-vs-soft-PLC table, a Mermaid diagram of the two development tracks converging on the running device with the artifact→scan mapping, and a callout on where Yocto fits (the firmware layer, its own artifact). Explains why PlcSps is a composite target. Co-Authored-By: Claude Opus 4.8 --- docs/guide/plc.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/docs/guide/plc.md b/docs/guide/plc.md index fb65bc8..cf0a7fd 100644 --- a/docs/guide/plc.md +++ b/docs/guide/plc.md @@ -11,6 +11,72 @@ the control application *and* the device it runs on. | A device firmware image | Firmware SBOM / CVE (opt-in) | | A reachable endpoint (WebVisu, OPC UA) | DAST / pentest (opt-in) | +## Anatomy: a soft PLC is a SoC + Linux + runtime + +A CODESYS controller is **not** a monolithic appliance like a classic Siemens +S7. It is **PC-based ("soft") control** — commodity silicon running a +general-purpose Linux, with a **software PLC runtime** as just another process: + +| Classic PLC (e.g. Siemens S7) | Soft PLC (CODESYS-on-Yocto, OpenPLC-on-Raspbian) | +| --- | --- | +| Proprietary hardware + firmware | Commodity SoC (x86 / ARM) | +| Proprietary OS | General-purpose Linux (a **Yocto** image, or Raspbian) | +| Proprietary runtime | Software runtime (**CODESYS Control**, or OpenPLC) | +| STEP7 / TIA project | IEC 61131-3 control app (ST / LD / FBD / SFC) | + +Because of this, the device is built along **two independent tracks**, by +different people, on different timelines, and shipped separately. It also +inherits the **entire Linux / IT attack surface on top of** the OT / control +one — which is exactly why a PLC/SPS target is treated as a **composite**: +Certifai ingests one artifact per layer and scans each with the right pipeline. + +```mermaid +flowchart TB + subgraph TA["Track A · Device platform — built by the hardware OEM / vendor"] + direction LR + A1["Yocto / OpenEmbedded
BSP + RT kernel"] --> A2["Bake in the CODESYS
Control for Linux runtime"] --> A3["bitbake → device image
.wic / .tar + manifest"] + end + subgraph TB2["Track B · Control application — built by the machine builder / customer"] + direction LR + B1["CODESYS IDE
ST / LD / FBD / SFC + WebVisu"] --> B2["Reference CODESYS +
vendor libraries"] --> B3["Compile → download
to device (gateway 11740)"] + end + + A3 --> DEV(["Running soft-PLC device
SoC + Linux + runtime + control app
Modbus · OPC UA · EtherNet/IP · WebVisu"]) + B3 --> DEV + + subgraph CERT["What Certifai scans — one layer per artifact"] + direction LR + S1["Firmware layer
FirmwareStatic · SBOM · CVE"] + S2["Control-logic layer
PLC SAST — ST + FBD/LD"] + S3["Control-app SBOM
libraries + runtime → CVE"] + S4["Running layer
ICS probe · DAST (WebVisu)"] + end + + A3 -. firmware image .-> S1 + B1 -. PLCopen XML / ST via git .-> S2 + B2 -. projectarchive (zip) .-> S3 + DEV -. live URL / provisioned .-> S4 + + classDef yocto fill:#fde68a,stroke:#b45309,color:#111 + classDef codesys fill:#bfdbfe,stroke:#1d4ed8,color:#111 + classDef dev fill:#e9d5ff,stroke:#7e22ce,color:#111 + classDef cert fill:#bbf7d0,stroke:#15803d,color:#111 + class A1,A2,A3 yocto + class B1,B2,B3 codesys + class DEV dev + class S1,S2,S3,S4 cert +``` + +::: tip Where Yocto fits +Yocto is **Track A** — the *build system* for the device platform. It produces +the Linux image and bakes in the CODESYS runtime, so it is the **firmware +layer**, entirely separate from the control application. Hand it to Certifai as +its own **firmware image** artifact (scanned by the firmware pipeline, not the +PLC pipeline). The device OS need not be Yocto — Raspbian/Debian/Buildroot, or +even an RTOS / bare-metal, are all possible — but Yocto is the common, +product-grade industrial choice. +::: + ## Two ways to deliver the project You can either **upload** the project when onboarding, or point Certifai at a -- 2.54.0