canopy-security API Reference

List audit events with filtering and pagination.

Query parameters:

Response (200): Array of AuditEvent objects.

Get a single audit event by ID. Reads archive ∪ live (#1208): the live PK probe first, else the archive twin — an archived row keeps resolving.

Response (200): AuditEvent object.

Response (404): Event not found.

The scoped, transaction-time change-history of one person’s eligibility facts (epic &56 / T1-6, ADR-027 §4). Projects the append-only audit_events ledger to the attributed *.claimed / income.closed events canopy-persons emits (T1-5), filtered to one person and one resource kind, ordered by the hash-chain insert time (created_at, strictly increasing) — oldest first. One resource returns a fact type’s full history (claims, corrections, and the close); the entry action distinguishes them.

Path parameters:

Response (200): Array of FactChangeEntry objects, each carrying person_id, fact_id, version_id (claim only), action (claim / close), actor_sub / actor_role (the authoring worker/applicant; null for a close — the ADR-019 on-behalf-of limitation), claim_source, claim_status, the opaque per-kind before (superseded windows) and after (new value; null for a close), recorded_at (the audit row’s transaction-time), and the opaque event_hash. Since T2-6 MR9 (#687, ADR-036) the PII money leaves inside before/after are sealed (a SealedValue envelope — canopy-security never holds the DEK), so this endpoint surfaces ciphertext for them and the worker UI renders a (sealed) marker; the structural discriminators (*_type, frequency) stay plaintext. The actual figure is read from the system-of-record (canopy-persons) — see #920.

Response (400): Unknown resource. 403: caller is neither service-class nor admin.

Minimum role: service-class token or admin (the same house auth as the rest of the service). Worker (caseworker) scoping is enforced at the canopy-web BFF — which gates on the worker’s case access + program scope, resolves the household’s members, and fans out here per member to compose the household view — because canopy-security cannot see the worker identity until the ADR-019 plumbing lands. canopy-security stays a self-contained leaf (ADR-001): it calls no other service.

HTTP audit ingress for broker-less services (Plan 3 MR5a, ADR-026). canopy-security normally ingests audit events via the RabbitMQ wildcard subscriber, but the applicant portal (canopy-portal) is Postgres- and RabbitMQ-free, so its session security events (mint / revoke / kill-switch) post here instead. The server mints the event_id and chains the row through the same insert_audit_event path the subscriber uses (ADR-014) — an HTTP-ingested event is indistinguishable from a broker-ingested one in the chain.

Minimum role: service-class, or the scoped portal credential (portal:audit:write, #1441 — the portal’s session security events arrive citizen-class; the exchange-audit sinks keep their service arm). Any other principal returns 403.

Callers post this best-effort / fire-and-forget — a canopy-security outage must never break the applicant flow, so the portal logs and drops failures rather than retrying them into the request path.

Request: AuditEventIngestRequest

event_timestamp defaults to the ingest time and metadata to {} when omitted. household_id is parsed to a UUID for the typed audit_events.household_id column; a non-UUID drops to NULL (it never breaks the hash chain, which hashes content + timestamp).

programs (#1519) is the publisher’s program-scope assertion for the row’s audit_events.programs column: [] = asserted program-neutral (visible to every scoped worker view), ["snap", …] = the named storage slugs, omitted/null = no assertion — the store then derives from the event-type routing key or the curated neutral families, else stores NULL (invisible to scoped worker views; see the worker-portal audit model in authorization-inventory.adoc). An assertion containing an unknown slug is rejected as a whole — the row stores NULL, with no fall-through to derivation (a malformed assertion must not be partially honored or silently re-derived). Like household_id, the column is OUTSIDE the frozen v1 chain hash (dedup_key precedent — the 20261128000000 migration header records the posture).

The endpoint is mode-split (#1207, ADR-014 Amendment 7; dormant until the #1279 cutover flips CANOPY_SECURITY__CHAIN_V2_APPEND_ENABLED):

List breach detection alerts.

Query parameters: limit, offset, status

Response (200): Array of BreachAlert objects.

Get a single alert.

Response (200): BreachAlert object.

Response (404): Alert not found.

Update alert status (acknowledge, investigate, resolve).

Request: UpdateAlertStatus

status is required; resolved_by is optional.

Response (200): updated BreachAlert object.

Response (404): Alert not found.

List all NIST SP 800-53 control mappings tracked by the system.

Response (200): Array of NistControlMapping objects with control ID, description, and implementation status.

Get aggregate audit statistics (per-service action counts) over a trailing time window.

Query parameters: days (optional) — trailing window over created_at; defaults to 30, clamped to a 366-day cap. The window is mandatory server-side (#1229): there is no unbounded full-table aggregate path, and the query rides the idx_audit_events_created_at_id range with a statement timeout so an abandoned client cannot leave the aggregate running on the audit-ingest DB.

Response (200): Array of AuditSummaryRow objects (source_service, action, count) for events in the window.

C6 verification status for one family target (ADR-014 Amendment 8; the derivation precedence is plan D6).

Query parameters:

Response (200 or 503): ChainStatusResponse — the SAME typed body on both codes. HTTP mapping: healthy/verifying → 200; unknown/stale/error/breached → 503, so a consumer reading only the status code fails closed while a typed consumer still gets the full picture. The body carries state (the six-state machine), reasons[] (every firing derivation input — the closed StatusReason vocabulary), epoch, per-shard coverage (shards[]: tail verified-through / head / lag / stamps + scrub cursor / target / cycle stamps), backlog (audit family only — staged / parked / inbox-parked / DLQ depth; null for fti, typed applicability), trusted_manifest (the verifier-checked anchor: id / seq / age), and — on breached — the oldest unresolved incident_id plus its typed breached_position.

Enqueue a durable manual verification job — never a synchronous walk (the #1245 OOM class stays dead). Jobs are token-claimed, target-scoped, and crash-safe: the work definition (instance / epoch / per-shard targets) is captured once at first claim, a reclaim resumes the SAME vector, and coverage is all-or-nothing. ONE active job per target (family, or family + service); manual runs never feed the status machine in either direction.

Request: ChainVerifyRequest

loop ∈ {tail, scrub, family-full}, default family-full (tail + scrub
census + manifest). service is required exactly for family=fti. incident_id (optional) marks a revalidation job for the incident-resolution runbook (Security Operations): it bypasses the family halt gate and must run the incident’s DETECTED loop (or family-full).

Response (202): ChainVerifyJobAccepted — {job_id, poll_url}.

Response (409): verification_in_progress — an active job already exists for the target; the body carries its job_id (idempotent — the caller learns the in-flight id, no duplicate work).

Response (503): verifier_unavailable — queue at CHAIN_JOB_MAX_QUEUED, verifier disabled, or family unconfigured.

Poll one verify job. Requester-scoped: service callers see only their own jobs; admin sees all; an unknown or foreign id returns 404 (existence is not disclosed across requesters).

Response (200): ChainVerifyJobStatus — state ∈ {queued, running, done, error}, requested_loop, attempts (reclaims increment), the finalizing run summary once done, and error_code ∈ {coverage_incomplete, verifier_error, integrity_rejected, crashed} once error.

Per-event verification attestation — the citation-PDF input ("Cite for hearing" refuses to issue without it).

Query parameters: event_id (uuid, required), family, service (same rules as status).

Response (200): ChainAttestation. attested: true iff the position is found (view-mediated, indexed, across archive ∪ live), the row’s (instance, epoch) match the ACTIVE topology, seq sits within BOTH the shard’s tail verified_through AND the trusted (verifier-checked) manifest tip, and the family state is attestable (healthy/verifying). Otherwise attested: false with reason ∈ {unknown_event, newer_than_checkpoint, beyond_trusted_manifest, state_not_attestable, verifier_unavailable, foreign_topology}.

The closed request-error vocabulary (plan D8 — each row is a named test; this table is the doc source of truth):

Enqueue a durable archive run — never executes inline. The run moves rows whose received_at is older than the requested age threshold (cutoff computed by the database clock) from audit_events to audit_events_archive in bounded, per-chunk-committed transactions, always retaining the chain-head row.

Minimum role: admin only, USER-ONLY (#1427): service-class tokens are always 403 (service_class_on_user_only), and under enforcement the bearer must be an exchanged per-target token carrying admin. The run row records requested_by = admin:{sub} via EffectiveUser (scheduled runs record scheduler), so the requester must be a person.

Request: ArchiveRequest

archive_after_days is an age threshold, not a retention value — the archive retains rows indefinitely, so archiving early shortens nothing (retention policy — floors, legal hold, purge — is #1303). Sanity domain 1..=36500; outside it → 400.

Response (202): ArchiveRunAccepted — {run_id, poll_url}; the Location header carries the poll URL.

Response (400): archive_after_days outside 1..=36500.

Response (403): caller lacks admin role (service tokens included).

Response (409): an archive run is already queued or running — ONE active run total. The body carries that run’s ArchiveRunAccepted handle (no Location header): the caller learns the in-flight id, no duplicate work.

Response (503): database pool exhausted — retry later.

Idempotency: the run row is durable, so a replay under the same Idempotency-Key returns the stored handle (no transient-409 class exists). Use a fresh key per continuation run — e.g. when re-POSTing after a more: true outcome to drain a backlog.

Poll one archive run. Minimum role: service-class token or admin.

Response (200): ArchiveRunStatus — the durable run row projected onto the wire: run_id, state ∈ {queued, running, done, error}, requested_by (admin:{sub} or scheduler), requested_at, the frozen config snapshot (archive_after_days, chunk_size, max_chunks_per_pass), attempts (lease-expiry reclaims increment; the ladder finalizes error/crashed with progress intact), the per-chunk committed progress (chunks_committed, rows_archived — durable and pollable mid-run and after a crash), more, error_code/error_detail once error, and started_at/finished_at.

error_code is the closed set {duplicate_overlap, upgrade_state_unrepaired, statement_timeout, db_error, crashed} — each maps to a runbook procedure (Security Operations).

more semantics (set at done): the pass ended on a full chunk, so more movable rows may remain (this coexists with the retained chain head — more is about the chunk budget, not the head). more: true also pulls the scheduler’s next due time forward to the catch-up cadence, so backlogs drain without operator action.

Response (404): unknown archive run.

One keyset page of archived audit events, newest first.

Query parameters:

Response (200): Array of AuditEvent objects, ORDER BY received_at DESC, id DESC. Page 2 = pass the last row’s (received_at, id) as the cursor.

Response (400): limit out of domain, or a lone cursor half (validated before the query — negative paging can never reach PostgreSQL).

User-only (admin or quality_control) bulk export of the audit log (#1427: service bearers 403; enforced routes require an exchanged per-target token).

Query parameters:

Response (200): Audit events within the requested window (JSON array of AuditEvent, or CSV per format). The export reads archive ∪ live (#1208): a UNION ALL over the twin tables with explicit columns, ordered event_timestamp ASC, id ASC — the window spans the archive seam without truncation.

Response (400): Invalid time window or limit.

Response (403): Not a user-only-admissible bearer — service-class token, or the caller lacks the admin/quality_control role.