dohertj2/scadalink-design
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(cli): document scadalink audit group + audit-config rename (#23 M8)

Browse Source
This commit is contained in:
Joseph Doherty
2026-05-20 22:03:32 -04:00
parent ba8ddcc032
commit 36d58e8988
1 changed files with 109 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
src/ScadaLink.CLI/README.md
View File

@@ -1049,14 +1049,119 @@ Features:
---
### `audit-log` — Audit log queries
### `audit` — Centralized Audit Log
#### `audit-log query`
Read access to the central append-only **Audit Log** (#23) — the record of every
script-trust-boundary action: outbound API calls (sync + cached), outbound DB
operations (sync + cached), notifications, and inbound API calls. This is distinct
from the configuration-change audit trail exposed by [`audit-config`](#audit-config--configuration-change-audit-log).
Query the central audit log with optional filters and pagination.
The subcommands map directly onto the `GET /api/audit/query` and
`GET /api/audit/export` management endpoints. Filters and the result columns mirror
the Central UI **Audit** page, so a CLI query and a UI query with the same filters
return the same rows — CLI ↔ UI filter parity is intentional.
**Permissions.** Querying requires the `OperationalAudit` permission (roles `Admin`,
`Audit`, or `AuditReadOnly`). Exporting requires the stricter `AuditExport` permission
(roles `Admin` or `Audit`) — read access does *not* imply export access. A request
without the required role returns exit code `2`.
#### `audit query`
Query audit log events with optional filters and keyset pagination.
```sh
scadalink --url <url> audit-log query [options]
scadalink --url <url> audit query [options]
```
| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `--since` | no | — | Start time: relative (`1h`, `24h`, `7d`) or ISO-8601 |
| `--until` | no | — | End time: relative (`1h`, `24h`, `7d`) or ISO-8601 |
| `--channel` | no | — | Filter by channel (`OutboundApi`, `OutboundDb`, `Notification`, `InboundApi`) |
| `--kind` | no | — | Filter by event kind |
| `--status` | no | — | Filter by status (single value) |
| `--site` | no | — | Filter by source site ID |
| `--instance` | no | — | Filter by instance |
| `--target` | no | — | Filter by target (external system, DB connection, notification list) |
| `--actor` | no | — | Filter by actor |
| `--correlation-id` | no | — | Filter by correlation ID |
| `--errors-only` | no | `false` | Show only failed events (`status=Failed`; overrides `--status`) |
| `--page-size` | no | `100` | Events per page (1–1000) |
| `--all` | no | `false` | Fetch every page, following the keyset cursor |
| `--format` | no | `json` | Output format: `json` (JSONL, one event per line) or `table` |
With `--format table`, events render as an aligned text table with columns
`OccurredAtUtc`, `Channel`, `Kind`, `Status`, `Target`, `Actor`, `DurationMs`,
`HttpStatus`; long `Target`/`Actor` values are truncated with an ellipsis. With
`--format json` (the default), each page is emitted as JSONL — one JSON object per
line — which streams cleanly under `--all` across many pages.
#### `audit export`
Export audit log events to a file. The export streams from the server, so it is not
bounded by the query page size.
```sh
scadalink --url <url> audit export --since <time> --until <time> --format <fmt> --output <path> [filters]
```
| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `--since` | yes | — | Start time: relative (`1h`, `24h`, `7d`) or ISO-8601 |
| `--until` | yes | — | End time: relative (`1h`, `24h`, `7d`) or ISO-8601 |
| `--format` | yes | — | Export format: `csv`, `jsonl`, or `parquet` |
| `--output` | yes | — | Destination file path |
| `--channel` | no | — | Filter by channel |
| `--kind` | no | — | Filter by event kind |
| `--status` | no | — | Filter by status |
| `--site` | no | — | Filter by source site ID |
| `--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`).
> Use `csv` or `jsonl`.
#### `audit verify-chain`
Verify the audit log hash chain for a given month.
```sh
scadalink --url <url> audit verify-chain --month <YYYY-MM>
```
| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `--month` | yes | — | Month to verify, `YYYY-MM` (e.g. `2026-05`) |
> **v1 no-op.** Hash-chain tamper-evidence is not enabled in this release. The
> subcommand validates the `--month` argument and prints a notice pointing at the
> v1.x roadmap in `Component-AuditLog.md`; it exits `0` without contacting the server.
> The command exists now so scripts and operator habits do not need to change when
> tamper-evidence ships.
---
### `audit-config` — Configuration-change audit log
Query the configuration-change audit trail (the `IAuditService` record of admin
edits to templates, instances, sites, etc.). This is **separate** from the
centralized [`audit`](#audit--centralized-audit-log) group above.
> **Renamed.** This group was named `audit-log` before #23 M8. The old name still
> works as a deprecated alias — `scadalink audit-log query ...` resolves the full
> subcommand tree unchanged — but prints a deprecation warning to stderr:
> `Warning: 'audit-log' is deprecated and will be removed in a future release. Use 'audit-config' instead.`
> Migrate scripts to `audit-config`; the `audit-log` alias will be removed in a
> future release.
#### `audit-config query`
Query the configuration-change audit log with optional filters and pagination.
```sh
scadalink --url <url> audit-config query [options]
```
| Option | Required | Default | Description |