feat(sdk): Enhance dynamic provider loading and compliance framework

[StylusFrost]

Summary

• Add dynamic provider loading via Python entry points, enabling external/custom providers to be discovered and integrated without modifying Prowler's core codebase
• New dynamic provider contract on the Provider base class (12 methods: from_cli_args, get_output_options, get_stdout_detail, get_finding_sort_key, get_summary_entity, get_finding_output_data, get_html_assessment_summary, generate_compliance_output, get_mutelist_finding_args, display_compliance_table, init_parser, is_external_tool_provider)
• Entry point discovery via prowler.providers, prowler.checks.{provider}, and prowler.compliance groups with caching, CLI auto-discovery, and fallback across output, compliance, mutelist, compliance table display, and check resolution

Changes

• prowler/providers/common/provider.py — Dynamic provider contract methods (12), entry point discovery (_load_ep_provider, get_available_providers, get_providers_help_text), init_global_provider fallback to entry points when built-in import fails, new is_tool_wrapper_provider(provider) helper that combines the EXTERNAL_TOOL_PROVIDERS frozenset with the class attribute, and new is_builtin(provider) helper that uses importlib.util.find_spec to discriminate built-in vs external providers upfront (surfaces missing transitive dependencies with clear error messages)
• prowler/__main__.py — Dynamic else fallback for output options and compliance CSV generation for unknown providers; consults Provider.is_tool_wrapper_provider() instead of the frozenset directly
• prowler/lib/cli/parser.py — Auto-discovers external providers and appends them to --help usage/epilog dynamically
• prowler/lib/outputs/outputs.py — if chain converted to if/elif/else with dynamic fallback via get_stdout_detail and get_finding_sort_key
• prowler/lib/outputs/summary_table.py — Dynamic fallback via get_summary_entity for unknown providers
• prowler/lib/outputs/finding.py — Support for external provider finding output data
• prowler/lib/outputs/html/html.py — Dynamic fallback for HTML assessment summary
• prowler/lib/outputs/compliance/compliance.py — Dynamic fallback via display_compliance_table() for custom compliance table rendering, with automatic fallback to generic table
• prowler/lib/check/check.py — Check module resolution falls back to entry points; mutelist dispatch else clause via get_mutelist_finding_args()
• prowler/lib/check/utils.py — Check and compliance discovery merges built-in and entry point sources; _recover_ep_checks(provider, service=None) filters by .services.{service}. in the entry-point dotted path; recover_checks_from_provider no longer exits early on ModuleNotFoundError and always consults entry points
• prowler/lib/check/compliance_models.py — Compliance directory discovery from entry points
• prowler/lib/check/models.py — Support for external provider check metadata; all 9 CheckMetadata validators consult Provider.is_tool_wrapper_provider() instead of the frozenset
• prowler/config/config.py — Configuration support for external providers; load_and_validate_config_file now unwraps the namespaced format for every built-in and external provider (previously only 5 hardcoded providers)
• prowler/providers/common/arguments.py — CLI argument parsing for external providers; discriminates built-in vs external upfront via Provider.is_builtin() so missing transitive dependencies in built-ins fail loudly with a clear message instead of silently falling through to entry points
• tests/providers/external/test_dynamic_provider_loading.py — 77 tests covering provider discovery, entry point loading/caching, CLI parser integration, check resolution fallback, dispatch fallbacks, mutelist dispatch, compliance table dispatch, base contract defaults, compliance framework discovery, is_tool_wrapper_provider helper, service-filtered entry-point check discovery, is_builtin helper, and built-in-with-missing-dependency clean failure

Review Fixes

Commits addressing @HugoPBrito's review:

• e8487d068 — load_and_validate_config_file unwraps namespaced config for every provider, not just the 5 hardcoded built-ins
• 60e76570 — is_external_tool_provider wired into the execution flow (3 call sites in __main__.py) and the 9 CheckMetadata validators via the new Provider.is_tool_wrapper_provider() helper
• cf70d1f9f — from_cli_args return value honored in the dynamic fallback call site, with tolerance for providers that set the global from __init__
• 0883baad7 — External providers work with --service (removed premature sys.exit(1) and the if not service: gate around entry points)
• 907166d88 — Discriminate built-in vs external providers upfront via importlib.util.find_spec, so missing transitive dependencies in built-ins (e.g. boto3) fail loudly with a clear error message instead of silently re-routing to entry points

Test Plan

• pytest tests/providers/external/test_dynamic_provider_loading.py — 77 tests pass
• pytest tests/lib/ — all tests pass (no regressions)
• Pre-commit hooks pass (flake8, black, isort, bandit, trufflehog all green)
• 27/28 CLI parameters verified working with template external provider (--excluded-service tracked in PROWLER-1419)
• No changes to existing provider behavior — all fallbacks are else clauses after existing if/elif chains
• CI passes

[github-actions]

✅ All necessary CHANGELOG.md files have been updated.

[github-actions]

✅ Conflict Markers Resolved

All conflict markers have been successfully resolved in this pull request.

[codecov]

Codecov Report

❌ Patch coverage is 97.59036% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.58%. Comparing base (7c6d658) to head (cf99e02).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff             @@
##           master   #10700       +/-   ##
===========================================
+ Coverage   59.14%   71.58%   +12.43%     
===========================================
  Files           8      116      +108     
  Lines         399     8566     +8167     
===========================================
+ Hits          236     6132     +5896     
- Misses        163     2434     +2271     

Flag	Coverage Δ
prowler-py3.10-config	71.58% <97.59%> (?)
prowler-py3.10-external	20.78% <92.16%> (?)
prowler-py3.10-kubernetes	?
prowler-py3.10-lib	71.28% <96.08%> (?)
prowler-py3.11-config	71.58% <97.59%> (?)
prowler-py3.11-external	20.78% <92.16%> (?)
prowler-py3.11-kubernetes	?
prowler-py3.11-lib	71.28% <96.08%> (?)
prowler-py3.12-config	71.58% <97.59%> (?)
prowler-py3.12-external	20.78% <92.16%> (?)
prowler-py3.12-kubernetes	?
prowler-py3.12-lib	71.28% <96.08%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
prowler	71.58% <97.59%> (+12.43%)	⬆️
api	∅ <ø> (∅)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🔒 Container Security Scan

Image: prowler:cc1de3b
Last scan: 2026-05-05 07:07:41 UTC

📊 Vulnerability Summary

Severity	Count
🔴 Critical	4
Total	4

4 package(s) affected

⚠️ Action Required

Critical severity vulnerabilities detected. These should be addressed before merging:

• Review the detailed scan results
• Update affected packages to patched versions
• Consider using a different base image if updates are unavailable

---

📋 Resources:

• Download full report (see artifacts)
• View in Security tab
• Scanned with Trivy

[HugoPBrito]

Request changes — see inline comments for the specifics. One cross-cutting issue that doesn't anchor to any single line in the diff:

YAML namespace unwrap only knows about 5 providers

prowler/config/config.py:244-253 only sniffs aws, gcp, azure, kubernetes and m365. Prowler ships 16+ built-ins, so twelve are outside the list (nhn, github, googleworkspace, cloudflare, iac, llm, image, mongodbatlas, oraclecloud, openstack, alibabacloud, vercel).

A github user writing a namespaced config:

github:
  token: abc

The sniff finds none of the five keys, falls into the else at line 250, github isn't in the safeguard at line 252, and the function returns {'github': {'token': 'abc'}} whole. github_provider receives the wrapped dict instead of the inner block.

This is a latent bug in master for 12 built-ins; the PR inherits it and additionally blocks any external plug-in from using the namespaced format. One change covers both:

if provider in config_file:
    config = config_file.get(provider, {})
else:
    config = config_file if config_file else {}

[HugoPBrito]

Three more issues — see inline comments.

[HugoPBrito]

When a plugin re-registers an existing built-in CheckID (an edit over Prowler's own check), the executed module and the loaded metadata come from different sources:

• _resolve_check_module tries the built-in path first and returns it. Entry points are only consulted if the built-in import fails, so the executed module is the built-in one.
• CheckMetadata.get_bulk() (models.py:419-432) walks the loader output (built-ins first, entry points appended last) and does bulk[check_id] = metadata. Last write wins, so the plugin's metadata replaces the built-in's for the same CheckID.

Net effect: built-in code runs with the plugin's Severity, Description, Remediation, etc. A finding generated by code that expected LOW is published with the plugin's HIGH. Audit assumptions silently break.

Pick precedence once and apply it to both module and metadata — never split the source. Suggested: plugin wins (registering a duplicate is most likely an intentional edit, not a coincidence), with a logger.warning naming the overridden built-in.

Test: register an entry-point check sharing a built-in CheckID, run the check, and assert both lib and check.metadata come from the same source.

[StylusFrost]

Fixed in c7aa5368.

Picked precedence and applied it consistently across the three lookups so the executed module and the loaded metadata always come from the same source. The chosen direction is built-in wins on collision, with a logger.warning naming the shadowed plug-in:

1. _resolve_check_module (check.py): built-in first, entry point only when the built-in is absent.
2. CheckMetadata.get_bulk (models.py): first-write-wins on CheckID, plug-in duplicate is ignored and a warning is emitted naming the metadata file.
3. Provider.init_global_provider (provider.py): same pattern extended to the provider name itself, since the same divorce is possible there (built-in provider class running plug-in checks). When a plug-in registers a name colliding with a built-in, the built-in is loaded and the plug-in is announced as ignored.

Reasoning for built-in wins instead of plug-in wins: a security tool benefits more from fail-loud predictability than from permissive overrides. A plug-in lowering a check's severity, or shadowing a provider's session setup, would silently change the user's security posture. With built-in wins, plug-ins remain first-class extenders (new providers, new services, new checks under new CheckIDs all keep working) but cannot replace existing built-ins. Override is still possible by renaming, and the warning tells the user how.

Tests:

• test_resolve_check_module_builtin_wins_over_entry_point: module resolution with both sources present, asserts built-in wins and the plug-in is not loaded.
• test_get_bulk_builtin_wins_on_check_id_collision: metadata loader with a duplicate CheckID, asserts built-in metadata stays and a warning is emitted naming the plug-in path.
• test_init_global_provider_warns_when_plugin_shadowed_by_builtin: provider name collision, asserts the warning fires before dispatch.

[HugoPBrito]

Same masking pattern as recover_checks_from_provider in utils.py, in a different file:

try:
    return import_check(builtin_path)
except ModuleNotFoundError:
    pass  # falls through to entry points

If a built-in check exists but its module fails to import for an unrelated reason (broken transitive dep, misconfigured client, etc.), the ModuleNotFoundError is caught silently and we resolve via entry points. If a plugin happens to register the same name, it silently runs in place of the built-in. This is worse than just hiding errors: a plugin can hijack a built-in check by causing its import to fail.

Apply the same fix:

if importlib.util.find_spec(builtin_path) is not None:
    return import_check(builtin_path)  # any error here is real, surface it
# Only fall through to entry points if the built-in module truly doesn't exist

Test: patch a built-in check so its module raises ImportError("missing: foo") and assert _resolve_check_module re-raises that error instead of falling back to the entry-point loader.

[StylusFrost]

Fixed in 82132a93.

_resolve_check_module now uses importlib.util.find_spec to check if the built-in module exists before importing - same pattern already applied in init_global_provider via Provider.is_builtin(). If the built-in is absent, we fall through to entry points cleanly. If the built-in exists but its import fails (broken transitive dep, etc.), the error propagates instead of being silently swallowed and replaced by an entry-point plug-in that happens to share the check name.

Added a regression guard test_resolve_check_module_surfaces_error_when_builtin_import_fails that registers a same-named entry-point check and asserts it does NOT take over when the built-in raises ImportError.

[HugoPBrito]

stdout_report() was extended to accept provider=None, but the call site in report() (line 88) doesn't pass it:

stdout_report(finding, color, verbose, status, fixer)

So for any external/custom provider, the else branch inside stdout_report falls back to Provider.get_global_provider(). That defeats the purpose of the new parameter and re-introduces the dependency on the global singleton this PR set out to remove.

Pass the local provider through:

stdout_report(finding, color, verbose, status, fixer, provider=provider)

Test: invoke report() after setting Provider._global_provider = None (or to a different provider) and assert the output uses the provider argument.

[StylusFrost]

Fixed in e7f23bb1.

report() now passes its local provider through to stdout_report, so the dynamic else inside stdout_report no longer needs to fall back to the global singleton for external providers. Wires the new parameter the way the change was intended.

Added a regression guard test_report_propagates_provider_to_stdout_report that clears Provider._global and asserts report() still renders the finding using the local provider's get_stdout_detail(), proving the argument is being used instead of the global.

[HugoPBrito]

list_modules calls walk_packages, which imports each package to walk it. Catching ModuleNotFoundError broadly here masks two distinct conditions:

try:
    modules = list_modules(provider, service)
    ...
except ModuleNotFoundError:
    pass  # falls through to entry points

If a built-in service exists but one of its modules fails because of a broken transitive dependency, walk_packages raises ModuleNotFoundError with a different name than the service path. We swallow it and silently fall through to entry points. The user either never sees the real error or ends up running an entry-point check that happens to share the same name (see the duplicate-CheckID comment).

Distinguish "service doesn't exist" from "service exists but failed to import":

service_path = (
    f"prowler.providers.{provider}.services.{service}"
    if service else f"prowler.providers.{provider}.services"
)
if importlib.util.find_spec(service_path) is not None:
    modules = list_modules(provider, service)  # any error here is real, surface it
    ...
# Only fall through to entry points if the built-in service truly doesn't exist

Test: patch a built-in service so one of its modules raises ImportError("missing: foo") and assert recover_checks_from_provider re-raises instead of silently falling back.

[StylusFrost]

Fixed in 82132a93.

recover_checks_from_provider now distinguishes "service doesn't exist" from "service exists but failed to import" via importlib.util.find_spec(service_path), exactly as you suggested. Removed the except ModuleNotFoundError: pass that was masking real import errors. Built-in services that fail to import now surface the error through the function's global exception handler (logs the original ImportError class and message at CRITICAL, then sys.exit(1)) instead of silently routing to entry points.

Added a regression guard test_recover_checks_surfaces_error_when_builtin_service_import_fails that mocks a broken built-in service and asserts the import error wins over a same-named entry-point plug-in.

[HugoPBrito]

Nice work introducing Provider.is_tool_wrapper_provider() as the single source of truth here (and at :303, :426). But line 202 still uses the hardcoded list:

elif default_execution and provider not in ["iac", "llm"]:
    args.output_formats.extend(get_available_compliance_frameworks(provider))

Any new tool-wrapper provider (built-in or external) silently misses this branch unless someone also remembers to edit this list — exactly the bug the helper was meant to prevent.

elif default_execution and not Provider.is_tool_wrapper_provider(provider):
    args.output_formats.extend(get_available_compliance_frameworks(provider))

A grep for ["iac", "llm"] / "iac" / "llm" would also help confirm no other call site duplicates the same decision.

[StylusFrost]

Fixed in 5e87657.

The line now uses Provider.is_tool_wrapper_provider(provider) so the compliance-framework branch is skipped for any tool wrapper - built-in (iac, llm, image) or external plug-in declaring is_external_tool_provider = True. No behavior change for the built-ins (image already returned an empty list of frameworks, so extend([]) was a no-op).

Per your suggestion I grepped for ["iac", "llm"] / "iac" / "llm" / "image" across prowler/. The remaining hits fall into two buckets:

• scan.py:97 and scan.py:164 use provider.type in ("iac", "image") - note the asymmetry: llm is intentionally excluded because it has no synthetic llm_scan check. Consolidating these to is_tool_wrapper_provider would route llm into a branch that tries to execute a non-existent check. I'm leaving these as-is; happy to revisit if you'd prefer a separate refactor that introduces a per-tool-wrapper "synthetic check name" registry.

• main.py:392-396, 428 and the dispatch chain in provider.py are per-provider branches with different logic per tool wrapper (each one needs distinct kwargs / setup), so the binary helper doesn't apply there.

If you'd rather see scan.py consolidated too, let me know and I'll open a separate PR with the synthetic-check-registry approach

[StylusFrost]

Follow-up fix on find_spec for external providers

Problem

importlib.util.find_spec on a dotted submodule path imports the parent package to resolve the child. For an external provider — whose package does not live under prowler.providers.{provider} — that parent import raises ModuleNotFoundError and propagates; it does not return None.

Reproducer:

>>> importlib.util.find_spec("prowler.providers.<external>.services")
ModuleNotFoundError: No module named 'prowler.providers.<external>'

Two earlier call sites in this PR used find_spec directly on prowler.providers.{provider}.services...:

• recover_checks_from_provider in prowler/lib/check/utils.py
• _resolve_check_module in prowler/lib/check/check.py

For external providers, the propagated ModuleNotFoundError was caught by the broad except Exception in recover_checks_from_provider → logger.critical(...) + sys.exit(1). Entry points were never consulted, so plug-ins that registered checks correctly via prowler.checks.{provider} were unreachable.

A third call site, Scan.scan in prowler/lib/scan/scan.py, was still using a hard-coded f"prowler.providers.{type}.services..." + import_check(...) and bypassed the unified resolver entirely.

Solution

The canonical guard for "is this provider shipped with the SDK?" is Provider.is_builtin, which already wraps find_spec in try/except (ImportError, ValueError). Two changes:

1. Extract the predicate to a leaf module — prowler/providers/common/builtin.py::is_builtin_provider, depending only on importlib.util. Provider.is_builtin delegates to it. This is the same pattern applied earlier in the PR for is_tool_wrapper_provider, and avoids the import cycle (prowler.lib.check.* → prowler.providers.common.provider → prowler.config.config → prowler.lib.check.*) that CodeQL flagged.
2. Gate the built-in branch on is_builtin_provider(provider) at all three call sites, so external providers fall through to the entry-point lookup as intended:
   • prowler/lib/check/utils.py::recover_checks_from_provider
   • prowler/lib/check/check.py::_resolve_check_module
   • prowler/lib/scan/scan.py::Scan.scan — also rewired to delegate to _resolve_check_module(...) instead of the hard-coded path, restoring the single source of truth for resolving check modules.

tests/lib/scan/scan_test.py updated to patch _resolve_check_module instead of import_check to follow the new code path.

Why this matters

is_builtin already existed in this PR; the bug was simply that the call sites duplicated find_spec logic instead of consuming it. The fix removes that duplication and makes the entry-point path actually reachable for installed external providers.