Compliance frameworks

Overview

Vigilo's compliance module provides a workspace-scoped library of Framework rows (SOC2, ISO27001, HIPAA today; more in the roadmap), Control rows under each framework, and a WorkspaceControlEvidence table that maps live evidence to specific controls. Evidence can be uploaded manually, attached from existing artifacts (audit log rows, changes, runbooks), or auto-collected by continuous monitor plugins (WB.14 implied, full library landing incrementally). A ComplianceSnapshotHistory rolls up control pass rate daily so trends are visible. AuditorShareToken (WB.15) creates read-only external links for an auditor to review without giving them a workspace account.

The compliance pages live under /ws/{slug}/governance/frameworks. The default landing view is the framework grid: each framework as a tile with a pass rate ring, count of in-progress controls, and the next gap to close.

Why it exists

A compliance audit cycle without tooling looks like: spreadsheet of controls, one row per control, one column per quarter, frantic evidence collection two weeks before the auditor walks in, conflicting versions of the spreadsheet between security and engineering. Most of the work is data gathering; the actual review is hours.

The framework module collapses the gathering into a continuous activity: every change, every cert renewal, every onboarding step is a candidate piece of evidence, and the right ones auto-attach to the right controls. By the time the auditor arrives, the evidence is already there; the audit becomes a review of methodology, not a scramble for data.

Models

Framework

Framework is workspace-scoped. Fields: name, version, description, is_active. Built-in seeds for SOC2 (Type II), ISO 27001:2022, and HIPAA Security Rule are created on first workspace activation of each. Custom frameworks (e.g. PCI DSS, internal control sets) can be created manually.

Control

Control belongs to a Framework. Fields: code (the framework's own identifier, e.g. CC6.1 for SOC2), name, description, category, owner_role (default approver role), evidence_required (text guidance for what evidence looks like).

The SOC2 / ISO27001 / HIPAA seeds populate the standard control catalogs. Note: the seeds today provide the structure (codes + names + descriptions) — full evidence requirement text and continuous monitor wiring lands incrementally. Expect to do some manual setup until the full library lands.

WorkspaceControlEvidence

The join table that links evidence (a URL, a file, an audit log row, a change request, a runbook) to a control. Fields: control, evidence_kind (audit_log / change / runbook / file / url / other), evidence_ref (polymorphic ref — UUID for an internal entity, URL for an external link), attached_by, attached_at, status (pending_review, accepted, rejected), notes.

Multiple evidence rows can satisfy one control; one piece of evidence can satisfy multiple controls.

Continuous monitor plugins

Each framework has a set of automated monitors that run nightly to check whether ambient controls are in a healthy state. Built-in monitors include:

• mfa-enforcement — verifies Workspace.settings['mfa_required']=True for all members. Auto-creates evidence rows pointing at the policy + a list of compliant members.
• member-onboarding-audit — verifies every member with high-privilege roles passed through the onboarding checklist. Attaches the audit entries for member.invite + member.onboarding_completed.
• audit-log-retention — verifies audit_retention.retention_days meets the framework's stated minimum (SOC2: 365, ISO: 365, HIPAA: 2190). Attaches the current retention policy as evidence.
• cert-renewal-success-rate — for any control mentioning cryptographic key management, attaches the rolling 90-day cert renewal success rate from the FastAPI cert DB.
• incident-postmortem-coverage — attaches the % of severity >= sev2 incidents in the last quarter that have a postmortem. SOC2 controls around incident response use this.

Monitors run via vigilo.compliance.monitor_sweep daily. Each monitor reports pass, fail, or unknown for the controls it covers. The result is attached as a WorkspaceControlEvidence with status auto-set to accepted on pass and pending_review on fail.

ComplianceSnapshotHistory

A daily Celery task vigilo.compliance.snapshot_history writes one ComplianceSnapshotHistory row per (workspace, framework, date) with the pass rate (fraction of controls with at least one accepted evidence row) and a breakdown by control category. The history page renders a 90-day trend chart so you can see whether you're improving.

AuditorShareToken (WB.15)

Auditors need read-only access without becoming workspace members. AuditorShareToken rows are workspace-scoped, framework-scoped tokens that expose /auditor/{token}/... — a stripped-down read-only UI showing the framework's controls, evidence, and snapshot history.

Fields: token (random URL-safe slug, 40 chars), workspace, framework, created_by, created_at, expires_at, revoked_at. The auditor uses the URL directly; no login required. The link is single-purpose: only the specific framework's data is visible, no other workspace data, no actions, no member list.

Revoke any time from Compliance → Auditor links; revocation is immediate and the token URL returns 410 Gone.

Common workflows

1. Enable SOC2 for a workspace

1. Open Governance → Frameworks → Add framework → SOC2 (Type II).
2. The seed migration populates ~64 standard SOC2 Trust Services Criteria controls.
3. The continuous monitors start running on the next nightly sweep.
4. Review the gap list — controls with no evidence are flagged red.

2. Attach evidence to a control

1. Click any control in the framework view.
2. Use Attach evidence. Options:
   • From audit log — opens a picker filtered to actions the control might cover.
   • From change — pick a change request.
   • Upload file — attach a PDF or screenshot.
   • External URL — paste a link to a runbook in Confluence, a Jira ticket, etc.
3. Save. The evidence appears in the control's evidence list with status pending_review (or accepted if it came from a monitor).
4. An admin or auditor reviews and clicks Accept or Reject.

3. Share with an external auditor

1. Compliance → Auditor links → New link.
2. Pick the framework (e.g. SOC2). Set expires_at (default 30 days).
3. Copy the URL and send to the auditor over a secure channel.
4. Auditor opens the URL; sees controls, evidence, snapshot trend; no other workspace data is visible.
5. When the audit concludes, click Revoke.

4. Investigate a dropping pass rate

1. Compliance → SOC2 → Trend.
2. Identify the day the pass rate dropped.
3. Click the day on the chart to see which controls regressed (evidence expired or new evidence rejected).
4. Address each regression by attaching new evidence or fixing the underlying gap.

Permissions

External auditors via share tokens have no role in Vigilo and can only read the share-token URL.

Troubleshooting

Pass rate is 0%. Monitors haven't run yet or no manual evidence has been attached. Wait for the nightly sweep or attach evidence manually.

A monitor that should pass is failing. Click the monitor's "view detail" link to see the raw check output. Most common cause: a single non-compliant member dragging the whole mfa-enforcement check to fail. Fix the underlying state.

Auditor share link returns 404. The token expired or was revoked. Check Compliance → Auditor links and create a new one.

Seed migration didn't create controls. The seed lives in the compliance app migrations. If the app wasn't in INSTALLED_APPS when the workspace was created, the seed didn't run. Run python manage.py seed_compliance_controls --workspace {slug} to backfill.

Custom framework: how? Compliance → Frameworks → New framework. Add Control rows manually or import a CSV. No continuous monitors are auto-wired; you'll need to set up ComplianceEvidenceQuery rows (see evidence collection article) to automate.

Related articles

• Evidence collection — automate evidence attachment.
• Audit log — the most common source of evidence.
• Vendor risk — vendor assessment outputs that map to vendor-management controls.
• Risk register — control-mapped risks.