# Code Review — ScriptAnalysis

| Field | Value |
|-------|-------|
| Module | `src/ZB.MOM.WW.ScadaBridge.ScriptAnalysis` |
| Design doc | `docs/requirements/Component-ScriptAnalysis.md` |
| Status | Reviewed |
| Last reviewed | 2026-06-20 |
| Reviewer | claude-agent |
| Commit reviewed | `4307c381` |
| Open findings | 0 |

## Summary

This is the first formal review of the ScriptAnalysis component (#25), the single
authoritative source of truth for the ScadaBridge script trust boundary. The module
is small (5 source files, ~700 lines) and well-documented, and its core design is
**sound**: the trust verdict is genuinely **semantic** (Roslyn symbol resolution in
Pass 1), not a string/regex deny-list, so the classic spelling-based evasions —
aliases, `using static`, `global::`, partial-namespace qualification — are correctly
defeated by resolving the symbol rather than the text. The reflection-gateway
hardening (Pass 2) closes the `typeof(x).Assembly.GetType("System.IO.File")` class of
bypass that a namespace-only deny-list cannot see. All four documented consumers
(Template Engine, Site Runtime, Inbound API, Central UI) genuinely delegate to
`ScriptTrustValidator.FindViolations` and **hard-reject** on a non-empty result; none
re-implements or relaxes the policy. A reflection-based parity guard for the
compile-only surfaces exists in `SiteRuntime.Tests`. **No working trust-boundary
bypass was found at HEAD against the production (cluster-hosted) configuration.**

That said, the review surfaced several real issues. The highest-impact one is a
**silent degradation of the semantic pass when `TRUSTED_PLATFORM_ASSEMBLIES` is
unavailable** (single-file/AOT/trimmed host): `AnalysisReferences` falls back to the
5-assembly minimal set, after which a *bare* forbidden type inside an *allowed*
namespace (the documented `Process` via `using System.Diagnostics;` case) no longer
resolves and slips Pass 1 entirely — and Pass 2 never flags bare identifiers, only
dotted spellings (ScriptAnalysis-001). This is the only finding that can weaken the
verdict, and it is narrow (the production hosts carry a TPA list, and the downstream
real `Compile` gate catches it for two of the four consumers), so it is rated High
rather than Critical. The remaining findings are robustness/correctness/doc issues:
the semantic pass swallows nothing but the unresolved-symbol fallback is namespace-
spelling-dependent (Medium); `nameof(...)` over-flags legitimate non-forbidden uses
inconsistently (Low, documented-intentional but worth pinning); `ParseDiagnostics`/
`Compile` drop warnings despite the doc promising "errors and warnings"; there is no
caching/throttling of the Roslyn compilations (performance); the `extraReferences`
XML-doc on `FindViolations` is contradicted by the Central UI consumer; and the
adversarial test corpus, though good, has gaps (no extension-method, no
TPA-fallback, no `file`-scoped/`unsafe`, no verbatim/Unicode-escape identifier
cases). The trust boundary is **semantically sound in production**; the open items
harden the edges and align the spec.

## Checklist coverage

| # | Category | Examined | Notes |
|---|----------|----------|-------|
| 1 | Correctness & logic bugs | ☑ | `nameof` over-flags inconsistently (ScriptAnalysis-005); `GetSyntacticScopes` only returns text for dotted names so a bare unresolved forbidden identifier yields no scope (root of ScriptAnalysis-001/002). |
| 2 | Akka.NET conventions | ☑ | No issues found — module has no actors, no Akka dependency (by design; csproj references only Roslyn + Commons). Stateless static APIs, thread-safe. |
| 3 | Concurrency & thread safety | ☑ | No issues found — all public surfaces are static/stateless; the shared `static readonly` policy collections are read-only after init; `HardeningWalker` is per-call. `AnalysisReferences` eager-built once at type init. |
| 4 | Error handling & resilience | ☑ | `RoslynScriptCompiler.Compile` converts exceptions into a fail-the-gate error entry (fail-safe). `BuildAnalysisReferences` swallows per-assembly read errors and silently falls back to the minimal set — the silent fallback is the resilience gap (ScriptAnalysis-001). |
| 5 | Security | ☑ | Semantic (symbol-based) verdict — no spelling bypass found in production. One conditional degradation (TPA-absent host) weakens Pass 1 to spelling-dependent (ScriptAnalysis-001); `extraReferences` can never cause a false allow (verified). Defence-in-depth only, as documented — not a runtime sandbox (ScriptAnalysis-008). |
| 6 | Performance & resource management | ☑ | No compilation caching/throttling; every gate call re-parses, rebuilds a compilation, and re-runs Roslyn — `FindViolations` builds a fresh `CSharpCompilation` against the *full framework* reference set on every call (ScriptAnalysis-006). |
| 7 | Design-document adherence | ☑ | `ParseDiagnostics`/`Compile` drop warnings though doc says "errors and warnings" (ScriptAnalysis-004); `AnalysisReferences` (full-framework set) is not described in REQ-SA-2, which says DefaultReferences (ScriptAnalysis-007). |
| 8 | Code organization & conventions | ☑ | No issues found — POCO/static layout is clean, namespace correct, depends only on Commons + Roslyn. `ScriptCompileSurface` lives in ScriptAnalysis (not Commons) — acceptable as it mirrors a runtime surface and is consumed here. |
| 9 | Testing coverage | ☑ | Good adversarial reject/allow corpus, but missing: TPA-fallback degradation, extension methods, verbatim/Unicode-escape identifiers, `unsafe`/pointer, comment/trivia, and `AnalysisReferences`/exception paths (ScriptAnalysis-003). |
| 10 | Documentation & comments | ☑ | `FindViolations` XML-doc claim "Forbidden references are NOT added here" is contradicted by the Central UI consumer forwarding `compilation.References` (ScriptAnalysis-007, doc half). Otherwise thorough and accurate. |

## Findings

### ScriptAnalysis-001 — Semantic trust pass silently degrades to spelling-dependent when `TRUSTED_PLATFORM_ASSEMBLIES` is unavailable

| | |
|--|--|
| Severity | High |
| Category | Security |
| Status | Resolved |
| Location | `src/ZB.MOM.WW.ScadaBridge.ScriptAnalysis/ScriptTrustPolicy.cs:146-184`; interacts with `ScriptTrustValidator.cs:111-136`, `:195-213` |

**Description**

`AnalysisReferences` is the reference set that lets Pass 1 (the semantic symbol pass —
the *authoritative* guard) resolve every type a script names to its true namespace.
It is built from `AppContext.GetData("TRUSTED_PLATFORM_ASSEMBLIES")`. When that value
is absent — a single-file deployment, an AOT/trimmed host, or any runtime that does
not publish the TPA list — `BuildAnalysisReferences` falls back to the 5-assembly
`DefaultReferences` set (`ScriptTrustPolicy.cs:183`) **silently** (the per-assembly
`catch { }` at `:165`/`:178` and the `Count > 0` fallback at `:183` emit nothing).

After that fallback, a *bare* forbidden type that lives inside an *allowed* namespace
no longer resolves. The policy's own documented example is exactly this case:
`using System.Diagnostics; var p = Process.Start("x");`. `System.Diagnostics` is an
allowed namespace (so `VisitUsingDirective` does not flag the import), and bare
`Process` is an `IdentifierName`. With `Process.dll` absent from the minimal
reference set, `model.GetSymbolInfo` returns no symbol, so Pass 1 falls to
`GetSyntacticScopes`, which returns an empty scope list for a bare (dotless)
identifier (`ScriptTrustValidator.cs:210-212`). Pass 2's `HardeningWalker` only flags
forbidden *dotted* names and forbidden `using` imports — never a bare identifier
token (`VisitIdentifierName`, `:373-395`, only checks `dynamic`/`Activator`). The
forbidden `Process.Start` therefore slips the trust validator entirely. The same
degradation reopens the broader "forbidden type in an allowed namespace reached as a
bare identifier" class that the full-framework reference set was specifically added
(commit `06975720`, M3.6) to close.

This is rated High not Critical because: (a) the production hosts (Akka.NET cluster,
docker topology) run on a normal framework-dependent runtime that publishes the TPA
list, so the full set is loaded; and (b) for two of the four consumers (Template
Engine, Site Runtime) the downstream real `Compile` gate against a curated reference
set independently rejects an undefined `Process` symbol. But Inbound API and the
Central UI run gate rely on `FindViolations` for the reflection/namespace verdict,
and a deployment-mode change that drops the TPA list would silently weaken the
boundary with no diagnostic.

**Recommendation**

Make the degradation loud and fail-safe: when the TPA list is unavailable, log a
warning (or expose a diagnostic flag the consumers can surface), and — more
importantly — add the BCL assemblies that host the forbidden-type-in-allowed-namespace
cases (at minimum `System.Diagnostics.Process`) to `DefaultAssemblies` so they resolve
even in the minimal fallback. Alternatively, extend Pass 2 to flag bare identifiers
whose name matches the simple name of a known forbidden type (e.g. `Process`,
`WebClient`), independent of symbol resolution, so the verdict never depends solely on
the reference set being complete.

**Resolution**

Resolved 2026-06-20 (commit `fd618cf1`): the TPA-absent fallback now folds the
assemblies hosting the forbidden anchor types (Process, Socket, File, Thread, Assembly,
Marshal) into the minimal validation reference set so a bare forbidden type still
resolves and is flagged; an `AnalysisReferencesDegraded` flag + a `Trace.TraceWarning`
make the degraded mode observable. CRITICAL: anchors are added ONLY to the validation
`AnalysisReferences`, never to `DefaultReferences` — keeping the compile gate from being
able to bind `Process`. Verified by a TPA-fallback test that a bare `Process.Start` is
still rejected.

### ScriptAnalysis-002 — Pass 2 (syntactic hardening) is spelling-dependent and cannot catch a bare forbidden identifier on its own

| | |
|--|--|
| Severity | Medium |
| Category | Security |
| Status | Deferred |
| Location | `src/ZB.MOM.WW.ScadaBridge.ScriptAnalysis/ScriptTrustValidator.cs:289-395`; `:195-213` |

**Description**

Pass 2 (`HardeningWalker`) is purely textual: `VisitUsingDirective` flags forbidden
`using` imports (`:289-295`), `VisitQualifiedName`/`VisitMemberAccessExpression` flag
forbidden *dotted* names (`:298-369`), and `VisitIdentifierName` flags only the bare
identifiers `dynamic`/`Activator` (`:373-395`). It cannot independently flag any other
bare forbidden identifier — it relies entirely on Pass 1's semantic resolution for
that. The two passes are therefore not the "two independent guards" the design implies
for the bare-identifier case: for an unresolved bare identifier (see
ScriptAnalysis-001) **neither** pass fires. `GetSyntacticScopes` deliberately returns
nothing for dotless names (`:210-212`, "bare local identifiers cannot reach a forbidden
namespace") — which is true only while Pass 1 resolves them; once resolution fails the
assumption breaks.

This is the structural root of ScriptAnalysis-001 and is recorded separately because
it is a design property (the syntactic pass is not self-sufficient against bare names)
that should be acknowledged even after the TPA-fallback hole is closed: the defence is
single-layered, not double-layered, for the bare-identifier vector.

**Recommendation**

Document explicitly that Pass 1 is the sole guard for bare (single-identifier)
forbidden references and that Pass 2 only backstops *spelled* forbidden namespaces. If
genuine defence-in-depth is wanted for bare names, add a simple-name deny-set to Pass 2
(the simple names of the forbidden root types — `Process`, `WebClient`, `Marshal`,
`Registry`, `Thread`, `File`, `Directory`, etc.), accepting the small false-positive
risk on a script's own identically-named local, which a security gate should tolerate.

**Resolution**

Deferred 2026-06-20: strengthening Pass-2 (syntactic) so a bare forbidden identifier is
caught without Pass-1 symbol resolution is a defence-in-depth enhancement; the
production path (TPA present, two-layer compile gate on most call sites) is sound.
Recorded for a follow-up.

### ScriptAnalysis-003 — Adversarial test corpus has bypass-relevant gaps

| | |
|--|--|
| Severity | Medium |
| Category | Testing coverage |
| Status | Resolved |
| Location | `tests/ZB.MOM.WW.ScadaBridge.ScriptAnalysis.Tests/ScriptTrustValidatorTests.cs`; `RoslynScriptCompilerTests.cs` |

**Description**

The reject/allow corpus is solid for the spelled-namespace, alias, `using static`,
`global::`, reflection-gateway, generic-argument, and nested-lambda vectors. For a
security-critical trust boundary, however, several bypass-relevant cases are untested:

- **TPA-fallback degradation** (ScriptAnalysis-001) — no test forces
  `AnalysisReferences` onto the minimal set and asserts that bare `Process`/`WebClient`
  is still rejected. This is the highest-value missing test.
- **Extension methods** — no test that a forbidden-namespace extension method invoked
  in receiver-position (`x.SomeForbiddenExt()`) is resolved and flagged.
- **Verbatim / Unicode-escaped identifiers** — `@dynamic`, `dynamic`,
  `Activator`, or `GetType` are not exercised; `VisitIdentifierName` compares
  `Identifier.ValueText`, which decodes Unicode escapes (so it likely holds), but the
  case is not pinned, and `dynamic` is matched via `text == "dynamic"` (`:380`) which is
  a separate path from the `ForbiddenIdentifiers` set.
- **`unsafe`/pointer/`stackalloc`** — relies implicitly on `ScriptOptions` defaulting
  `AllowUnsafe=false`; not asserted.
- **Comment/trivia and string-literal payloads** — no test that a forbidden namespace
  inside a comment or string is *not* flagged (false-positive guard) and that a
  forbidden token reconstructed only at runtime from strings is correctly *not* the
  validator's concern (documents the sandbox caveat).

**Recommendation**

Add the cases above, prioritising the TPA-fallback test (inject a minimal-reference
build of `AnalysisReferences` or factor the reference set so a test can force the
fallback) and the extension-method test. Add a verbatim/Unicode-escape identifier
reject test for `dynamic`/`Activator`/`GetType`.

**Resolution**

Resolved 2026-06-20 (commit `fd618cf1`): added 18 adversarial tests — TPA-fallback
bare-Process/Socket, extension-method invocation, verbatim/Unicode-escaped identifiers,
`unsafe` blocks (benign vs forbidden-API-inside), and comment/string-literal
false-positive guards.

### ScriptAnalysis-004 — `ParseDiagnostics`/`Compile` drop warnings though the design doc promises "errors and warnings"

| | |
|--|--|
| Severity | Low |
| Category | Design-document adherence |
| Status | Resolved |
| Location | `src/ZB.MOM.WW.ScadaBridge.ScriptAnalysis/RoslynScriptCompiler.cs:30-33`, `:73-76` |

**Description**

REQ-SA-3 states `Compile` returns the diagnostics "filtered to errors and warnings"
and `ParseDiagnostics` returns "syntax-level diagnostics (errors and warnings)". The
code filters `d.Severity == DiagnosticSeverity.Error` only in both methods
(`RoslynScriptCompiler.cs:31` and `:74`), so warnings are silently dropped. Filtering
to errors-only is arguably the safer choice for a compile *gate* (a warning should not
block a deploy), but the code and the spec disagree, and a future maintainer reading
the doc will expect warnings in the returned list.

**Recommendation**

Reconcile: either change the doc (REQ-SA-3) to say "errors only", or include warnings
and let callers decide. Given the gate semantics, updating the doc to "error-severity
diagnostics" is the cleaner fix.

**Resolution**

Resolved 2026-06-20 (commit `fd618cf1`): corrected the design doc (REQ-SA-3) to
'error-severity only', matching the compile wrapper's existing behaviour (a warning must
not block a deploy gate). Code unchanged.

### ScriptAnalysis-005 — `nameof(forbiddenType)` flagging is inconsistent between passes and across resolution states

| | |
|--|--|
| Severity | Low |
| Category | Correctness & logic bugs |
| Status | Deferred |
| Location | `src/ZB.MOM.WW.ScadaBridge.ScriptAnalysis/ScriptTrustValidator.cs:42-48`, `:99-136`, `:298-325` |

**Description**

The class comment (`:42-48`) states that a forbidden type inside `nameof(...)` is
"deliberately flagged" as a conservative fail-safe, and `Rejects_NameOf_ForbiddenType`
pins `nameof(System.IO.File)`. However the flagging is incidental, not deliberate, and
inconsistent: `nameof(System.IO.File)` is caught because the inner `System.IO.File` is
a `QualifiedNameSyntax`/member access that both passes inspect directly — the
`nameof` wrapper is irrelevant. A bare `nameof(Process)` (after `using
System.Diagnostics;`, with full TPA loaded) resolves `Process` to a real symbol and
*is* flagged by Pass 1; but the same `nameof(Process)` under the minimal-reference
fallback resolves to nothing and is *not* flagged. So the "deliberate fail-safe"
behaviour actually varies with the reference set, and `nameof` — which produces only a
compile-time string and reaches no API — is a genuine false positive that will reject a
legitimate script doing `nameof(System.Net.IPAddress)` for a log message.

**Recommendation**

Decide the intended semantics explicitly. If `nameof` should be allowed (it reaches no
runtime API), special-case `NameOfExpression`/`InvocationExpression` named `nameof` to
suppress the inner-reference report. If it should be rejected, make that uniform
regardless of resolution state (tie to a simple-name check), and keep the test. Either
way, align the comment with the actual, deterministic behaviour.

**Resolution**

Deferred 2026-06-20: the `nameof(forbiddenType)` over-flagging is a documented
deliberate fail-safe; whether `nameof` (which reaches no API) should be allowed vs
uniformly rejected is a design-owner decision. Recorded; no behaviour change this pass.

### ScriptAnalysis-006 — No caching or throttling of Roslyn compilations; full-framework compilation rebuilt per call

| | |
|--|--|
| Severity | Low |
| Category | Performance & resource management |
| Status | Deferred |
| Location | `src/ZB.MOM.WW.ScadaBridge.ScriptAnalysis/ScriptTrustValidator.cs:73-97`; `RoslynScriptCompiler.cs:50-71` |

**Description**

`FindViolations` parses the script and builds a fresh `CSharpCompilation` against the
**entire framework reference set** (`AnalysisReferences`, potentially hundreds of
`MetadataReference`s) on every call (`:87-95`). `RoslynScriptCompiler.Compile`
similarly creates a new `CSharpScript` and calls `.Compile()` per call. Roslyn
compilation is the expensive part of these calls. The metadata references are cached
(built once in `AnalysisReferences`), which is the main cost, so this is Low rather
than Medium — but for the Central UI editor path (which can call the validator on every
keystroke-debounced analysis) and for batch template validation (many scripts per
deploy), the absence of any per-source memoisation or a bounded compilation cache means
repeated work. There is no back-pressure or concurrency cap either; the Inbound API
review (InboundAPI-009) already noted uncapped recompilation downstream.

**Recommendation**

Consider a small bounded cache keyed on a hash of `(code, globalsType)` for `Compile`
results and on `code` for `FindViolations` verdicts (the verdict is a pure function of
the source and the static policy). At minimum, document that callers on hot paths
(editor live-analysis) should debounce and cache, and confirm the Central UI debounces
before calling.

**Resolution**

Deferred 2026-06-20: compilation caching/throttling (the full-framework
`CSharpCompilation` is rebuilt per `FindViolations` call) is a performance enhancement,
not a correctness defect. Recorded for a follow-up.

### ScriptAnalysis-007 — `FindViolations` `extraReferences` XML-doc contradicts the Central UI consumer; `AnalysisReferences` undocumented in REQ-SA-2

| | |
|--|--|
| Severity | Low |
| Category | Documentation & comments |
| Status | Resolved |
| Location | `src/ZB.MOM.WW.ScadaBridge.ScriptAnalysis/ScriptTrustValidator.cs:57-64`; `ScriptTrustPolicy.cs:125-144`; `docs/requirements/Component-ScriptAnalysis.md:74-80` |

**Description**

Two doc/code mismatches, neither a vulnerability:

1. The `extraReferences` XML-doc on `FindViolations` (`:57-64`) says "Forbidden
   references are NOT added here". But the Central UI run gate calls
   `FindViolations(tree.ToString(), compilation.References)`
   (`CentralUI/ScriptAnalysis/ScriptAnalysisService.cs:1319-1320`), forwarding the full
   BCL surface as `extraReferences`. This is in fact *safe* (the deny-list is by
   namespace/type, so adding references can only improve resolution, never produce a
   false allow — and the policy comment at `ScriptTrustPolicy.cs:138-142` says exactly
   that), but the `FindViolations` doc as written implies the caller must not pass
   forbidden assemblies, which is both unnecessary and contradicted in practice.

2. REQ-SA-2 in the design doc describes Pass 1 as using "the full trusted-platform
   reference set from `ScriptTrustPolicy.DefaultReferences`". The code uses a separate
   `ScriptTrustPolicy.AnalysisReferences` (the full framework), and `DefaultReferences`
   is explicitly the *minimal* set used by `RoslynScriptCompiler`. The doc conflates the
   two and never mentions `AnalysisReferences` or the TPA mechanism — material because
   that mechanism is the heart of the security verdict (and of ScriptAnalysis-001).

**Recommendation**

Rewrite the `extraReferences` doc to state that extra references only widen symbol
resolution and never whitelist a forbidden API. Update REQ-SA-2 to describe
`AnalysisReferences` (full-framework, TPA-sourced) versus `DefaultReferences` (minimal,
runtime-fidelity), and note the TPA-fallback behaviour.

**Resolution**

Resolved 2026-06-20 (commit `fd618cf1`): corrected the `FindViolations`
`extraReferences` XML doc (extra references only widen resolution, never whitelist) and
documented `AnalysisReferences` vs `DefaultReferences` in REQ-SA-2.

### ScriptAnalysis-008 — Static trust gate is defence-in-depth, not a sandbox; correctly documented but worth recording as a standing risk

| | |
|--|--|
| Severity | Low |
| Category | Security |
| Status | Won't Fix |
| Location | `src/ZB.MOM.WW.ScadaBridge.ScriptAnalysis/ScriptTrustValidator.cs:34-40`; `docs/requirements/Component-ScriptAnalysis.md:151` |

**Description**

The component is explicit (both in code comments and REQ-SA-5) that it is a
compile-time deny-list, not a runtime sandbox: scripts execute in-process, and a
sufficiently determined script could reconstruct a forbidden API at runtime via paths
the static walker cannot see (e.g. building type names from runtime strings, or any
gap in the deny-list). The reflection-gateway hardening narrows this, and the
`dynamic`/`Activator` bans close the obvious late-binding routes, but the residual risk
is real and inherent to in-process execution of partially-trusted C#. This is recorded
(not as a defect of this module, which behaves as designed) so the standing risk is
visible in the audit trail and is revisited if/when the deferred runtime boundary
(restricted `AssemblyLoadContext` / curated reference set / out-of-process sandbox) is
scoped.

**Recommendation**

Keep the caveat prominent. Track the runtime-boundary work as a roadmap item; in the
meantime ensure the curated *execution* reference sets (SiteRuntime `ScriptAssemblies`,
`RoslynScriptCompiler` `DefaultReferences`) stay minimal so that even a deny-list miss
cannot bind a forbidden type at execution time (this is the real second layer of
defence for the compile-running consumers).

**Resolution**

Won't Fix 2026-06-20: the static gate is intentionally defence-in-depth, not a runtime
sandbox — this is the explicitly-documented design posture, not a defect. Recorded as a
standing risk for visibility.