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

docs(audit): emit ApiInbound.Completed audit row per request

Browse Source
This commit is contained in:
Joseph Doherty
2026-05-20 08:25:14 -04:00
parent c7ddfc7140
commit 61ec4161bf
1 changed files with 5 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/requirements/Component-InboundAPI.md
View File

@@ -116,8 +116,9 @@ API method scripts are compiled at central startup — all method definitions ar
## API Call Logging ## API Call Logging
- **Only failures are logged.** Script execution errors (500 responses) are logged centrally. - **Every request — success or failure — emits one `ApiInbound.Completed` row** to `ICentralAuditWriter` from request middleware before the HTTP response is flushed. The row captures the API key **name** (never the key material), remote IP, user-agent, response status, duration, and truncated request/response bodies per the Audit Log capture policy (see Component-AuditLog.md, Payload Capture Policy). This supersedes the earlier failures-only stance: operational API traffic is now part of the centralized audit log, so configuration changes and call activity share a single retention/query surface.
- Successful API calls are **not** logged — the audit log is reserved for configuration changes, not operational traffic. - Script execution errors (500 responses) remain captured on the same `ApiInbound.Completed` row (response status + error fields) rather than emitting a separate failure-only event.
- **Non-blocking semantics.** Middleware audit-write failures are logged and metricked (see Health Monitoring #11 — `CentralAuditWriteFailures`) but **never affect the HTTP response**: a failed audit append does not turn a successful API call into an error returned to the caller.
- No rate limiting — this is a private API in a controlled industrial environment with a known set of callers. Misbehaving callers are handled operationally (disable the API key). - No rate limiting — this is a private API in a controlled industrial environment with a known set of callers. Misbehaving callers are handled operationally (disable the API key).
## Request Flow ## Request Flow
@@ -197,7 +198,8 @@ Inbound API scripts **cannot** call shared scripts directly — shared scripts a
- **Configuration Database (MS SQL)**: Stores API keys and method definitions. - **Configuration Database (MS SQL)**: Stores API keys and method definitions.
- **Communication Layer**: Routes requests to sites when method implementations need site data. - **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). - **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. Optionally, API call activity can be logged. - **Configuration Database (via IAuditService)**: All API key and method definition changes are audit logged.
- **Audit Log (#23)**: Every inbound API request emits an `ApiInbound.Completed` row via `ICentralAuditWriter` from request middleware (non-blocking for the HTTP response). Payload truncation/redaction follows the Audit Log Payload Capture Policy.
- **Cluster Infrastructure**: API is hosted on the active central node and fails over with it. - **Cluster Infrastructure**: API is hosted on the active central node and fails over with it.
## Interactions ## Interactions