dohertj2/ScadaBridge
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(m3): document Script Analysis component (#25); reconcile consumer specs + README/CLAUDE component list

Browse Source
This commit is contained in:
Joseph Doherty
2026-06-16 20:05:24 -04:00
parent 069757209a
commit fb5f14e04f
6 changed files with 191 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/requirements/Component-InboundAPI.md
+12 -6
View File
@@ -197,12 +197,17 @@ Inbound API scripts **cannot** call shared scripts directly — shared scripts a
> **No direct database access.** Inbound API scripts are not given a raw database
> client. Handing a script a raw `SqlConnection` is in direct tension with the
> ScadaBridge script trust model (scripts are forbidden `System.IO`, `Process`,
> `Threading`, `Reflection`, and raw network access; `ForbiddenApiChecker`
> statically enforces this). Scripts interact with the system only through the
> curated `Route` and `Parameters` surfaces above. If a method needs data from
> the configuration or machine-data databases, that access belongs behind a
> dedicated, scoped helper — not a general-purpose connection — and would be
> added here as an explicit design change.
> `Threading`, `Reflection`, and raw network access). The `ForbiddenApiChecker`
> statically enforces this by delegating to the shared `ScriptAnalysis`
> `ScriptTrustValidator` (component #25), which is the single authoritative
> source of truth for the forbidden-API policy. The unified policy permits
> `System.Diagnostics.Stopwatch`/`Debug` while retaining the `Process`-only ban,
> and adds reflection-gateway member and `dynamic`/`Activator` hardening.
> This is defence-in-depth static enforcement, not a true runtime sandbox. Scripts
> interact with the system only through the curated `Route` and `Parameters`
> surfaces above. If a method needs data from the configuration or machine-data
> databases, that access belongs behind a dedicated, scoped helper — not a
> general-purpose connection — and would be added here as an explicit design change.
### Routing Behavior
- The `Route.To()` helper resolves the instance's site assignment from the configuration database and routes the request to the correct site cluster via the Communication Layer.
@@ -232,6 +237,7 @@ Inbound API scripts **cannot** call shared scripts directly — shared scripts a
- **Communication Layer**: Routes requests to sites when method implementations need site data.
- **Security & Auth**: API key validation (separate from LDAP/AD — API uses key-based auth).
- **Configuration Database (via IAuditService)**: All API key and method definition changes are audit logged.
- **Script Analysis (#25)**: `ForbiddenApiChecker` delegates to `ScriptTrustValidator.FindViolations` for the authoritative forbidden-API verdict during script compilation and validation.
- **Audit Log (#23)**: Every inbound API request emits an `ApiInbound.Completed` row via `ICentralAuditWriter` from request middleware (non-blocking for the HTTP response). Request and response bodies are captured in full up to `AuditLog:InboundMaxBytes` (default 1 MiB) per the Audit Log Payload Capture Policy; redaction (headers + per-target body redactors) still applies before persistence.
- **Cluster Infrastructure**: API is hosted on the active central node and fails over with it.