SOC 2 Controls skill for Codex

Done well means: each control is something the systems enforce (not a promise in a policy document), it produces dated evidence without someone remembering to take screenshots, and the evidence matches what the policy says. The auditor (a licensed CPA firm) decides what satisfies a criterion; engineering makes the control real and the evidence easy to pull.

Orient first

• Ask for the scope: Type I (design at a point in time) or Type II (operating effectiveness over an observation window, typically 3-12 months); which Trust Services Criteria (Security is always in; Availability, Confidentiality, Processing Integrity, Privacy are optional); which systems are in the boundary.
• Read the existing policies and the control list (from the compliance platform or the auditor’s request list). Controls in policies that no system enforces are the main source of exceptions.
• Read AGENTS.md and find the real systems: Git host, CI, cloud accounts, identity provider, ticketing, on-call, logging.

Engineering control map

Area	TSC	Control (enforced)	Evidence
Identity	CC6.1	SSO via the IdP for GitHub, cloud console, CI, production tools; MFA enforced	IdP app list; org MFA/SSO setting export
Access provisioning	CC6.2, CC6.3	Access granted by ticket with manager approval; removed within 24h of offboarding	Ticket samples; IdP deprovisioning logs
Access review	CC6.2, CC6.3	Quarterly review of privileged and production access, changes actioned	Signed review export with removals
Least privilege	CC6.3	No standing prod admin; break-glass with alerting	IAM policy export; break-glass alert config
Encryption	CC6.1, CC6.7	TLS in transit; KMS at rest on DBs, buckets, backups	Config export / IaC
Change management	CC8.1	Protected default branch, required review, required CI, no direct pushes	Ruleset export; PR samples
Vulnerability mgmt	CC7.1	Dependency, container and cloud scanning with SLA by severity	Scanner reports; ticket ageing
Logging and monitoring	CC7.2	Central logs, retention set, alerts routed to on-call	Retention config; alert rules; pager history
Incident response	CC7.3-CC7.5	Documented IR process, tabletop or real incident per year, postmortems	IR doc; postmortem links
Backups and recovery	A1.2, A1.3	Automated backups; restore tested at least annually	Backup policy; restore test record
Vendor management	CC9.2	Critical vendors reviewed annually (their SOC 2 report, DPA)	Vendor list with review dates

Remediation SLAs commonly used (confirm against the written policy): critical 7-15 days, high 30 days, medium 90 days. Whatever the policy says is what the auditor tests.

Change management in GitHub

Enforce with repository rulesets (org-level where possible) so the setting is uniform:

gh api repos/OWNER/REPO/rulesets --jq '.[] | {id, name, enforcement}'
gh api repos/OWNER/REPO/rulesets/RULESET_ID --jq '.rules[].type'
# expect: pull_request (required approvals >= 1, dismiss stale reviews),
#         required_status_checks, non_fast_forward, deletion
gh api repos/OWNER/REPO/branches/main/protection 2>/dev/null   # classic protection, if used

• Required approvals at least 1, from someone other than the author; dismiss stale approvals on new commits; require code owner review for infra and auth paths.
• Bypass list empty or limited to a break-glass role, and every bypass reviewed. An admin who can merge without review is a finding in every Type II sample.
• Infrastructure changes go through the same flow (Terraform in Git, applied by CI). Console changes in production break the control; detect them with drift detection or CloudTrail alerts.
• Changing org rulesets or IdP enforcement affects everyone; propose the change and apply it only after the user confirms.

Evidence collection that runs itself

Write small scripts that export evidence with dates, and run them on a schedule (CI cron) into a restricted bucket or the compliance platform. Prefer the compliance platform’s native integrations when they cover a control; script only the gaps.

# Sample of merged PRs with reviewers for the observation window
gh pr list --repo OWNER/REPO --state merged --search "merged:2026-07-01..2026-09-30" \
  --limit 500 --json number,title,author,mergedAt,reviews,mergedBy \
  > evidence/cc8.1/prs-2026Q3.json

# PRs merged without an approving review (should be empty or explained)
jq '[.[] | select(([.reviews[] | select(.state=="APPROVED")] | length) == 0)
     | {number, title, author: .author.login, mergedBy: .mergedBy.login}]' \
  evidence/cc8.1/prs-2026Q3.json

# Org members without 2FA (needs org admin token)
gh api "orgs/ORG/members?filter=2fa_disabled" --jq '.[].login'

# AWS: IAM users with console access and no MFA (read-only IAM permissions)
aws iam generate-credential-report >/dev/null; sleep 5
aws iam get-credential-report --query Content --output text | base64 --decode \
  | awk -F, 'NR>1 && $4=="true" && $8=="false" {print $1}'

Evidence rules:

• Every artifact is dated, shows the system it came from, and covers the whole population or the auditor’s sample, not a hand-picked example.
• Keep evidence in a restricted location; exports contain names, emails and access lists.
• Screenshots only where no export exists, with the URL and clock visible.

Gaps that cause exceptions

• Offboarding removes the IdP account but a local GitHub, cloud IAM user or database user survives. Reconcile every system against HR’s leaver list monthly.
• Shared accounts or long-lived access keys for humans. Replace with SSO and roles.
• Emergency hotfix pushed directly to main with “will review later” and no later review. Policy should define the emergency path with retroactive review within a set time.
• Access reviews done but not actioned: the export shows a “remove” decision and the access still exists a month later.
• Restore test never performed; backups configured is not the same as recoverable.
• Policy promises (encryption of laptops, annual training, background checks) with no system or record behind them. Either implement or change the policy before the window.

Verification

• For each control, run its evidence query for the last full month and confirm the output shows the control operating with zero unexplained exceptions.
• Pick five random merged PRs, five leavers and five production access grants; trace each end to end as an auditor would.
• List remaining gaps with owner and date, and hand the control matrix to the compliance owner. Whether a gap is acceptable is the auditor’s judgement, not Codex’s.

Output template

| Control ID | TSC | Control | System enforcing | Evidence source | Frequency | Status | Owner |
|---|---|---|---|---|---|---|---|
| ENG-CM-01 | CC8.1 | Default branch requires 1 approval + CI | GitHub org ruleset "prod-default" | evidence/cc8.1/*.json | Quarterly export | Operating | @platform |
| ENG-AC-03 | CC6.2 | Leavers removed from AWS within 24h | IAM Identity Center via Okta SCIM | Okta deprovision log | Monthly reconciliation | Gap: 2 local IAM users | @infra, 2026-11-15 |