Add draft project security threat-model document

[potiuk]

Summary

This PR adds an initial draft of a project-level security
threat-model document (draft-THREAT-MODEL.md) so that automated
security scanners running against this repository have a
maintainer-facing reference for which classes of findings are
in-scope vs. out-of-scope for the project.

The document follows the rubric format used by several other ASF
projects piloting improved security-model discoverability for
agentic scanners. Every claim carries a provenance tag:

• (documented) — paraphrased from public artefacts (this repo or
  the project website), cited inline.
• (inferred) — synthesised from code structure or domain
  knowledge; the PMC has not confirmed.
• (maintainer) — confirmed by a PLC4X PMC member in response
  to this draft. (Zero in this initial draft.)

Draft stats:

• ~50 documented claims
• ~45 inferred claims (each maps to a §14 question)
• 31 open questions for maintainers in §14

§14 is the highest-leverage section: answering each question
either promotes one (inferred) tag to (maintainer) or corrects
the underlying claim.

Why "draft-" prefix?

The file is named draft-THREAT-MODEL.md rather than
SECURITY-THREAT-MODEL.md because this is a proposal for the
PMC to review — please correct, reject, or discuss as needed.
Once the PMC ratifies (or substantially edits) the content, the
file can be renamed in a follow-up PR and a discoverability
scaffold (AGENTS.md → SECURITY.md → the model) added so
scanners can mechanically follow the chain.

What this is, and what it is not

This is not a security audit. It is a working triage document
— the reference a triager holds against an inbound report to
decide whether the report is about a PLC4X vulnerability or
about caller misuse / operator misconfiguration / an out-of-scope
concern.

The draft was generated by an automated agentic security scan
being piloted by the ASF Security team; the discoverability work
is independent of any specific scan run.

How to review

1. §14 first. Each answer either confirms one (inferred) tag or
   replaces the inferred claim with the correct one.
2. After that, please skim §3 (out-of-scope) and §13 (triage
   dispositions) — those govern how a vulnerability report would
   be triaged.

Reply edits / corrections inline on the PR, or to the original
security@apache.org thread, whichever fits the PMC's workflow.

🤖 Generated with Claude Code

[sruehl]

LGTM, also it emphasizes PlcAuthentication quite often whereas at this point I don't even know what it is used by. OT Stuff is usually open like a barn door

[Copilot]

Copilot reviewed 1 out of 1 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[potiuk]

Thanks @sruehl. Fair point — you're right that in practice a lot of OT/PLC deployments run unauthenticated, and the draft over-weights PlcAuthentication. It's the driver-layer credential abstraction for the few protocols that do carry auth (e.g. OPC UA user/password, TLS client certs), but if it's rarely used in the field I'm happy to demote it from a primary boundary to a "where present" note and lead instead with the unauthenticated-by-default reality as the modeled baseline. I'll push that revision — does that match how you'd frame it?

[chrisdutz]

Generally looks good to me.

[potiuk]

Thanks @chrisdutz — approval much appreciated, and all 11 notes are folded in. Highlights:

• OPC UA defaults → secure-by-default: §14 Q14/Q15/Q16 now record that the insecure defaults aren't the supported posture. In particular the permissive certificate verifier is marked a gap to fix (VALID), not OUT-OF-MODEL, per your "should be changed and reported" — the §9 false-friend entry and §13 disposition table are updated to match.
• SPI3 forward-references captured as (maintainer) notes: tls/tls-psk transport (Q8), ETS/XML parser hardening (Q18), per-connection fixed-length ring-buffer bounding allocation (Q11/Q19), the optional debug filesystem audit-log, and the spi-module restructuring.
• Clarifications folded into §9: nonces are protocol-provided only (none beyond spec); PLC4X proxies the target PLC's permission checks and provides none of its own.

On the OPC UA cert default — happy to help file a tracking issue in the PLC4X tracker if useful, but I'll leave that to the PMC. I've replied on and resolved the threads; the model is the PMC's to merge whenever.

[potiuk]

Resolving the remaining copilot-pull-request-reviewer suggestion threads — @chrisdutz's review is folded and the PR is approved.