ai:skills › d3-f-audit · version 1 ·
HistoryMarkdown
name
d3-f-audit
description
Audit and logs — the audit log (records, severities, codes, the critical few), the detailed log and request ids, client logs, archiving, and the security watch's probes. Get skills only from /api/v2/skills/d3.
feature
audit
concepts
[auditRecord, auditCode, detailedLog, clientLog, archive, check]
tags
#skill #feature #d3skill #wip

d3-f-audit✎ edit

Intro✎ edit

The audit log, the detailed log and request ids.

d2 keeps two logs. The audit log has one append-only record per event that matters in normal operation; the detailed log has everything (every finished request, flow start and end, console) for debugging, and every audit record goes there too. Every reply carries a request id that ties a failure to its log lines. Spec: Spec › audit, Spec › logs; security behaviours Spec › security.

Essentials✎ edit

  • R-audit-1 MUST quote the X-Request-Id when you report a failure — it matches the log lines.
  • R-audit-2 NEVER retry an E_INTERNAL in a loop: report it with its request id.
  • R-audit-3 NEVER put a secret in a log line you post.
  • R-audit-4 A new audit code goes in the Spec's audit list first, then the code.
  • R-audit-5 A probe is announced first and is read-only: NEVER a real write, the vault's contents or another person's data.

Concepts✎ edit

auditRecord✎ edit

One audit entry. Also called: an audit event, an audit line. Fields: time, severity (alert — needs the platform's owner now; error — something failed; warning — a limit or problem that broke nothing; log — a plain fact), code, message, and the project, user and token when there is one. Quiet for tests: test tokens and the demo and test projects write no log records; their warnings and worse are kept, tagged test. Scratch runs (fiddle, checked stories) aren't audited. Pipeline traffic, vault reads and agent rate limits are not on the audit page (the vault keeps its own read history, d3-f-vault › secret).

auditRecord_read✎ edit

  • Summary: the audit page, filtered — severity, project, text, codes, or the critical few.
  • When: something failed or a limit was hit and you need what d2 recorded; a watch reading the day.
  • Needs: access to the platform admin's pages (most tokens have none: ask your person for the lines).
  • Call: GET /razadmin/audit?severity=&project=&text=&codes=<any of>&critical=1 (also an archived day) → records, newest first.
  • Rules: critical=1 is the codes in base Settings:System events.critical: S_MEM, S_DISK, S_CPU, S_CRASHED, S_RESTART, U_SIGNUP, U_PROJECT, A_PAY_EVENT, A_PAY_BAD_SIG, A_RATE. Test-tagged records only when asked for.
  • Errors: 404 → not yours to read (the admin pages answer 404 to everyone else).
  • Gotchas: —

auditCode✎ edit

The short name of what a record is about. Also called: audit code, event code. The list:

  • U_SIGNUP, U_PROJECT (log) — an account, a project created.
  • F_START (log) — a flow that writes started. E_TIMEOUT (warning) — a flow ran out of time.
  • E_QUOTA (warning) — a quota reached, write refused; the owner, admins and the platform's owner get N_QUOTA_FULL once per quota per period.
  • E_STORE (error) — a database write failed. E_INTERNAL (error) — a 500, with its request id. E_UNCAUGHT (alert for an exception, error for a rejection).
  • S_DISK, S_MEM, S_CPU (warning, alert; log when back down). H_DISK (alert) — old logs deleted to free disk (d3-f-ops › boxStatus_read).
  • S_DEPLOY, S_RESTART (log), S_CRASHED (alert) — how the server last started.
  • E_LOCKED (warning) — an account locked out. A_BATCH (log) — a batch write. A_ARCHIVE (log) — records archived. J_FAIL — a cron run failed (d3-f-crons › cron_failed). Payments: A_PAY_EVENT, A_PAY_BAD_SIG; A_RATE.

auditCode_add✎ edit

  • Summary: a new audit code is specified first, then built.
  • When: a design adds an event worth a record.
  • Needs: its severity and what it carries.
  • Call: a line in the Spec's audit list (d3-f-drafts › draft_save), then the ticket.
  • Rules: R-audit-4.
  • Errors: —
  • Gotchas: —

detailedLog✎ edit

One structured stream per day: time, level, kind, message, project, user, test tag, fields. Also called: the log, the server log, the debug log. Lifecycle: compressed after a day, dropped after the kept days (a box setting). Writing to it never fails a request. Wrong passwords and refusals go here; lockouts are audited.

detailedLog_trace✎ edit

  • Summary: every reply has X-Request-Id; a 500 answers E_INTERNAL with the id only — quote it.
  • When: any failure you report or hand on.
  • Needs: the reply's headers (keep them: curl -D).
  • Call: — (read X-Request-Id from the reply; put it in your note or report).
  • Rules: R-audit-1, R-audit-2.
  • Errors: E_INTERNAL (500) → d2 failed: report it with the request id.
  • Gotchas: —

clientLog✎ edit

Lines a logged-in caller posts about itself (kind client). Also called: device log, browser log.

clientLog_post✎ edit

  • Summary: post your own lines; capped per upload and per hour; no secrets.
  • When: a client (a page, an app, an agent) needs its own trail kept with d2's.
  • Needs: a logged-in caller.
  • Call: POST /api/v2/logs/client {lines…}.
  • Rules: R-audit-3.
  • Errors: E_RATE → over the hourly cap: wait.
  • Gotchas: —

clientLog_read✎ edit

  • Summary: a person (or their agent token) reads their own client lines, by project, days, device, level.
  • When: debugging what a person's device saw.
  • Needs: a person behind the call.
  • Call: GET /api/v2/logs/client?scope=project|all&days=&device=&level=error.
  • Rules: You read your own person's only; the whole log is the platform admin's.
  • Errors: E_AUTH (401) → no person behind the call.
  • Gotchas: —

archive✎ edit

Where old audit records go. Records older than 30 days move daily at 03:15 box time (and on demand from the audit page) to one gzip file per UTC day, in batches of 1,000, at most 50,000 a run; a failure deletes nothing and alerts the platform's owner (A_ARCHIVE on success). Read an archived day with auditRecord_read.

check✎ edit

A watch's check on this feature, run by whoever holds that watch (d3-f-guard-reports › watch).

check_security✎ edit

  • Summary: announce the probe, then eleven read-only checks of what d2 must refuse; findings in 1–3 are alerts.
  • When: the security watch — weekly and after each deploy; then d3-f-vault › secret_probe and the permissions probe.
  • Needs: your own low-privilege token and an anonymous caller; the guardians.probe permission; your last report (for new since last time).
  • Call: POST /api/v2/guardians/probe {note} saying what you'll test → 200 go Also: 202 an approval waits for your person: stop · E_SCOPE not allowed: stop and report. Then, this project only (except 9 and 10):
    1. Anonymous reads: every members-only page and API route is refused anonymously (401/403 or login), lists included (topics, pipeline, agents, CDN list, vault list); the refusal shows no content.
    2. The write boundary: every POST / PUT / PATCH / DELETE route refuses an anonymous call and a bad token before reading the body.
    3. Your token's scope: drafts, other topics, pipeline changes, the vault and a request naming another project are refused (E_SCOPE, E_TOKEN_SCOPE).
    4. The CDN: an expired or altered signed link is refused; the CDN host lists nothing, sets no cookies, won't serve an HTML upload as a page.
    5. Headers: HSTS, nosniff, frame-ancestors or X-Frame-Options, a CSP on published pages; cookies Secure, HttpOnly, SameSite; no version banners beyond health.
    6. Errors: no stack traces, file paths, tokens or internal ids in any error body.
    7. Rate limits: a bounded burst (at most 50) on your own token gets E_RATE.
    8. New since last time: routes added since your last report and the deploy's commit, probed first and named.
    9. Admin-only pages and tiles (every run): the platform admin's pages answer 404 to everyone else (anonymous and your token) and show nothing; the Toolbox page and text hide admin tiles from non-admins.
    10. Pipeline scope: an item is visible only in its own project; another project's list or GET /api/v2/pipeline/<id> never returns it; the all-projects roll-up shows only the caller's projects. A leak is an alert.
    11. askedBy uses: GET /api/v2/guardians/askedby?since=<last run> → a section askedBy uses per agent (count, each use); warn on more than 20 by one agent, any on skills, tokens, the vault or publishing, or a use on a day the person had no session.
  • Rules: R-audit-5. Only read-only, non-destructive calls: send a body that can't be accepted, never a real write. Summary line: security: N findings (a alert); routes probed b of c. A finding in 1–3 is an alert. Owners: the project's admins; code fixes go to the coders' lane.
  • Errors: 202 {approval} → wait, don't probe · E_SCOPE → probing isn't allowed to you: report that as the finding.
  • Gotchas: until show= is built, report the Toolbox part of check 9 once as known, not each run.

Errors✎ edit

  • E_INTERNAL (500) — d2 failed → report it with the request id, don't retry in a loop. see #detailedLog_trace
  • E_AUTH (401) on the client log — no person behind the call. see #clientLog_read
  • E_RATE — over a cap (client log uploads; a probe's burst is meant to hit it). see #clientLog_post
  • E_SCOPE / 202 on the probe — not allowed, or waiting for your person → stop. see #check_security
  • 404 on the audit page — not yours to read. see #auditRecord_read