Skills DirectorySearch all skills ↗AI agent skill · by @prowler-cloud
Prowler Compliance
Creates, syncs, audits and manages Prowler compliance frameworks end-to-end. Covers the two supported JSON schemas (universal multi-provider and legacy per-provider), the SDK model tree (legacy attribute classes, universal ComplianceFramework, ConfigRequirements guardrails), output formatters (legacy per-framework + universal data-driven), API/UI consumption, upstream sync workflows, and cloud-auditor check-mapping reviews. Trigger: When working with compliance frameworks (CIS, CIS Controls, NIST, PCI-DSS, SOC2, GDPR, ISO27001, ENS, MITRE ATT&CK, CCC, C5, CSA CCM, DORA, KISA ISMS-P, ASD Essential Eight, DISA STIG, CISA SCuBA, SecNumCloud, FedRAMP, HIPAA, NIS2, Prowler ThreatScore), creating a universal multi-provider framework, adding ConfigRequirements guardrails, syncing with upstream catalogs, auditing check-to-requirement mappings, adding output formatters, or fixing compliance JSON bugs (duplicate IDs, empty Version, wrong Section, stale check refs).
Archived 2026-10-23 · Source updated 2026-09-18 · License: Apache-2.0. Check the original repository for the latest version.
SKILL.md instructions
## When to Use
Use this skill when:
- Creating a new compliance framework for any provider — **decide universal vs legacy first** (see below)
- **Syncing an existing framework with an upstream source of truth** (CIS, FINOS CCC, CSA CCM, NIST, ENS, etc.)
- Adding requirements to existing frameworks, or extending a universal framework to a new provider
- Mapping checks to compliance controls
- **Adding `ConfigRequirements` guardrails** so configurable checks can't silently satisfy a requirement with a loosened config
- **Auditing existing check mappings as a cloud auditor** ("are these mappings correct?", "which checks apply?", "review the mappings")
- **Adding a new legacy output formatter** (table dispatcher + per-provider classes + CSV models)
- **Fixing JSON bugs**: duplicate IDs, empty Version, wrong Section, stale check refs, inconsistent FamilyName, padded tangential check mappings
- Investigating why a finding/check isn't showing under the expected compliance framework in the UI
- Understanding compliance framework structures and attributes
The authoritative contributor doc is `docs/developer-guide/security-compliance-framework.mdx` —
keep this skill and that doc consistent when either changes. For **reviewing**
a compliance PR, use the sister skill
[prowler-compliance-review](../prowler-compliance-review/SKILL.md) instead.
## Universal vs Legacy: The First Decision
Prowler supports **two JSON schemas**. Choosing wrong means unnecessary Python
code, so decide this before anything else. At load time both converge: legacy
files are adapted into the universal `ComplianceFramework` model
(`adapt_legacy_to_universal()`), so the difference is about **authoring cost
and capabilities**, not about what the rest of Prowler sees.
### Side-by-side comparison
| | Universal (recommended for new frameworks) | Legacy provider-specific |
|---|---|---|
| File location | `prowler/compliance/<framework>.json` (top level) | `prowler/compliance/<provider>/<framework>_<version>_<provider>.json` |
| Providers | Any number, one file (`checks` dict keyed by provider) | Exactly one provider per file (one file per provider to multi-cover) |
| Key style | lowercase (`framework`, `requirements`, `checks`) | Capitalized (`Framework`, `Requirements`, `Checks`) |
| Attribute schema | Declared **in the JSON itself** via `attributes_metadata`, validated at load | Pydantic class per framework family in `compliance_models.py` (code change for new shapes) |
| Attributes per requirement | One flat dict (`attributes: {...}`) | List of objects (`Attributes: [{...}]`) — only `Attributes[0]` is used downstream |
| Table/CSV/OCSF output | Data-driven from `outputs.table_config` — **zero Python changes** | Formatter package + registrations in `compliance.py`, `__main__.py`, `export.py` |
| Guardrails field | `config_requirements` (+ mandatory `Provider` per constraint) | `ConfigRequirements` (`Provider` omitted) |
| Loader behavior on error | Lenient: logs + skips file (`load_compliance_framework_universal`) | Fail-fast: `sys.exit(1)` (`load_compliance_framework`) |
| Loaded by | Only `get_bulk_compliance_frameworks_universal()` | Both loaders (`Compliance.get_bulk()` + universal, via adapter) |
| Shipped examples | `cis_controls_8.1.json`, `csa_ccm_4.0.json`, `dora_2022_2554.json` | Everything else (~105 files across 11 providers) |
### When to use which
**Use universal when** (any of these):
- The framework is **new to Prowler** — no existing attribute class, no
existing formatter. This is the default: zero Python changes needed.
- The framework spans (or will span) **more than one provider** — DORA, CSA
CCM, CIS Controls. One file covers all providers; extending to a new
provider is a one-line `checks` edit.
- The attribute shape is **unique to this framework** — declare it in
`attributes_metadata` instead of adding a Pydantic class to the Union.
**Use legacy only when extending an existing legacy family**:
- A new **version** of a shipped legacy framework (CIS 8.0 for AWS → new
`cis_8.0_aws.json`, same `CIS_Requirement_Attribute`, same `cis/` formatter).
- An existing legacy framework for a **new provider** (ENS for m365 → new
`ens_rd2022_m365.json` + `ens_m365.py` transformer).
- Consistency with the family matters more than the universal benefits — a
lone `cis_8.0_aws` in universal format while 20+ CIS files stay legacy
would fragment the family.
**Never**: start a brand-new single-provider framework as legacy "because it's
only AWS today". Universal handles single-provider fine (the `checks` dict
just has one key) and you skip 3 output files + 3 registrations.
### The same requirement in both schemas
Universal (`prowler/compliance/my_framework_1.0.json`):
```json
{
"framework": "My-Framework",
"name": "My Framework 1.0",
"version": "1.0",
"description": "...",
"attributes_metadata": [
{"key": "Section", "type": "str", "required": true},
{"key": "Service", "type": "str"}
],
"outputs": {"table_config": {"group_by": "Section"}},
"requirements": [
{
"id": "MF-1.1",
"name": "Root MFA",
"description": "Root account must have MFA enabled.",
"attributes": {"Section": "IAM", "Service": "iam"},
"checks": {
"aws": ["iam_root_mfa_enabled"],
"azure": []
}
}
]
}
```
Legacy (`prowler/compliance/aws/my_framework_1.0_aws.json` — plus a second
file per extra provider, plus formatter + registrations):
```json
{
"Framework": "My-Framework",
"Name": "My Framework 1.0 for AWS",
"Version": "1.0",
"Provider": "AWS",
"Description": "...",
"Requirements": [
{
"Id": "MF-1.1",
"Name": "Root MFA",
"Description": "Root account must have MFA enabled.",
"Attributes": [
{"ItemId": "MF-1.1", "Section": "IAM", "Service": "iam"}
],
"Checks": ["iam_root_mfa_enabled"]
}
]
}
```
Same control, but the universal file already covers Azure, validates its own
attribute schema, and renders table/CSV/OCSF with no code. Field-by-field
references for each schema follow below.
## Architecture (Mental Model)
Prowler compliance is a four-layer system. Bugs usually happen where one layer
doesn't match another, so know all four before touching anything.
### Layer 1: SDK / Core Models — `prowler/lib/check/`
All in **Pydantic v1** (`from pydantic.v1 import ...`). Three model groups live
in `compliance_models.py`:
**Legacy tree** — `Compliance` → `Compliance_Requirement` / `Mitre_Requirement`:
- One `*_Requirement_Attribute` class per framework family. Registered today (Union order matters):
`ASDEssentialEight`, `CIS`, `ENS`, `ISO27001_2013`, `AWS_Well_Architected`,
`KISA_ISMSP`, `Prowler_ThreatScore`, `CCC`, `C5Germany`, `CSA_CCM`, `STIG`
(Okta IDaaS), and `Generic_Compliance_Requirement_Attribute` as fallback.
- **Generic MUST stay LAST** in `Compliance_Requirement.Attributes: list[Union[...]]` —
Pydantic v1 tries union members in order; Generic first would swallow every
framework-specific attribute. NIST 800-53/CSF, PCI DSS, GDPR, HIPAA, SOC2,
FedRAMP, SecNumCloud etc. intentionally use Generic.
- A `root_validator` rejects empty `Framework`, `Provider` or `Name`.
- MITRE uses the separate `Mitre_Requirement` model (`Tactics`, `SubTechniques`,
`Platforms`, `TechniqueURL` at requirement top level, per-provider
`Mitre_Requirement_Attribute_{AWS,Azure,GCP}`).
**Universal tree** — `ComplianceFramework` → `UniversalComplianceRequirement`:
- Flat `attributes: dict` per requirement, schema declared in
`attributes_metadata` (key, label, type, enum, required, `enum_display`,
`enum_order`, `output_formats`). A `root_validator` rejects missing required
keys, unknown keys (drift guard), enum violations, and int/float/bool type
mismatches. If `attributes_metadata` is omitted, **no validation runs**.
- `checks: dict[provider, list[check_id]]` — the provider list of the framework
is **derived** from these keys (`get_providers()` / `supports_provider()`);
the top-level `provider` field is only a fallback.
- `outputs.table_config` (group_by, split_by, scoring, labels) drives the CLI
table; `outputs.pdf_config` exists in the model but **is not consumed by the
API PDF pipeline yet** (see Layer 4).
**Guardrails** — `Compliance_Requirement_ConfigConstraint`:
- Fields `Check`, `ConfigKey`, `Operator` (`lte|gte|eq|in|subset|superset`),
`Value`, optional `Provider` (required in universal multi-provider files).
- A `root_validator` rejects Value/Operator type mismatches at load time.
- Evaluation is centralized in `prowler/lib/check/compliance_config_eval.py`
(`evaluate_config_constraints`, `apply_config_status`, `get_effective_status`,
`CONFIG_NOT_VALID_PREFIX = "Configuration not valid for this requirement."`),
shared by CSV/OCSF/table outputs **and** the API backend. A violated
constraint forces the requirement to FAIL and prepends the reason to
`status_extended`. Constraints whose `ConfigKey` is absent from
`audit_config` are skipped (defaults assumed compliant).
**Loaders**:
- `Compliance.get_bulk(provider)` — legacy: scans only
`prowler/compliance/{provider}/` (+ external JSONs via the
`prowler.compliance` entry-point group). Does NOT see top-level universal files.
- `get_bulk_compliance_frameworks_universal(provider)` — scans **both** the
top-level `prowler/compliance/` and every provider subdirectory, adapting
legacy files via `adapt_legacy_to_universal()` (flattens `Attributes[0]` to a
dict, wraps `Checks` as `{provider: [...]}`, infers `attributes_metadata`).
Also loads external universal frameworks via the
`prowler.compliance.universal` entry-point group (built-ins win collisions).
- `get_check_compliance(finding, provider_type, bulk_checks_metadata)` lives in
**`prowler/lib/outputs/compliance/compliance_check.py`** (not in
`lib/check/compliance.py`). It builds the per-finding dict keyed
`f"{Framework}-{Version}"` **only when Version is non-empty** — an empty
Version silently produces the key `"{Framework}"` and breaks downstream
filters and tests.
- `prowler/lib/check/compliance.py` now contains only
`update_checks_metadata_with_compliance()`.
### Layer 2: JSON Catalogs — `prowler/compliance/`
See "Compliance Catalog Coverage" below.
### Layer 3: Output Formatters — `prowler/lib/outputs/compliance/`
**Universal path** (no Python needed per framework):
- `universal/universal_table.py` — `get_universal_table()`, renders the CLI
table from `outputs.table_config` + `attributes_metadata`.
- `universal/universal_output.py` — `UniversalComplianceOutput`, builds the CSV
Pydantic model **dynamically** from `attributes_metadata`.
- `universal/ocsf_compliance.py` — `OCSFComplianceOutput`; OCSF output is
**always generated** for universal frameworks regardless of `--output-formats`.
- Orchestrated by `process_universal_compliance_frameworks()` in
`compliance.py`, which runs **before** any legacy dispatch and removes the
processed frameworks from the set.
**Legacy path** — per-framework directory, usually:
```text
{framework}/
├── __init__.py
├── {framework}.py # get_{framework}_table() summary-table function
├── {framework}_{provider}.py # One ComplianceOutput subclass per provider
└── models.py # One Pydantic CSV row model per provider
```
Directories today: `asd_essential_eight`, `aws_well_architected`, `c5`, `ccc`,
`cis`, `cisa_scuba`, `ens`, `generic`, `iso27001`, `kisa_ismsp`,
`mitre_attack`, `okta_idaas_stig`, `prowler_threatscore`, `universal`.
Known deviations (don't "fix" them without a reason): `iso27001/` has no table
file (falls to the generic table), `aws_well_architected/` has no per-provider
files, `cisa_scuba/` only ships googleworkspace.
- CSV writers emit `;`-delimited files with UPPERCASE headers
(`ComplianceOutput.batch_write_data_to_file`). Field names in `models.py`
are **public API** — renaming breaks downstream consumers.
- **Circular import rule**: the table file (`{framework}.py`) must not import
`Finding` directly or transitively (`compliance.compliance` → table module →
`ComplianceOutput` → `Finding` → `get_check_compliance` → cycle). Keep table
files bare (`colorama`, `tabulate`, `prowler.config.config`); when a module
genuinely needs both, use `if TYPE_CHECKING:` or function-local imports (see
`universal_output.py` / `process_universal_compliance_frameworks`).
- Legacy table functions have no docstrings; the universal ones do. Match the
style of the file family you're touching.
- Dispatcher `display_compliance_table()` in `compliance.py` order:
universal (`table_config`) first → `cis_` → `ens_` → `mitre_attack` →
`kisa` → `prowler_threatscore_` → `c5_` → `ccc_` → `asd_essential_eight`
(substring) → `okta_idaas_stig` → else provider hook
(`provider.display_compliance_table()`, may raise `NotImplementedError`) →
`get_generic_compliance_table()`. iso27001, aws_well_architected and
cisa_scuba ride the fallback on purpose.
### Layer 4: API / UI
- **API lazy loaders**: `api/src/backend/api/compliance.py` —
`LazyComplianceTemplate` / `LazyChecksMapping` (per-provider lazy caches over
`get_bulk_compliance_frameworks_universal`, with Gunicorn background warm-up).
- **API CSV export dispatch**: `COMPLIANCE_CLASS_MAP` in
`api/src/backend/tasks/jobs/export.py`, consumed from `tasks/tasks.py`. It is
a dict `provider → [(predicate, exporter_class)]` with `GenericCompliance` as
fallback. Predicates mix **`startswith` for multi-version families**
(`cis_`, `ens_`, `iso27001_`, `ccc_`, `cisa_scuba_`, ...) and **exact
`name == ...` for true singletons** (`mitre_attack_aws`,
`prowler_threatscore_*`, `asd_essential_eight_aws` — and inconsistently
`c5_azure`/`c5_gcp`, while aws uses `startswith("c5_")`). Rule of thumb: if
the framework can ever grow versions or variants, use `startswith`.
- **API overview ingestion**: `create_compliance_requirements()` in
`api/src/backend/tasks/jobs/scan.py` builds per-region rows from the lazy
template and persists `ComplianceRequirementOverview` (COPY with bulk-create
fallback) plus `ComplianceOverviewSummary`.
- **API PDF reports**: `api/src/backend/tasks/jobs/reports/` — hardcoded
`FRAMEWORK_REGISTRY` (own `FrameworkConfig` dataclass, NOT the SDK
`PDFConfig`) with one generator class per framework. Only
`prowler_threatscore`, `ens`, `nis2`, `csa_ccm` and `cis` have PDFs today;
adding one means a generator class + registry entry + wiring in `report.py`.
- **UI mapper routing**: `ui/lib/compliance/compliance-mapper.ts` —
`getComplianceMappers()` keyed by the JSON's `framework` value
(e.g. `"CIS"`, `"CIS-Controls"`, `"DORA"`, `"Okta-IDaaS-STIG"`). Unregistered
frameworks **fall back to the generic mapper + `GenericCustomDetails`
automatically** — a dedicated mapper/detail panel is a first-class upgrade,
not a requirement to render.
- **UI grouping varies per mapper**: generic/cis group by
`Section`/`SubSection`, iso by `Category`, ccc by `FamilyName`. All read
`attributes[0]` — inconsistent values within one JSON become separate tree
branches, so normalize before shipping.
- **UI types**: `ui/types/compliance.ts` — one `*AttributesMetadata` interface
per framework, added to the `AttributesItemData` metadata union.
- **UI icons**: `ui/components/icons/compliance/` + `IconCompliance.tsx`.
Registration is an ordered substring match (`COMPLIANCE_LOGOS`): put
framework-specific keywords **before** generic ones (`nist` before `nis2`,
`cisa` before `cis`; `aws` deliberately last).
### The CLI Pipeline (end-to-end)
```text
prowler aws --compliance cis_7.0_aws # framework key = JSON basename
↓
Compliance.get_bulk("aws") # legacy frameworks
get_bulk_compliance_frameworks_universal("aws") # legacy (adapted) + universal
↓
update_checks_metadata_with_compliance() # attaches compliance to CheckMetadata
↓
execute_checks() → Finding objects
↓
get_check_compliance(finding, "aws", bulk) # dict "{Framework}-{Version}" → [req_ids]
↓
process_universal_compliance_frameworks() # universal: CSV + OCSF, then removed from set
per-provider elif branches in __main__.py # legacy: AWSCIS(...).batch_write_data_to_file()
↓
display_compliance_table() # universal table first, then legacy elifs,
# then generic fallback
```
---
## Compliance Catalog Coverage
Counts as of 2026-07 (109 JSON files). Regenerate before trusting them:
```bash
for d in prowler/compliance/*/; do printf "%s: %s\n" "$(basename $d)" "$(ls $d*.json 2>/dev/null | wc -l)"; done
ls prowler/compliance/*.json # universal, top-level
```
**Universal (top-level, multi-provider)**: `cis_controls_8.1.json` (18
providers), `csa_ccm_4.0.json` (aws/azure/gcp/alibabacloud/oraclecloud),
`dora_2022_2554.json` (aws/azure/gcp/alibabacloud/cloudflare).
**Legacy per-provider** (families, not exhaustive versions):
| Provider | # | Framework families |
|---|---|---|
| aws | 45 | CIS 1.4–7.0, NIST 800-53 r4/r5, NIST 800-171 r2, NIST CSF 1.1/2.0, PCI 3.2.1/4.0, ISO 27001 2013/2022, HIPAA, GDPR, SOC2, FedRAMP low/moderate r4 + 20x KSI low, ENS RD2022, MITRE ATT&CK, C5, CCC, CISA, FFIEC, RBI, Well-Architected (security/reliability), FTR, FSBP, AWS AI Security Framework, AWS Account Security Onboarding, Audit Manager Control Tower, GxP 21 CFR 11 / EU Annex 11, KISA ISMS-P 2023 (en+ko), NIS2, ASD Essential Eight, SecNumCloud 3.2, Prowler ThreatScore |
| azure | 19 | CIS 2.0–6.0, ISO 27001 2022, ENS RD2022, MITRE ATT&CK, PCI 4.0, HIPAA, SOC2, NIS2, RBI, C5, CCC, FedRAMP 20x KSI low, SecNumCloud 3.2, Prowler ThreatScore |
| gcp | 17 | CIS 2.0–5.0, ISO 27001 2022, ENS RD2022, MITRE ATT&CK, PCI 4.0, HIPAA, SOC2, NIS2, RBI, C5, CCC, FedRAMP 20x KSI low, SecNumCloud 3.2, Prowler ThreatScore |
| kubernetes | 8 | CIS 1.8–2.0.1, ISO 27001 2022, PCI 4.0, Prowler ThreatScore |
| m365 | 5 | CIS 4.0/6.0/7.0, ISO 27001 2022, Prowler ThreatScore |
| alibabacloud | 3 | CIS 2.0, SecNumCloud 3.2, Prowler ThreatScore |
| oraclecloud | 3 | CIS 3.0/3.1, SecNumCloud 3.2 |
| github | 2 | CIS 1.0/1.2.0 |
| googleworkspace | 2 | CIS 1.3, CISA SCuBA 0.6 |
| okta | 1 | Okta IDaaS STIG V1R2 |
| nhn | 1 | ISO 27001 2022 |
Providers with a compliance directory but no frameworks yet: cloudflare, iac,
linode, llm, mongodbatlas, openstack, stackit. Provider keys inside universal
`checks` dicts must match directory names under `prowler/providers/` (lowercase).
---
## Universal Schema Reference
Full spec in `docs/developer-guide/security-compliance-framework.mdx`. Skeleton:
```json
{
"framework": "DORA",
"name": "Digital Operational Resilience Act (DORA) 2022/2554",
"version": "2022/2554",
"description": "Shown in --list-compliance and PDF reports.",
"icon": "dora",
"attributes_metadata": [
{"key": "Pillar", "label": "Pillar", "type": "str", "required": true,
"enum": ["ICT Risk Management", "..."],
"output_formats": {"csv": true, "ocsf": true}},
{"key": "Article", "type": "str", "required": true}
],
"outputs": {
"table_config": {"group_by": "Pillar"},
"pdf_config": {"group_by_field": "Pillar", "charts": ["..."]}
},
"requirements": [
{
"id": "DORA-Art5",
"name": "Governance and organisation",
"description": "Requirement text verbatim from the source.",
"attributes": {"Pillar": "ICT Risk Management", "Article": "Article 5"},
"checks": {
"aws": ["iam_no_root_access_key"],
"azure": [],
"gcp": []
},
"config_requirements": [
{"Check": "iam_user_accesskey_unused", "Provider": "aws",
"ConfigKey": "max_unused_access_keys_days", "Operator": "lte", "Value": 45}
]
}
]
}
```
### Universal fields, top level (`ComplianceFramework`)
| Field | Type | Required | Notes |
|---|---|---|---|
| `framework` | string | Yes | Short identifier (`DORA`, `CSA-CCM`, `CIS-Controls`). This is the key the UI mapper routes on. |
| `name` | string | Yes | Human-readable full name. |
| `version` | string | No (never leave empty) | Framework version/edition (`8.1`, `2022/2554`). |
| `description` | string | Yes | Shown in `--list-compliance` and PDF reports. |
| `provider` | string | No | Fallback only — the effective provider list is derived from `checks` keys across requirements (`get_providers()`). |
| `icon` | string | No | Short icon slug. |
| `attributes_metadata` | array | No (strongly recommended) | Declares the schema of every `attributes` key. **If omitted, no attribute validation runs at all.** |
| `outputs` | object | No | `table_config` (CLI table) + `pdf_config` (modeled, not yet consumed by the API). |
| `requirements` | array | Yes | List of requirement objects (below). |
### Universal fields, per requirement (`UniversalComplianceRequirement`)
| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | Yes | Unique within the framework. |
| `description` | string | Yes | Requirement text verbatim from the source. |
| `name` | string | No | Short title. |
| `attributes` | dict | No (default `{}`) | Flat dict; every key must be declared in `attributes_metadata` (unknown keys are rejected at load when metadata exists). |
| `checks` | dict | No (default `{}`) | `{provider: [check_ids]}`, lowercase keys matching `prowler/providers/` dirs. Empty list = manual requirement for that provider. |
| `config_requirements` | array | No | Guardrails; each constraint **must** carry `Provider`. |
| `tactics`, `sub_techniques`, `platforms`, `technique_url` | — | No | MITRE-style extras (auto-populated when adapting legacy MITRE files). |
### `attributes_metadata` entry fields (`AttributeMetadata`)
| Field | Type | Notes |
|---|---|---|
| `key` | string (required) | Attribute name as used in `requirement.attributes`. |
| `label` | string | Human-readable label for CSV headers / PDF. |
| `type` | string | `str` (default), `int`, `float`, `bool`, `list_str`, `list_dict`. Only int/float/bool are enforced at load; the rest are documentation. |
| `enum` | list | Allowed values — enforced at load. Use it whenever the value set is closed. |
| `required` | bool | Enforced at load: every requirement must carry the key non-null. |
| `enum_display` / `enum_order` | dict / list | Per-enum-value visual metadata (label, abbreviation, color, icon) and ordering for PDF rendering. |
| `chart_label` | string | Axis label when the attribute is used in charts. |
| `output_formats` | object | `{"csv": bool, "ocsf": bool}`, both default `true` — toggles inclusion per output. |
Key rules:
- `--compliance` key = JSON basename without `.json` (`dora_2022_2554`).
- Auto-discovered: no `__init__.py`, no formatter, no dispatcher registration.
- `table_config.group_by`, `pdf_config.group_by_field` and every
`charts[].group_by` must reference a key declared in `attributes_metadata`.
- Runtime type validation only covers `int`/`float`/`bool`; `str`/`list_str`/
`list_dict` are documentation-only.
- Extending to a new provider = adding a key to `requirement.checks`. Nothing else.
- **No automatic check-existence validation at load time** — a typo'd check id
silently produces a requirement with no findings. Always run the
check-existence cross-check (see Validation).
- In universal files, always set `Provider` on every config constraint so a
guardrail authored for an AWS check never affects Azure/GCP scans of the
same requirement.
## Legacy Schema Reference
Base legacy file structure:
```json
{
"Framework": "FRAMEWORK_NAME",
"Name": "Full Framework Name with Version",
"Version": "X.X",
"Provider": "AWS",
"Description": "Framework description...",
"Requirements": [
{
"Id": "requirement_id",
"Name": "Optional requirement name",
"Description": "Requirement description",
"Attributes": [ ... ],
"Checks": ["check_name_1"],
"ConfigRequirements": [ ... ]
}
]
}
```
### Legacy fields, top level (`Compliance`)
| Field | Type | Required | Notes |
|---|---|---|---|
| `Framework` | string | Yes (non-empty, validated) | Canonical identifier (`CIS`, `ENS`, `NIST-800-53-Revision-5`). |
| `Name` | string | Yes (non-empty, validated) | Human-readable name with version. |
| `Version` | string | Optional in the model — **never leave it empty in practice** | Empty Version silently degrades the `get_check_compliance()` key to `"{Framework}"` (gotcha #4). Must match the version substring in the filename. |
| `Provider` | string | Yes (non-empty, validated) | Upper-cased single provider (`AWS`, `AZURE`, `GCP`, `M365`, ...). One file = one provider. |
| `Description` | string | Yes | Framework scope and purpose. |
| `Requirements` | array | Yes | Requirement objects (below), or `Mitre_Requirement` objects for MITRE files. |
### Legacy fields, per requirement (`Compliance_Requirement`)
| Field | Type | Required | Notes |
|---|---|---|---|
| `Id` | string | Yes | Unique within the framework; follow the source numbering exactly (`1.1`, `A.5.1`, `CCC.Core.CN01.AR01`). |
| `Description` | string | Yes | Verbatim from the source catalog. |
| `Name` | string | No | Optional short title (NIST-style catalogs use it). |
| `Attributes` | array of objects | Yes | Parsed against the Union of attribute classes below; only `Attributes[0]` survives the universal adaptation and drives UI grouping. |
| `Checks` | array of strings | Yes | Check ids automating the requirement; `[]` = manual. |
| `ConfigRequirements` | array | No | Guardrails; `Provider` is omitted (the file is single-provider). |
MITRE files use `Mitre_Requirement` instead, which adds `Tactics`,
`SubTechniques`, `Platforms`, `TechniqueURL` at the requirement top level.
### Attribute shapes per framework family
Unlike universal (schema in-file), a legacy requirement's `Attributes` must
match one of the Pydantic classes registered in
`Compliance_Requirement.Attributes` — a shape matching no class **silently
falls through to Generic**, dropping its specific fields. The most common
shapes (full field sets in `compliance_models.py`):
### CIS — `cis_{version}_{provider}`
```json
{
"Section": "1 Identity and Access Management",
"SubSection": "Optional subsection",
"Profile": "Level 1",
"AssessmentStatus": "Automated",
"Description": "...", "RationaleStatement": "...", "ImpactStatement": "...",
"RemediationProcedure": "...", "AuditProcedure": "...",
"AdditionalInformation": "...", "DefaultValue": "...", "References": "https://..."
}
```
`Profile`: `Level 1|Level 2|E3 Level 1|E3 Level 2|E5 Level 1|E5 Level 2`.
`AssessmentStatus`: `Automated|Manual`.
### ENS — `ens_rd2022_{provider}`
```json
{
"IdGrupoControl": "op.acc.1", "Marco": "operacional",
"Categoria": "control de acceso", "DescripcionControl": "...",
"Nivel": "alto", "Tipo": "requisito",
"Dimensiones": ["trazabilidad", "autenticidad"],
"ModoEjecucion": "automatico", "Dependencias": []
}
```
`Nivel`: `opcional|bajo|medio|alto`. `Tipo`: `refuerzo|requisito|recomendacion|medida`.
`Dimensiones`: `confidencialidad|integridad|trazabilidad|autenticidad|disponibilidad`.
### ISO 27001 — `iso27001_{year}_{provider}`
```json
{
"Category": "A.5 Organizational controls",
"Objetive_ID": "A.5.1", "Objetive_Name": "Policies for information security",
"Check_Summary": "Summary of what is being checked"
}
```
Note: `Objetive_ID` / `Objetive_Name` use this exact (mis)spelling.
### MITRE ATT&CK — `mitre_attack_{provider}` (separate requirement model)
```json
{
"Name": "Exploit Public-Facing Application", "Id": "T1190",
"Tactics": ["Initial Access"], "SubTechniques": [],
"Platforms": ["IaaS"], "Description": "...",
"TechniqueURL": "https://attack.mitre.org/techniques/T1190/",
"Checks": ["guardduty_is_enabled"],
"Attributes": [
{"AWSService": "Amazon GuardDuty", "Category": "Detect",
"Value": "Minimal", "Comment": "..."}
]
}
```
`AzureService`/`GCPService` for the other providers. `Category`:
`Detect|Protect|Respond`. `Value`: `Minimal|Partial|Significant`.
### CCC — `ccc_{provider}`
```json
{
"FamilyName": "Data", "FamilyDescription": "...",
"Section": "CCC.Core.CN01 Encrypt Data for Transmission", "SubSection": "",
"SubSectionObjective": "...",
"Applicability": ["tlp-green", "tlp-amber", "tlp-red"],
"Recommendation": "...",
"SectionThreatMappings": [{"ReferenceId": "CCC", "Identifiers": ["CCC.Core.TH02"]}],
"SectionGuidelineMappings": [{"ReferenceId": "NIST-CSF", "Identifiers": ["PR.DS-02"]}]
}
```
`Applicability` holds TLP tags (`tlp-clear|tlp-green|tlp-amber|tlp-red`).
### ASD Essential Eight — `asd_essential_eight_aws`
```json
{
"Section": "Patch applications", "MaturityLevel": "ML1",
"AssessmentStatus": "Automated", "CloudApplicability": "partial",
"MitigatedThreats": ["..."], "Description": "...",
"RationaleStatement": "...", "ImpactStatement": "...",
"RemediationProcedure": "...", "AuditProcedure": "...",
"AdditionalInformation": "...", "References": "..."
}
```
`MaturityLevel`: `ML1|ML2|ML3`. `CloudApplicability`: `full|partial|limited|non-applicable`.
### DISA STIG — `okta_idaas_stig_v1r2_okta`
```json
{
"Section": "...", "Severity": "high", "RuleID": "...", "StigID": "...",
"CCI": ["CCI-000015"], "CheckText": "...", "FixText": "..."
}
```
`Severity`: `high|medium|low` (maps to CAT I/II/III).
### Other registered shapes
- **AWS Well-Architected** (`aws_well_architected_framework_{pillar}_pillar_aws`):
`Name`, `WellArchitectedQuestionId`, `WellArchitectedPracticeId`, `Section`,
`SubSection`, `LevelOfRisk`, `AssessmentMethod`, `Description`,
`ImplementationGuidanceUrl`.
- **KISA ISMS-P** (`kisa_isms_p_2023_{provider}`): `Domain`, `Subdomain`,
`Section`, `AuditChecklist`, `RelatedRegulations`, `AuditEvidence`,
`NonComplianceCases`.
- **C5** (`c5_{provider}`): `Section`, `SubSection`, `Type`, `AboutCriteria`,
`ComplementaryCriteria`.
- **CSA CCM** (legacy shape; the shipped CSA CCM 4.0 is universal): `Section`,
`CCMLite`, `IaaS`, `PaaS`, `SaaS`, `ScopeApplicability`.
- **Prowler ThreatScore** (`prowler_threatscore_{provider}`): `Title`,
`Section`, `SubSection`, `AttributeDescription`, `AdditionalInformation`,
`LevelOfRisk` (1–5), `Weight` (1/8/10/100/1000). Pillars: 1 IAM, 2 Attack
Surface, 3 Logging and Monitoring, 4 Encryption. Available for aws,
azure, gcp, kubernetes, m365, alibabacloud.
- **Generic (fallback)**: `ItemId`, `Section`, `SubSection`, `SubGroup`,
`Service`, `Type`, `Comment` — all optional. Used by NIST, PCI, GDPR,
HIPAA, SOC2, FedRAMP, CISA, FFIEC, RBI, NIS2, GxP, SecNumCloud, etc.
## Config Guardrails (`ConfigRequirements`)
Requirements backed by [configurable checks](https://docs.prowler.com/developer-guide/configurable-checks)
can be silently "satisfied" by a loosened `audit_config` (e.g. CIS demands
45-day unused credentials but the scan ran with `max_unused_access_keys_days: 120`).
Guardrails force such requirements to FAIL:
```json
"ConfigRequirements": [
{"Check": "iam_user_accesskey_unused",
"ConfigKey": "max_unused_access_keys_days", "Operator": "lte", "Value": 45}
]
```
- Operators: `lte`/`gte` (numeric thresholds), `eq` (toggles/exact — use JSON
booleans, not 0/1), `in` (scalar in allowed set), `subset` (allowlists —
widening breaks it), `superset` (denylists — removing an entry breaks it).
- `Value` must be the **strictest** setting the control text tolerates.
- `ConfigKey` must be spelled exactly as the check reads it; unknown keys are
silently skipped (defaults assumed OK).
- Guardrails only tighten (PASS→FAIL), never relax.
- Universal files: lowercase `config_requirements` + mandatory `Provider` per
constraint.
- Tests: `tests/lib/check/compliance_config_eval_test.py`,
`compliance_config_constraint_model_test.py`,
`compliance_config_requirements_data_test.py`, plus per-output tests under
`tests/lib/outputs/compliance/`.
---
## Workflow A: Sync a Framework With an Upstream Catalog
Use when the framework is maintained upstream (CIS Benchmarks, FINOS CCC, CSA
CCM, NIST, ENS, etc.) and Prowler needs to catch up.
### Step 1 — Cache the upstream source
Download every upstream file to a local cache so iterations don't hit the
network. For FINOS CCC:
```bash
mkdir -p /tmp/ccc_upstream
catalogs="core/ccc storage/object management/auditlog management/logging ..."
for p in $catalogs; do
safe=$(echo "$p" | tr '/' '_')
gh api "repos/finos/common-cloud-controls/contents/catalogs/$p/controls.yaml" \
-H "Accept: application/vnd.github.raw" > "/tmp/ccc_upstream/${safe}.yaml"
done
```
### Step 2 — Run the generic sync runner against a framework config
The sync tooling is three layers, so adding a framework only takes a YAML
config (plus a parser module for an unfamiliar upstream format):
```text
skills/prowler-compliance/assets/
├── sync_framework.py # generic runner — works for any framework
├── configs/ccc.yaml # per-framework config (canonical example)
└── parsers/finos_ccc.py # parser module for FINOS CCC YAML
```
```bash
python skills/prowler-compliance/assets/sync_framework.py \
skills/prowler-compliance/assets/configs/ccc.yaml
```
The runner loads the config, dynamically imports `parser.module`, calls
`parse_upstream(config) -> list[dict]`, then applies generic post-processing
(id-uniqueness safety net, `FamilyName` normalization, legacy check-mapping
preservation with config-driven fallback keys) and writes the provider JSONs
with Pydantic post-validation.
**To add a new framework sync**:
1. Write `assets/configs/{framework}.yaml` (see `ccc.yaml`). Required sections:
- `framework` — `name`, `display_name`, `version` (**never empty** — the
runner refuses to start, because empty Version breaks the
`get_check_compliance()` key), `description_template`.
- `providers` — list of `{key, display}` pairs.
- `output.path_template` — e.g.
`"prowler/compliance/{provider}/cis_{version}_{provider}.json"`.
- `upstream.dir` — local cache (Step 1).
- `parser.module` — module under `parsers/`; the rest of `parser.` is
passed through opaque.
- `post_processing.check_preservation.primary_key` (almost always `Id`) and
`fallback_keys` — lists of `Attributes[0]` field names composed into
tuples for recovering mappings when ids change. CCC:
`- [Section, Applicability]`; CIS: `- [Section, Profile]`; NIST:
`- [ItemId]`. List-valued fields are frozen to `frozenset` automatically.
- `post_processing.family_name_normalization` (optional) — raw → canonical
map; the UI groups by the exact attribute value, so upstream variants
otherwise become separate tree branches.
2. Reuse an existing parser or write `parsers/{name}.py` implementing
`parse_upstream(config) -> list[dict]` returning Prowler-format
requirements with **guaranteed-unique ids**. The runner raises on
duplicates — it never silently renumbers, because mutating a canonical
upstream id (CIS `1.1.1`, NIST `AC-2(1)`) would be catastrophic. The parser
owns all upstream quirks: foreign-prefix rewriting, genuine collision
renumbering, multi-shape handling.
**Gotchas the runner already handles** (from the FINOS CCC v2025.10 sync):
- **Multiple upstream YAML shapes.** Most FINOS CCC catalogs use
`control-families: [...]` but `storage/object` uses top-level
`controls: [...]`. A single-shape parser silently drops entire catalogs —
this exact bug dropped ObjStor for a full iteration. Test with one file of
each shape.
- **Whitespace collapse.** Upstream `|` block scalars keep newlines; Prowler
stores single-line. Collapse with `" ".join(value.split())`.
- **Foreign-prefix id rewriting.** Upstream aliases requirements across
catalogs keeping the original prefix (`CCC.AuditLog.CN08.AR01` nested under
`CCC.Logging.CN03`) — rewrite to fit the parent (`CCC.Logging.CN03.AR01`).
- **Genuine upstream collisions.** Two different requirements sharing one id
(upstream typo): renumber the second to the next free number; check-mapping
preservation recovers by the fallback keys.
- **Populate `Version`** — fail-fast beats the silent broken-key bug.
### Step 3 — Validate before committing
Run the full Validation section below (universal loader + check existence +
CLI smoke + pytest).
### Step 4 — Add an attribute model if needed
Only if the framework has fields beyond
`Generic_Compliance_Requirement_Attribute` and must stay legacy. Add the class
to `compliance_models.py` and register it in the
`Compliance_Requirement.Attributes` Union **before Generic** (Generic stays
last). For new frameworks, prefer universal `attributes_metadata` instead.
---
## Workflow B: Audit Check Mappings as a Cloud Auditor
Use when the user asks to review existing mappings. This is the
highest-value compliance task — it surfaces padded mappings with zero actual
coverage and missing mappings for legitimate coverage.
### The golden rule
> A Prowler check's title/risk MUST **literally describe what the requirement
> text says**. "Related" is not enough. If no check actually addresses the
> requirement, leave the checks list empty (MANUAL) — **honest MANUAL is worth
> more than padded coverage**.
### Audit process
1. **Build a per-provider check inventory** — `assets/build_inventory.py`
(writes `/tmp/checks_{provider}.json` for every provider discovered under
`prowler/providers/`).
2. **Query it** — `assets/query_checks.py` (run from the repository root):
```bash
python skills/prowler-compliance/assets/query_checks.py aws encryption transit # keyword AND-search
python skills/prowler-compliance/assets/query_checks.py aws --service iam # all iam checks
python skills/prowler-compliance/assets/query_checks.py aws --id kms_cmk_rotation_enabled
```
3. **Dump a framework section with current mappings** — `assets/dump_section.py`:
```bash
python skills/prowler-compliance/assets/dump_section.py ccc "CCC.Core."
python skills/prowler-compliance/assets/dump_section.py cis_5.0_aws "1."
```
4. **Encode explicit REPLACE decisions** — `assets/audit_framework_template.py`:
```python
DECISIONS = {}
DECISIONS["CCC.Core.CN01.AR01"] = {
"aws": ["cloudfront_distributions_https_enabled", ...],
"azure": ["storage_secure_transfer_required_is_enabled", ...],
"gcp": ["cloudsql_instance_ssl_connections"],
# Missing provider key = leave the legacy mapping untouched
}
# Empty list = EXPLICITLY MANUAL (overwrites legacy)
DECISIONS["CCC.Core.CN01.AR07"] = {"aws": [], "azure": [], "gcp": []}
```
**REPLACE, not PATCH.** Full lists make the audit reproducible and surface
hidden assumptions in the legacy data.
5. **Pre-validate** every check id against the inventory; the script MUST
abort with stderr listing typos (real audits caught
`storage_secure_transfer_required_enabled` →
`storage_secure_transfer_required_is_enabled`,
`sqlserver_minimum_tls_version_12` →
`sqlserver_recommended_minimal_tls_version`, and several checks that
simply don't exist).
6. **Apply + validate + test**:
```bash
python /path/to/audit_script.py
uv run pytest -n auto tests/lib/outputs/compliance/ tests/lib/check/ -q
```
For the curated mapping table (requirement text → AWS/Azure/GCP checks) and
the list of controls Prowler genuinely cannot verify, see
[references/check-mapping-reference.md](references/check-mapping-reference.md).
---
## Workflow C: Add a New Universal Framework
1. Author `prowler/compliance/{framework}_{version}.json` following the
Universal Schema Reference above (use `dora_2022_2554.json` or
`csa_ccm_4.0.json` as template).
2. Declare every attribute in `attributes_metadata` (with `required`/`enum`
where possible — that's your load-time validation) and a
`outputs.table_config.group_by`.
3. Map checks per provider; add `config_requirements` (with `Provider`) for
configurable checks; leave empty lists for manual requirements — **include
every requirement of the source catalog** (coverage percentages depend on
the full denominator).
4. Validate (section below). No Python registration of any kind is needed for
CLI table/CSV/OCSF.
5. Optional first-class UI: mapper in `ui/lib/compliance/{framework}.tsx`,
registration in `getComplianceMappers()` under the JSON's `framework` value,
detail panel, `*AttributesMetadata` type, and icon (ordered keyword!). Until
then the generic mapper renders it.
6. Optional API extras: CSV exporter entry in `COMPLIANCE_CLASS_MAP`; PDF
generator + `FRAMEWORK_REGISTRY` entry if a PDF is required.
7. Tests: extend `tests/lib/check/universal_compliance_models_test.py` with a
case loading the new JSON. The parametrized `test_loads_as_universal`
already picks the file up automatically.
8. Changelog fragment `prowler/changelog.d/<slug>.added.md` + user-guide
tutorial under `docs/user-guide/compliance/tutorials/` for high-profile
frameworks.
## Workflow D: Add a New Legacy Output Formatter
Only for new members of an existing legacy family. Follow the `c5/` or `ccc/`
layout exactly:
1. `mkdir prowler/lib/outputs/compliance/{framework}` with `__init__.py`.
2. `{framework}.py` — copy `c5/c5.py`, change function name + framework
string; the diff should be just those lines. No docstring (legacy style).
3. `models.py` — one Pydantic CSV row model per provider. Column sets differ
per provider (`AccountId`/`Region` vs `SubscriptionId`/`Location` vs
`ProjectId`/`Location`); per-provider files are the convention — don't
collapse them into a parameterized class, reviewers will reject it.
4. `{framework}_{provider}.py` — `{Framework}_{Provider}(ComplianceOutput)`
with `transform()`; this file may import `Finding`.
5. Register:
- `compliance.py` → `display_compliance_table()` `elif` branch (+ top import).
- `prowler/__main__.py` → per-provider `elif compliance_name.startswith(...)`
branches instantiating the writer classes.
- `api/src/backend/tasks/jobs/export.py` → `COMPLIANCE_CLASS_MAP` entries
(`startswith` for families, exact match only for true singletons).
6. Tests under `tests/lib/outputs/compliance/{framework}/` + fixtures in
`tests/lib/outputs/compliance/fixtures.py` (1 evaluated + 1 manual
requirement to exercise both `transform()` paths).
**Circular import warning**: the table file must not import `Finding` directly
or transitively (cycle: `compliance.compliance` → table → `ComplianceOutput` →
`Finding` → `get_check_compliance` → `compliance.compliance`). Keep it bare;
use `TYPE_CHECKING`/function-local imports where both are genuinely needed.
---
## Validation (run before every commit)
1. **Schema load (both formats)**:
```python
from prowler.lib.check.compliance_models import (
load_compliance_framework_universal,
get_bulk_compliance_frameworks_universal,
)
fw = load_compliance_framework_universal("prowler/compliance/<file>.json")
assert fw is not None, "check logs for the ValidationError"
print(fw.framework, len(fw.requirements), fw.get_providers())
assert "<file_basename>" in get_bulk_compliance_frameworks_universal("aws")
```
Remember: the universal loader is lenient (skips broken files with a log
line) — an `assert fw is not None` is mandatory, a green scan is not proof.
2. **Check existence** — no loader validates this; a stale id is silent dead
weight:
```python
import json
from pathlib import Path
for prov in ["aws", "azure", "gcp"]:
real = {p.stem.replace(".metadata", "")
for p in Path(f"prowler/providers/{prov}/services").rglob("*.metadata.json")}
data = json.load(open(f"prowler/compliance/{prov}/<file>.json"))
refs = {c for r in data["Requirements"] for c in r["Checks"]}
missing = refs - real
assert not missing, f"{prov} missing: {missing}"
```
(For universal files use `r.get("checks", {}).get(prov, [])` instead —
requirements may legitimately omit a provider key.)
3. **CLI smoke test**:
```bash
uv run python prowler-cli.py <provider> --list-compliance # appears?
uv run python prowler-cli.py <provider> --compliance <key> --log-level ERROR
```
Verify the CSV under `output/compliance/`, the summary table sections, and
the findings roll-up.
4. **Tests**:
```bash
uv run pytest -n auto tests/lib/check/universal_compliance_models_test.py \
tests/lib/outputs/compliance/
```
`test_loads_as_universal` is parametrized over **every** JSON in
`prowler/compliance/` (top-level + subdirectories) — a malformed file fails
CI here even if you never wrote a dedicated test.
5. **What CI/pre-commit do and don't cover**: pre-commit only guarantees
well-formed/pretty JSON (`check-json`, `pretty-format-json`) — no semantic
validation. The workflow `.github/workflows/pr-check-compliance-mapping.yml`
flags PRs adding new checks without mapping them to any framework (label
`needs-compliance-review`; skip with label `no-compliance-check`). Semantic
validation happens in the pytest suite above and manually via
`skills/prowler-compliance-review/assets/validate_compliance.py` (note:
that validator assumes the **legacy** schema).
6. **Prowler Local Server**: `docker compose up` and confirm the compliance
page renders requirements, sections and widgets.
---
## Conventions and Hard-Won Gotchas
1. **Universal first.** A new framework that starts as legacy needs 3 output
files + 3 registrations; the same framework as universal needs zero. Only
extend legacy families.
2. **`Generic_Compliance_Requirement_Attribute` stays LAST** in the legacy
Attributes Union — Pydantic v1 tries members in order; Generic first
silently swallows every specific shape.
3. **Pydantic v1 everywhere in `compliance_models.py`**
(`from pydantic.v1 import ...`). Don't mix in v2.
4. **`get_check_compliance()` lives in
`prowler/lib/outputs/compliance/compliance_check.py`** and keys the dict
`f"{Framework}-{Version}"` only when Version is non-empty. Never ship
`Version: ""` — the key silently degrades to `"{Framework}"` and breaks
filters, tests and `--compliance`. For legacy files the filename version
substring must match `Version` (the CLI reads
`compliance_framework.split("_")[1]`).
5. **`Compliance.get_bulk()` does not see top-level universal files** — only
`get_bulk_compliance_frameworks_universal()` does. Wire new code paths
against the universal loader.
6. **Loader leniency differs**: legacy loader exits the process on a broken
JSON; universal loader logs and skips. A missing framework after your edit
usually means the universal loader dropped it — check the logs.
7. **Circular import protection**: legacy table dispatcher files must not
import `Finding` (directly or transitively). Use `TYPE_CHECKING` or
function-local imports when a module needs both sides (that's how the
universal formatter does it).
8. **Per-provider formatter files are the legacy convention** — but know the
exceptions before flagging them (iso27001 has no table file,
aws_well_architected has no per-provider files, cisa_scuba is
googleworkspace-only). CSV model field names are public API.
9. **CSV output**: `;` delimiter, UPPERCASE headers. OCSF compliance output is
always generated for universal frameworks regardless of `--output-formats`.
10. **`COMPLIANCE_CLASS_MAP` mixes predicate styles**: `startswith` for
multi-version families, exact `==` for singletons. When in doubt use
`startswith` — exact match blocked versioned CCC variants until 2026.
11. **UI grouping is per-mapper, always on `attributes[0]`**: generic/cis →
`Section`/`SubSection`, iso → `Category`, ccc → `FamilyName`. Inconsistent
values (or empty Section) create orphan/duplicate tree branches — normalize
before shipping.
12. **UI has a generic fallback** — an unregistered framework still renders.
A dedicated mapper/panel/icon is an upgrade, not a prerequisite.
13. **Icon registration is ordered substring matching** in
`IconCompliance.tsx` — specific keywords before generic (`nist` before
`nis2`, `cisa` before `cis`, `aws` last).
14. **API PDF pipeline is not `PDFConfig`-driven yet** — it has its own
`FRAMEWORK_REGISTRY` (5 frameworks). Don't assume adding `pdf_config` to a
JSON produces a PDF in Prowler App.
15. **Pre-validate every check id** against the per-provider inventory before
writing JSON. No loader will catch a typo; the requirement just never
matches a finding.
16. **REPLACE beats PATCH** for audit decisions — full explicit lists are
reproducible and surface legacy assumptions.
17. **When no check applies, MANUAL is correct.** Don't pad mappings with
tangential checks; compliance reports must stay actionable.
18. **Include every requirement of the source catalog**, automated or not —
compliance percentages use the full requirement count as denominator.
19. **Provider coverage is asymmetric** (AWS dense; Azure/GCP thinner; new
providers minimal). Accept it — don't force parity Prowler can't verify.
20. **Guardrail authoring**: strictest tolerated `Value`, exact `ConfigKey`
spelling, `Provider` mandatory in universal files, booleans as JSON
booleans. Malformed constraints are treated as satisfied — validate with
the config tests, don't trust silence.
---
## Useful One-Liners
```bash
# Find duplicate requirement IDs (legacy | universal)
jq -r '.Requirements[].Id' file.json | sort | uniq -d
jq -r '.requirements[].id' file.json | sort | uniq -d
# Count manual requirements (legacy | universal, per provider)
jq '[.Requirements[] | select((.Checks | length) == 0)] | length' file.json
jq '[.requirements[] | select((.checks.aws // [] | length) == 0)] | length' file.json
# List unique check references (legacy | universal)
jq -r '.Requirements[].Checks[]' file.json | sort -u
jq -r '.requirements[].checks[]? | .[]' file.json | sort -u
# Providers covered by a universal framework
jq '[.requirements[].checks | keys[]] | unique' file.json
# Spot inconsistent grouping values (UI tree branches)
jq '[.Requirements[].Attributes[0].Section] | unique' file.json
jq '[.Requirements[].Attributes[0].FamilyName] | unique' file.json
# Requirements with config guardrails (empty arrays are truthy in jq — check length)
jq '[.Requirements[] | select((.ConfigRequirements // []) | length > 0)] | length' file.json
# Diff requirement ids between two versions
diff <(jq -r '.Requirements[].Id' a.json | sort) <(jq -r '.Requirements[].Id' b.json | sort)
# Where is a check mapped across all frameworks?
grep -rl "my_check_name" prowler/compliance/
# Does a check exist?
find prowler/providers/aws/services -name "{check_id}.metadata.json"
# Validate one file with the universal loader
python -c "from prowler.lib.check.compliance_models import load_compliance_framework_universal as l; fw=l('prowler/compliance/aws/cis_7.0_aws.json'); print(fw.framework, len(fw.requirements))"
```
## Commands
```bash
prowler {provider} --list-compliance
prowler {provider} --compliance cis_7.0_aws
prowler aws --compliance cis_7.0_aws pci_4.0_aws
prowler aws --compliance dora_2022_2554 # universal key = file basename
prowler aws --list-compliance-requirements cis_7.0_aws
prowler aws --compliance cis_7.0_aws -M csv json html
```
## Code References
### Layer 1 — SDK / Core
- `prowler/lib/check/compliance_models.py` — legacy + universal model trees,
`Compliance_Requirement_ConfigConstraint`, all loaders and the
legacy→universal adapter
- `prowler/lib/check/compliance.py` — `update_checks_metadata_with_compliance`
- `prowler/lib/check/compliance_config_eval.py` — guardrail evaluation
(shared with the API)
- `prowler/lib/outputs/compliance/compliance_check.py` — `get_check_compliance`
- `prowler/lib/check/utils.py` — `list_compliance_modules`
### Layer 2 — JSON Catalogs
- `prowler/compliance/*.json` — universal, multi-provider (auto-discovered)
- `prowler/compliance/{provider}/` — legacy, per-provider (auto-discovered)
### Layer 3 — Output Formatters
- `prowler/lib/outputs/compliance/universal/` — `universal_table.py`,
`universal_output.py`, `ocsf_compliance.py`
- `prowler/lib/outputs/compliance/{framework}/` — legacy per-framework packages
- `prowler/lib/outputs/compliance/compliance.py` —
`process_universal_compliance_frameworks`, `display_compliance_table`
- `prowler/lib/outputs/compliance/compliance_output.py` — `ComplianceOutput`
base + CSV writer
- `prowler/__main__.py` — universal processing + per-provider legacy writer
branches
### Layer 4 — API / UI
- `api/src/backend/api/compliance.py` — `LazyComplianceTemplate`,
`LazyChecksMapping`, cache warm-up
- `api/src/backend/tasks/jobs/export.py` — `COMPLIANCE_CLASS_MAP`
- `api/src/backend/tasks/jobs/scan.py` — `create_compliance_requirements`
(overview ingestion)
- `api/src/backend/tasks/jobs/reports/` — PDF generators + `FRAMEWORK_REGISTRY`
- `ui/lib/compliance/compliance-mapper.ts` — mapper routing + generic fallback
- `ui/lib/compliance/{framework}.tsx` — per-framework mappers
- `ui/components/compliance/compliance-custom-details/` — detail panels
- `ui/types/compliance.ts` — attribute metadata types
- `ui/components/icons/compliance/` + `IconCompliance.tsx` — icons (ordered)
### Tests
- `tests/lib/check/universal_compliance_models_test.py` — includes the
parametrized `test_loads_as_universal` over every shipped JSON
- `tests/lib/check/compliance_check_test.py`,
`compliance_config_eval_test.py`, `compliance_config_constraint_model_test.py`,
`compliance_config_requirements_data_test.py`, `mitre_config_requirements_test.py`
- `tests/lib/outputs/compliance/` — per-framework + universal + dispatcher +
config-status coverage tests; shared `fixtures.py`
## Resources
- **Docs (source of truth for contributors)**:
`docs/developer-guide/security-compliance-framework.mdx` (both schemas,
guardrails, validation, PR process),
`docs/user-guide/compliance/tutorials/compliance.mdx`,
`docs/user-guide/compliance/tutorials/cross-provider-compliance.mdx`
- **Repo tooling** (`util/compliance/`): CSV→JSON generators
(`generate_json_from_csv/`), `ccc/from_yaml_to_json.py`,
`compliance_mapper/`, `threatscore/`
- **Skill assets** ([assets/](assets/)):
- `sync_framework.py` + `configs/ccc.yaml` + `parsers/finos_ccc.py` —
config-driven upstream sync (Workflow A)
- `build_inventory.py`, `query_checks.py`, `dump_section.py`,
`audit_framework_template.py` — audit tooling (Workflow B)
- Legacy JSON templates: `cis_framework.json`, `ens_framework.json`,
`iso27001_framework.json`, `mitre_attack_framework.json`,
`prowler_threatscore_framework.json`, `generic_framework.json`
- **References**:
[references/compliance-docs.md](references/compliance-docs.md) — model/loader
quick reference;
[references/check-mapping-reference.md](references/check-mapping-reference.md)
— curated requirement-text → checks mapping table + honest-MANUAL list
- **Sister skill**:
[prowler-compliance-review](../prowler-compliance-review/SKILL.md) — PR
review checklist + `validate_compliance.py` (legacy-schema validator)
- After editing this skill's frontmatter, run
`./skills/skill-sync/assets/sync.sh` to regenerate the AGENTS.md auto-invoke
tables.