feat(plc): ingest CODESYS projects from a git repo (SAST + SBOM) (#171)

docs/.vitepress/config.mts

@@ -20,6 +20,7 @@ export default withMermaid(defineConfig({
           { text: 'Getting Started', link: '/guide/getting-started' },
           { text: 'Adding Repositories', link: '/guide/repositories' },
           { text: 'Running Scans', link: '/guide/scanning' },
+          { text: 'PLC / SPS (CODESYS)', link: '/guide/plc' },
           { text: 'Understanding Findings', link: '/guide/findings' },
           { text: 'SBOM & Licenses', link: '/guide/sbom' },
           { text: 'Issues & Tracking', link: '/guide/issues' },

docs/guide/plc.md

@@ -0,0 +1,78 @@
+# PLC / SPS Projects (CODESYS)
+
+Certifai analyzes industrial control logic (IEC 61131-3) for PLC/SPS targets such
+as CODESYS projects. A single PLC/SPS target is treated as a **composite device**:
+the control application *and* the device it runs on.
+
+| What you provide | What Certifai does |
+| --- | --- |
+| PLC project (PLCopen XML / ST, or a `.projectarchive`) | **Control-logic SAST** — semantic security rules over ST **and** graphical FBD/LD |
+| A `.projectarchive` | **Control-app SBOM** — the referenced CODESYS libraries + the runtime version, matched against known CVEs |
+| A device firmware image | Firmware SBOM / CVE (opt-in) |
+| A reachable endpoint (WebVisu, OPC UA) | DAST / pentest (opt-in) |
+
+## Two ways to deliver the project
+
+You can either **upload** the project when onboarding, or point Certifai at a
+**git repository** (recommended — every scan is just a `git pull`, no re-upload).
+
+### Option A — Upload
+
+On the onboarding wizard, choose target type **PLC / SPS**, then attach a **PLC
+project** artifact and pick its format:
+
+- **PLCopen XML** (`.xml`) — export from CODESYS via *Project → Export PLCopenXML*.
+- **Structured Text** (`.st`) — a raw ST file.
+- **Project archive** (`.projectarchive`) — *File → Project Archive → Save/Send
+  Archive…* with **"Referenced libraries"** ticked. This is the only form that
+  also yields the **library + runtime SBOM**.
+
+### Option B — Git repository (recommended)
+
+Attach a **Git repository** artifact to the PLC/SPS target. Certifai clones it and
+runs the control-logic scan over the exported source in the repo.
+
+## Best-case git repository layout
+
+Because the binary `.project` does not diff or merge in git, commit **textual
+exports** for review-friendly SAST, and include the **`.projectarchive`** so the
+library/runtime SBOM is available too:
+
+```text
+my-plc-project/
+├── src/
+│   ├── PLC_PRG.xml          # PLCopen XML export (ST or FBD/LD) — one per POU
+│   ├── PumpController.xml
+│   ├── SafetyInterlock.xml
+│   └── GVL.xml              # global variable lists, also as PLCopen XML
+├── PumpStation.projectarchive   # optional but recommended → library + runtime SBOM
+└── README.md
+```
+
+**Guidelines**
+
+- **Export to PLCopen XML** (`Project → Export PLCopenXML`), one file per POU, and
+  commit those. ST, **and graphical FBD/LD**, are both analyzed.
+- Alternatively commit raw `.st` / `.exp` / `.scl` files — also analyzed.
+- **Do not** commit only the binary `.project` — it cannot be parsed (and does not
+  diff). If you want the library SBOM, commit the **`.projectarchive`** as well.
+- CODESYS's built-in Git integration, which stores an exported representation,
+  works too — as long as the committed form is PLCopen XML / textual.
+
+::: tip What unlocks what
+- **Control-logic SAST** needs textual source in the repo (PLCopen XML or `.st`).
+- **Library + runtime SBOM** needs a **`.projectarchive`** — PLCopen XML exports do
+  **not** carry the referenced libraries.
+:::
+
+## What the scanner finds
+
+The control-logic rules are CWE-mapped and include: hardcoded credentials
+(CWE-798), default/weak passwords (CWE-1393), safety interlock / watchdog bypass
+(CWE-1384), unchecked array indexing (CWE-129), division-by-zero (CWE-369,
+guard-aware), cleartext/insecure communication (CWE-319), insecure protocol ports
+(CWE-319, e.g. Modbus 502, FTP 21, Telnet 23), and unstructured jumps (CWE-691).
+
+The **SBOM** view lists the CODESYS libraries (`pkg:codesys/<name>@<version>`) and
+the runtime; matching runtime components (e.g. the `Cmp*` / `3SLicense` libraries)
+surface real CODESYS advisories as CVE alerts.