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

docs(audit): Parquet cold archive shipped, default off (ScadaBridge#42)

Browse Source 
Component-AuditLog Retention & Purge describes the archive: directory and
layout, the three files, consistency with the hash chain (SHARED read,
guarded switch, anchor = archived chain end), fail-closed purge, retention
interplay (per-channel overrides are not archived, their tombstones are),
verify/read, and the AuditLog:Archive configuration. alog.md §13.6/§15.2/§16,
CLAUDE.md, HighLevelReqs AL-12, Component-CLI, Component-ManagementService,
docs/components/{CLI,ManagementService}.md and the CLI README drop the
"deferred / 501" wording and document `audit archive list|verify` and the
parquet export.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 17:01:03 -05:00
parent d1fc336e18
commit 3ff463b6fd
9 changed files with 136 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/ZB.MOM.WW.ScadaBridge.CLI/README.md
+38 -2
View File
@@ -1996,8 +1996,10 @@ scadabridge --url <url> audit export --since <time> --until <time> --format <fmt
| `--target` | no | — | Filter by target |
| `--actor` | no | — | Filter by actor |
> `--format parquet` is accepted by the CLI but the server returns `501 Not
> Implemented` — Parquet archival is deferred to v1.x (see `Component-AuditLog.md`).
> `--format parquet` (ScadaBridge#42) writes one Parquet file with the same 24 columns
> as `csv`/`jsonl` (ids as strings, UTC microsecond timestamps, enums as names). A
> central older than #42 answers `501 Not Implemented`; the CLI prints the message and
> exits 1.
> Use `csv` or `jsonl`.
#### `audit tree` (M5.3 T8)
@@ -2069,6 +2071,40 @@ end, `DuplicateSequence`, `IncompleteLink`). `--format table` prints a summary;
The chain only exists once `AuditLog:HashChain:Enabled` is on for the central nodes
(default off); see `Component-AuditLog.md`, Security & Tamper-Evidence.
#### `audit archive list` / `audit archive verify`
List and verify the AuditLog Parquet cold archives (ScadaBridge#42) that the retention
purge writes when `AuditLog:Archive:Enabled` is on (default off).
```sh
scadabridge --url <url> audit archive list
scadabridge --url <url> audit archive verify --name <archive>
```
| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `--name` | yes (`verify`) | — | Archive name as `list` prints it: `auditlog-YYYY-MM-yyyyMMddTHHmmssfffZ` |
`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`).
| Exit code | Meaning |
|-----------|---------|
| `0` | Verified |
| `3` | Not verified — a file was altered, the chain is broken, or the anchor mismatches |
| `1` | Request error (`ARCHIVE_NOT_CONFIGURED`, `NOT_FOUND`, `INVALID_ARGUMENT`, server error) |
| `2` | Authorization failure (needs `Administrator` or `Viewer`, not site-scoped) |
The archive files are plain Parquet; read them with any Parquet tool, e.g. DuckDB:
`SELECT * FROM '<dir>/2025/auditlog-2025-10-….parquet'`. See `Component-AuditLog.md`,
Retention & Purge.
---
### `audit-config` — Configuration-change audit log