docs(audit): record the removal of the hash chain and the two-login hardening

Component-AuditLog (Security & Tamper-Evidence now a removal note, archive format v2, config),
Component-CLI, Component-ManagementService, HighLevelReqs AL-11/AL-12, docs/components/CLI, the CLI
README, alog.md §11.4/§15 and CLAUDE.md. New production script docs/plans/sql/RemoveAuditLogHashChain.sql
(idempotent, from migration 64); AddAuditLogHashChain.sql marked superseded. Historical plans,
deployment records and deploy-prep packs are left as written.

Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8
This commit is contained in:
Joseph Doherty
2026-11-15 17:37:33 -05:00
parent ed2ed0a367
commit b418408c0f
10 changed files with 194 additions and 395 deletions
+7 -70
View File
@@ -2096,69 +2096,8 @@ The command is idempotent — running it multiple times converges (only rows whe
`SourceNode IS NULL` are eligible; already-set rows are untouched). Backed by
`POST /api/audit/backfill-source-node`. Requires `Admin` role.
#### `audit verify-chain`
Verify the audit log hash chain for a given month.
```sh
scadabridge --url <url> audit verify-chain --month <YYYY-MM>
```
| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `--month` | yes | — | UTC calendar month to verify, `YYYY-MM` (e.g. `2026-05`) |
Sends the `VerifyAuditChain` management command (ScadaBridge#41). The server
recomputes every link of that month's AuditLog hash chain and reports the first
break, if any: partition, `ChainSeq`, `EventId` and kind (`HashMismatch` = edited or
reordered row, `MissingRow` = deleted row, `HeadMismatch` = rows deleted from the
end, `DuplicateSequence`, `IncompleteLink`). `--format table` prints a summary;
`json` prints the result object.
| Exit code | Meaning |
|-----------|---------|
| `0` | `Intact`, or `NotChained` (nothing chained for that month yet) |
| `3` | `Broken` — tamper evidence; see `firstBreak` |
| `1` | Request error (bad month, `CHAIN_BUSY`, server error) |
| `2` | Authorization failure (needs `Administrator` or `Viewer`, not site-scoped) |
The chain only exists once `AuditLog:HashChain:Enabled` is on for the central nodes
(default off); see `Component-AuditLog.md`, Security & Tamper-Evidence.
#### `audit verify-heads`
Check AuditLog chain heads that were exported off-box (ScadaBridge#107) against the
database chain.
```sh
scadabridge --url <url> audit verify-heads --path <file-or-directory>
```
| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `--path` | yes | — | An export file, or a directory read recursively for `*.jsonl` / `*.log` / `*.txt` |
The central nodes write one JSON record per month head (`month`, `lastSeq`, `lastHash`,
purge anchor, chained-row and tombstone counts, `exportedAtUtc`, `node`) when
`AuditLog:HashChain:HeadExport:Enabled` is on — to append-only files
(`{Directory}/{yyyy}/audit-chain-heads-{yyyy-MM-dd}-{node}.jsonl`) or to syslog (RFC 5424, the
JSON record as the message). The CLI reads both forms (the JSON object is taken from each
line's first `{` to its last `}`, so a syslog collector's prefixes do not matter), keeps one
record per distinct (month, sequence, hash), and sends `VerifyAuditChainHeads`. Per record the
server reports `Matches`, `Extended`, `Purged` (the link was removed by a partition purge —
check the month's archive), or a failure: `Mismatch` (the chain was rewritten and re-hashed),
`Regressed` (head rolled back), `MissingHead`, `MissingLink` (a chained row deleted outside the
purge paths), `CountMismatch`.
| Exit code | Meaning |
|-----------|---------|
| `0` | Every exported head is consistent with the database |
| `3` | At least one failure — tamper evidence |
| `1` | No records found, bad input, `CHAIN_BUSY`, server error |
| `2` | Authorization failure (needs `Administrator` or `Viewer`, not site-scoped) |
Run it with `audit verify-chain`: `verify-chain` recomputes each month's links;
`verify-heads` proves the database still holds the heads that left the box.
`audit verify-chain` and `audit verify-heads` were removed on 2026-11-15 with the AuditLog
hash chain (IT security request; see `Component-AuditLog.md`, Security & Tamper-Evidence).
#### `audit archive list` / `audit archive verify`
@@ -2176,17 +2115,15 @@ scadabridge --url <url> audit archive verify --name <archive>
`list` sends `ListAuditArchives` and prints each archive's name, partition, status
(`Archived` = written, purge not confirmed; `Purged` = the partition was switched out
and the archive is the only copy), row counts and size. `verify` sends
`VerifyAuditArchive`: the server checks both Parquet files' SHA-256 against the
manifest, recomputes the archived month's hash chain from the archived rows and
tombstones, and compares the chain end with the checkpoint anchor the purge left in
`AuditLogChainHead` (`Matches`, `Superseded` by a later purge of late rows,
`NotPurged`, or `Mismatch`).
and the archive is the only copy), row count and size. `verify` sends
`VerifyAuditArchive`: the server checks the data file's size and SHA-256 and its row
count against the manifest. It proves the file is the one the archive wrote; archives are
unsigned and carry no tamper evidence.
| Exit code | Meaning |
|-----------|---------|
| `0` | Verified |
| `3` | Not verified — a file was altered, the chain is broken, or the anchor mismatches |
| `3` | Not verified — the data file is missing, altered, or its row count differs from the manifest |
| `1` | Request error (`ARCHIVE_NOT_CONFIGURED`, `NOT_FOUND`, `INVALID_ARGUMENT`, server error) |
| `2` | Authorization failure (needs `Administrator` or `Viewer`, not site-scoped) |