HIPAA Compliance Testing for Healthcare Software
HIPAA violations are expensive. The OCR (Office for Civil Rights) levied over $135 million in penalties in 2023 alone. More importantly, the violations that lead to those penalties are almost always preventable software behaviors: unencrypted PHI in logs, APIs that return more data than requested, missing audit trails, or access controls that were bypassed "temporarily" and never restored.
Every one of those failures has a test you could have written. This post shows you how.
HIPAA Technical Safeguards: What Is Actually Testable
The HIPAA Security Rule (45 CFR §164.312) specifies four categories of technical safeguards:
- Access Control (§164.312(a)) — Unique user identification, emergency access, automatic logoff, encryption
- Audit Controls (§164.312(b)) — Hardware, software, and procedural mechanisms to record and examine activity
- Integrity (§164.312(c)) — PHI must not be improperly altered or destroyed
- Transmission Security (§164.312(e)) — Encryption of PHI in transit
Each of these has direct software implementations and each can be tested automatically.
Defining PHI in Your Test Context
Before writing tests, enumerate what PHI your system holds. HIPAA defines 18 PHI identifiers. The most commonly tested in software contexts:
# tests/hipaa/phi_identifiers.py
PHI_FIELDS = [
"patient_name",
"date_of_birth",
"admission_date",
"discharge_date",
"ssn",
"medical_record_number",
"health_plan_beneficiary_number",
"account_number",
"certificate_number",
"diagnosis_code",
"procedure_code",
"treatment_notes",
"prescription_details",
"ip_address", # Under HIPAA if linked to healthcare visit
"email", # Under HIPAA if in context of healthcare communication
]
def assert_no_phi_in_response(response_text: str, context: str = ""):
"""
Check that none of the known PHI field names appear unexpectedly in a response.
Call this on error messages, logs, and any response not explicitly designed to carry PHI.
"""
found = [f for f in PHI_FIELDS if f in response_text.lower()]
if found:
raise AssertionError(
f"PHI field names found in {context}: {found}\n"
f"Response: {response_text[:500]}"
)Testing Access Controls (§164.312(a))
# tests/hipaa/test_access_control.py
import pytest
import requests
BASE_URL = "https://api.example.com"
class TestHIPAAAccessControls:
def test_phi_requires_authentication(self):
"""No PHI endpoint should be reachable without a valid session."""
phi_endpoints = [
"/api/patients",
"/api/patients/123/records",
"/api/patients/123/diagnoses",
"/api/records/search",
"/api/prescriptions",
]
for endpoint in phi_endpoints:
resp = requests.get(f"{BASE_URL}{endpoint}")
assert resp.status_code in (401, 403), \
f"PHI endpoint {endpoint} returned {resp.status_code} without auth"
def test_role_based_access_to_phi(self):
"""
HIPAA minimum necessary standard: users should only access PHI
relevant to their role. A billing clerk should not see clinical notes.
"""
billing_token = self._login_as("billing_clerk@clinic.com")
clinical_token = self._login_as("physician@clinic.com")
patient_id = "test-patient-001"
# Clinical notes: physician can access, billing cannot
clinical_resp = requests.get(
f"{BASE_URL}/api/patients/{patient_id}/clinical-notes",
headers={"Authorization": f"Bearer {clinical_token}"}
)
assert clinical_resp.status_code == 200
billing_resp = requests.get(
f"{BASE_URL}/api/patients/{patient_id}/clinical-notes",
headers={"Authorization": f"Bearer {billing_token}"}
)
assert billing_resp.status_code in (403, 404), \
"Billing clerk can access clinical notes — violates minimum necessary standard"
# Billing info: billing can access, physician gets limited view
billing_info_resp = requests.get(
f"{BASE_URL}/api/patients/{patient_id}/billing",
headers={"Authorization": f"Bearer {billing_token}"}
)
assert billing_info_resp.status_code == 200
def test_automatic_session_timeout(self):
"""
§164.312(a)(2)(iii) — Automatic logoff is an addressable safeguard.
Verify session timeout is configured within acceptable limits.
"""
resp = requests.post(f"{BASE_URL}/auth/login", json={
"email": "physician@clinic.com",
"password": "testpassword"
})
token_data = resp.json()
# Healthcare applications: typically 15-30 minute timeout is expected
if "expires_in" in token_data:
max_idle_seconds = 30 * 60 # 30 minutes
assert token_data["expires_in"] <= max_idle_seconds, \
f"Session timeout {token_data['expires_in']}s is too long for HIPAA context"
def test_emergency_access_procedure_exists(self):
"""
§164.312(a)(2)(ii) — Emergency access is a required safeguard.
Verify there is a documented and testable break-glass mechanism.
"""
# Test that an emergency access endpoint exists and requires justification
emergency_resp = requests.post(
f"{BASE_URL}/api/emergency-access",
json={
"patient_id": "test-patient-001",
"justification": "Patient unresponsive, treating physician unavailable"
},
headers={"Authorization": f"Bearer {self._get_emergency_token()}"}
)
# Must require a justification — not just grant access silently
assert emergency_resp.status_code in (200, 201)
assert "access_granted" in emergency_resp.json()
assert "audit_event_id" in emergency_resp.json(), \
"Emergency access must create an audit event"
def test_cross_patient_data_isolation(self):
"""
A patient authenticated as themselves must not be able to access
another patient's records by guessing or incrementing IDs.
"""
patient_a_token = self._login_as("patient-a@example.com")
# Try to access patient B's records using patient A's session
resp = requests.get(
f"{BASE_URL}/api/patients/patient-b-id/records",
headers={"Authorization": f"Bearer {patient_a_token}"}
)
assert resp.status_code in (403, 404), \
"IDOR vulnerability: Patient A can access Patient B's records"Testing Audit Controls (§164.312(b))
# tests/hipaa/test_audit_controls.py
import time
import requests
class TestHIPAAAuditControls:
def test_phi_access_is_logged(self):
"""Every read of PHI must generate an audit log entry."""
admin_token = self._get_admin_token()
physician_token = self._login_as("physician@clinic.com")
patient_id = "test-patient-001"
before = int(time.time())
requests.get(
f"{BASE_URL}/api/patients/{patient_id}/records",
headers={"Authorization": f"Bearer {physician_token}"}
)
audit_resp = requests.get(
f"{BASE_URL}/api/admin/audit-log",
params={
"resource_type": "patient_record",
"resource_id": patient_id,
"from": before
},
headers={"Authorization": f"Bearer {admin_token}"}
)
events = audit_resp.json()["events"]
assert len(events) >= 1, \
f"PHI access to patient {patient_id} not recorded in audit log"
event = events[0]
required_fields = ["user_id", "timestamp", "action", "resource_id", "ip_address"]
for field in required_fields:
assert field in event, f"Audit event missing required field: {field}"
def test_phi_modification_is_logged(self):
"""Updates to PHI must be audited with before and after values or change summary."""
physician_token = self._login_as("physician@clinic.com")
admin_token = self._get_admin_token()
patient_id = "test-patient-001"
before = int(time.time())
requests.patch(
f"{BASE_URL}/api/patients/{patient_id}",
json={"treatment_notes": "Updated treatment plan."},
headers={"Authorization": f"Bearer {physician_token}"}
)
audit_resp = requests.get(
f"{BASE_URL}/api/admin/audit-log",
params={"event_type": "phi.modified", "from": before},
headers={"Authorization": f"Bearer {admin_token}"}
)
assert len(audit_resp.json()["events"]) >= 1
def test_failed_phi_access_attempts_are_logged(self):
"""Unauthorized access attempts must be logged for anomaly detection."""
billing_token = self._login_as("billing_clerk@clinic.com")
admin_token = self._get_admin_token()
before = int(time.time())
# This will be a 403 — but it must still generate an audit entry
requests.get(
f"{BASE_URL}/api/patients/test-patient-001/clinical-notes",
headers={"Authorization": f"Bearer {billing_token}"}
)
audit_resp = requests.get(
f"{BASE_URL}/api/admin/audit-log",
params={"event_type": "access.denied", "from": before},
headers={"Authorization": f"Bearer {admin_token}"}
)
assert len(audit_resp.json()["events"]) >= 1, \
"Denied access attempt not recorded — cannot detect intrusion attempts"Testing Transmission Security (§164.312(e))
# tests/hipaa/test_transmission_security.py
import ssl
import socket
import requests
class TestTransmissionSecurity:
def test_tls_version_is_current(self):
"""
HIPAA requires encryption of PHI in transit. TLS 1.2 is the minimum;
TLS 1.3 is preferred. SSLv3, TLS 1.0, and TLS 1.1 must be disabled.
"""
hostname = "api.example.com"
port = 443
# Try to connect with TLS 1.1 — must fail
try:
context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
context.maximum_version = ssl.TLSVersion.TLSv1_1
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
with socket.create_connection((hostname, port), timeout=5) as sock:
with context.wrap_socket(sock, server_hostname=hostname):
assert False, "Server accepted TLS 1.1 — must be disabled for HIPAA"
except (ssl.SSLError, OSError):
pass # Connection refused — correct behavior
def test_hsts_header_is_present(self):
"""HSTS prevents downgrade attacks that could expose PHI."""
resp = requests.get("https://api.example.com/health")
hsts = resp.headers.get("Strict-Transport-Security", "")
assert hsts, "HSTS header missing — PHI could be exposed via HTTP downgrade"
assert "max-age=" in hsts
# HIPAA context: at least 1 year
import re
max_age_match = re.search(r"max-age=(\d+)", hsts)
assert max_age_match and int(max_age_match.group(1)) >= 31536000
def test_phi_not_in_http_get_params(self):
"""
GET parameters appear in access logs, browser history, and referrer headers.
PHI must never be passed in URL query strings.
"""
# Search for patients should use POST body, not GET params
# Test that GET with PHI in URL is either rejected or redirected
resp = requests.get(
f"{BASE_URL}/api/patients/search?ssn=123-45-6789",
allow_redirects=False
)
# Either reject the request or not support GET with PHI params
assert resp.status_code in (400, 404, 405), \
"PHI accepted in GET query parameters — will appear in server logs"Testing PHI in Logs
One of the most common HIPAA violations is PHI leaking into application logs.
# tests/hipaa/test_phi_log_leakage.py
import subprocess
import re
PHI_PATTERNS = [
r"\b\d{3}-\d{2}-\d{4}\b", # SSN format
r"\b\d{3}-\d{3}-\d{4}\b", # Phone number
r"\bDOB:\s*\d{4}-\d{2}-\d{2}\b", # Date of birth label
r"diagnosis_code",
r"treatment_notes",
r"medical_record_number",
]
def test_application_logs_do_not_contain_phi():
"""
Scan recent application logs for PHI patterns.
Run this in your staging environment after integration tests generate real traffic.
"""
# Retrieve last N lines of application log
result = subprocess.run(
["kubectl", "logs", "--tail=1000", "deployment/api-server"],
capture_output=True, text=True
)
log_content = result.stdout
violations = []
for pattern in PHI_PATTERNS:
matches = re.findall(pattern, log_content, re.IGNORECASE)
if matches:
violations.append(f"Pattern '{pattern}': {len(matches)} matches")
assert not violations, \
f"PHI found in application logs:\n" + "\n".join(violations)Building a HIPAA Test Suite
Organize your HIPAA tests into a dedicated directory and run them as a required CI gate on any change that touches PHI-handling code:
# .github/workflows/hipaa-compliance.yml
name: HIPAA Compliance Tests
on:
pull_request:
paths:
- "src/patients/**"
- "src/records/**"
- "src/auth/**"
- "src/audit/**"
- "migrations/**"
jobs:
hipaa-tests:
runs-on: ubuntu-latest
environment: staging
steps:
- uses: actions/checkout@v4
- name: Run HIPAA compliance tests
run: pytest tests/hipaa/ -v --tb=short
- name: Check for PHI in recent logs
run: pytest tests/hipaa/test_phi_log_leakage.py -vThe goal is a suite that catches the five most common HIPAA software violations before they reach production: missing access control, inadequate audit logging, PHI in error messages, PHI in logs, and weak transmission security. Each of those is a test you can write today. The alternative is finding out about them from OCR.