@open-agreements/open-agreements 0.2.0 → 0.3.0

package/skills/soc2-readiness/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: soc2-readiness
+description: >-
+  Assess SOC 2 Type II readiness. Map Trust Services Criteria to controls,
+  identify gaps, and build a remediation plan. Uses NIST SP 800-53 (public
+  domain) as canonical reference with SOC 2 criterion cross-mapping.
+license: MIT
+compatibility: >-
+  Works with any AI agent. Enhanced with compliance MCP server for live
+  status data. Falls back to embedded reference material when no live data
+  available.
+metadata:
+  author: open-agreements
+  version: "0.1.0"
+  frameworks:
+    - SOC 2 Type II
+    - NIST SP 800-53 Rev 5
+    - ISO 27001:2022
+---
+
+# SOC 2 Readiness Assessment
+
+Assess readiness for a SOC 2 Type II audit. This skill walks through the Trust Services Criteria, identifies gaps, maps to NIST controls, and generates a prioritized remediation plan.
+
+## Security Model
+
+- **No scripts executed** — markdown-only procedural guidance
+- **No secrets required** — works with reference checklists
+- **IP-clean** — AICPA Trust Services Criteria are publicly cited; descriptions are original writing
+- **Evidence stays local** — all collection outputs go to local filesystem
+
+## When to Use
+
+Activate this skill when:
+
+1. **First SOC 2 preparation** — building controls from scratch for initial Type I or Type II
+2. **Pre-audit readiness check** — 4-8 weeks before audit window opens
+3. **Gap analysis after scope change** — new systems, services, or trust criteria added
+4. **Remediation planning** — translating audit findings into actionable work items
+5. **Dual-framework mapping** — already pursuing ISO 27001 and need SOC 2 overlap analysis
+
+Do NOT use for:
+- ISO 27001 internal audit — use `iso-27001-internal-audit`
+- Evidence collection mechanics — use `iso-27001-evidence-collection`
+- Contract review — use legal agreement skills
+
+## Core Concepts
+
+### Trust Services Criteria (TSC)
+
+SOC 2 is organized around 5 Trust Services Categories. **Security (CC)** is always in scope; others are optional based on your service:
+
+| Category | Criteria | When Required |
+|----------|----------|---------------|
+| **Security** (CC) | CC 1-9 (33 criteria) | Always required |
+| **Availability** (A) | A 1.1-1.3 (3 criteria) | SaaS with uptime SLAs |
+| **Processing Integrity** (PI) | PI 1.1-1.5 (4 criteria) | Data processing services |
+| **Confidentiality** (C) | C 1.1-1.2 (2 criteria) | Handling confidential data |
+| **Privacy** (P) | P 4-8 (7 criteria) | PII processing |
+
+### SOC 2 vs. ISO 27001
+
+| Dimension | SOC 2 | ISO 27001 |
+|-----------|-------|-----------|
+| Governing body | AICPA | ISO/IEC |
+| Geography | Primarily US/Canada | Global |
+| Type | Attestation report by CPA | Certification by audit body |
+| Scope | Service-specific | Organization-wide ISMS |
+| Controls | Flexible (you define) | 93 Annex A controls |
+| Output | SOC 2 report (restricted/general use) | Certificate |
+| Overlap | ~70% overlap with ISO 27001 Annex A | ~70% overlap with SOC 2 CC |
+
+### Decision Tree: Scope Selection
+
+```
+What service are you getting audited on?
+├── SaaS product → Security + Availability (+ Confidentiality if you handle sensitive data)
+├── Data processing → Security + Processing Integrity + Confidentiality
+├── Infrastructure → Security + Availability
+├── API service → Security (+ PI if you transform data)
+│
+Do you handle PII?
+├── YES → Add Privacy category
+├── NO → Skip Privacy
+│
+Do you have uptime SLAs?
+├── YES → Include Availability
+├── NO → Optional (but customers expect it for SaaS)
+```
+
+## Step-by-Step Workflow
+
+### Step 1: Define Scope and Categories
+
+1. **Identify the service** being audited (product name, description, boundaries)
+2. **Select Trust Services Categories** using the decision tree above
+3. **Define system boundaries**: infrastructure, software, people, procedures, data
+4. **Document sub-service organizations** (cloud providers, payment processors, etc.)
+5. **Determine audit type**: Type I (point-in-time) or Type II (period of time, usually 6-12 months)
+
+### Step 2: Assess Current State
+
+For each applicable Common Criterion (CC), assess whether controls are:
+- **Designed** — control exists on paper
+- **Implemented** — control is operating
+- **Effective** — control achieves its objective (evidence exists)
+
+```
+# If Internal ISO Audit MCP server is available (SOC 2 maps to ISO 27001 Annex A):
+list_controls(domain="technological")                       # List tech controls (maps to CC 6-8)
+get_control_guidance(control_id="A.5.15")                   # Get guidance for ISO control mapped from CC 6.1
+get_nist_mapping(control_id="AC-2", direction="nist_to_iso")  # Find ISO controls from NIST reference
+search_guidance(query="incident response")                  # Search for controls matching SOC 2 criteria
+```
+
+### Step 3: Map Controls to Criteria
+
+Each CC maps to specific NIST controls. Use this mapping to identify what you need:
+
+#### CC 1 — Control Environment
+
+| Criterion | Focus | NIST Controls | ISO Cross-Reference |
+|-----------|-------|---------------|---------------------|
+| CC 1.1 | Integrity and ethics | PS-1, PS-3, PS-6 | A.6.1, A.6.2, A.6.4 |
+| CC 1.2 | Board oversight | PM-1, PM-2 | C.5.1, C.5.3 |
+| CC 1.3 | Organizational structure | PM-2 | C.5.3 |
+| CC 1.4 | Competence commitment | AT-2, PS-3 | A.6.1, A.6.3 |
+| CC 1.5 | Accountability | PS-3, PS-4 | A.6.4, A.6.5 |
+
+#### CC 2 — Communication and Information
+
+| Criterion | Focus | NIST Controls | ISO Cross-Reference |
+|-----------|-------|---------------|---------------------|
+| CC 2.1 | Internal information | AU-2, SI-5 | C.7.5.1 |
+| CC 2.2 | Internal communication | PM-2, AT-2 | C.7.4, A.6.3 |
+| CC 2.3 | External communication | PM-1 | A.5.14 |
+
+#### CC 3 — Risk Assessment
+
+| Criterion | Focus | NIST Controls | ISO Cross-Reference |
+|-----------|-------|---------------|---------------------|
+| CC 3.1 | Risk objectives | PM-9, RA-1 | C.6.1.1 |
+| CC 3.2 | Risk identification | RA-3 | C.6.1.2, C.8.2 |
+| CC 3.3 | Fraud risk | RA-3 | C.6.1.2 |
+| CC 3.4 | Change impact | RA-3, CM-4 | C.6.1.2, A.8.9 |
+
+#### CC 4 — Monitoring Activities
+
+| Criterion | Focus | NIST Controls | ISO Cross-Reference |
+|-----------|-------|---------------|---------------------|
+| CC 4.1 | Ongoing monitoring | CA-7, PM-6 | C.9.1 |
+| CC 4.2 | Deficiency evaluation | CA-2 | C.9.2.1 |
+
+#### CC 5 — Control Activities
+
+| Criterion | Focus | NIST Controls | ISO Cross-Reference |
+|-----------|-------|---------------|---------------------|
+| CC 5.1 | Risk mitigation | AC-5 | A.5.3 |
+| CC 5.2 | Technology controls | AC-1, IA-2 | A.5.15, A.8.5 |
+| CC 5.3 | Policy deployment | PM-1, PL-1 | A.5.1, C.5.2 |
+
+#### CC 6 — Logical and Physical Access
+
+| Criterion | Focus | NIST Controls | ISO Cross-Reference |
+|-----------|-------|---------------|---------------------|
+| CC 6.1 | Access control | AC-2, AC-3, IA-2, SC-28 | A.5.15, A.8.5, A.8.24 |
+| CC 6.2 | Access provisioning | AC-2, PS-4, PS-5 | A.5.18, A.6.5 |
+| CC 6.3 | Access modification | AC-2, AC-6 | A.5.15, A.5.18 |
+| CC 6.4 | Physical access | PE-2, PE-3, PE-6 | A.7.2, A.7.4 |
+| CC 6.5 | Asset disposal | MP-6 | A.7.10, A.7.14 |
+| CC 6.6 | Threat detection | RA-5, SI-4 | A.8.8, A.8.16 |
+| CC 6.7 | Transmission security | SC-8 | A.5.14, A.8.24 |
+| CC 6.8 | Malware prevention | SI-2, SI-3 | A.8.7, A.8.19 |
+
+#### CC 7 — System Operations
+
+| Criterion | Focus | NIST Controls | ISO Cross-Reference |
+|-----------|-------|---------------|---------------------|
+| CC 7.1 | Operational monitoring | CM-6, RA-5 | A.8.9, A.8.8 |
+| CC 7.2 | Anomaly detection | AU-6, SI-4 | A.8.15, A.8.16 |
+| CC 7.3 | Incident response | IR-4 | A.5.24, A.5.25 |
+| CC 7.4 | Incident management | IR-5, IR-6 | A.5.25, A.5.26 |
+| CC 7.5 | Recovery | CP-4, CP-9, CP-10 | A.5.30, A.8.13 |
+
+#### CC 8 — Change Management
+
+| Criterion | Focus | NIST Controls | ISO Cross-Reference |
+|-----------|-------|---------------|---------------------|
+| CC 8.1 | Change control | CM-3, CM-5, SA-3 | A.8.9, A.8.25, A.8.32 |
+
+#### CC 9 — Risk Mitigation
+
+| Criterion | Focus | NIST Controls | ISO Cross-Reference |
+|-----------|-------|---------------|---------------------|
+| CC 9.1 | Risk mitigation | CP-2, RA-7 | A.5.30, C.6.1.3 |
+| CC 9.2 | Vendor management | AC-20, SA-9 | A.5.19, A.5.22 |
+
+### Step 4: Generate Gap Analysis
+
+For each criterion, document:
+
+```markdown
+## Gap: [CC x.x] — [Brief description]
+
+**Current State**: [What exists today]
+**Required State**: [What the auditor expects]
+**Gap**: [What's missing]
+**Remediation**:
+1. [Specific action item]
+2. [Specific action item]
+**Priority**: Critical / High / Medium / Low
+**Effort**: [Days/weeks to remediate]
+**Owner**: [Person responsible]
+**Evidence Needed**: [What to collect after fix]
+```
+
+### Step 5: Build Remediation Plan
+
+Prioritize gaps by:
+1. **Critical** — Audit will fail without this (CC 6.1, 6.2, 7.2, 7.5, 8.1)
+2. **High** — Likely finding if not addressed (CC 1.4, 3.2, 6.6, 7.3)
+3. **Medium** — Auditor will note but may not be a finding
+4. **Low** — Best practice, not strictly required
+
+### Step 6: Readiness Report
+
+Generate a structured readiness assessment:
+
+1. **Executive summary** — overall readiness percentage, estimated time to audit-ready
+2. **Scope** — service description, trust categories, audit type
+3. **Control matrix** — all applicable criteria with status (designed/implemented/effective)
+4. **Gap analysis** — prioritized list of gaps with remediation plan
+5. **Timeline** — remediation milestones leading to audit window
+
+## Quick Reference: Top SOC 2 Failures
+
+| # | Criterion | Common Failure | Fix |
+|---|-----------|---------------|-----|
+| 1 | CC 6.1 | MFA not universal | Enforce MFA on all systems with sensitive data |
+| 2 | CC 6.2 | Access not revoked on termination | Automate deprovisioning; verify within 24h |
+| 3 | CC 7.2 | No log monitoring | Configure alerts for auth failures, privilege changes |
+| 4 | CC 8.1 | No change management | Require PR reviews; document deployment process |
+| 5 | CC 7.5 | Backups never tested | Restore from backup quarterly; document results |
+| 6 | CC 3.2 | No risk assessment | Conduct and document annual risk assessment |
+| 7 | CC 6.6 | No vulnerability scanning | Deploy automated scanning; remediate criticals in 30d |
+| 8 | CC 1.4 | Security training incomplete | Require annual training; track completion |
+| 9 | CC 9.2 | Vendor risk not assessed | Maintain vendor register; collect SOC 2 reports |
+| 10 | CC 7.3 | No incident response plan | Document plan; conduct tabletop exercise |
+
+## DO / DON'T
+
+### DO
+- Start with Security (CC) criteria — they're always required and cover ~80% of effort
+- Map to ISO 27001 if pursuing both frameworks — ~70% control overlap
+- Collect evidence throughout the audit period, not just at audit time
+- Include sub-service organizations in your description
+- Define the audit period before starting evidence collection
+
+### DON'T
+- Include trust categories you can't support — better to pass on fewer than fail on more
+- Assume Type I is "easy" — it requires all controls to be designed and implemented
+- Forget the system description — auditors review this first and use it to scope their testing
+- Use generic/template control descriptions — auditors expect your controls to match your actual environment
+- Ignore complementary user entity controls (CUECs) — your customers need to know their responsibilities
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| First SOC 2, no existing controls | Start with CC 6 (access) and CC 8 (change management) — fastest to implement |
+| Already have ISO 27001 | Map Annex A controls to SOC 2 CC; ~70% are already covered |
+| Auditor requests evidence we don't have | Collect it now; document the process; note in description if control was implemented mid-period |
+| Multiple environments (prod/staging/dev) | Only production environment needs to be in scope; document boundaries clearly |
+| Sub-service org (AWS/GCP/Azure) | Use SOC 2 Type II report from the provider; document which controls they cover |
+
+## Rules
+
+For detailed SOC 2-specific guidance:
+
+| File | Coverage |
+|------|----------|
+| `rules/logical-access.md` | CC 6.1–6.8 — access control, provisioning, physical, threat detection |
+| `rules/system-operations.md` | CC 7.1–7.5 — monitoring, anomaly detection, incident response, recovery |
+| `rules/change-vendor-management.md` | CC 8.1, CC 9.1–9.2 — change control, risk mitigation, vendor management |
+| `rules/control-environment.md` | CC 1.1–1.5 — governance, ethics, org structure, competence, accountability |
+| `rules/risk-assessment.md` | CC 3.1–3.4 — risk objectives, identification, fraud risk, change impact |
+| `rules/control-activities.md` | CC 5.1–5.3 — risk mitigation selection, technology controls, policy deployment |
+| `rules/communication-info.md` | CC 2.1–2.3 — internal/external communication, information quality |
+| `rules/monitoring-activities.md` | CC 4.1–4.2 — ongoing monitoring, deficiency evaluation |
+| `rules/optional-categories.md` | A 1.x, PI 1.x, C 1.x — Availability, Processing Integrity, Confidentiality |
+| `rules/privacy-criteria.md` | P 1.x–8.x — Privacy criteria (when PII in scope) |
+
+## Attribution
+
+SOC 2 criteria mapping and readiness procedures developed with [Internal ISO Audit](https://internalisoaudit.com) (Hazel Castro, ISO 27001 Lead Auditor, 14+ years, 100+ audits).
+
+## Runtime Detection
+
+1. **Internal ISO Audit MCP server available** (best) — Live ISO 27001 control guidance with NIST cross-references. SOC 2 criteria map to ISO 27001 Annex A controls (~70% overlap); use `get_nist_mapping` for bidirectional lookup. Server: `internalisoaudit.com/api/mcp`
+2. **Local compliance data available** (good) — Reads `compliance/` directory with SOC 2 test metadata
+3. **Reference only** (baseline) — Uses embedded criteria mapping and checklists in `rules/`

package/skills/soc2-readiness/rules/change-vendor-management.md

@@ -0,0 +1,104 @@
+# Change and Vendor Management — CC 8.1, CC 9.1–9.2
+
+Per-criterion audit guidance for change control, risk mitigation, and third-party management.
+
+## CC 8.1 — Change control
+
+**Priority**: Critical | **NIST**: CM-3, CM-5, SA-3 | **ISO**: A.8.9, A.8.25, A.8.32
+
+Auditors assess whether changes to production systems follow a documented, consistent process — authorization, testing, approval, and deployment. This is one of the top 5 most-tested criteria. Expect auditors to select a sample of production changes and trace each through the full lifecycle.
+
+**What auditors test**:
+- Sample 10-15 production deployments: verify each had a code review, testing evidence, and approval before merge
+- Segregation of duties: the person who writes code cannot be the sole approver and deployer
+- Emergency change process: hotfixes still require documentation (even if retroactive)
+- Rollback capability: evidence that changes can be reverted if issues arise
+- Branch protection: direct pushes to production branch are blocked; force-push is disabled
+
+**Evidence to prepare**:
+```bash
+# GitHub: merged PRs with review status
+gh pr list --state merged --limit 20 --json number,title,author,reviewDecision,mergedAt,mergedBy
+
+# GitHub: branch protection rules
+gh api repos/{owner}/{repo}/branches/main/protection | jq '{
+  required_reviews: .required_pull_request_reviews.required_approving_review_count,
+  dismiss_stale: .required_pull_request_reviews.dismiss_stale_reviews,
+  enforce_admins: .enforce_admins.enabled,
+  required_status_checks: .required_status_checks.contexts
+}'
+
+# GitHub: check for direct pushes bypassing PR process
+gh api repos/{owner}/{repo}/commits --per-page=20 | \
+  jq '[.[] | select(.parents | length == 1)] | .[] | {sha: .sha[0:8], message: .commit.message[0:60], author: .author.login}'
+
+# CI/CD: verify automated tests run on PRs
+gh api repos/{owner}/{repo}/actions/workflows --jq '.workflows[] | {name, state}'
+```
+- Change management policy document
+- Emergency change procedure (when and how hotfixes are handled)
+- Deployment runbook or CI/CD pipeline documentation
+
+**Startup pitfalls**:
+- Founders bypass branch protection using admin override — auditors see this in the commit history
+- "We review in Slack" — verbal approvals aren't auditable; use PR reviews
+- No emergency change process — every hotfix is undocumented and unreviewed
+- Testing means "it works on my machine" — no automated test suite or staging environment
+
+---
+
+## CC 9.1 — Risk mitigation activities
+
+**Priority**: High | **NIST**: CP-2, RA-7 | **ISO**: A.5.30, C.6.1.3
+
+Auditors verify that identified risks have corresponding mitigation activities — controls, insurance, transfer, or documented acceptance. A risk register without linked mitigations is incomplete. The connection between risk assessment (CC 3) and concrete risk treatment is what auditors evaluate here.
+
+**What auditors test**:
+- Risk register entries include treatment decisions: mitigate, transfer, accept, or avoid
+- Accepted risks have documented justification and management sign-off
+- Mitigation controls are mapped to specific risks (traceability from risk to control)
+- Business continuity plan addresses the organization's top operational risks
+- Insurance coverage reviewed annually (cyber insurance, E&O, D&O as applicable)
+
+**Evidence to prepare**:
+- Risk register with treatment column (mitigate/transfer/accept/avoid) and control mapping
+- Risk acceptance forms signed by management for accepted risks
+- Business continuity plan covering top-5 operational risk scenarios
+- Cyber insurance certificate of coverage (current policy period)
+- Management review minutes where risk treatment decisions were discussed
+
+---
+
+## CC 9.2 — Vendor and third-party management
+
+**Priority**: Critical | **NIST**: AC-20, SA-9 | **ISO**: A.5.19, A.5.22
+
+Auditors verify that the organization identifies, assesses, and monitors third-party vendors who access, store, or process data on its behalf. This includes cloud providers, SaaS tools, payment processors, and contractors with system access. The vendor management program should be proportionate to risk.
+
+**What auditors test**:
+- Vendor inventory: comprehensive list of vendors with data access, criticality rating, and review dates
+- Risk assessment for critical vendors: documented evaluation of security posture before onboarding
+- SOC 2 or equivalent reports collected annually from critical vendors (cloud providers, data processors)
+- Vendor contracts include security requirements, data handling terms, and breach notification clauses
+- Ongoing monitoring: critical vendor reviews at least annually, not just at initial onboarding
+
+**Evidence to prepare**:
+```bash
+# GitHub: list third-party integrations
+gh api orgs/{org}/installations --jq '.installations[] | {app_slug, permissions, events}'
+
+# GCP: list external service accounts with access
+gcloud projects get-iam-policy {project} --format=json | \
+  jq '.bindings[] | .members[] | select(contains("serviceAccount")) | select(contains("gserviceaccount.com") | not)'
+```
+- Vendor register (name, service, data access level, criticality, last review date)
+- Vendor SOC 2 Type II reports for critical vendors (AWS, GCP, Azure, Stripe, etc.)
+- Vendor security assessment questionnaire template
+- Data processing agreements (DPAs) with vendors handling personal data
+- Vendor onboarding and offboarding procedures
+
+**Startup pitfalls**:
+- No vendor inventory — dozens of SaaS tools adopted without tracking who has data access
+- Relying on "they're a big company, they must be secure" instead of collecting SOC 2 reports
+- No DPAs with vendors processing personal data — GDPR and SOC 2 both require this
+- Vendor review is one-and-done at onboarding — no annual reassessment

package/skills/soc2-readiness/rules/communication-info.md

@@ -0,0 +1,85 @@
+# Communication and Information — CC 2.1–2.3
+
+Per-criterion audit guidance for information quality, internal communication, and external communication.
+
+## CC 2.1 — Internal information quality
+
+**Priority**: Medium | **NIST**: AU-2, SI-5 | **ISO**: C.7.5.1
+
+Auditors assess whether the organization generates and uses quality information to support the functioning of internal controls. This means security-relevant information — logs, metrics, reports, alerts — is accurate, timely, and available to the people who need it for decision-making.
+
+**What auditors test**:
+- Security-relevant information is generated: audit logs, access reports, vulnerability scans, incident records
+- Information is accurate and complete: logs capture required fields (who, what, when, where)
+- Information is timely: reports and dashboards are current, not stale exports from months ago
+- Information systems are protected: audit logs cannot be modified or deleted by the users they track
+- Data used for control monitoring is validated (e.g., access review data matches actual system state)
+
+**Evidence to prepare**:
+```bash
+# GCP: verify audit logging is enabled
+gcloud projects get-iam-policy {project} --format=json | jq '.auditConfigs'
+
+# GCP: verify log integrity (export to separate project or write-once sink)
+gcloud logging sinks list --format=json | jq '.[] | {name, destination}'
+
+# GitHub: audit log availability
+gh api orgs/{org}/audit-log --jq '.[0:3] | .[] | {action, actor, created_at}'
+```
+- List of security reports and dashboards with update frequency
+- Audit log configuration showing required event types are captured
+- Log integrity controls (separate storage account, write-once policies)
+
+---
+
+## CC 2.2 — Internal communication
+
+**Priority**: Medium | **NIST**: PM-2, AT-2 | **ISO**: C.7.4, A.6.3
+
+Auditors verify that security-related information — policies, responsibilities, changes, and expectations — is communicated effectively to all personnel. Internal communication isn't just "we have a wiki"; it's demonstrating that people actually receive and understand security requirements.
+
+**What auditors test**:
+- Security policies are communicated to all employees (not just published and forgotten)
+- Onboarding includes security expectations, reporting procedures, and acceptable use
+- Changes to security policies or procedures are communicated when they occur
+- Regular security updates: newsletters, all-hands mentions, Slack announcements
+- Employees in interviews can describe their security responsibilities and reporting channels
+
+**Evidence to prepare**:
+- Onboarding checklist showing security communication steps
+- Security awareness communication records (email announcements, Slack messages, all-hands slides)
+- Policy change communication evidence (email or message notifying staff of updates)
+- Security training materials covering roles and responsibilities
+- Internal security FAQ or knowledge base
+
+**Startup pitfalls**:
+- Security policies exist but nobody outside the security/compliance function knows about them
+- Onboarding mentions security verbally but nothing is documented or acknowledged
+- Policy changes happen silently — no communication when procedures are updated
+
+---
+
+## CC 2.3 — External communication
+
+**Priority**: Medium | **NIST**: PM-1 | **ISO**: A.5.14
+
+Auditors verify that the organization communicates security-relevant information to external parties — customers, regulators, vendors, and the public — through appropriate channels. This includes the system description, security practices, incident notifications, and contractual commitments.
+
+**What auditors test**:
+- Security practices communicated to customers: security page, trust center, or documentation
+- SOC 2 report distribution process: how customers request and receive the report
+- Incident notification: contractual obligations met for customer communication during incidents
+- Regulatory reporting: process for notifying regulators of security events when required
+- Vendor communication: security requirements communicated to third parties in contracts and onboarding
+
+**Evidence to prepare**:
+- Security page or trust center URL (public-facing security information)
+- NDA or report request process for SOC 2 report distribution
+- Customer-facing incident communication templates and procedures
+- Contractual breach notification obligations inventory
+- Vendor security requirements (contract clauses, questionnaire, or onboarding materials)
+
+**Startup pitfalls**:
+- No public security page — customers can't find any information about security practices
+- SOC 2 report shared openly without NDA — report is meant to be restricted use
+- Incident notification process undefined — scrambling to communicate during an actual incident

package/skills/soc2-readiness/rules/control-activities.md

@@ -0,0 +1,95 @@
+# Control Activities — CC 5.1–5.3
+
+Per-criterion audit guidance for risk mitigation selection, technology controls, and policy deployment.
+
+## CC 5.1 — Risk mitigation selection
+
+**Priority**: High | **NIST**: AC-5 | **ISO**: A.5.3
+
+Auditors verify that the organization selects and deploys control activities that mitigate identified risks to acceptable levels. This is the bridge between the risk assessment (CC 3) and actual controls — each significant risk should trace to one or more controls. Segregation of duties is a key element auditors evaluate here.
+
+**What auditors test**:
+- Control activities are mapped to specific risks from the risk register (traceability)
+- Segregation of duties: conflicting responsibilities are separated across different individuals
+- Key incompatible functions identified and separated: access provisioning vs. access review, code development vs. deployment approval, payment initiation vs. payment approval
+- Compensating controls documented where full segregation isn't feasible (common in small teams)
+- Control design considers both preventive (stop it before it happens) and detective (find it after it happens) controls
+
+**Evidence to prepare**:
+- Risk-to-control mapping matrix (risk register entries linked to specific controls)
+- Segregation of duties matrix identifying incompatible functions and how they're separated
+- Compensating controls documentation for small-team exceptions
+- Control design rationale for critical risks (why this control was selected over alternatives)
+
+**Startup pitfalls**:
+- No traceability between risks and controls — controls exist but aren't linked to specific risks
+- Segregation of duties impossible with 3-person engineering team — document compensating controls instead of ignoring the requirement
+- Only preventive controls, no detective controls — if prevention fails, there's no detection
+
+---
+
+## CC 5.2 — Technology general controls
+
+**Priority**: High | **NIST**: AC-1, IA-2 | **ISO**: A.5.15, A.8.5
+
+Auditors verify that technology infrastructure supporting the control environment is itself controlled. This covers IT general controls (ITGCs): access management for infrastructure, authentication mechanisms, and the foundational technology controls that other controls depend on.
+
+**What auditors test**:
+- Infrastructure access controls: who can access production servers, databases, cloud consoles
+- Authentication strength: MFA enforced for infrastructure access (cloud console, SSH, VPN)
+- Automated controls functioning correctly: CI/CD gates, automated access reviews, scheduled scans
+- Dependency management: technology controls don't rely on manual processes that could be skipped
+- Technology control monitoring: alerts when automated controls fail or are bypassed
+
+**Evidence to prepare**:
+```bash
+# GitHub: branch protection (automated control)
+gh api repos/{owner}/{repo}/branches/main/protection | jq '{
+  required_reviews: .required_pull_request_reviews.required_approving_review_count,
+  required_checks: .required_status_checks.contexts,
+  enforce_admins: .enforce_admins.enabled
+}'
+
+# GCP: organization policies (automated guardrails)
+gcloud resource-manager org-policies list --organization={org_id} --format=json | jq '.[].constraint'
+
+# GitHub: required status checks (CI gates)
+gh api repos/{owner}/{repo}/branches/main/protection/required_status_checks | jq '.contexts'
+```
+- Infrastructure access control matrix (who has access to what, at what level)
+- Automated control inventory (CI/CD gates, automated scans, scheduled reviews)
+- Technology control failure alerting configuration
+
+**Startup pitfalls**:
+- All engineers have production database access "for debugging" — violates least privilege
+- CI/CD pipeline has no required checks — tests are optional and frequently skipped
+- Cloud console access not protected by MFA — "it's inconvenient" is not an acceptable justification
+
+---
+
+## CC 5.3 — Policy and procedure deployment
+
+**Priority**: Medium | **NIST**: PM-1, PL-1 | **ISO**: A.5.1, C.5.2
+
+Auditors verify that security policies and procedures are formalized, approved, communicated, and accessible to all relevant personnel. Policies must be living documents — reviewed periodically, updated when changes occur, and acknowledged by employees.
+
+**What auditors test**:
+- Information security policy suite exists: overarching policy plus supporting procedures
+- Policies are approved by management (signature or formal approval record)
+- Policies are reviewed at least annually and updated when significant changes occur
+- Employees can access policies (intranet, shared drive, wiki) and know where to find them
+- Policy acknowledgment: employees sign or electronically acknowledge reading policies
+- Version control: policies have version numbers, effective dates, and review dates
+
+**Evidence to prepare**:
+- Policy inventory (list of all security-related policies with version, effective date, next review date)
+- Signed management approval for each policy
+- Policy acknowledgment records (employee signatures or electronic acknowledgment log)
+- Policy distribution mechanism (shared drive link, wiki URL, HRIS integration)
+- Policy review log showing annual review was conducted with any changes noted
+
+**Startup pitfalls**:
+- Policies exist in someone's Google Drive but aren't shared or discoverable
+- No version control — impossible to prove which version was in effect during the audit period
+- Policies never reviewed after initial creation — outdated content that doesn't match current practices
+- Acknowledgment collected at onboarding but not when policies are updated