docs(plc): add soft-PLC architecture + CODESYS/Yocto lifecycle diagram

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 <noreply@anthropic.com>

compliance-agent/src/pipeline/orchestrator.rs

@@ -409,11 +409,17 @@ impl PipelineOrchestrator {
             new_count += self.run_ics_probe(target, &target_id, scan_run_id).await?;
         }
         if plc || ics {
-            // PLC/SPS device: also DAST against a WebVisu / exposed endpoint. The
-            // control-logic scan already consumed the code artifact, so the SAST
-            // pipeline is not re-run.
+            // PLC/SPS device: also DAST against a WebVisu / exposed endpoint, but
+            // only when DAST is actually planned — a device reachable only over an
+            // industrial protocol (e.g. modbus://) has no web surface to crawl, and
+            // running DAST there just fails at reconnaissance. Gating here (not only
+            // at provisioning) also stops a DAST target left over from an earlier
+            // run from re-triggering. The control-logic scan already consumed the
+            // code artifact, so the SAST pipeline is not re-run.
+            if plan.has(ScanType::Dast) {
                 self.update_phase(scan_run_id, "dast_scanning").await;
                 self.maybe_trigger_dast(&target_id, scan_run_id).await;
+            }
             return Ok(new_count);
         }
 

compliance-core/src/scan_matrix.rs

@@ -14,8 +14,12 @@ use crate::models::{ArtifactKind, OnboardedTarget, ScanType, TargetType};
 pub enum ArtifactRequirement {
     /// Source code — a git repo or a source archive.
     Code,
-    /// A reachable running instance (live URL / endpoint).
+    /// A reachable running instance (any live URL / endpoint, scheme-agnostic —
+    /// e.g. the ICS probe works off the host:port of a modbus:// or http:// ref).
     RunningUrl,
+    /// A reachable **web** endpoint — a live URL with an http(s) scheme. DAST is
+    /// an HTTP crawler, so a modbus:// / opc.tcp:// endpoint does not satisfy it.
+    HttpUrl,
     /// A firmware image / binary blob.
     Firmware,
     /// A PLC project (PLCopen XML or Structured Text).
@@ -134,7 +138,7 @@ fn sast_umbrella() -> Vec<ScanRule> {
 /// The rule set for a target type. Scans that are never applicable to a type are
 /// simply absent (e.g. DAST is not listed for a PLC target).
 pub fn rules_for(target_type: TargetType) -> Vec<ScanRule> {
-    use ArtifactRequirement::{Firmware, Mobile, Plc, RunningUrl};
+    use ArtifactRequirement::{Firmware, HttpUrl, Mobile, Plc, RunningUrl};
     match target_type {
         TargetType::WebApp | TargetType::BackendService => {
             let mut r = sast_umbrella();
@@ -142,7 +146,7 @@ pub fn rules_for(target_type: TargetType) -> Vec<ScanRule> {
                 ScanType::Dast,
                 true,
                 "Dynamic scan of the running endpoint",
-                RunningUrl,
+                HttpUrl,
             ));
             r
         }
@@ -203,7 +207,7 @@ pub fn rules_for(target_type: TargetType) -> Vec<ScanRule> {
                 ScanType::Dast,
                 false,
                 "Dynamic scan of exposed network services (if any)",
-                RunningUrl,
+                HttpUrl,
             ));
             r
         }
@@ -249,7 +253,7 @@ pub fn rules_for(target_type: TargetType) -> Vec<ScanRule> {
                     ScanType::Dast,
                     false,
                     "Dynamic scan of the running device (WebVisu / exposed services)",
-                    RunningUrl,
+                    HttpUrl,
                 ),
                 ScanRule::new(
                     ScanType::IcsProbe,
@@ -285,7 +289,9 @@ pub fn supports_pentest(target_type: TargetType) -> bool {
 fn representative_kind(req: ArtifactRequirement) -> Option<ArtifactKind> {
     match req {
         ArtifactRequirement::Code => Some(ArtifactKind::GitRepo),
-        ArtifactRequirement::RunningUrl => Some(ArtifactKind::LiveUrl),
+        ArtifactRequirement::RunningUrl | ArtifactRequirement::HttpUrl => {
+            Some(ArtifactKind::LiveUrl)
+        }
         ArtifactRequirement::Firmware => Some(ArtifactKind::FirmwareImage),
         ArtifactRequirement::Plc => Some(ArtifactKind::PlcProject),
         ArtifactRequirement::Mobile => Some(ArtifactKind::MobilePackage),
@@ -294,11 +300,22 @@ fn representative_kind(req: ArtifactRequirement) -> Option<ArtifactKind> {
     }
 }
 
+/// Whether a live-URL reference is an http(s) web endpoint (vs. an industrial
+/// endpoint like `modbus://` / `opc.tcp://`, which DAST cannot crawl).
+fn is_http_url(source_ref: &str) -> bool {
+    let s = source_ref.trim();
+    s.starts_with("http://") || s.starts_with("https://")
+}
+
 /// Whether the target carries an artifact that satisfies the requirement.
 fn requirement_satisfied(req: ArtifactRequirement, target: &OnboardedTarget) -> bool {
     match req {
         ArtifactRequirement::Code => target.code_artifact().is_some(),
         ArtifactRequirement::RunningUrl => target.has(ArtifactKind::LiveUrl),
+        ArtifactRequirement::HttpUrl => target
+            .artifacts
+            .iter()
+            .any(|a| a.kind == ArtifactKind::LiveUrl && is_http_url(&a.source_ref)),
         ArtifactRequirement::Firmware => target.has(ArtifactKind::FirmwareImage),
         // A PLC project artifact, or a code artifact (git repo / source archive)
         // holding the control logic as PLCopen XML / ST exports — the common way
@@ -322,6 +339,10 @@ pub fn applicable_scans(target: &OnboardedTarget) -> Vec<ScanOption> {
             let required_artifact = representative_kind(rule.requires);
             let blocked_reason = if satisfied {
                 None
+            } else if rule.requires == ArtifactRequirement::HttpUrl {
+                // A live URL may be present but non-HTTP (e.g. modbus://): be
+                // specific so the user knows DAST needs a web endpoint.
+                Some("no http(s) live URL — DAST needs a web endpoint".to_string())
             } else {
                 Some(match required_artifact {
                     Some(kind) => format!("no {kind} artifact provided"),
@@ -462,6 +483,49 @@ mod tests {
             .is_none());
     }
 
+    #[test]
+    fn plc_with_modbus_url_offers_ics_probe_but_blocks_dast() {
+        // A soft-PLC reachable only over Modbus/TCP (no WebVisu). The ICS probe
+        // is applicable (it works off host:port), but DAST — an HTTP crawler —
+        // must be blocked so it isn't offered/run against a non-web endpoint.
+        let t = target_with(
+            TargetType::PlcSps,
+            vec![Artifact::live_url("modbus://plc-sim:502")],
+        );
+        let opts = applicable_scans(&t);
+        let ics = option(&opts, ScanType::IcsProbe).expect("ics probe offered");
+        assert!(
+            ics.blocked_reason.is_none(),
+            "ICS probe should be unblocked for a modbus:// endpoint"
+        );
+        assert!(!ics.default_on, "ICS probe stays opt-in (default-off)");
+        let dast = option(&opts, ScanType::Dast).expect("dast listed");
+        assert!(
+            dast.blocked_reason.is_some(),
+            "DAST must be blocked without an http(s) endpoint"
+        );
+        assert!(!dast.default_on);
+    }
+
+    #[test]
+    fn plc_with_http_webvisu_offers_both_dast_and_ics_probe() {
+        // A PLC exposing a WebVisu over HTTP: both DAST (web) and the ICS probe
+        // (OT ports on the same host) are applicable.
+        let t = target_with(
+            TargetType::PlcSps,
+            vec![Artifact::live_url("http://plc.local/webvisu")],
+        );
+        let opts = applicable_scans(&t);
+        assert!(option(&opts, ScanType::Dast)
+            .expect("dast offered")
+            .blocked_reason
+            .is_none());
+        assert!(option(&opts, ScanType::IcsProbe)
+            .expect("ics probe offered")
+            .blocked_reason
+            .is_none());
+    }
+
     #[test]
     fn pentest_support_matches_reachable_families() {
         assert!(supports_pentest(TargetType::WebApp));

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<br/>BSP + RT kernel"] --> A2["Bake in the CODESYS<br/>Control for Linux runtime"] --> A3["bitbake → device image<br/>.wic / .tar + manifest"]
+    end
+    subgraph TB2["Track B · Control application — built by the machine builder / customer"]
+        direction LR
+        B1["CODESYS IDE<br/>ST / LD / FBD / SFC + WebVisu"] --> B2["Reference CODESYS +<br/>vendor libraries"] --> B3["Compile → download<br/>to device (gateway 11740)"]
+    end
+
+    A3 --> DEV(["Running soft-PLC device<br/>SoC + Linux + runtime + control app<br/>Modbus · OPC UA · EtherNet/IP · WebVisu"])
+    B3 --> DEV
+
+    subgraph CERT["What Certifai scans — one layer per artifact"]
+        direction LR
+        S1["Firmware layer<br/>FirmwareStatic · SBOM · CVE"]
+        S2["Control-logic layer<br/>PLC SAST — ST + FBD/LD"]
+        S3["Control-app SBOM<br/>libraries + runtime → CVE"]
+        S4["Running layer<br/>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