fd90b2acd1
Implements all 22 WS6 tasks completing Phase 3 Enterprise. Column-level encryption (AES-256-CBC, Vault-backed key) via EncryptionService applied to credentials.secret_hash, credentials.vault_path, webhook_subscriptions.vault_secret_path, and agent_did_keys.vault_key_path. Backward-compatible: isEncrypted() guard skips decryption for existing plaintext rows until next read-write cycle. Audit chain integrity (CC7.2): AuditRepository computes SHA-256 Merkle hash on every INSERT (hash = SHA-256(eventId+timestamp+action+outcome+agentId+orgId+prevHash)). AuditVerificationService walks the full chain verifying hash continuity. AuditChainVerificationJob runs hourly; sets agentidp_audit_chain_integrity Prometheus gauge to 1 (pass) or 0 (fail). TLS enforcement (CC6.7): TLSEnforcementMiddleware registered as first middleware in Express stack; 301 redirect on non-https X-Forwarded-Proto in production. SecretsRotationJob (CC9.2): hourly scan for credentials expiring within 7 days; increments agentidp_credentials_expiring_soon_total. ComplianceController + routes: GET /audit/verify (auth+audit:read scope, 30/min rate-limit); GET /compliance/controls (public, Cache-Control 60s). ComplianceStatusStore: module-level map updated by jobs, consumed by controller. Prometheus: 2 new metrics (agentidp_credentials_expiring_soon_total, agentidp_audit_chain_integrity); 6 alerting rules in alerts.yml. Compliance docs: soc2-controls-matrix.md, encryption-runbook.md, audit-log-runbook.md, incident-response.md, secrets-rotation.md. Tests: 557 unit tests passing (35 suites); 26 new tests (EncryptionService, AuditVerificationService); 19 compliance integration tests. TypeScript clean. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
4.6 KiB
4.6 KiB
SOC 2 Type II Controls Matrix — SentryAgent.ai AgentIdP
This document maps the five in-scope SOC 2 Trust Services Criteria (TSC) controls to their corresponding implementation artefacts, mechanisms, and automated verification methods.
Controls Matrix
| Control ID | TSC Criterion Name | Implementation File | Mechanism | Automated Check |
|---|---|---|---|---|
| CC6.1 | Encryption at Rest | src/services/EncryptionService.ts |
AES-256-CBC column-level encryption on credentials.secret_hash, credentials.vault_path, webhook_subscriptions.vault_secret_path, agent_did_keys.vault_key_path. Key is stored in HashiCorp Vault KV v2 at path configured by ENCRYPTION_KEY_VAULT_PATH. IV is randomised per encryption call. Backward-compat: isEncrypted() gate allows plaintext rows to coexist during migration. |
GET /api/v1/compliance/controls returns CC6.1 status. Status is set to passing on service startup when EncryptionService initialises. |
| CC6.7 | TLS Enforcement | src/middleware/TLSEnforcementMiddleware.ts |
Express middleware registered as the first middleware in the app stack (before all routes and body parsers). In NODE_ENV=production, checks X-Forwarded-Proto header set by the upstream load balancer/reverse proxy. Any non-HTTPS request receives a 301 Moved Permanently redirect to https://. |
GET /api/v1/compliance/controls returns CC6.7 status. TLS enforcement is a static configuration control; status is set to passing on application startup. |
| CC7.2 | Audit Log Integrity | src/services/AuditVerificationService.ts, src/repositories/AuditRepository.ts, src/jobs/AuditChainVerificationJob.ts |
Each audit event (audit_events table) stores a hash (SHA-256 of eventId + timestamp + action + outcome + agentId + organizationId + previousHash) and previous_hash linking it to the prior event. An immutability trigger prevents UPDATE/DELETE on audit_events. AuditChainVerificationJob re-walks the entire chain every hour. |
Prometheus gauge agentidp_audit_chain_integrity (1 = passing, 0 = failing). Prometheus alert AuditChainIntegrityFailed fires when gauge = 0. GET /api/v1/audit/verify triggers an on-demand verification. GET /api/v1/compliance/controls returns CC7.2 status. |
| CC9.2 | Secrets Rotation | src/jobs/SecretsRotationJob.ts |
SecretsRotationJob runs every hour (configurable via SECRETS_ROTATION_CHECK_INTERVAL_MS) and queries credentials for active credentials expiring within 7 days. For each, it increments the agentidp_credentials_expiring_soon_total Prometheus counter with the owning agent_id. Operators are expected to act on the alert within the 7-day window. |
Prometheus counter agentidp_credentials_expiring_soon_total per agent_id. Prometheus alert CredentialExpiryApproaching fires when any increase is detected. GET /api/v1/compliance/controls returns CC9.2 status. |
| CC7.1 | Webhook Dead-Letter Monitoring | src/workers/WebhookDeliveryWorker.ts |
WebhookDeliveryWorker processes webhook deliveries from a Redis queue. After exhausting all retry attempts (configurable WEBHOOK_MAX_RETRIES), the delivery is moved to dead-letter status and agentidp_webhook_dead_letters_total is incremented. |
Prometheus counter agentidp_webhook_dead_letters_total per organization_id. Prometheus alert WebhookDeadLetterAccumulating fires when > 10 dead-letters accumulate in 1 hour. GET /api/v1/compliance/controls returns CC7.1 status. |
Evidence Collection
For a SOC 2 Type II audit, the following evidence should be collected:
| Evidence Type | Collection Method |
|---|---|
| Encryption at rest configuration | Export Vault KV v2 policy + _encryption_migration_log table contents |
| TLS certificate and enforcement logs | Load balancer access logs + X-Forwarded-Proto middleware responses |
| Audit chain integrity report | GET /api/v1/audit/verify with full date range |
| Secrets rotation compliance | Prometheus metric history for agentidp_credentials_expiring_soon_total |
| Webhook dead-letter rate | Prometheus metric history for agentidp_webhook_dead_letters_total |
| Immutable audit log dump | Direct PostgreSQL export of audit_events table with hash verification |
References
- SOC 2 Trust Services Criteria: AICPA TSC 2017
- OpenAPI spec:
docs/openapi/compliance.yaml - Encryption runbook:
docs/compliance/encryption-runbook.md - Audit log runbook:
docs/compliance/audit-log-runbook.md - Incident response:
docs/compliance/incident-response.md - Secrets rotation:
docs/compliance/secrets-rotation.md