Engineering Compliance. Not Afterthought.

Automated HIPAA Security Rule (§164.312) gap assessments for AWS environments — built by engineers, for engineers who care about security.

• What Is This? (Plain English)
• Why I Built This
• Problem vs. Solution
• How It Works
• HIPAA Controls Covered
• Risk Scoring Methodology
• Tech Specs
• Security First
• Quick Start
• Sample Output
• CI/CD Integration
• Roadmap
• About the Builder
• Disclaimer
• License

Imagine you're responsible for a healthcare application that stores patient medical records in Amazon Web Services (AWS). You've heard about HIPAA — the law that protects patient health information — and you know your system needs to comply with it.

HIPAA Sentinel is a security tool that automatically checks whether your AWS setup follows HIPAA rules.

It runs a series of checks (we call them "controls") against your cloud infrastructure — things like:

• Are your storage buckets encrypted? ✓
• Is multi-factor authentication enabled for all admin accounts? ✓
• Are audit logs turned on to track who accessed what? ✓
• Are your databases protected from the public internet? ✓

After running, it gives you two reports:

1. Gap Report (JSON) — For your technical team, showing exactly what failed and how to fix it
2. Executive Summary (Markdown) — For leadership, showing your compliance score in plain English

You can run it manually, or automatically every time you deploy code to catch problems early.

I built HIPAA Sentinel because I got tired of seeing the same pattern play out over and over in healthcare organizations.

Here's what usually happens: A startup lands their first healthcare client. They spin up AWS. They store patient data. Then someone asks, "Are we HIPAA compliant?" and the answer is usually "We think so."

Six months later, they're staring down a potential breach notification, a OCR audit letter, or worse — a ransomware attack that exploited a misconfigured S3 bucket. The CFO is asking why no one caught this earlier. The answer is always the same: we didn't have a way to continuously verify our controls.

Traditional compliance approaches fail for one reason: they're periodic, not continuous. You hire a consultant, they spend two weeks auditing your environment, they produce a PDF, and then that PDF sits in a drawer until next year's audit. In between? Nothing. Your environment changes daily. Your compliance posture shouldn't be a yearly snapshot.

I built HIPAA Sentinel because I believe:

1. Compliance should be continuous, not point-in-time. If you can't verify your controls daily, you're flying blind.
2. Engineers should own security, not abdicate it. Giving a CISO a PDF doesn't make your systems secure. Giving engineers automated checks does.
3. Security tools should be run by the same people who deploy code. If your CI/CD pipeline can catch a missing semicolon, it should also catch a missing encryption key.

This tool isn't about replacing compliance professionals — it's about giving engineers the ammunition to demonstrate they're building secure systems from day one.

HIPAA Sentinel operates in three phases:

flowchart TD
    A[Phase 1: Initialize] --> B[Phase 2: Execute Controls]
    B --> C[Phase 3: Generate Reports]
    
    A --> A1[Load config.yaml]
    A --> A2[Initialize AWS SDK]
    A --> A3[Validate credentials]
    
    B --> B1[Access Control Checks]
    B --> B2[Audit Logging Checks]
    B --> B3[Encryption Checks]
    B --> B4[Network Security Checks]
    
    C --> C1[Calculate Risk Scores]
    C --> C2[Generate gap-report.json]
    C --> C3[Generate executive-summary.md]
    
    style A fill:#1e3a5f,color:#fff
    style B fill:#1e3a5f,color:#fff
    style C fill:#1e3a5f,color:#fff

hipaa-sentinel/
├── cmd/                           # CLI entry point
│   └── main.go                   # Command-line interface
├── config/                        # Configuration management
│   ├── config.go                 # Configuration loading and validation
│   └── mock.go                   # Mock configuration for testing
├── controls/                     # Control execution packages
│   ├── controls.go               # Core control execution logic
│   ├── accesscontrol/            # §164.312(a)(1) Access Control
│   │   ├── checker.go            # Control checker implementation
│   │   └── mock.go               # Mock AWS responses
│   ├── auditlogs/                # §164.312(b) Audit Controls
│   │   ├── checker.go            # Control checker implementation
│   │   └── mock.go               # Mock AWS responses
│   ├── encryption/               # §164.312(e)(2)(ii) Encryption
│   │   ├── checker.go            # Control checker implementation
│   │   └── mock.go               # Mock AWS responses
│   └── networksecurity/          # §164.312(e)(1) Network Security
│       ├── checker.go            # Control checker implementation
│       └── mock.go               # Mock AWS responses
├── reporters/                     # Report generation
│   ├── reporters.go              # Main reporter logic
│   ├── gapreport.go              # JSON gap report generator
│   └── executive.go              # Executive summary generator
├── reports/                       # Generated reports
│   ├── gap-report.json           # Detailed findings in JSON
│   └── executive-summary.md     # Executive summary in Markdown
├── config.yaml                   # Configuration file
├── go.mod                        # Go module dependencies
└── README.md                     # This file

Each control category is weighted based on its impact to ePHI confidentiality, integrity, and availability:

pie
    title Category Weight Distribution
    "Access Control" : 30
    "Audit Logging" : 25
    "Encryption" : 25
    "Network Security" : 20

Category Score = (Passing Controls ÷ Total Controls) × 100 × Category Weight
Overall Score = Sum of All Category Scores ÷ Sum of All Weights

Severity Mapping:

HIPAA Sentinel is designed with read-only, least-privilege principles. The tool never modifies your infrastructure — it only reads configuration to assess compliance.

A security tool that modifies infrastructure is a liability. Here's why read-only is the right design:

1. Trust boundary: You shouldn't need to trust a third-party tool with write access to your AWS environment
2. Audit trail: Changes should go through your existing CI/CD and change management processes
3. Accident prevention: A misconfigured tool could inadvertently expose data; read-only eliminates this risk
4. Compliance: Many compliance frameworks require separation between assessment and enforcement

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "HIPAASentinelReadAccess",
      "Effect": "Allow",
      "Action": [
        "iam:GetUser",
        "iam:GetAccountPasswordPolicy",
        "iam:ListUsers",
        "iam:ListRoles",
        "iam:ListMFADevices",
        "cloudtrail:DescribeTrails",
        "cloudtrail:GetTrailStatus",
        "cloudtrail:LookupEvents",
        "s3:GetBucketEncryption",
        "s3:GetBucketVersioning",
        "s3:GetPublicAccessBlock",
        "s3:ListBuckets",
        "rds:DescribeDBInstances",
        "rds:DescribeDBClusters",
        "ec2:DescribeVpcs",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeInstances",
        "kms:ListKeys",
        "kms:GetKeyRotationStatus"
      ],
      "Resource": "*"
    }
  ]
}

Test the tool immediately without AWS credentials:

# Clone and build
git clone https://github.com/hipaa-sentinel/hipaa-sentinel.git
cd hipaa-sentinel
go build -o hipaa-sentinel ./cmd

# Run with mock data
./hipaa-sentinel --dry-run

Run against your actual AWS environment:

# Configure your AWS credentials
aws configure

# Run the assessment
./hipaa-sentinel --config ./config.yaml

# Or with CLI flags
./hipaa-sentinel --region us-east-1 --output ./reports

# hipaa-sentinel/config.yaml

# AWS Configuration
aws:
  region: us-east-1
  profile: default

# Output Configuration
output:
  directory: ./reports
  format: json

# Control Categories (include or exclude)
controls:
  include:
    - accesscontrol
    - auditlogs
    - encryption
    - networksecurity

# Scoring Weights
weights:
  accesscontrol: 30
  auditlogs: 25
  encryption: 25
  networksecurity: 20

# Dry Run Mode (uses mock data)
dry_run: false

# Logging
logging:
  level: info
  verbose: false

   _   __     __          __
  / | / /__  / /_  __  __/ /___ _
 /  |/ / _ \/ __ \/ / / / / __ `t`/
/ /|  /  __/ /_/ / /_/ / / /_/ /
/_/ |_/\___/_.___/\__,_/_/\__,_/

  S E N T I N E L
  AWS HIPAA Compliance Checker

 ==================================================

Starting HIPAA compliance assessment...

 ==================================================
            HIPAA COMPLIANCE ASSESSMENT SUMMARY
 ==================================================

 ⚠️ Overall Score: 56.3%

 ⚠️ Status: NON-COMPLIANT

 Control Results:
   ✓ Passed:    9
   ✗ Failed:    7
   ○ Skipped:   0
   ! Errors:    0

 Findings by Severity:
   🔴 Critical: 5
   🟠 High:     1
   🟡 Medium:   1
   🔵 Low:      0

 Category Scores:
   Access Control: 75.0%
   Audit Logs: 100.0%
   Encryption: 25.0%
   Network Security: 25.0%

 Reports saved to: ./reports
   - gap-report.json
   - executive-summary.md

# HIPAA Compliance Executive Summary

**Assessment Date:** March 7, 2026

## Executive Overview

⚠️ **ACTION REQUIRED** - Your organization has security gaps that need attention

## Key Metrics

| Metric | Value |
|--------|-------|
| Overall Risk Score | 56% |
| Total Controls Checked | 16 |
| Controls Passing | 9 |
| Controls Needing Attention | 7 |
| Critical Issues | 5 |
| High Priority Issues | 1 |

## Recommended Next Steps

1. Address 5 critical security issues immediately to meet HIPAA requirements
2. Resolve 1 high-priority security gap within the next 30 days
3. Implement encryption for all data at rest and in transit
4. Review and restrict network access to prevent unauthorized data exposure
5. Strengthen access controls with multi-factor authentication for all users

name: HIPAA Compliance Gate

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  hipaa-compliance:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.21'

      - name: Build HIPAA Sentinel
        run: go build -o hipaa-sentinel ./cmd

      - name: Run HIPAA Compliance Check
        run: |
          ./hipaa-sentinel --dry-run --output ./reports

      - name: Upload Gap Report
        uses: actions/upload-artifact@v4
        with:
          name: hipaa-gap-report
          path: reports/gap-report.json

      - name: Upload Executive Summary
        uses: actions/upload-artifact@v4
        with:
          name: hipaa-executive-summary
          path: reports/executive-summary.md

      - name: Check for Critical Findings
        run: |
          CRITICAL=$(grep -c '"severity": "Critical"' reports/gap-report.json || true)
          if [ "$CRITICAL" -gt 0 ]; then
            echo "❌ HIPAA Sentinel blocked deployment: $CRITICAL critical findings"
            cat reports/executive-summary.md
            exit 1
          fi
          echo "✅ No critical HIPAA findings"

HIPAA Sentinel is a tool, not legal advice.

This tool helps you assess technical controls against the HIPAA Security Rule, but it does not guarantee HIPAA compliance. HIPAA compliance involves administrative, physical, and technical safeguards, as well as business associate agreements, policies, procedures, and ongoing risk analysis.

Always consult with a qualified HIPAA compliance professional or legal counsel for official compliance assessments. The authors and contributors of this project accept no liability for decisions made based on this tool's output.

MIT License — See LICENSE for full text.