content(what-is): expand the SOC 2 explainer

[alexleventer]

Summary

Rewrites content/what-is/what-is-soc-2.md from a general overview into a deeper reference that an engineering or compliance team can actually use. Body grows from ~290 lines to ~180 well-structured lines with clearer tables, FAQ, and IaC integration patterns.

What changed

• Opening definition — quotable one-paragraph definition followed by a short lead-in covering AICPA, SSAE 18, and the voluntary nature of SOC 2.
• Why it matters — sales gate for SaaS, trust without exposing internals, forcing function for the security program.
• Trust Services Criteria table — Security (required), Availability, Processing Integrity, Confidentiality, Privacy. Includes a "when it applies" column.
• Type I vs. Type II comparison table — question answered, period covered, evidence, time-to-issue, buyer preference.
• SOC 1 / SOC 2 / SOC 3 table — clarifies who each report is for so readers stop confusing them.
• SOC 2+ section — common combinations: HITRUST, HIPAA, ISO 27001, NIST CSF, CSA STAR.
• Seven-step audit process — scoping → readiness → remediation → observation period → fieldwork → report issuance → renewal. Names compliance-automation platforms (Vanta, Drata, Secureframe, Thoropass) where relevant.
• SOC 2 vs ISO 27001 vs HITRUST table — origin, format, scope, typical buyer use.
• IaC + SOC 2 section — concrete control patterns: change management evidence via PRs, IAM as code, policy as code in CI, ESC for secrets, reusable components for secure defaults, drift detection.
• FAQ — ten doubt-removers: certification vs. attestation, Type I or II, cost, audit duration, scope choice, who can audit, public sharing, subprocessors and carve-outs, GDPR relationship.
• Learn-more cross-links — cloud security, HIPAA, HITRUST, secrets management, configuration management.

Test plan

• make serve; visit /what-is/what-is-soc-2/ and confirm all four tables and headings render correctly
• Spot-check cross-links (/what-is/what-is-hipaa/, /what-is/what-is-hitrust/, /what-is/what-is-cloud-security/, /docs/insights/policy/)
• CI lint + pinned review

🤖 Generated with Claude Code

[pulumi-bot]

Your site preview for commit 2e146a9 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-19144-2e146a9d.s3-website.us-west-2.amazonaws.com

[alexleventer]

@claude - review this pr please

[pulumi-bot]

Claude finished @alexleventer's task in 2m 17s —— View job

---

PR Review: content(what-is): expand the SOC 2 explainer

Tasks:

• Gather context and understand the request
• Read the changed file and diff
• Review content for accuracy, style, and quality
• Post review feedback

---

Overall assessment

This is a genuine improvement — the rewrite transforms a shallow overview into a useful reference with well-structured tables, a clear audit process walkthrough, and a strong IaC integration section. All internal cross-links are valid, heading case is correct throughout, and the FAQ format follows the style guide. A few issues to address before merge.

---

Issues

1. Bold-wrapped opening definition — inconsistent with peer pages

content/what-is/what-is-soc-2.md, line 10

**SOC 2 (System and Organization Controls 2) is an attestation report...** A SOC 2 report...

Peer pages in the same family (what-is-hipaa.md, what-is-hitrust.md, what-is-cloud-security.md) open with plain prose, not a bold-wrapped definition block. The full-sentence bold span is also awkward visually — it creates a misleading block-emphasis that implies everything before the ** is a definition and the trailing sentence is secondary.

Suggest dropping the ** markers and writing it as regular prose, e.g.:

SOC 2 (System and Organization Controls 2) is an attestation report produced by an
independent CPA firm that evaluates a service provider's controls against the AICPA's
Trust Services Criteria (security, availability, processing integrity, confidentiality,
and privacy). A SOC 2 report is what most US enterprise buyers ask SaaS vendors to
produce before signing a contract.

Fix this →

---

2. meta_desc format inconsistency

content/what-is/what-is-soc-2.md, line 3

meta_desc: "SOC 2 is an AICPA attestation..."

Every peer page in content/what-is/ uses the YAML block scalar form:

meta_desc: |
    SOC 2 is an AICPA attestation...

The inline quoted string works, but it's inconsistent with the established pattern. Minor, but worth aligning.

Fix this →

---

3. External link needs verification

content/what-is/what-is-soc-2.md, line 12

[SSAE 18](https://us.aicpa.org/research/standards/auditattest/ssae)

The AICPA merged with CIMA and the website has been reorganized under aicpa-cima.com. The us.aicpa.org domain may still redirect, but this URL format is from the old site structure and is worth verifying before merge. If it's broken, the standard is now at aicpa-cima.com — or it can simply be unlinked since "SSAE 18" is a well-known named standard.

---

Minor suggestion

authors field — The page retains authors: ["asaf-ashirov"] from the original. If the PR author wants to take credit for the rewrite, they should be added. If intentional to keep the original attribution, that's fine too.

---

What's done well

• All internal cross-links resolve correctly: /what-is/what-is-hipaa/, /what-is/what-is-hitrust/, /what-is/what-is-cloud-security/, /what-is/what-is-secrets-management/, /what-is/what-is-configuration-management/, /docs/insights/policy/, /docs/iac/concepts/components/, /product/esc/, /docs/get-started/
• H2 headings are correctly in sentence case; H3 FAQ headings end with ? as required by the style guide for FAQ JSON-LD detection
• Ordered list items for the audit process correctly use 1. throughout
• Tables are accurate and well-structured — the Type I/II comparison and the SOC 1/2/3 differentiation table are particularly useful
• The IaC integration section maps Pulumi products (CrossGuard, ESC, components) concretely to SOC 2 control areas — this is the strongest section of the rewrite
• Factual claims (cost ranges, timelines, compliance platform names) are reasonable and consistent with current market reality

---

| Branch preview

[CamSoper]

@claude #new-review

[github-actions]

Pre-merge Review — Last updated 2026-05-19T18:55:50Z

Tip

Summary: This PR is a substantive rewrite and expansion of the /what-is/what-is-soc-2/ explainer — adding the TSC table, Type I vs II comparison, SOC 1/2/3 table, SOC 2+ variants, audit-process steps, ISO/HITRUST comparison, an IaC-supports-SOC-2 section, and a 9-question FAQ. All 6 previously-outstanding factual contradictions are resolved; deprecated "CrossGuard" term replaced with "Pulumi Policies" per @CamSoper. No outstanding findings.

Review confidence:

Dimension	Level	Notes
mechanics	HIGH
facts	HIGH	46-claim verification trail completed; all 6 contradictions resolved. Re-verified after force-push/rebase — no regression.

Investigation log

• Force-push detected: history rewritten since last review; re-reviewed against full PR diff at HEAD (16cc04c).
• Cross-sibling reads: not run (not in a templated section)
• External claim verification: 34 of 46 claims verified (3 unverifiable, 6 contradicted) · previous trail reused; new commits only changed author frontmatter, one quantifier word, and terminology — no re-extraction needed.
• Frontmatter sweep: author field updated; meta_desc unchanged.
• Code execution: not run (no static/programs/ change)

🚨 Outstanding	⚠️ Low-confidence	💡 Pre-existing	✅ Resolved
0	0	0	7

🔍 Verification trail

See previous run — unchanged since 78719ba

Claim-by-claim trail is unchanged. See the 2026-05-19T16:14:27Z run for the full 46-claim log.

🚨 Outstanding in this PR

No outstanding findings.

⚠️ Low-confidence

No low-confidence findings.

💡 Pre-existing issues in touched files (optional)

No pre-existing issues in touched files.

✅ Resolved since last review

• [L61] content/what-is/what-is-soc-2.md — "Most vendors do Type I once and then move to a continuous Type II cycle." — quantifier softened to "Many vendors" as suggested; framing now matches what sources can support. (resolved in 16cc04c)
• [L56] Period covered table cell: corrected "Usually 6 or 12 months" to "Typically 3 to 12 months (6- and 12-month windows are most common)" — the 3-month minimum is now correctly represented. (resolved in 78719ba)
• [L61] Type II minimum observation period: corrected "at least 6 months" to "at least 3 months (most first audits use a 6-month window; 12 months is standard for the steady-state cycle)." (resolved in 78719ba)
• [L89] First-audit timeline (body): corrected "9–14 months" to "6–12 months — usually 3–6 months of readiness and remediation, followed by the observation period and audit fieldwork." (resolved in 78719ba)
• [L126] Language list: restored JavaScript and changed "C#" to ".NET" to match the canonical list at content/docs/iac/languages-sdks/_index.md. (resolved in 78719ba)
• [L144] First-audit timeline (FAQ): corrected "9–14 months" to "6–12 months." (resolved in 78719ba)
• [L156] CPA firm language: removed false "registered with the AICPA" registry claim; rewritten to "licensed by a state board of accountancy and following the AICPA's SSAE 18 attestation standard." Consistency fix also applied at L12. (resolved in 78719ba)

📜 Review history

• 2026-05-19T15:58:36Z — Initial review: 6 contradicted factual claims (SOC 2 observation-period minimum, first-audit timeline ×2, language list, CPA-firm registration). (37cda4b)
• 2026-05-19T16:14:27Z — re-reviewed after fix push (1 new commit, 78719ba); all 6 outstanding resolved, 0 new findings.
• 2026-05-19T17:47:59Z — history rewritten since last review (force-push/rebase onto master); re-reviewed against HEAD (16cc04c). L61 quantifier ("most" → "many") resolved; author updated to alex-leventer. 0 outstanding, 0 low-confidence.
• 2026-05-19T18:55:50Z — deprecated term removed: "CrossGuard" replaced with "Pulumi Policies" per @CamSoper (46324f9). 0 new findings.

---

Need a re-review? Want to dispute a finding? Mention @claude and include #update-review.
(For ad-hoc questions or fixes, just @claude — no hashtag.)

[github-actions]

🤖 Review regenerated on @CamSoper's request.

[alexleventer]

@claude - fix all the outstanding items and then #update-review

[github-actions]

🤖 Review updated on @alexleventer's request.

[CamSoper]

@claude

• rebase this branch
• replace the author with alex-leventer
• use your suggested phrasing on L61
• #update-review

[github-actions]

🤖 Review updated on @CamSoper's request.

[CamSoper]

@claude Remove all references to CrossGuard (deprecated term) and #update-review

[CamSoper]

@claude Remove all references to CrossGuard (deprecated term) and #update-review

[github-actions]

🤖 Review updated on @CamSoper's request.