ATO Readiness & Compliance Certification Matrix

On this page

Overview

This document maps federal regulatory requirements to Canopy’s implementation. It serves as the compliance certification matrix for Authority to Operate (ATO) evaluation.

Canopy processes data governed by multiple federal authorities:

  • IRS Publication 1075 — Federal Tax Information (FTI) protection for TANF and Medicaid

  • HIPAA — Protected Health Information (PHI) for Medicaid and CHIP

  • 7 USC §2025(e) / 7 CFR Part 272 — IEVS income verification for SNAP

  • NIST SP 800-53 — Security and privacy controls baseline

Policy traceability (every eligibility threshold ↔ authoritative source) is treated as a first-class ATO concern under ADR-011. The formal evidence statement — what each CI gate proves and how to regenerate the audit pack — is at ADR-011 Policy-Trace ATO Evidence (#413).

IRS Publication 1075 — Federal Tax Information

FTI is used by TANF and Medicaid programs for income verification. Canopy isolates FTI per ADR-004.

Pub 1075 Control Canopy Implementation ADR Status

Authorized access: FTI accessible only to authorized personnel

FTI physically isolated in canopy-tanf and canopy-medicaid databases. No cross-program database access (ADR-001). Role-based access control enforced on all handlers. Code-level enforcement: cargo xtask compliance audit-data-tenancy (CI job compliance-data-tenancy) scans every service’s migrations and source for protected field-name patterns and fails the build if FTI, IEVS, or SSA SOLQ/BINDEX fields surface in an unauthorised service. Authorisation matrix at compliance/data-tenancy-authorisation.toml.

ADR-001, ADR-004

✓ Implemented

Need-to-know: Minimum necessary access

Program service isolation — canopy-snap cannot query canopy-tanf database. Each service has its own connection pool and credentials.

ADR-001

✓ Implemented

Audit trail: All FTI access logged

fti_audit_log table schema exists in canopy-tanf and canopy-medicaid migrations. canopy-security wildcard subscriber captures all system events.

ADR-004

Partial — schema exists; dedicated FTI access middleware not yet implemented

7-year retention: FTI audit records retained minimum 7 years (Pub 1075 AU-11)

Archive management restored in canopy-security (#1208): durable async archive runs move rows past the operator-set archive_after_days age threshold into audit_events_archive per bounded, per-chunk-committed passes; the archive retains rows indefinitely, so retention is archive ∪ live. Retention floors + legal-hold become a general config-driven lifecycle under ADR-041 (#1303).

—

Partial — archive + configurable retention shipped; the enforced 7-year floor + legal-hold lifecycle is #1303 (ADR-041)

Encryption at rest: FTI encrypted when stored

AES-256-GCM field-level encryption for SSN (canopy-common crypto module). Other PII fields encrypted at database level when PostgreSQL TDE is enabled.

—

Partial — SSN encrypted; recommend PostgreSQL TDE for full coverage

Encryption in transit: FTI encrypted during transmission

rustls for all HTTP. PostgreSQL connections require sslmode=require in production. RabbitMQ supports amqps://.

—

✓ Configured

Event bus scrubbing: FTI never in event payloads

Publisher validates payloads against 27 restricted field names. FTI fields (agi, tax_return, federal_tax_information) are blocked before publish.

ADR-004

✓ Enforced at runtime

Annual inspection readiness: Audit logs available for IRS review

GET /v1/security/events API exports audit events. Archive API provides historical data. Hash chain verification confirms log integrity.

—

✓ API available

HIPAA — Protected Health Information (Medicaid/CHIP)

HIPAA Control Canopy Implementation Status

Minimum necessary: Access limited to minimum required

canopy-medicaid isolated database (ADR-001). Clinical data not shared with other program services.

✓ Implemented

Access controls: Role-based, user-level

Keycloak OIDC RBAC with 6 roles. All medicaid handlers require eligibility_specialist_or_above.

✓ Implemented

Audit controls: All PHI access recorded

canopy-security wildcard subscriber. All medicaid API calls generate audit events.

✓ Implemented

Encryption at rest

SSN: AES-256-GCM. Other PHI: recommend PostgreSQL TDE in production.

Partial

Encryption in transit

rustls, sslmode=require, amqps://

✓ Configured

Integrity controls: Data tamper detection

Determination signatures (ECDSA P-256 JWS). Audit hash chain (SHA-256).

✓ Implemented

Business Associate Agreements

Not documented — requires per-deployment BAA between state agency and hosting provider/integrator.

Gap — state responsibility

IEVS — Income and Eligibility Verification System

IEVS Requirement (7 USC §2025(e)) Canopy Implementation Status

Mandatory verification: Income verified against federal/state databases

canopy-verification service with IEVS adapter trait. NoopIevsAdapter for UAT; real adapter requires Georgia DOL API credentials and SSA Computer Matching Agreement.

✓ Architecture (NoopAdapter for UAT)

Data isolation: IEVS responses stored only in authorized program service

IEVS match results stored in canopy-snap database only (ievs_match_results, ievs_discrepancies tables). Per ADR-004, canopy-verification is transient — does not persist IEVS data.

✓ Implemented

Event bus scrubbing: No IEVS data in events

Publisher validates payloads — wage_records, ui_record, sdx_record, bendex_record, quarterly_wages, weekly_benefit_amount, monthly_ssi_amount, monthly_benefit_amount all blocked.

✓ Enforced

Discrepancy resolution: Worker can resolve income discrepancies

Worker portal Income tab shows discrepancies. POST /actions/resolve-discrepancy endpoint. Threshold: >$100/month variance.

✓ Implemented

Federal reporting: FNS-388 and FNS-7176 QC universe

canopy-reporting assembles from upstream services. FNS-7176 CSV export per column specification.

✓ Implemented

Data Retention Policy

Data Type Minimum Retention Maximum Retention Authority

FTI audit logs

7 years

7 years

IRS Publication 1075 §4 / AU-11

HIPAA PHI audit logs

6 years

7 years

45 CFR §164.530(j)

IEVS match results

Per CMA term

CMA term + 1 year

State Computer Matching Agreement

SNAP determination records

3 years

7 years

7 CFR 272.1(f)

General audit events

3 years

5 years

State records retention schedule

Notice PDFs

3 years

7 years

7 CFR 272.1(f)

Benefit issuance records

3 years

7 years

7 USC §2016(h)

The Minimum / Maximum columns are the legal envelope (federal floor to records-schedule ceiling). The concrete retention bound — and whether purge is enabled — are per-jurisdiction ruleset values, per chain family (ADR-003 / ADR-011; legal-hold aware), chosen within that envelope and bounded below by the federal floor — never a source constant.

Archive management (current state): archive and purge of the audit hash chains are governed by the ADR-014 chain-v2 contract (§C7), which specifies a contiguous chain_seq prefix per shard (retention decides eligibility, chain_seq decides the boundary), verification from the previous trusted boundary, and an externally-signed per-shard boundary manifest before local deletion — superseding the earlier single-transaction POST /v1/security/archive sweep.

NOTE

Superseded by ADR-041 (epic &74). The FTI hash chain + the chain-v2 archive/purge machinery are being retired for a general logging + jurisdiction-owned redaction facility, with retention + legal-hold as a general config-driven lifecycle (#1303) and external tamper-evidence delegated to the deployment logging facility. The chain_seq-prefix archive contract above describes the outgoing mechanism; retirement is gated behind a proven replacement (#1304). The re-scoped batching/index/scheduling work for archive_old_events stays as #1208.

NIST SP 800-53 Control Mapping

See NIST Architecture Mapping for the full control-by-control mapping.

Summary of key control families:

Family Controls Canopy Implementation

AC (Access Control)

AC-2, AC-3, AC-6, AC-7

Keycloak user provisioning, RBAC middleware, least privilege roles, account lockout via Keycloak

AU (Audit)

AU-2, AU-3, AU-6, AU-9, AU-11

Wildcard event subscriber, structured EventEnvelope, audit review API, hash chain integrity, archive management

IA (Identification & Authentication)

IA-2, IA-5, IA-8

Keycloak OIDC RS256 JWT, password policy in Keycloak, JWKS auto-refresh

SC (System & Communications Protection)

SC-8, SC-12, SC-13, SC-28

rustls TLS, ECDSA P-256 key management, AES-256-GCM encryption, PostgreSQL sslmode=require

SI (System & Information Integrity)

SI-2, SI-3, SI-4, SI-10

cargo-deny CVE remediation, SAST in CI, canopy-security breach detection, input validation

Gap Analysis

Gap Severity Remediation Plan

FTI access middleware not implemented

High

Tracked in fti-audit-logging plan Steps 1-9 (#149-157). Post-UAT.

PHI field-level encryption (beyond SSN)

Medium

Enable PostgreSQL TDE in production deployment. No code change required.

BAA documentation template

Medium

State agency responsibility. Provide template in deployment guide.

Re-encryption migration tooling

Low

Build migration tool for key rotation. Tracked as future enhancement.

Network-level segmentation documentation

Medium

Document in deployment guide. Recommend service mesh (Istio/Linkerd) for mTLS.
Edit this page · default