Compliance engineering implementation guide¶

Status: Current | Last reviewed: 2026-08-30

TrueServe now has an enforceable engineering baseline for SOC 2, HIPAA, GDPR, PCI DSS 4.0.1, CCPA/CPRA, CSA STAR, ISO/IEC 27001, and ISO/IEC 42001. The repository also contains a planning-only FedRAMP High AWS GovCloud profile. This implementation does not make TrueServe certified, attested, validated, or authorized. Contracts, operating evidence, independent examinations, and government authorization remain separate work.

What the implementation enforces¶

Layer	Enforcement
Policy source	JSON Schema validates versioned profiles. Exact profile hashes, expiry, regions, data classes, services, models, contracts, features, and required controls form the policy input.
Deployment ceiling	Terraform produces a manifest with partition, region, admitted profile hashes, and verified application controls. A tenant cannot activate a profile unless the manifest is verified and includes every required control.
Tenant assignment	Platform-admin APIs and database triggers reject planned, retired, unreviewed, expired, out-of-range, or unsupported assignments. Assignment expiry cannot exceed profile expiry.
Authoring and publish	Agent and workflow publishing evaluates the assigned profile, records the decision, and pins the profile revision, hash, and decision ID to the immutable artifact.
Runtime	Conversation and workflow startup reload trusted database state, checks the deployment manifest, repeats policy evaluation, and pins both compliance and AI-governance evidence to runtime records.
Providers	Default deny applies to provider, service type, exact model, region, inference scope, data class, fallback, and contract evidence. Bedrock guardrail ID and numbered version reach the actual invocation request.
Evidence	Critical records enter a tenant-specific SHA-256 chain. The exporter verifies the chain and writes deterministic, KMS-encrypted S3 Object Lock objects. Hash mismatch and stale delivery recovery fail safely.
Privacy	Verified requests cover access, portability, rectification, deletion, objection, restriction, and sale or sharing opt-out. Legal holds override deletion. The worker deletes database content and every exact S3 object version it knows.
AI governance	Governed releases require inventory, intended purpose, impact level, human oversight for high impact, approved risk assessment, passing exact-artifact evaluation, and independent expiring approval.
PCI	The payment vault is the only component permitted to handle PAN or a full IBAN. It returns tokens and masked metadata. Database and log guards reject prohibited card data.
Workloads	The regulated Helm overlay enables restricted pod settings, strict service-mesh mTLS, authorization policy, default-deny networking, dedicated service accounts, External Secrets, and explicit IRSA roles.
AWS	The regulated stack supplies multi-AZ RDS and Redis, customer-managed KMS keys, private endpoints, protected versioned storage, WORM evidence storage, CloudTrail, Config, Security Hub, flow logs, GuardDuty, alarms, and exact workload IAM.
Supply chain	Ordinary, hotfix, and environment-specific builds emit SBOM and provenance artifacts and sign immutable digests. Promotion verifies the upstream signer, recursively copies OCI referrers, and signs the target digest. The compliance workflow validates policy, database invariants, charts, Terraform, and the required release-workflow controls. Live branch protection, registry, admission, and vulnerability settings still require verification.

The canonical clause-level mapping lives in compliance/controls/catalog.yaml. Its maintenance guide identifies the indexed editions and the required assessor reconciliation. A mixed control has working code but still needs a customer, operator, contract, or live-environment action.

Available profiles¶

Profile key	State	Intended use
`commercial-regulated-us`	Active in source	Commercial US security, SOC 2, CSA STAR, ISO 27001, and ISO 42001 engineering boundary.
`hipaa-us`	Active in source	US PHI processing, only after the BAA chain and eligible service review are complete.
`privacy-us`	Active in source	CCPA/CPRA regional, rights, and retention restrictions.
`privacy-eu`	Active in source	GDPR regional, transfer, rights, and retention restrictions.
`pci-segmented-us`	Active in source	Segmented payment boundary, subject to acquirer or QSA scope confirmation.
`fedramp-high-us-govcloud`	Planned and non-assignable	GovCloud Class D build target. No environment has been deployed or authorized.

"Active in source" means the profile may be assigned only in an independently verified deployment whose manifest pins the same SHA-256. It does not mean an external compliance claim is active.

Build a commercial regulated environment¶

Create an isolated AWS account or approved account boundary, a private VPC, at least two private subnets in separate Availability Zones, and a private EKS cluster. Enable every EKS control-plane log and customer-managed Kubernetes secret encryption.
Copy commercial.tfvars.example to a protected, environment-specific location outside Git. Replace every placeholder. Configure an encrypted, locked remote Terraform backend.
Recompute and review the exact profile hashes with python scripts/compliance/validate.py. Never copy a hash from an unreviewed branch.
Keep deployment_verified = false and all application_controls_verified values false for the first plan and apply.
Run terraform -chdir=infra/stacks/aws-regulated init, plan, and the approved apply process. Capture the plan, approval, state version, resource inventory, and outputs as evidence.
Map these outputs into values-compliance-regulated.yaml: both bucket names, both KMS key ARNs, the database and Redis secret ARNs, the External Secrets reader role, every workload role, and the Bedrock role.
Set the exact Bedrock guardrail ID and numbered version. DRAFT and placeholders are rejected for a verified manifest.
Validate External Secrets retrieval, database TLS, Redis TLS, private DNS, endpoint routing, pod identity, default-deny networking, strict mTLS, backup restore, alarm delivery, audit export, privacy processing, and provider deny paths.
Before the first signed promotion, dispatch branch-build-deploy.yml on dev with rebuild_all=true. This establishes an SBOM, provenance, and verified signature for every current source image; promotion intentionally rejects an older unsigned image.
Verify MFA, vulnerability blocking, registry referrer support, SBOM/provenance/signature acceptance, independent AI approval, and the customer-specific BAA, DPA, or PCI AOC evidence.
Record the approved evidence ticket. Set each proven application_controls_verified entry to true, set eks_customer_managed_encryption_verified = true, and only then set deployment_verified = true. Apply again and use the resulting compliance_deployment_manifest_json unchanged.
Render the chart with the verified manifest. The Helm boundary rejects missing secrets, placeholder identities, region mismatch, a different envelope key, disabled envelope enforcement, or an incomplete verified configuration.

Terraform reads and verifies the existing EKS endpoint mode and log types. The explicit encryption attestation exists because a pre-existing cluster can hide implementation detail from this stack. Treat that input as an evidence-backed assertion, not a convenience flag.

Synchronize profiles and activate a tenant¶

Run profile synchronization from apps/ai-manager with an approved signer configuration:

pnpm exec tsx scripts/sync-compliance-profiles.ts

Production rejects unsigned profile bundles. COMPLIANCE_ALLOW_UNSIGNED_PROFILES=true works only outside production for local development.

Use POST /api/admin/tenants/{tenantId}/compliance as a platform administrator. Supply:

{
  "profileKey": "hipaa-us",
  "revision": 1,
  "enforcementMode": "enforce",
  "retentionDays": 365,
  "reason": "Approved PHI production boundary CHG-1234",
  "contractEvidence": {
    "BAA": { "evidence_id": "GRC-BAA-42" },
    "DPA": { "evidence_id": "GRC-DPA-18" }
  }
}

The API rejects an unverified environment, a stale profile hash, a missing required control, a missing profile, a planned profile, and retention outside the profile range. The database independently rechecks profile status, review and expiry, actor authority, reason, evidence shape, and retention.

Start in audit mode only for synthetic or non-regulated data. In that mode the system records denials without blocking them. Move to enforce only after deny-path results and downstream contracts have been reviewed. Never place regulated data in an audit-mode tenant.

Release an agent or workflow¶

For a compliance-assigned tenant:

Declare data classifications and required features in the artifact configuration.
Use a provider, exact model, region, and inference scope that the assigned profile admits.
Configure the deployment's exact Bedrock guardrail ID and numbered version for every Bedrock LLM stage.
Register the AI system through /api/ai-governance/{subjectType}/{subjectId}.
Record an approved risk assessment with a separate approver.
Run the approved evaluation suite against the exact draft SHA-256 and store its evidence URI, evidence hash, runner identity, provenance, and timestamps.
Obtain an independent, expiring release approval for that exact artifact hash.
Publish. The transaction records the policy and governance decisions and pins their evidence IDs to the published version.
Run preflight and one negative test. A changed draft invalidates evaluation and approval because the artifact hash changes.

Evidence operations¶

The audit exporter reads compliance_audit_events, verifies each involved tenant's full chain, and writes one deterministic JSON object per sequence to the evidence bucket. S3 Object Lock uses compliance mode. An existing object must carry the same event hash. A crashed delivery becomes eligible after its lease and remains idempotent.

Operators must alert on:

failed or stale compliance_audit_delivery_state rows;
an invalid result from verify_compliance_audit_chain(tenant_id);
CloudTrail, Config, GuardDuty, Security Hub, VPC flow-log, backup, or KMS alarms;
privacy requests approaching due_at or stuck past their worker lease;
expired profile reviews, assignments, exceptions, AI approvals, contracts, or provider eligibility reviews;
published artifacts whose pinned profile or AI evidence no longer matches current approved use.

Use GET /api/admin/tenants/{tenantId}/compliance/evidence to retrieve recent policy decisions, audit events, and the current chain result. Keep evidence objects and GRC records out of Git.

Required verification commands¶

python scripts/compliance/validate.py
PYTHONPATH=libs/envelope-encryption python -m pytest libs/envelope-encryption/tests -q
helm lint charts/trueserve-stack -f charts/trueserve-stack/values-compliance-regulated.yaml
helm lint charts/trueserve-stack -f charts/trueserve-stack/values-compliance-regulated.yaml -f charts/trueserve-stack/values-compliance-govcloud-planned.yaml
terraform -chdir=infra/stacks/aws-regulated init -backend=false
terraform -chdir=infra/stacks/aws-regulated validate

The dedicated compliance gate also runs cross-language policy tests, AI governance and encryption tests, chart assertions, repeatable migrations, and negative database invariants.

External acceptance still required¶

SOC 2 requires management assertions and a CPA examination over the defined system and period.
HIPAA requires role analysis, a BAA chain, risk analysis, policies, training, contingency testing, and breach operations.
GDPR and CCPA require legal-role decisions, notices, contracts, transfer analysis, DPIAs or risk assessments where required, appeals, non-discrimination, and downstream processor execution.
PCI requires confirmed scope, provider AOCs, applicable SAQ/AOC or ROC, scanning, penetration and segmentation tests, key operations, training, and incident evidence.
CSA STAR requires the chosen Level 1 submission or Level 2 assurance route.
ISO 27001 and ISO 42001 require operating management systems, internal audit, management review, corrective action, and certification audits when certification is claimed.
FedRAMP requires the work in GovCloud readiness. No code flag can substitute for an authorization decision.