SOC 2 Compliance Coding Guidelines

1. Overview

SOC 2 (Service Organization Control 2) is an auditing framework developed by the AICPA for service organizations that store, process, or transmit customer data. It evaluates controls based on five Trust Services Criteria: Security, Availability, Processing Integrity, Confidentiality, and Privacy. SOC 2 Type I assesses control design at a single point in time; Type II evaluates operating effectiveness over a 3-to-12-month observation period and is the standard customers demand. Audits typically cost $20K-$100K+ depending on scope and complexity. The core principle for developers: “Say something, do something, prove you always do what you say.” Every control you implement must be documented, consistently enforced, and produce evidence that auditors can verify.

2. The 5 Trust Services Criteria

Security is always in scope. The other four are selected based on what your service does. A SaaS platform handling customer data typically includes Security + Availability + Confidentiality at minimum.

3. Common Criteria (CC1-CC9) — Security Deep Dive

4. Access Controls (CC6)

Key Principles

• RBAC over user checks — Define roles with explicit permissions. Never check for specific users; always check roles or permissions.
• Least privilege — Start with zero access, grant only what is needed. Scoped API keys, not global keys.
• Audit everything — Log every authorization decision (granted and denied) with user ID, resource, permission, IP, and timestamp.
• Session limits — 15-minute idle timeout, 12-hour absolute timeout, maximum 3 concurrent sessions per user, secure cookie flags (HttpOnly, Secure, SameSite=Strict).
• MFA for sensitive actions — Require MFA for admin operations, data export, role changes, and API key management.
• API key hygiene — Hash keys at rest (never store plaintext), enforce expiration (90 days max), scope to specific permissions, show raw key only once at creation.
• Quarterly access reviews — Export active users with roles and last login; flag accounts inactive 90+ days for deprovisioning; audit all permission changes.
• Deprovisioning checklist — On termination: deactivate account, terminate all sessions, revoke all API keys, revoke OAuth tokens, remove from all groups. Log every step.

Implementation code: RBAC middleware (Python, Node.js), session management, API key lifecycle, access review SQL queries, deprovisioning automation — see resources/access-encryption.md

5. Encryption Standards

Requirements

Anti-patterns

• Never hardcode secrets: DATABASE_URL = "postgresql://admin:s3cr3t@..." is a CC6 violation.
• Never commit .env, *.pem, *.key, or credentials.* files. Enforce via .gitignore.
• Always load secrets from vault at runtime, fall back to environment variables.

Implementation code: AES-256 encrypt/decrypt with key rotation, TLS config, vault-based secrets loading (Python, Node.js) — see resources/access-encryption.md

6. Logging and Monitoring (CC7)

What to Log

Log Requirements

• Format: Structured JSON with timestamp, service, event, actor (user_id, IP, user_agent, session_id), resource (type, id), action, outcome, request_id.
• Retention: Audit logs 365 days minimum, application logs 90 days, security logs 365 days with real-time alerting.
• Immutability: Append-only storage. No edits or deletes. Encrypted at rest (AES-256). Restricted access (admin + auditor only).

Implementation code: Structured audit logger (Python, Node.js), log retention policy config — see resources/logging-change-incident.md

7. Change Management (CC8)

Branch Protection Rules

• At least 1 approving review required; dismiss stale reviews; require code owner reviews.
• Required status checks: unit tests, integration tests, security lint. Branch must be up to date.
• Enforce for admins — no bypasses. No direct push. No force pushes. No deletions. Linear history required.

Deployment Requirements

• Every deployment links to a tracked change request (ticket/PR/CR).
• Author and approver must be different people (segregation of duties).
• All tests must pass before deployment. Rollback plan required.
• Deployment record includes: deployment_id, environment, timestamp, deployer (service account), change_request, PR, commit SHA, approver, author, tests_passed, rollback_plan, changes_summary.

Emergency Changes

• Allowed only for: active security incidents, customer-affecting outages, production data integrity issues.
• Requires verbal approval from on-call lead (documented within 24 hours), post-deployment review within 48 hours, retroactive change request ticket, and root cause analysis.

Implementation code: Branch protection YAML, deployment validation, emergency change policy — see resources/logging-change-incident.md

8. Incident Response (CC7)

Severity Classification

Key Components

• Health checks: Component-level status endpoints (database, cache, storage, external APIs) with latency measurement.
• Anomaly detection: Thresholds for failed logins (10/user/hour, 50/IP/hour), API errors (100/min), data exports (500MB), admin actions (50/hour), after-hours admin logins (1).
• Containment automation: On suspected compromise, immediately disable account, terminate sessions, revoke all credentials, block suspicious IPs, preserve evidence.
• Post-incident review: Timeline (detected, acknowledged, contained, resolved, post-mortem), impact assessment (customers affected, data exposed, downtime), root cause, remediation (immediate + long-term), lessons learned, action items with owners.

Implementation code: Health check endpoints, anomaly detection, severity definitions, containment automation, post-incident template — see resources/logging-change-incident.md

9. Availability Controls

Key Patterns

• Circuit breaker: Track failures per dependency. After threshold (e.g., 5 failures), open circuit and reject requests immediately. After recovery timeout, allow test requests. Close circuit after success threshold met.
• Retry with exponential backoff: Max 3 retries, base delay 1s, max delay 30s, jitter to prevent thundering herd. Only retry on transient errors (502, 503, 504, ECONNRESET, ETIMEDOUT).
• Backup verification: Monthly restoration tests to isolated environment. Verify checksum, restore, validate data integrity (record counts + sample records). Log results as SOC 2 evidence.

Implementation code: Circuit breaker (Python), retry with backoff (Node.js), backup verification — see resources/availability-integrity.md

10. Processing Integrity Controls

Key Patterns

• Input validation: Validate at every API boundary. Use schema validation (Pydantic, Joi, etc.). Reject invalid data early. Log validation failures with endpoint and error details.
• Idempotency: State-changing operations must accept an idempotency key. Check for existing result before processing. Store results with 24-hour TTL. Log both new processing and replays.
• Data reconciliation: Periodic cross-system checks (e.g., usage records vs invoices). Flag discrepancies exceeding threshold (e.g., $0.01). Alert on mismatches. Log reconciliation results as evidence.

Implementation code: Input validation (Python Pydantic, Node.js), idempotency pattern, billing reconciliation — see resources/availability-integrity.md

11. Data Handling

11.1 Data Classification

11.2 Retention and Deletion

• On customer deletion: remove from all tables (records, files, metadata, API keys, sessions), verify zero remaining rows, log with full audit trail.
• Test data: Never use production customer data in non-production environments. Generate synthetic data or properly anonymize (mask names, emails, phones, addresses; preserve structural non-PII fields).

12. Vendor Management (CC9)

Vendor Registry Requirements

Every third-party vendor accessing customer data must have a registry entry tracking:

• Vendor name, service provided, data access level, data classification
• SOC 2 report status (type, date, findings, next review)
• Contract clauses: data protection, audit rights, breach notification SLA, deletion on termination, subprocessor notification
• Risk rating (low/medium/high/critical), review dates, owner

Security Requirements Checklist

• SOC 2 Type II report available and reviewed
• Data encryption at rest (AES-256 or equivalent)
• Data encryption in transit (TLS 1.2+)
• Access controls with least privilege
• Incident response plan with notification SLA
• Business continuity and disaster recovery plan
• Background checks for employees accessing data
• Data deletion capability upon contract termination
• Subprocessor disclosure and notification
• Right to audit clause in contract
• Data residency and jurisdiction compliance
• Vulnerability management program

Annual vendor security assessments are required. Log assessment initiation and results.

13. Type I vs Type II — Developer Impact

Type I answers: “Are your controls designed properly?” Type II answers: “Do your controls actually work, consistently, over time?”

14. Evidence Generation Patterns

Auditors typically request 200-300 evidence items. Automate collection wherever possible.

Evidence Categories

Implementation code: Evidence category map, automated quarterly export function — see resources/evidence-collection.md

15. Common Mistakes

16. Quick Reference

DO

• Encrypt all customer data at rest (AES-256) and in transit (TLS 1.2+)
• Implement RBAC with least privilege — check permissions, not usernames
• Log all authentication, authorization, data access, and configuration changes
• Use structured JSON logs with timestamps, user IDs, IPs, and request IDs
• Require peer review for all code changes — no self-merges
• Link every deployment to a tracked change request
• Rotate secrets and API keys on a defined schedule (90 days maximum)
• Set session timeouts (15-minute idle, 12-hour absolute)
• Validate all inputs at API boundaries
• Use idempotency keys for state-changing operations
• Test backup restoration monthly and log results
• Run quarterly access reviews and deactivate unused accounts
• Maintain a vendor inventory with annual security reviews
• Classify data and apply controls matching the classification level
• Generate automated evidence exports for auditors
• Document and test incident response procedures annually
• Use unique service accounts with minimum necessary scope
• Mask or exclude PII from log entries

DO NOT

• Hardcode secrets, API keys, or credentials in source code
• Use production customer data in test or staging environments
• Allow self-approval of code changes or deployments
• Deploy without automated tests passing
• Share service accounts or credentials between people or systems
• Store logs in mutable storage where entries can be edited or deleted
• Skip input validation because “the frontend handles it”
• Swallow exceptions without logging them
• Use Access-Control-Allow-Origin: * on authenticated endpoints
• Grant admin access by default — start with minimum permissions
• Ignore failed login attempts — alert on brute force patterns
• Delete audit logs before the retention period expires
• Skip vendor security reviews because “they are a big company”
• Deploy emergency changes without retroactive documentation
• Assume encryption is handled by the infrastructure — verify it
• Log raw credentials, tokens, or full credit card numbers

Resources

Detailed implementation code for each control area:

• resources/access-encryption.md — RBAC middleware, session management, API key lifecycle, access review queries, user deprovisioning, AES-256 encryption, TLS configuration, secrets management
• resources/logging-change-incident.md — Structured audit logger, log retention config, branch protection YAML, deployment tracking, emergency change policy, health checks, anomaly detection, severity classification, containment automation, post-incident review template
• resources/availability-integrity.md — Circuit breaker pattern, retry with exponential backoff, backup verification, input validation, idempotency, data reconciliation
• resources/evidence-collection.md — Evidence category map, automated quarterly evidence export