/prowler-compliance

name: prowler-compliance
description: >
  Creates, syncs, audits and maintains Prowler compliance frameworks: universal
  multi-provider JSON (preferred) and legacy per-provider JSON, ConfigRequirements
  guardrails, output formatters, external compliance plug-ins (entry points), and
  check-to-requirement mapping audits.
  Trigger: When working with compliance frameworks (CIS, CIS Controls, NIST,
  PCI-DSS, SOC2, GDPR, ISO27001, ENS, MITRE ATT&CK, CCC, C5, CSA CCM, DORA, CMMC,
  Cyber Essentials, FedRAMP 20x, KISA ISMS-P, ASD Essential Eight, DISA STIG,
  CISA SCuBA, SecNumCloud, HIPAA, NIS2, Prowler ThreatScore), creating a universal
  framework, adding ConfigRequirements guardrails, syncing with upstream catalogs,
  auditing check mappings, adding output formatters, or fixing compliance JSON bugs.
license: Apache-2.0
metadata:
  author: prowler-cloud
  version: "2.1"
  scope: [root, sdk]
  auto_invoke:
    - "Creating/updating compliance frameworks"
    - "Creating a universal (multi-provider) compliance framework"
    - "Mapping checks to compliance controls"
    - "Adding ConfigRequirements guardrails to compliance requirements"
    - "Syncing compliance framework with upstream catalog"
    - "Auditing check-to-requirement mappings as a cloud auditor"
    - "Adding a compliance output formatter (per-provider class + table dispatcher)"
    - "Fixing compliance JSON bugs (duplicate IDs, empty Section, stale refs)"
allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task

When to Use

• Creating a framework (decide universal vs legacy first), adding requirements or providers to one
• Mapping checks, adding `ConfigRequirements` guardrails, auditing existing mappings
• Syncing with an upstream catalog, adding a legacy output formatter, fixing JSON bugs
• Explaining why a finding does not show under a framework (CLI, API or UI)

For reviewing a compliance PR use [prowler-compliance-review](../prowler-compliance-review/SKILL.md). Contributor doc: `docs/developer-guide/security-compliance-framework.mdx`.

Universal vs Legacy: decide first

Both formats load into the universal `ComplianceFramework` model (legacy via `adapt_legacy_to_universal()`). The difference is authoring cost.

| | Universal (default for new frameworks) | Legacy per-provider | |---|---|---| | Location | `prowler/compliance/<framework>_<version>.json` | `prowler/compliance/<provider>/<framework>_<version>_<provider>.json` | | Providers | Any, in one file (`checks: {provider: [...]}`) | One per file | | Keys | lowercase (`framework`, `requirements`, `checks`) | Capitalized (`Framework`, `Requirements`, `Checks`) | | Attribute schema | Declared in-file (`attributes_metadata`), validated at load | Pydantic class in `compliance_models.py` | | CLI table/CSV/OCSF | Data driven from `outputs.table_config`, no Python | Formatter package + registrations | | Guardrails | `config_requirements` (+ `Provider` on each) | `ConfigRequirements` | | Shipped (5.48) | `cis_controls_8.1`, `cmmc_2.0`, `csa_ccm_4.0`, `cyber_essentials_3.3`, `dora_2022_2554`, `fedramp_20x_frr_class_c_2026`, `fedramp_20x_ksi_2026` | Everything under provider dirs |

Use **legacy only** to extend an existing legacy family (new CIS version for a provider that already has CIS, ENS for a new provider). Everything else, including single-provider frameworks, is universal.

Files a new framework needs

| Piece | Universal | Legacy (new family member) | |---|---|---| | JSON | `prowler/compliance/<key>.json` | `prowler/compliance/<provider>/<key>.json` | | Attribute model | none (`attributes_metadata`) | existing class, or new class before Generic in the Union | | CLI table / CSV / OCSF | none (needs `outputs.table_config`) | reuse family package; new provider = `{framework}_{provider}.py` + `models.py` row + branch in `prowler/__main__.py` | | API compliance CSV | none (auto via `process_universal_compliance_frameworks`) | `COMPLIANCE_CLASS_MAP` entry in `api/src/backend/tasks/jobs/export.py` (else `GenericCompliance`) | | API PDF | only if required: generator + `FRAMEWORK_REGISTRY` + `report.py` wiring | same | | UI | optional: mapper + `getComplianceMappers()` entry keyed by `framework`, detail panel, type, icon | same; unknown frameworks use the generic mapper | | Dashboard | optional (`dashboard/compliance/generic.py` fallback) | optional | | Changelog | `prowler/changelog.d/<slug>.added.md` (towncrier fragment, not `CHANGELOG.md`) | same |

Critical Rules

1. **Universal files need `outputs.table_config`** (`group_by` = a declared attribute key). Without it the framework loads and lists but produces no compliance CSV, OCSF or table. 2. **Declare `attributes_metadata`** with `required`/`enum` where possible. If it is missing nothing is validated; when present, unknown keys are rejected. 3. **Set `version`/`Version` for any versioned framework.** `get_check_compliance()` keys legacy findings `"{Framework}-{Version}"`, or just `"{Framework}"` when Version is empty (31 unversioned legacy files ship that way, e.g. `hipaa_aws`, `soc2_aws`, `mitre_attack_aws`). Changing Version on an existing file changes that key. Keep the filename version equal to `Version` (the CIS table matches `compliance_framework.split("_")[1]` against `Version`). 4. **Provider keys** in universal `checks` are lowercase directory names under `prowler/providers/`. Extending to a provider = adding a key. Every `config_requirements` entry carries `Provider`. 5. **Generic stays LAST** in `Compliance_Requirement.Attributes` (Pydantic v1 tries members in order). `compliance_models.py` uses `pydantic.v1` only. 6. **Loaders differ.** `Compliance.get_bulk()` sees only provider dirs and exits on a broken built-in file; the universal loader also reads top-level files and logs-and-skips broken ones. A framework that "disappears" was usually skipped: check the log. 7. **Universal-only frameworks are not in `CheckMetadata.Compliance`**, so the