Compliance Review

Evaluate your application against industry-specific regulatory requirements. This review translates dense compliance frameworks into concrete, testable technical checks — and validates them through browser-based testing. Non-compliance can result in severe fines, legal action, and loss of business.

When to use

Use /compliance-review when:

• Building applications for regulated industries (healthcare, finance, government)
• Preparing for a compliance audit (SOC 2, HIPAA, PCI-DSS)
• Adding payment processing or health data features
• Expanding to GDPR-regulated markets
• After infrastructure or architecture changes that affect data handling

Standards Referenced

• HIPAA — Health Insurance Portability and Accountability Act (Technical Safeguards §164.312)
• SOC 2 — Service Organization Control (Trust Service Criteria)
• PCI-DSS v4.0 — Payment Card Industry Data Security Standard
• GDPR — General Data Protection Regulation (Technical Measures)

Phase Overview

Phase 1: EDUCATE   → Compliance context and applicable frameworks
Phase 2: SCOPE     → Determine which frameworks apply, identify regulated data
Phase 3: ANALYZE   → Browser-based checks against framework requirements
Phase 4: REPORT    → Findings mapped to specific regulatory sections
Phase 5: REMEDIATE → Fix guidance + YAML regression tests for continuous compliance

Phase 1: Educate

Why this matters: HIPAA violations: up to $1.9M per violation category per year. PCI-DSS non-compliance: $5,000-$100,000/month in fines plus liability for breaches. SOC 2 failures: loss of enterprise customers who require it. GDPR: up to 4% of global annual revenue. These aren't theoretical — enforcement is active and increasing.

Compliance frameworks are large documents. This review extracts the technical requirements testable in a web application — not the organizational/procedural requirements (policies, training, vendor management) that require human process review.

Phase 2: Scope

Determine applicable frameworks

1. Auto-detect from codebase:

   • Health data handling (HIPAA indicators: HL7, FHIR, patient records, PHI references)
   • Payment processing (PCI-DSS indicators: Stripe, Braintree, credit card fields, payment forms)
   • EU user data (GDPR indicators: consent banners, cookie notices, EU deployments)
   • Audit logging (SOC 2 indicators: audit trail, event logging, access logs)

2. Ask the user:

   • Which frameworks apply? (auto-detected, confirm)
     • HIPAA — healthcare / protected health information
     • SOC 2 — enterprise SaaS / customer data
     • PCI-DSS — payment card data
     • GDPR — EU personal data
     • Other (specify)
   • Target URL: Where is the app running?
   • Regulated data types: What regulated data does the app handle? (auto-detected)
   • Test credentials: Accounts with access to regulated data for testing

3. Map regulated data flows:

   • Where regulated data enters the system (forms, APIs, imports)
   • Where it's displayed (dashboards, reports, exports)
   • Where it's stored client-side (if anywhere)
   • Where it's transmitted (API endpoints, third-party services)

Phase 3: Analyze

Run only the sections applicable based on Phase 2 scoping. Open a browser session with new_session using record_evidence: true.

HIPAA Technical Safeguards (HIP)

Applicable when: application handles Protected Health Information (PHI).

Browser validation: Navigate to pages with PHI. Test access controls. Check for PHI in URLs, storage, console. Test session timeout by waiting. Test logout completeness.

SOC 2 Trust Service Criteria (SOC)

Applicable when: enterprise SaaS handling customer data.

Browser validation: Test authentication boundaries, password policies, MFA flows, role-based access, audit logging visibility.

PCI-DSS v4.0 (PCI)

Applicable when: application processes, stores, or transmits cardholder data.

Browser validation: Walk through the payment flow. Check card display masking. Inspect storage and console for cardholder data. Verify payment form is iframe/hosted (SAQ A compliance).

GDPR Technical Requirements (GDPR)

Applicable when: application handles EU personal data. (Note: privacy-specific checks are in /privacy-review — this section covers GDPR's technical/compliance obligations.)

Browser validation: Test consent flows, data export, account deletion, privacy policy accessibility. Check third-party script origins for cross-border transfer concerns.

Phase 4: Report

Generate a structured report saved to shiplight/reports/compliance-review-{date}.md:

# Compliance Review Report
**Date:** {date}
**URL:** {url}
**Frameworks evaluated:** {HIPAA, SOC 2, PCI-DSS, GDPR}
**Regulated data types:** {PHI, cardholder data, EU personal data}

## Overall Compliance Score: {X}/10 | Confidence: {X}%

## Framework Scores
| Framework | Score | Pass | Fail | N/A | Critical Gaps |
|-----------|-------|------|------|-----|---------------|
| HIPAA | 6/10 | 8 | 3 | 1 | Session timeout, PHI in URL |
| SOC 2 | 7/10 | 9 | 2 | 1 | No MFA, weak audit trail |
| PCI-DSS | 8/10 | 10 | 1 | 1 | Card data in console |
| GDPR | 5/10 | 5 | 4 | 1 | Consent, data export, erasure |

## Compliance Status by Check
(Full table of all checks with PASS/FAIL/N-A status, evidence, and confidence)

## Critical Non-Compliance Items
(Findings that could result in regulatory action, ordered by risk)

## Audit Preparation Checklist
- [ ] Fix all CRITICAL findings
- [ ] Fix all HIGH findings
- [ ] Document accepted risks for MEDIUM findings
- [ ] Run YAML regression tests before audit date
- [ ] Prepare evidence documentation from this report

Confidence Scoring

• 90-100%: Browser-validated, compliance violation confirmed (e.g., PHI visible without auth, card number in console)
• 70-89%: Strong evidence from inspection (e.g., missing header, no timeout behavior)
• 50-69%: Architectural concern based on code patterns (e.g., audit logging might be incomplete)
• Below 50%: Don't report — compliance findings must be substantiated

Phase 5: Remediate

1. Fix guidance (example)

#### HIP-02: No session auto-timeout
**Regulation:** HIPAA §164.312(a)(2)(iii) — Automatic logoff
**Risk:** Unattended sessions with PHI visible
**Current:** Sessions persist indefinitely
**Fix:** Implement idle timeout (HIPAA recommends ≤15 minutes for PHI access)
- Add client-side idle detection (mouse, keyboard events)
- Server-side session expiry as backup
- Show warning dialog at 12 minutes
- Auto-logout and clear screen at 15 minutes

2. YAML regression test

- name: hip-02-session-auto-timeout
  description: Verify session auto-timeout for HIPAA compliance
  severity: critical
  standard: HIPAA-164.312(a)(2)(iii)
  steps:
    - URL: /login
    - intent: Log in with test credentials
      action: fill
      locator: "getByLabel('Email')"
      value: "test@example.com"
    - intent: Enter password
      action: fill
      locator: "getByLabel('Password')"
      value: "testpass123"
    - intent: Submit login form
      action: click
      locator: "getByRole('button', { name: 'Sign in' })"
    - WAIT_UNTIL: Dashboard with PHI is visible
      timeout_seconds: 15
    - VERIFY: Session timeout warning appears after inactivity period
      timeout_seconds: 900
    - VERIFY: User is automatically logged out after timeout expires
      timeout_seconds: 300

Save all YAML tests to shiplight/tests/compliance-review.test.yaml.

Depth Levels

• --quick: Critical checks only — authentication boundaries + data exposure. ~3 minutes.
• default: Full applicable framework. ~10-15 minutes.
• --thorough: All checks + multi-role testing + edge cases + documentation review. ~25-40 minutes.

Tips

• Run the compliance review specific to your framework: "run HIPAA checks only"
• Compliance requires evidence — use record_evidence: true and generate_html_report for audit documentation
• YAML regression tests from this review serve as continuous compliance monitoring
• This review covers technical requirements only — organizational requirements (policies, training) need human review
• For privacy-specific concerns, complement with /privacy-review
• For security-specific concerns, complement with /security-review
• Close session with close_session and use generate_html_report for evidence