Compliance Hub & Reporting

Reference for the Compliance Hub: how the status of each control is worked out, how controls with no automated evidence are attested, how work is delegated and reviewed, how remediations are tracked, and how reports are generated, sealed and shared.

Where This Page Fits

Two shorter pages sit beside this one. The readiness score and how evidence is stored are on Readiness Score & Frameworks. When the background collector runs, the evidence files you upload and auditor access are on Evidence Collection. On all three, “evidence vault” means one thing: the sealed copies of report runs described under Evidence Vault, Share Links & File Verification.

What The Hub Guarantees

Compliance numbers are only useful if someone who did not produce them can trust them. Two rules make that possible.

Program & Auditor Room

In plain words: Program is where a compliance manager keeps the company’s own governance records: policies, risks, vendors and the list of which controls apply. Auditor room is where they deal with the outside auditor: a read-only link, the auditor’s requests for more evidence, the download package, and a public security page for the company.

Beyond per-control evidence, the hub keeps the governance records an auditor asks for and gives you controlled ways to show them your posture. In the app these are two tabs: Program (Policies, Risks, Vendors, Statement of Applicability, document templates and your scope) and Auditor room (Evidence requests, Auditor links, Trust Center, Evidence package, Control mapping). Who may read and change them, and the endpoints behind each tab, are under Technical detail below.

If something here is not working as you expect, start with When something goes wrong.

Evidence the probe could not gather — inconclusive, unknown, not_run, na, not_applicable — maps to attention, a counted gap. It never reads as a pass.

Live Control States

The live control state is the continuous per-control status that powers the hub. These routes sit under /reports/compliance/* and carry the soft complianceEnabled licence gate: allowed unless the Zonitix licensing server (the store) has explicitly disabled the Compliance Hub (an absent flag is allowed — the gate fails open).

The Rollup Rule An Inspector Checks

A refresh reads the append-only AuditEvidence rows tagged [ACTIVE VERIFICATION], groups them by control, and collapses each distinct signal (probe or alert) to its newest row. Then it applies a strict worst-status ordering — a control is a pass only if every signal passes:

• Any failing signal → fail. A later-finishing pass from a different probe cannot mask a confirmed fail.
• Else any inconclusive signal → attention. inconclusive / unknown / not_run / na / not_applicable evidence is treated as a gap, never as a pass.
• Else any pass older than the TTL → stale. The freshness window is 30 days (freshnessTtlDays: 30); a pass that has not been re-observed inside it degrades to stale rather than staying green forever. (That window is for automatically collected evidence; a manual pass — reviewed or attested — carries a 365-day window.)
• Otherwise → pass.

Auto-rolled states are stamped origin: "auto". The verifiable invariant on top of all of this: a state you set by hand is stamped origin: "manual" and the auto-rollup skips it entirely — a manual override is never auto-clobbered until an operator clears it. (When the rollup does touch an auto row, it preserves that row’s existing owner and dueDate.)

What The Hub Collects By Itself

In plain words: the hub does not wait for someone to upload proof for every control. On the collector’s timer (the schedule is on Evidence Collection), and whenever a compliance manager clicks Collect now, it reads seventeen sources inside your own instance and your connected systems, and records what it found against the controls each source covers. The Evidence & integrations tab shows whether each source is healthy, which controls are covered automatically for the framework you are working on, what needs attention now, and every piece of evidence attached to a control so far.

Each source runs as its own step and is recorded as ok or failed, so one broken source does not stop the others. A failed source is named in the refresh response (failedCollectors, each with id, label and error), in GET /harvest-status, and in the audit entry for the run. A source that could not run never turns a control green: missing evidence rolls up as attention, as described under Live Control States above.

When a control that was passing stops passing after a run, the hub writes a COMPLIANCE_CONTROL_DRIFT audit entry for that control (warning level, with the status it left and the one it moved to) and emails the holders of manage_compliance one message listing up to 25 of the controls that drifted. The email needs outbound email to be configured; the audit entry is written either way.

The Evidence Library

The lower half of the Evidence & integrations tab lists the evidence attached to the controls of the selected framework, and opens the control each item belongs to. Files and links are attached to a control with POST /reports/compliance/evidence (see Evidence Collection for the upload itself).

Per-Requirement Device Evidence

Controls that depend on your devices can be decided in two ways: by one check of the whole fleet, or requirement by requirement (encryption, firewall, screen lock and so on). Screen lock is the narrow one. No agent reports it, so it passes only for a Mac that has a Screen Lock profile of 15 minutes or less installed through Apple MDM, and a Windows or Linux computer in the fleet keeps it from reading as verified. A three-way switch, Per-requirement device evidence, chooses between them. It appears on a control whose evidence comes from devices, for people who hold manage_compliance or manage_security.

• Off (off): the per-requirement results are not computed.
• Shadow (shadow, the default): they are computed and compared with today’s result, but the single fleet check still decides. The switch shows what would change for the control if you turned it on.
• On (on): the per-requirement results decide device controls. The app asks you to confirm, because control results can change across the fleet.

A change takes effect on the next evidence run, not at once, and is logged as COMPLIANCE_DEVICE_EVIDENCE_MODE_CHANGED. These routes carry the same soft complianceEnabled gate as the rest of the hub.

Attestations — Controls With No Automated Signal

In plain words: some controls cannot be checked by a machine, such as a board sign-off. For those, a compliance manager can state that the control is met and write down the basis. That statement is an attestation. It is done from the control’s drawer on the hub’s Overview tab, and the hub always shows it as Attested so nobody mistakes it for a checked result.

Some controls cannot be probed (a signed policy, a board sign-off). A manager records a manual pass on such a control by attesting it. The attestation is written onto the live control state itself — status pass, origin: "manual", with the attester, the time and the basis note stamped on the row — and the hub labels it Attested, never a plain green pass. An attested pass is excluded from the headline verified readiness figure and goes stale after 365 days.

The Attestation Policy

Whether a single person may assert a pass is a customer setting, shown as Manual attestation under the hub’s Compliance settings. It has three modes: Allow (allow — attest freely), Note required (note_required, the default — a basis note is mandatory), and Review only (review_only — attestation is disabled and every manual pass must go through submit → review). Like the separate-reviewer toggle, the write is gated on manage_security, a right the reviewer population does not hold, so the people it governs cannot relax it.

The same actions appear in the hub on a control’s drawer: Attest (manual pass)…, Waive (mark N/A)… (a justification is required), Clear N/A…, Return to automated collection… and Revoke pass…. Attesting logs COMPLIANCE_CONTROL_ATTESTED (or COMPLIANCE_CONTROL_ATTEST_OVERRODE_REVIEW, at warning level, when it overrides a review someone else submitted); the others log COMPLIANCE_CONTROL_PASS_REVOKED, COMPLIANCE_CONTROL_RETURNED_TO_AUTOMATED and COMPLIANCE_CONTROL_NA_CLEARED. A refused action is logged as COMPLIANCE_CONTROL_ACTION_REFUSED.

Delegate & Review (Work Breakdown)

In plain words: a compliance manager shares the work out on the hub’s Owners tab, giving each section or control to a named person with a due date. Each owner sees only their own list under My Work → My Compliance Tasks, attaches evidence and submits it. A second person then approves it or sends it back with a note.

A framework is rarely one person’s job. Assign each domain (section) to an owner with a due date, and where a section splits across people, redirect an individual control to a different owner — resolution is control override → section default → unassigned, so the common one-owner-per-section case stays a single row. Assigning someone auto-grants the scoped view_assigned_compliance right; on unassign the grant is reference-counted, so a person keeps access as long as they still own work anywhere.

Submit → Review, With Separation Of Duties

An assignee evidences a control and submits it for review (scoped — they can only submit a control assigned to them); a reviewer then approves it to pass or reopens it to attention with a required note emailed back to the owner. Separation of duties is enforced server-side from the verified caller, not the request body: the person who submitted a control cannot approve their own unless the customer turns the policy off or the caller is administrator. The toggle is write-gated on manage_security — a right the reviewer population does not hold — so reviewers cannot disable their own SoD requirement. A never-submitted control cannot be approved straight to pass, and only a control that is actually awaiting review can be approved or sent back; a single-party pass must go through /attest (see Attestations above), which is logged distinctly. A control that is already passing, already in review, or marked Not applicable cannot be submitted (409), and one an automated check reports as failing needs evidence attached before it can be submitted or attested.

Program & Auditor Room: Permissions And Endpoints

For the two tabs described under Program & Auditor Room above. Reads need view_reporting or manage_compliance; writes need manage_compliance unless noted. All paths below are under /api/v1/compliance/reports/compliance.

Auditor Links — A Read-Only Room Without A Login

Auditor room → Auditor links → Manage links → Create link mints a link to a read-only view of one framework’s controls: each control’s status, how it was established, and whether evidence is attached. The auditor needs no account — the link is the credential. It expires (30 days by default, 180 at most), can be revoked at any time, and every view is counted and logged. The view is redacted: it does not expose internal notes, personal data or your evidence files. As with report share links, the full link is shown once at creation; lose it and you revoke and create another.

From that room the auditor can raise an evidence request against a control. The people who manage compliance and the control’s owner are notified, the request appears under Auditor room → Evidence requests and on the owner’s My Compliance Tasks, and a manager marks it resolved once the evidence is in place.

Your Own Public Trust Center Page

Auditor room → Trust Center → Edit Trust Center builds a public security page for your company, served from your instance: a headline and intro, the frameworks you choose to show (as “In program” or with a readiness percentage — your choice), a list of security practices, and a contact address for report requests. Practices can be added automatically, and only from controls that are actually passing. Nothing is public until you publish it; until then the public address returns 404. Reading or editing the page needs GET / POST /trust-center (manage_compliance to edit or publish).

Readiness Digest — Retired

Earlier versions could email a lightweight readiness digest on its own cadence. That send path has been retired in favour of Scheduled reports (below), which do the same job under the recipient policy, with a sealed run history and failure alerts. A digest that was still enabled on an instance was carried over once, automatically, into an equivalent scheduled report — you will find it in the schedule list and can edit or delete it there. Nothing needs to be migrated by hand.

A call to either retired endpoint is still recorded in the audit log as COMPLIANCE_DIGEST_RETIRED_CALL, so an old script hitting it is visible.

Remediation Tracking

In plain words: when a control is failing, a compliance manager records who is fixing it and by when. That record is a remediation. It is created with Track fix and shows as Fix tracked next to the failing control on the hub’s Evidence & integrations tab. Deadline reminders go to the people assigned a section or control on the Owners tab, not to the owner named on a remediation.

A remediation records the fix for a control — an owner, a due date, and a status — keyed one-per (framework, controlId). framework, controlId and title are required; status defaults to open.

Writes log COMPLIANCE_REMEDIATION_TRACKED; deletes log COMPLIANCE_REMEDIATION_DELETED. On an update, omitted owner / dueDate are preserved rather than nulled.

Score Recompute — The Integrity Control

Saving an assessment is the record that continuous monitoring happened — it becomes historical evidence. Because any view_reporting user could otherwise POST an inflated 100%, the server does not trust the client’s numbers. It re-runs the report engine for the framework — the same build the on-screen report, the downloads and the scheduler use — and stores that result. Only framework is read from the request; every posted number is ignored.

The stored readiness, pass / fail / manual / N/A counts and findings are the engine’s, so the home card, the opened report and the sealed vault artifact are one computation and cannot disagree. Not-applicable controls are left out of the denominator; the whole rule is under Readiness Scoring & Audit Activity. Stored findings keep the verdict and an affected count, but not the named sample of affected identities. The audit entry COMPLIANCE_REPORT_RUN records the server-computed value, the serverComputed flag, and the client’s reported value alongside it.

The Reporting Engine

In plain words: the Report Engine is where anyone with reporting access picks a report from a library, runs it on live data, and exports it. It covers the operational reports (system overview, custom query, lifecycle, endpoint compliance, budget) and, where the Compliance Hub is on your plan, the framework reports. The step-by-step version is the guide Run, save and share a report.

The generation, download, schedule and run-history routes carry the soft reportingEnabled gate — allowed unless the store explicitly disabled reporting. /generate and /download build a report on demand from the same engine the scheduler uses; pdf is the default format; csv, xlsx (Excel workbook) and pptx (slides) are the alternatives, and /download also accepts zip for an auditor pack. In the app this is the Report Engine screen, under Analytics in the menu.

The report definition is validated, not coerced — a bad field is a 400, never a silently-wrong report. kind is one of compliance (default; shown in the app as Framework readiness) / overview (System overview) / query (Custom query) / lifecycle (Lifecycle reconciliation) / device-posture (Endpoint compliance) / budget (Budget report) / crosswalk (Framework crosswalk) / type2 (Type II period report); a compliance or type2 report requires a framework from the real catalog of 146 controls across 8 frameworks (CCPA, GDPR, HIPAA, HITRUST, ISO 27001, NIST CSF, PCI DSS, SOC 2) — a typo is rejected rather than scored against zero controls and emailed as a confident 0%.

What A Report May Contain: Permission And Licence Floors

view_reporting opens the engine, but a report is never a way around the permission that guards the same data on its own page. Two further floors apply on every generate, download, archive, schedule and share. Where several permissions are listed, any one is enough.

A query report that asks for a data set the caller cannot see is refused with 403. The curated kinds (overview, compliance) still run, because they need the whole estate to score, but the raw rows of a data set the caller cannot see are stripped and only counts and totals remain. A data set or kind whose module is switched off on the licence is refused with 403, and with 402 while a subscription is lapsed. A type2 report must carry its period as window: { from, to }: both dates are required, they are read as whole UTC days, and the period can be at most 12 months (366 days); anything else is a 400.

Run History Records Every Attempt

/reports/runs is the generation audit trail, and it records the failures as well as the successes. A run whose report generated but did not deliver is stored with status: "failed" and a deliveryError that names which half broke — the report existing but never reaching an inbox is still a failed run from the recipient’s point of view.

Evidence Vault, Share Links & File Verification

In plain words: the evidence vault keeps a frozen copy of a report exactly as it was when it ran, with a fingerprint that proves it has not been changed since. Compliance managers use it to hand an auditor the same file they saw, to send it through a link that expires, and to stop a copy from being cleared out while a matter is open (a legal hold). Anyone holding a file can check it is genuine without an account.

A report run can be archived: the PDF, CSV and Excel renderings are stored as a point-in-time artifact with a recorded SHA-256 and a keyed seal. From there a run can be downloaded again, placed on legal hold, shared through an expiring link, bundled into an auditor pack, and checked by anyone holding the file. Slides (pptx) are a presentation format and are not kept in the vault.

Every one of these applies the same per-report-kind permission floor as generating the report, so a caller who could not open a budget or device report cannot archive it, list its links or publish one. Drill-down rows are additionally limited by the data set they come from (user rows need view_users, log rows view_logs). The full table of floors is under The Reporting Engine above.

How Long A Run Is Kept

An archived run is stamped with a retention date when it is stored. The period is the reportEvidenceRetentionDays setting and defaults to 2,555 days (about seven years). There is no control for it on screen. A run on legal hold is exempt from the retention sweep for as long as the hold stands.

Share Links

A share link opens one archived artifact without a login — the link itself is the credential, so treat it like a password. It defaults to 7 days and cannot exceed 90. Only a hash of the link is stored, so it is shown once at creation and cannot be listed again; if you lose it, revoke and create another. Sharing the CSV hands out the raw rows rather than a rendered report, so it requires an explicit confirmation (confirmCsv: true). Creating a link logs REPORT_SHARE_LINK_CREATED at warning level, each open is logged, and naming a recipient ties those log entries to the person the link was issued to. A link only ever serves the stored bytes — never a freshly generated report.

“Verify This File” — No Account Needed

Each archived PDF is stamped with its run id and a verify address on your instance (/verify/report/<run id>). Anyone holding the file — your auditor, or a customer of yours — can open that page and drop the file in. The page computes the SHA-256 in the browser; the file itself is not uploaded. The instance answers only match or no match, and on a match the framework, observation window, generation time and (for a PDF) the public details of the certificate that signed it. It returns no scores, findings or names, and a no-match does not reveal whether the run exists. There is no trusted timestamp authority behind the signature, and the page says so.

A match requires both the hash to equal the vault record and that record’s seal to verify, so a tampered record answers no-match. The hash outlives the retention sweep (only the stored bytes are pruned), so a file stays verifiable for as long as its run row exists.

Signed Webhooks

When a schedule delivers to a webhook, every POST carries a signature header so the receiver can prove it came from your instance and was not replayed. The signing secret is generated by the server per schedule (prefix whsec_), stored encrypted, and returned exactly once — when the webhook is added or the secret is rotated.

Scheduled Reports (CRUD + Run-Now)

In plain words: a scheduled report is sent by itself, daily, weekly or monthly, to the people you list. It is built from live data at the moment it runs, not from a saved copy. Compliance managers set these up from the Scheduled button on the Report Engine screen; the app offers scheduling for Framework readiness reports, with a PDF and/or CSV attached.

Recurring reports, delivered by email and/or to a webhook. Reads need view_reporting; anything that changes what gets sent to people needs manage_compliance. All of these carry the soft reportingEnabled gate.

Validation rejects rather than coerces: recipients must be valid emails (lower-cased, de-duplicated, at most 50), everyHours must be 1–2160 (90 days), and formats must be a subset of pdf / csv / xlsx / pptx (defaults to ["pdf"]). At save time nothing is silently dropped: an invalid or off-policy recipient is a 400, so you never save a schedule that looks fine and is wrong.

Delivery: Email, Webhook, And Who May Receive

A schedule delivers to email recipients over the customer’s own SMTP, and/or POSTs the run to a Slack / Teams / HTTPS webhook. The webhook URL is not trusted blindly: it is run through an SSRF / DNS-rebinding guard — the host is resolved and re-checked at send time, so a URL that resolves to a private or internal address is rejected (a bad URL is a 400 at save). Who may be emailed is governed by a recipient policy that is enforced in one place for both the write path and the send path, so the two cannot drift: open (any valid address, the default), domains (a domain allowlist), or directory (recipients must be known users or in the allowlisted domain). You set it in Security Settings → Report Delivery. The two paths behave differently on purpose: saving a schedule with an off-policy recipient is rejected, while at send time each run drops any recipient that is no longer on-policy — so tightening the policy later stops an existing schedule from mailing an address you have since excluded. The policy fails safe for the customer — an unreadable setting or directory falls back to open, so a lookup failure never withholds a report.