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

docs(audit): hash-chain tamper evidence shipped, default off (ScadaBridge#41)

Browse Source 
Component-AuditLog Security & Tamper-Evidence describes the per-month chain,
the chaining job and its lock, both purge paths (checkpoint anchor,
tombstones), pre-existing rows, verification and what an unsigned chain does
not prove. alog.md §11.4/§16, CLAUDE.md, HighLevelReqs AL-11/12,
Component-CLI, Component-ManagementService, docs/components/CLI.md and the
CLI README drop the "no-op placeholder" wording.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 16:28:54 -05:00
parent 548bb9a725
commit dd99a9f5a5
8 changed files with 109 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/requirements/Component-CLI.md
+10 -6
View File
@@ -337,11 +337,15 @@ scadabridge audit verify-chain --month <YYYY-MM>
rows where `SourceNode IS NULL` and `OccurredAtUtc < --before`, in batches
(`--batch`, default 5000). Admin-only maintenance command. Idempotent.
Backed by `POST /api/audit/backfill-source-node`.
- `audit verify-chain` — hash-chain verification for the named month.
**No-op in v1**: the command is defined so the command tree is stable, but
verification only becomes meaningful once the hash-chain ships (see
Component-AuditLog.md, Security & Tamper-Evidence). Until then, the server
responds with a "verification not yet available" status and the CLI exits 0.
- `audit verify-chain --month <YYYY-MM>` (ScadaBridge#41) — verifies the AuditLog
hash chain for one UTC calendar month by sending the `VerifyAuditChain` management
command over `POST /management` (the one `audit` leaf that is a management contract
rather than a REST call). Reports `Intact` / `NotChained` / `Broken`, rows verified,
tombstones applied, the partition-purge anchor, the head sequence and unchained rows;
on `Broken`, the first break's partition, `ChainSeq`, `EventId` and kind. Exit code
`0` intact or not chained, `3` broken, `1` error, `2` authorization failure. Requires
`OperationalAudit` and a caller not scoped to specific sites. See
Component-AuditLog.md, Security & Tamper-Evidence.
### Health Commands
```
@@ -520,7 +524,7 @@ Configuration is resolved in the following priority order (highest wins):
- **System.CommandLine**: Command-line argument parsing.
- **Microsoft.AspNetCore.SignalR.Client**: SignalR client for the `debug stream` command's WebSocket connection.
- **Management Service (#18)**: The CLI hits the central cluster via the existing HTTP Management API (`POST /management`), which dispatches to the ManagementActor. The `scadabridge audit` command group rides a parallel REST surface on the same Host (`GET /api/audit/query` and `GET /api/audit/export`), sharing authentication (bearer token or HTTP Basic) with `/management` but bypassing the actor for read-only, keyset-paged / streaming workloads.
- **Audit Log (#23)**: The `scadabridge audit query`, `audit export`, `audit tree`, and `audit backfill-source-node` subcommands target the centralized Audit Log component's REST endpoints (`GET /api/audit/query`, `GET /api/audit/export`, `GET /api/audit/tree`, `POST /api/audit/backfill-source-node`) on the Host's Management API surface; `audit verify-chain` is a client-side no-op today (hash-chain deferred to v1.x). Permission checks (`OperationalAudit`, `AuditExport`, `Admin`) are enforced server-side by `AuditEndpoints`.
- **Audit Log (#23)**: The `scadabridge audit query`, `audit export`, `audit tree`, and `audit backfill-source-node` subcommands target the centralized Audit Log component's REST endpoints (`GET /api/audit/query`, `GET /api/audit/export`, `GET /api/audit/tree`, `POST /api/audit/backfill-source-node`) on the Host's Management API surface; `audit verify-chain` sends the `VerifyAuditChain` management command (`POST /management`, ScadaBridge#41). Permission checks (`OperationalAudit`, `AuditExport`, `Admin`) are enforced server-side by `AuditEndpoints`.
## Interactions