Skip to content
BranchesTags

Repository files navigation

ComplianceIQ

AI-Powered Compliance Control Mapping & Policy Generation for Azure

Accelerate regulatory compliance across Government, Healthcare, and Financial sectors

Azure License: MIT Compliance

Overview

ComplianceIQ is a toolkit for implementing security and compliance controls in Azure cloud environments. It combines pre-built compliance control catalogs with an AI-powered mapping agent that can automatically map any compliance framework to the Microsoft Cloud Security Benchmark (MCSB) and generate deployable Azure Policy initiatives.

Key Capabilities

  • AI-Powered Mapping — Upload a compliance PDF, and Azure OpenAI maps controls to Azure policies and Defender for Cloud recommendations
  • 7 Pre-Built Frameworks — Ready-to-use mappings for SAMA, ADHICS, Saudi Arabia Government (NDMO), Saudi Arabia Government (NCA CSCC), South African Government, and Oman Government
  • Azure Policy Generation — Export compliant Azure Policy initiative JSON, including Sovereign Landing Zone (SLZ) archetypes
  • Interactive Review UI — Streamlit-based web interface for reviewing, editing, and approving AI-generated mappings
  • End-to-End Pipeline — Upload PDF → Extract Controls → AI Map → Review → Export Policy
  • One-Click Deployment — Deploy to Azure Container Apps with azd up

Recent Improvements

  • Task Management System — Background tasks (AI mapping, PDF extraction) are tracked globally and survive page navigation. A task status bar shows active/completed jobs across all pages.
  • Persistent Session State — Controls, mappings, and policy decisions are auto-saved to Cosmos DB. Sessions can be recovered after browser refreshes or navigation.
  • Backend Application Logs — A new "Show Backend Logs" option in the sidebar streams live application logs from the backend container with configurable poll intervals.
  • Entra ID Authentication — Optional authentication via Container Apps Easy Auth v2, configurable through azd env set AUTH_CLIENT_ID during deployment.
  • Centralized State Management — All session state is initialized from a single schema, eliminating duplicate initialization code across pages.

Repository Structure

compliance-iq/
├── README.md                  # This file
├── LICENSE                    # MIT License
├── CONTRIBUTING.md            # Contribution guidelines
├── azure.yaml                 # Azure Developer CLI config
│
├── app/                       # AI Mapping Agent (full-stack application)
│   ├── backend/               #   FastAPI + Azure OpenAI + Cosmos DB
│   ├── frontend/              #   Streamlit web UI
│   ├── infra/                 #   Bicep IaC (Container Apps, OpenAI, Cosmos DB)
│   ├── tests/                 #   Integration tests
│   ├── README.md              #   App documentation
│   ├── QUICKSTART.md          #   5-minute local setup
│   ├── DEPLOYMENT.md          #   Azure deployment guide
│   └── TROUBLESHOOTING.md     #   Common issues & fixes
│
├── catalogues/                # Pre-built compliance control mappings (CSV)
│   ├── SAMA_Catalog_Azure_Mappings.csv
│   ├── ADHICS_Framework_Azure_Mappings.csv
│   ├── Saudi_Arabia_Government_Azure_Mappings.csv
│   ├── South_African_Government_Azure_Mappings.csv
│   ├── Oman_Government_Azure_Mappings.csv
│   └── CATALOG_SUMMARY.md
│
├── framework/                 # Azure Policy initiative JSON & deployment scripts
├── reference_documents/       # Source compliance framework PDFs
├── templates/                 # Simplified control templates for gap analysis
└── docs/                      # Supplementary guides & references

Supported Frameworks

Framework Region Sector Policies Catalog
SAMA Saudi Arabia Financial 48 View
ADHICS Abu Dhabi Healthcare 50 View
Saudi Arabia Government Saudi Arabia Government 58 View
NCA CSCC v1.5 Saudi Arabia Government / CNI 49 View
Oman Government Oman Government 53 View

Each catalog maps controls to:

  • Azure Policy names and definition IDs (GUIDs)
  • Microsoft Defender for Cloud control categories
  • Evidence examples and implementation guidance

Quick Start

Option 1: Use the Pre-Built Catalogs

git clone https://github.com/warrendt/compliance-iq.git
cd compliance-iq

# Browse catalogs for your sector
cat catalogues/SAMA_Catalog_Azure_Mappings.csv                    # Financial
cat catalogues/ADHICS_Framework_Azure_Mappings.csv               # Healthcare
cat catalogues/South_African_Government_Azure_Mappings.csv       # South Africa
cat catalogues/Saudi_Arabia_Government_Azure_Mappings.csv        # Saudi Arabia (Government)
cat catalogues/Oman_Government_Azure_Mappings.csv                # Oman
# Reference docs for newer frameworks
cat reference_documents/ndmo/NDMO_Azure_Controls_Mapping.md     # Saudi Arabia (NDMO)
cat reference_documents/nca/NCA_CSCC_to_Azure_Policy_Mapping.md # Saudi Arabia (NCA CSCC)

Option 2: Run the AI Mapping Agent Locally

cd app

# Backend
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.template .env   # Edit with your Azure OpenAI endpoint
az login
uvicorn app.main:app --reload --port 8000

# Frontend (new terminal)
cd ../frontend
pip install -r requirements.txt
streamlit run 1_🏠_Home.py --server.port 8501

See app/QUICKSTART.md for full setup instructions.

Option 3: Deploy to Azure

# One-command deployment with Azure Developer CLI
azd auth login
azd init
azd up

This provisions: Azure Container Apps, Azure OpenAI, Azure Cosmos DB, Container Registry, and VNet with private endpoints.

See app/DEPLOYMENT.md for detailed deployment guide.

Architecture

┌─────────────────────────────────────────────────────────┐
│             Streamlit Frontend (Port 8501)               │
│   Home │ AI Mapping │ Review │ Export │ PDF Pipeline     │
│                  │ Policy Explorer                       │
└─────────────────┬───────────────────────────────────────┘
                  │ REST API
┌─────────────────▼───────────────────────────────────────┐
│              FastAPI Backend (Port 8000)                 │
│  • MCSB Loader       • AI Mapping Service               │
│  • Sovereignty SLZ   • Policy Generator                 │
│  • PDF Extractor     • Cosmos DB Persistence             │
└────────┬──────────────────────────┬─────────────────────┘
         │                          │
┌────────▼────────┐     ┌──────────▼──────────────────────┐
│  Azure OpenAI   │     │  Mapping history & persistence  │
│  Structured Out │     │                                 │
└─────────────────┘     └─────────────────────────────────┘

Azure Infrastructure (deployed via Bicep):

  • Azure Container Apps (frontend + backend)
  • Azure OpenAI (with structured outputs)
  • Azure Cosmos DB (NoSQL — session & mapping storage)
  • Azure Container Registry
  • VNet with private endpoints
  • Entra ID authentication

Use Cases

Security Architects

Use the pre-built catalogs to identify Azure Policy definitions and Defender for Cloud controls for your regulatory framework. Extract policy GUIDs and deploy directly via CLI, Bicep, or Terraform.

Compliance Teams

Upload new compliance framework PDFs to the AI agent for automated mapping. Review and adjust AI-generated mappings through the web UI, then export audit-ready evidence documentation.

DevOps / Platform Engineers

Deploy Azure Policy initiatives generated by the toolkit. Use the framework/ directory for ready-made policy initiative JSON and PowerShell deployment scripts.

Azure Policy Initiative Deployment

The framework/ directory contains deployable Azure Policy initiative JSON for all 7 frameworks, plus tooling to keep GUIDs accurate.

All initiatives are assigned in DoNotEnforce (audit-only) mode. Policies evaluate resources and report compliance state, but do not block deployments or trigger auto-remediation. This is safe for production subscriptions.

# Deploy all 7 initiatives to your Azure subscription
cd framework/
.\DeployAllInitiatives.ps1 -TenantId <tenant-id> -SubscriptionId <subscription-id>

# Validate all policy GUIDs against live Azure data (2,748 built-in policies)
python3 validate_guids.py

# Force-refresh the Azure policy cache (bypasses 24h TTL)
python3 validate_guids.py --refresh-cache

# Search for a policy by keyword
python3 validate_guids.py --search "remote debugging"

# Apply the verified replacement map to fix any invalid GUIDs
python3 fix_guids.py --dry-run   # preview
python3 fix_guids.py             # apply

GUID Validation System — validate_guids.py caches all 2,748 Azure built-in policies locally and validates every GUID in every policies.json against real Azure data. DeployAllInitiatives.ps1 runs this check automatically as a pre-flight step before each deployment.

Trigger a compliance rescan (after deployment, to refresh Azure Policy state):

Start-AzPolicyComplianceScan
# or as a background job:
Start-AzPolicyComplianceScan -AsJob

Documentation

Document Description
app/QUICKSTART.md 5-minute local setup guide
app/DEPLOYMENT.md Azure deployment with azd
app/TROUBLESHOOTING.md Common issues & fixes
catalogues/CATALOG_SUMMARY.md Detailed catalog documentation
templates/CONTROL_TEMPLATES_README.md Simplified template usage
docs/PROCESS_DOCUMENTATION.md End-to-end process guide

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Author

Warren du Toit Cloud Solution Architect @ Microsoft

License

This project is licensed under the MIT License — see LICENSE for details.

About

AI-powered regulatory compliance mapping for Middle East & Africa frameworks (NCA ECC, SAMA CSF, PDPL, ADHICS, Oman CDC, MCSB)

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

6 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages